- Generated by
1.8.14
|
VVISF & VVGL
|
Representation of a GL resource of some sort- most commonly an OpenGL texture, but can also be other kinds of buffers (render buffers, VBOs, EBOs, FBO, etc). More...
#include <GLBuffer.hpp>
Classes | |
| struct | Descriptor |
| The Descriptor struct describes the hardware attributes of the GLBuffer. More... | |
Public Types | |
| enum | Type { Type_CPU, Type_RB, Type_FBO, Type_Tex, Type_PBO, Type_VBO, Type_EBO, Type_VAO } |
| Describes the several different kinds of GLBuffers. More... | |
| enum | Backing { Backing_None, Backing_Internal, Backing_External } |
| Indicates the relationship this buffer has with its backing. More... | |
| enum | BackingID { BackingID_None, BackingID_GWorld, BackingID_Pixels, BackingID_CVPixBuf, BackingID_CVTex, BackingID_NSBitImgRep, BackingID_RemoteIOSrf, BackingID_GenericExternalCPU, BackingID_QImage, BackingID_QVideoFrame } |
| The "BackingID" is an arbitrary enum that isn't used functionally by this lib. More... | |
| using | BackingReleaseCallback = function< void(GLBuffer &, void *)> |
| This defines a callback that is used to release the backing of a GLBuffer, where appropriate. The GLBuffer being released is the first var, and the GLBuffer's backingContext is the second var. The backingContext is probably a pointer to an object from another SDK that has been retained, and needs to be released/freed using the appropriate means. | |
Public Member Functions | |
| uint32_t | calculateBackingBytesPerRow () |
| Calculates the number of bytes that are required to display one row's worth of image data from this GLBuffer. | |
| uint32_t | calculateBackingLength () |
| Calculates the total number of bytes that are required to contain this GLBuffer's image data in system memory. | |
| Rect | glReadySrcRect () const |
| Only relevant where the GLBuffer is a texture. This is "srcRect", but converted to the texture's coordinates (normalized if the target is GL_TEXTURE_2D, non-normalized if it's GL_TEXTURE_RECTANGLE_EXT). | |
| bool | isFullFrame () const |
| Returns true if the receiver's image is full-frame (if the receiver's srcRect's origin is zero and size is the size of the reciver). | |
| bool | isNPOT2DTex () const |
| Returns true if the receiver is a texture, if the texture target is GL_TEXTURE_2D, if the texture's dimensions are power-of-two, and if the receiver's srcRect is NOT full-frame. | |
| bool | isPOT2DTex () const |
| Returns true if the receiver is a texture, if the texture target is GL_TEXTURE_2D, and if the texture's dimensions are power-of-two. | |
| bool | isContentMatch (GLBuffer &n) const |
| Returns a true if the receiver's timestamp is a match to the passed GLBuffer's timestamp (assumes that timestamps can be used to uniquely identify the content of a GLBuffer instance). | |
| string | getDescriptionString () const |
| Returns a std::string that describes some basic properties of the GLBuffer instance. | |
Public Attributes | |
| Descriptor | desc |
| Describes basic properties of the underlying resources. | |
| uint32_t | name = 0 |
| The name of the OpenGL object (the texture name/renderbuffer name/VBO name/etc) | |
| bool | preferDeletion = false |
| Whether or not the GL resources associated with the GL buffer should be freed when the GL buffer is deallocated. Defaults to 'false', which indicates that the GL resource should be pooled. | |
| Size | size = { 0, 0 } |
| The size of the OpenGL buffer, in pixels (only relevant where the GLBuffer represents an image). You should never change this value. | |
| Rect | srcRect = { 0, 0, 0, 0 } |
| Only relevant where the GLBuffer represents an image. The srcRect is the region (in pixels) of the texture/renderbuffer which comprises the GLBuffer's image. Most of the time this will be {0,0,size.width,size.height}, but it can also be a sub-region of the texture/renderbuffer, as is the case with a texture atlas. It is safe to change this value. | |
| bool | flipped = false |
| Whether or not the image in "srcRect" is flipped vertically. Other classes in VVGL and VVISF use this in an attempt to avoid having to run additional render passes that flip upside-down assets. | |
| Size | backingSize = { 0, 0 } |
| The size of the CPU backing, in pixels. | |
| Timestamp | contentTimestamp = { static_cast<uint64_t>(0), static_cast<uint32_t>(0) } |
| The content timestamp- when the buffer was created. Every GLBufferPool is capable of stamping the GLBuffers it vends. | |
| bool | pboMapped = false |
| If this is a PBO-type GLBuffer, this indicates whether or not the PBO is currently mapped, and must correspondingly be unmapped before use. | |
| BackingReleaseCallback | backingReleaseCallback = nullptr |
| If non-nil, this lambda/function is executed when GLBuffer's image resources are being deallocated. This is where you want to release any CPU-based resources that are retained by the GLBuffer in its 'backingContext' member var. | |
| void * | backingContext = nullptr |
| This is an arbitrary pointer that is stored with the GLBuffer at its creation, and passed to the backingReleaseCallback. If you're making a GLBuffer that uses a CPU resource provided by another SDK, this is where you store a copy of the pointer from the other SDK. | |
| BackingID | backingID = BackingID_None |
| Totally optional, used to describe where the backing came from. Sometimes you want to know what kind of backing a GLBuffer has, and access it. There's an enum describing some of the more common sources, and you can define and use your own values here. | |
| void * | cpuBackingPtr = nullptr |
| If the GLBuffer has any CPU-backed resources, this is a raw pointer to the beginning of the memory that OpenGL needs to work with. This is a weak ref, and if it's non-nil it's only valid for the lifetime of the GLBuffer. This may point to the beginning of the block of memory that OpenGL works with, but this member var should not be used to retain any underlying resources (that role is served by the 'backingContext' member var). | |
Related Functions | |
(Note that these are not member functions.) | |
| using | GLBufferRef = shared_ptr< GLBuffer > |
| Very common- GLBufferRef is a shared pointer around a GLBuffer. More... | |
| GLBufferRef | GLBufferCopy (const GLBufferRef &n) |
| GLBufferCopy returns a GLBufferRef for a new GLBuffer instance. This new instance of GLBuffer actually shares the same CPU/GPU resources as the passed buffer. More... | |
Representation of a GL resource of some sort- most commonly an OpenGL texture, but can also be other kinds of buffers (render buffers, VBOs, EBOs, FBO, etc).
Many GL objects- like buffers and textures- need to be explicitly created and deleted via gl* function calls. All these GL calls can get tedious and overwhelming as the scale and complexity of a GL project increases- particularly if these resources need to be safely shared between contexts. GLBuffer is an attempt to simplify that by using the lifetime of an instance of the GLBuffer class to govern the lifetime of the underlying GL resource- when the GLBuffer instance is deallocated, its underlying GL resource is returned to the GLBufferPool which created it, where it is either deleted or recycled for later use.
Notes on use:
Indicates the relationship this buffer has with its backing.
The "BackingID" is an arbitrary enum that isn't used functionally by this lib.
This enum- and GLBuffer's corresponding "backingID" member- exist to help track where an GLBuffer came from (if it was made from pixels, from another object, etc). This is purely for use by other frameworks/libs for introspection about the source of the GLBuffer- some values used by this lib are listed below, you should feel free to define your own IDs where you use VVGL to create GLBuffers that wrap CPU or GPU resources vended by another API.
| Enumerator | |
|---|---|
| BackingID_None | No backing ID or unknown backing ID. |
| BackingID_GWorld | The CPU backing is a GWorld, and must be freed appropriately. |
| BackingID_Pixels | The CPU backing was allocated by this library, and will be freed when the buffer's resources are no longer needed. |
| BackingID_CVPixBuf | The CPU backing was a CVPixelBufferRef allocated by CoreVideo- this GLBuffer maintains a strong reference to the CVPixelBuffer. |
| BackingID_CVTex | The GPU backing was a CVOpenGLTextureRef allocated by CoreVideo- this GLBuffer maintains a strong reference to the texture ref. |
| BackingID_NSBitImgRep | The CPU backing was an NSBitmapImageRep, which will be freed when the buffer's resources are no longer needed. |
| BackingID_RemoteIOSrf | The GLBuffer was created from an IOSurface (Mac SDK only) that was generated by another process. |
| BackingID_GenericExternalCPU | The GLBuffer was created from an external, CPU-based source. |
| BackingID_QImage | The CPU backing was a QImage, which will be deleted when the buffer's resources are no longer needed. |
| BackingID_QVideoFrame | The CPU backing was a QVideoFrame, which will be deleted when the buffer's resources are no longer needed. |
| enum VVGL::GLBuffer::Type |
|
related |
GLBufferCopy returns a GLBufferRef for a new GLBuffer instance. This new instance of GLBuffer actually shares the same CPU/GPU resources as the passed buffer.
One of the uses of this function is for texture atlases- with this function you can create GLBuffers that refer to a sub-region of a larger GLBuffer/texture, which is explicitly retained.
|
related |
Very common- GLBufferRef is a shared pointer around a GLBuffer.
This is the preferred means of working with GLBuffer- copying an instance of the GLBuffer class is potentially dangerous, as the underlying GL resource will not be duplicated. Working with a shared_ptr ensures that the underlying class instances will be retained as long as it's in use (and when the class instance is deleted, its corresponding GL resource will either be deleted or pooled).
1.8.14