VVISF & VVGL
Sample Code II- GLBuffer & GLBufferPool

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:

Because GLBuffers are generally treated as content-immutable, many of its more useful values are available by directly accessing the instance variables.

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:

// first create a shared context using one of the above methods (this is just a quick example)
// make the global buffer pool- this line creates the global buffer pool
// using the shared context (the buffer pool will use the shared context's
// OpenGL context to create or destroy any GL resources).
CreateGlobalBufferPool(sharedContext);
// make the global buffer pool- this is the same function call, but it
// creates a new context (a new OpenGL context) for the buffer pool.
CreateGlobalBufferPool(sharedContext->newContextSharingMe());
// makes a 1920x1080 GL texture (32 bits per pixel). the texture
// will be created by the global buffer pool's GL context
GLBufferRef tmpTex = CreateRGBATex(VVGL::Size(1920,1080));
// makes a 1920x1080 GL texture (32 bits per pixel). the texture
// will be created by whatever GL context is current in the executing thread.
// If no GL context is current, this won't work!
GLBufferRef tmpTex = CreateRGBATex(VVGL::Size(1920,1080), true);
// makes a 1920x1080 GL texture (128 bits per pixel).
// makes a CPU-based buffer- this GLBuffer doesn't have any GL resources,
// it's entirely RAM-based. the memory that contains the image data is
// allocated by this lib.
GLBufferRef tmpCPUImg = CreateRGBACPUBuffer(VVGL::Size(1920,1080));
// makes a CPU-based buffer- this GLBuffer doesn't have any GL resources
// either, but the memory that contains the image data has been allocated
// by another library and will be freed when the GLBuffer is deleted and its
// backing release callback (the block below) is executed.
VVGL::Size cpuImageSize(1920,1080);
VVGL::Size cpuBackingSize(1924,1080); // compensates for padding
void *cpuBitmapData = XXX;
AnotherAPIsImageObject *someImageRef = XXX;
cpuImageSize, // image size
cpuBitmapData, // bitmap data
cpuBackingSize, // bitmap size
someImageRef, // release callback context
[](GLBuffer & inBuffer, void * inReleaseCallbackContext) {
AnotherAPIsImageObject *tmpObj = (AnotherAPIsImageObject *)inReleaseCallbackContext;
// ...free 'tmpObj' here...
}
);