GLBuffer
VVGL::GLBuffer represents a buffer of some kind- it could be a buffer on the GPU (VRAM), or it could be a buffer on the CPU (RAM). Most of the time- almost all the time- a GLBuffer will represent an image.
The preferred interface for working with GLBuffer instances is GLBufferRef, which wraps a GLBuffer up in a std::shared_ptr<GLBuffer>. GLBuffer instances should be freed as soon as they are no longer in use- freeing a GLBuffer will, if appropriate, automatically return its resources to the buffer pool that created it.
Generally speaking, you probably won't be modifying GLBuffer instances- a very common workflow is "create a buffer, render into it, display the texture or use the texture as an input for rendering something else, delete the buffer". This isn't a "rule"- there's nothing explicitly preventing you from modifying a GLBuffer instance- it's just not a pattern employed by these libs or anything I've written with them. Destroying a buffer just returns it to the pool where it's available for re-use, so this workflow doesn't generally result in lots of textures being created/destroyed.
There are several different kinds of GLBuffers- here are the more common ones you'll encounter:
- Texture-type GLBuffers are probably the most common type you'll work with- they store an image in a GL texture.
- CPU-type GLBuffers store data in RAM- they do not have any associated GPU resources. These libs focus on GPU-related resources, but CPU-based images are still encountered when uploading data to textures (loading images, playing back video) or downloading data from textures (saving images or video). CPU-type GLBuffers can be created with memory allocated by this lib- or from blocks of memory that were allocated by something else (you can provide a release callback so the GLBuffer can retain objects from other classes for the duration of its lifetime).
- PBO-type GLBuffers store data in OpenGL pixel buffer objects (PBOs). PBOs are a simple, cross-platform way of efficiently uploading data to and downloading data from the texture, and you may receive these if you're using GLTexToCPUCopier to download texture data to system memory and haven't explicitly provided a CPU-type GLBuffer to copy into. The image-related properties of the PBO-type GLBuffer are populated with the values of the texture-type GLBuffer.
- VBO-type GLBuffers store data in OpenGL vertex buffer objects (VBOs). Typically these are used to provide geometry data to OpenGL- because of this, it generally doesn't make sense to treat these as if they were images.
Because GLBuffers are generally treated as content-immutable, many of its more useful values are available by directly accessing the instance variables.
- 'desc' is a VVGL::GLBuffer::Descriptor that describes the basic hardware properties of the GPU or CPU resources associated with a GLBuffer instance. This contains things like the internal format, pixel format, pixel type, backing type, target, etc.
- 'name' is the name of the GL resource
- 'size' is a VVGL::Size struct describing the size of the GPU/CPU resource. Note that the image represented by the GLBuffer may not occupy the full size of the GPU/CPU resource.
- 'srcRect' is a VVGL::Rect that describes the region of the GPU/CPU resource that contains the image represented by this GLBuffer.
- 'flipped' is a bool that describes whether or not the content in 'srcRect' is flipped vertically. Many SDKs vend image data that is "upside down", and by tracking this on a resource-by-resource basis it can be compensated for naturally without having to perform any unnecessary copies.
- 'contentTimestamp' is a VVGL::Timestamp struct that describes a time using the common 64-bit/32-bit value pair found in many SDKs. VVGL::GLBufferPool automatically timestamps any buffers it creates, or you can use this struct to provide your own timestamps from another API.
- 'pboMapped' is a bool that describes whether or not the PBO has been mapped into system memory. This is only valid for PBO-type GLBuffers, but if it's true the PBO's data can be accessed at the GLBuffer's 'cpuBackingPtr'.
- 'cpuBackingPtr' is a pointer to any resources associated with the GLBuffer in system memory. If the receiver is a CPU-type GLBuffer, or a PBO-type GLBuffer that is mapped, its data can be accessed for both reading and writing at this pointer.
GLBufferPool
GLBufferPool is the class responsible for creating, pool, and destroying GL assets like textures, PBOs, etc. This lib defines a global singleton that you should populate during setup by passing it a GLContext that it can use to create/destroy resources.
There are a variety of buffer creation functions listed in (VVGL- GLBuffer create functions)
Creating the global buffer pool, then a couple GL resources:
void *cpuBitmapData = XXX;
AnotherAPIsImageObject *someImageRef = XXX;
cpuImageSize,
cpuBitmapData,
cpuBackingSize,
someImageRef,
[](GLBuffer & inBuffer, void * inReleaseCallbackContext) {
AnotherAPIsImageObject *tmpObj = (AnotherAPIsImageObject *)inReleaseCallbackContext;
}
);