CopperSpice API  1.9.1
QOpenGLBuffer Class Reference

The QOpenGLBuffer class provides methods for creating and managing OpenGL buffer objects. More...

Public Typedefs

using RangeAccessFlags = QFlags< RangeAccessFlag >
 

Public Types

enum  Access
 
enum  RangeAccessFlag
 
enum  Type
 
enum  UsagePattern
 

Public Methods

 QOpenGLBuffer ()
 
 QOpenGLBuffer (const QOpenGLBuffer &other)
 
 QOpenGLBuffer (QOpenGLBuffer::Type type)
 
 ~QOpenGLBuffer ()
 
void allocate (const void *data, int count)
 
void allocate (int count)
 
bool bind ()
 
GLuint bufferId () const
 
bool create ()
 
void destroy ()
 
bool isCreated () const
 
void * map (QOpenGLBuffer::Access access)
 
void * mapRange (int offset, int count, QOpenGLBuffer::RangeAccessFlags access)
 
QOpenGLBuffer & operator= (const QOpenGLBuffer &other)
 
bool read (int offset, void *data, int count)
 
void release ()
 
void setUsagePattern (QOpenGLBuffer::UsagePattern value)
 
int size () const
 
QOpenGLBuffer::Type type () const
 
bool unmap ()
 
QOpenGLBuffer::UsagePattern usagePattern () const
 
void write (int offset, const void *data, int count)
 

Static Public Methods

static void release (QOpenGLBuffer::Type type)
 

Detailed Description

The QOpenGLBuffer class provides methods for creating and managing OpenGL buffer objects. Buffer objects are created in the OpenGL server so that the client application can avoid uploading vertices, indices, texture image data, etc every time they are needed.

Example

QOpenGLBuffer objects can be copied as a reference to the underlying OpenGL buffer object. A shallow copy will be done when objects are copied. The original object will be affected if the copy is modified.

QOpenGLBuffer buffer1(QOpenGLBuffer::IndexBuffer);
buffer1.create();
QOpenGLBuffer buffer2 = buffer1;

Member Typedef Documentation

Member Enumeration Documentation

This enum defines the access mode for QOpenGLBuffer::map().

Constant Value Description
QOpenGLBuffer::ReadOnly 0x88B8 Mapped for reading only
QOpenGLBuffer::WriteOnly 0x88B9 Mapped for writing only
QOpenGLBuffer::ReadWrite 0x88BA Mapped for reading and writing

This enum defines the access mode bits for QOpenGLBuffer::mapRange().

Constant Value Description
QOpenGLBuffer::RangeRead 0x0001 Buffer will be mapped for reading
QOpenGLBuffer::RangeWrite 0x0002 Buffer will be mapped for writing
QOpenGLBuffer::RangeInvalidate 0x0004 Discard the previous contents of the specified range
QOpenGLBuffer::RangeInvalidateBuffer 0x0008 Discard the previous contents of the entire buffer
QOpenGLBuffer::RangeFlushExplicit 0x0010 Indicates modifications are to be flushed explicitly via glFlushMappedBufferRange
QOpenGLBuffer::RangeUnsynchronized 0x0020 Indicates pending operations should not be synchronized before returning from mapRange()

This enum defines the type of OpenGL buffer object to create with QOpenGLBuffer.

Constant Value Description
QOpenGLBuffer::VertexBuffer 0x8892 Vertex buffer object for use when specifying vertex arrays
QOpenGLBuffer::IndexBuffer 0x8893 Index buffer object for use with glDrawElements()
QOpenGLBuffer::PixelPackBuffer 0x88EB Pixel pack buffer object for reading pixel data, used with glReadPixels(). Not supported under OpenGL/ES.
QOpenGLBuffer::PixelUnpackBuffer 0x88EC Pixel unpack buffer object for writing pixel data, used with glTexImage2D(). Not supported under OpenGL/ES.

This enum defines the usage pattern of a QOpenGLBuffer object.

Constant Value Description
QOpenGLBuffer::StreamDraw 0x88E0 Data set once and used a few times for drawing. In OpenGL/ES 1.1 identical to QOpenGLBuffer::StaticDraw.
QOpenGLBuffer::StreamRead 0x88E1 Data set once and used a few times for reading. Not supported with OpenGL/ES.
QOpenGLBuffer::StreamCopy 0x88E2 Data set once and used a few times for reading data for use in later drawing. Not supported with OpenGL/ES.
QOpenGLBuffer::StaticDraw 0x88E4 Data set once and used many times for drawing
QOpenGLBuffer::StaticRead 0x88E5 Data set once and used many times for reading. Not supported with OpenGL/ES.
QOpenGLBuffer::StaticCopy 0x88E6 Data set once and used many times for reading data for use in later drawing. Not supported with OpenGL/ES.
QOpenGLBuffer::DynamicDraw 0x88E8 Data modified repeatedly and used many times for drawing
QOpenGLBuffer::DynamicRead 0x88E9 Data modified repeatedly and used many times for reading data. Not supported with OpenGL/ES.
QOpenGLBuffer::DynamicCopy 0x88EA Data modified repeatedly and used many times for reading data for use in later drawing. Not supported under OpenGL/ES.

Constructor & Destructor Documentation

QOpenGLBuffer::QOpenGLBuffer ( )

Constructs a new buffer object of type QOpenGLBuffer::VertexBuffer and creates the QOpenGLBuffer instance. The actual buffer object in the OpenGL server is not created until create() is called.

See also
create()
QOpenGLBuffer::QOpenGLBuffer ( QOpenGLBuffer::Type  type)
explicit

Constructs a new buffer object using type and creates the QOpenGLBuffer instance. The actual buffer object in the OpenGL server is not created until create() is called.

See also
create()
QOpenGLBuffer::QOpenGLBuffer ( const QOpenGLBuffer &  other)

Constructs a shallow copy of other.

QOpenGLBuffer::~QOpenGLBuffer ( )

Destroys this buffer object including the storage being used in the OpenGL server.

Method Documentation

void QOpenGLBuffer::allocate ( const void *  data,
int  count 
)

Allocates count bytes of space to the buffer and initializes the buffer contents using data. Any previous contents will be removed. The create() method must be called before calling allocate() and the buffer must be bound to the current context.

See also
create(), read(), write()
void QOpenGLBuffer::allocate ( int  count)
inline

Allocates count bytes of space to the buffer. Any previous contents will be removed. The create() method must be called before calling allocate() and the buffer must be bound to the current context.

See also
create(), write()
bool QOpenGLBuffer::bind ( )

Binds the buffer associated with this object to the current OpenGL context. Returns false if binding was not possible, usually because type() is not supported on this OpenGL implementation.

The buffer must be bound to the same QOpenGLContext current when create() was called or to another QOpenGLContext that is sharing with it. Otherwise, false will be returned.

See also
create(), release()
GLuint QOpenGLBuffer::bufferId ( ) const

Returns the OpenGL identifier associated with this buffer. Returns zero if the buffer has not been created.

See also
isCreated()
bool QOpenGLBuffer::create ( )

Creates the buffer object in the OpenGL server. Returns true if the object was created, otherwise false is returned. This method will also return false if the OpenGL implementation does not support buffers or there is no current QOpenGLContext.

This method must be called with a current QOpenGLContext. The buffer will be bound to and can only be used in that context or any other context which is shared with it.

See also
allocate(), destroy(), isCreated(), write()
void QOpenGLBuffer::destroy ( )

Destroys this buffer object including the storage being used in the OpenGL server. All references to the buffer will become invalid.

bool QOpenGLBuffer::isCreated ( ) const

Returns true if this buffer has been created, otherwise returns false.

See also
create(), destroy()
void * QOpenGLBuffer::map ( QOpenGLBuffer::Access  access)

Maps the contents of this buffer into host memory and returns a pointer to the mapped buffer. Returns a nullptr if memory mapping is not possible. The access parameter indicates the type of access to be performed.

The create() method must be called before calling map() and the buffer must be bound to the current context.

This method is only supported under OpenGL ES 2.0 or earlier if the GL_OES_mapbuffer extension is present. When possible this method uses glMapBufferRange instead of glMapBuffer.

See also
bind(), create(), mapRange(), unmap()
void * QOpenGLBuffer::mapRange ( int  offset,
int  count,
QOpenGLBuffer::RangeAccessFlags  access 
)

Maps the range specified by offset and count of the contents of this buffer into host memory and returns a pointer to the mapped buffer. Returns a nullptr if memory mapping is not possible. The access parameter specifies a combination of access flags.

The create() method must be called before calling mapRange() and the buffer must be bound to the current context.

This method is not available on OpenGL ES 2.0 and earlier.

See also
bind(), create(), unmap()
QOpenGLBuffer & QOpenGLBuffer::operator= ( const QOpenGLBuffer &  other)

Assigns a shallow copy of other to this object.

bool QOpenGLBuffer::read ( int  offset,
void *  data,
int  count 
)

Reads the count number of bytes in this buffer starting at offset into data. Returns true on success. Returns false if reading from the buffer is not supported. Buffer reading is not supported under OpenGL/ES.

The create() method must be called before calling read() and the buffer must be bound to the current context.

See also
bind(), write()
void QOpenGLBuffer::release ( )

Releases the buffer associated with this object from the current OpenGL context. This method must be called with the same QOpenGLContext current as when bind() was called on the buffer.

See also
bind()
void QOpenGLBuffer::release ( QOpenGLBuffer::Type  type)
static

Releases the buffer associated with type in the current QOpenGLContext. This method is a direct call to glBindBuffer(type, 0) for use when the caller does not know which QOpenGLBuffer has been bound to the context but wants to make sure that it is released.

QOpenGLBuffer::release(QOpenGLBuffer::VertexBuffer);
void QOpenGLBuffer::setUsagePattern ( QOpenGLBuffer::UsagePattern  value)

Sets the usage pattern for this buffer object to value. This method must be called before allocate() or write().

See also
allocate(), usagePattern(), write()
int QOpenGLBuffer::size ( ) const

Returns the size of the data in this buffer, for reading operations. Returns -1 if fetching the buffer size is not supported or the buffer has not been created. It is assumed this buffer has been bound to the current context.

See also
bind(), isCreated()
QOpenGLBuffer::Type QOpenGLBuffer::type ( ) const

Returns the type of buffer represented by this object.

bool QOpenGLBuffer::unmap ( )

Unmaps the buffer after it was mapped into host memory with a previous call to map(). Returns true if this method succeeded, otherwise false is returned. The map() method must be called before calling unmap() and the buffer must be bound to the current context.

This method is only supported under OpenGL ES 2.0 and earlier if the GL_OES_mapbuffer extension is present.

See also
map()
QOpenGLBuffer::UsagePattern QOpenGLBuffer::usagePattern ( ) const

Returns the usage pattern for this buffer object. The default value is QOpenGLBuffer::StaticDraw.

See also
setUsagePattern()
void QOpenGLBuffer::write ( int  offset,
const void *  data,
int  count 
)

Replaces the count bytes of this buffer starting at offset with the contents of data. Any other bytes in the buffer will be left unmodified. The create() method must be called before calling write() and the buffer must be bound to the current context.

See also
allocate(), create(), read()