VVBufferPool framework

Data Structures
class	CIGLScene
	Subclass of GLScene for working with CoreImage resources. As written, the API renders CIImages to VVBuffers (typically textures of some sort), since this seems to be the easiest way to work with CI resources. Can be easily modified to render directly in a view. More...
class	GLScene
	Wrapper around a GL context with the intent of standardizing the more common render-to-texture operations while also making it easier to write customizable rendering code that doesn't necessarily require a different subclass for every purpose. Most of the rendering classes I write either use an instance of GLScene to do their rendering or descend directly from it (GLScene's nature- a discrete GL context with built-in render-to-texture- makes it a good choice of superclass when adding support for other hardware-accelerated APIs). More...
class	GLShaderScene
	Subclass of GLScene for working with vertex & frag shaders- just give it some shader strings and watch it go! More...
class	QCGLScene
	Subclass of GLScene for working with QC compositions. More...
struct	_VVBufferDescriptor
	This C struct describes the basic characteristics of a VVBuffer's internal GL properties. More...
class	VVBuffer
	VVBuffer represents a buffer- almost always in VRAM as a GL texture or renderbuffer- created and managed by VVBufferPool. Conceptually, it's safe to think of VVBuffers as "images" or "frames", as that is typically what they're used for. You should never alloc/init a VVBuffer- if you want a buffer, you need to get one by asking a VVBufferPool to create one for you. More...
class	VVBufferAggregate
	Convenience class i've been using lately to pass around groups of VVBuffers. this is a relatively new class, we'll see how it goes... More...
class	VVBufferCopier
	subclass of GLScene, used to copy the contents of VVBuffer instances by rendering them into a texture. More...
class	VVBufferGLView
	subclass of NSOpenGLView, fastest and easiest way to display a VVBuffer. automatically sizes the buffer proportionally to fit. More...
class	VVBufferPool
	Creates VVBuffers. Should be the only way you create VVBuffers- most projects will only have a single instance of VVBufferPool, which shares an OpenGL context with other parts of your program so GL resources (specifically textures) may be shared. More...
class	VVQCComposition
	Load a Quartz Composer composition and parse it as a text file (QC comps are basically big plists) to retrieve data about the composition without invoking the Quartz Composer runtime, which can be slow. More...
class	VVSizingTool
	Simplifies the act of generating transforms and other geometry-related data around the relatively common act of resizing one rect to fit inside another. More...

Typedefs
typedef enum _VVBufferType	VVBufferType
	These are the different kinds of VVBuffers.
typedef enum _VVBufferIntFormat	VVBufferIntFormat
	This desribes the internal format of the GL resource represented by a VVBuffer.
typedef enum _VVBufferPixFormat	VVBufferPixFormat
	This describes the pixel format of the GL resource represented by a VVBuffer.
typedef enum _VVBufferPixType	VVBufferPixType
	This describes the pixel type of the GL resource represented by a VVBuffer.
typedef enum _VVBufferCPUBack	VVBufferCPUBack
	The origin of any CPU-based content.
typedef enum _VVBufferGPUBack	VVBufferGPUBack
	The origin of any GPU-based content.
typedef enum _VVBufferBackID	VVBufferBackID
	The "VVBufferBackID" is an arbitrary enum that isn't used functionally by this framework. This enum- and VVBuffer's corresponding "backingID" member- exist to help track where a VVBuffer came from (if it was made from pixels, from another object, etc). More...
typedef struct _VVBufferDescriptor	VVBufferDescriptor
	This C struct describes the basic characteristics of a VVBuffer's internal GL properties.
typedef void(*	VVBufferBackingReleaseCallback )(id VVBufferBeingFreed, void *callbackContext)
	This is a function pointer- it gets called when the VVBuffer that owns it is being deallocated and needs to deallocate any resources associated with it. If you want to extend the VVBufferPool framework to wrap other APIs, you'll want to write your own callback function similar to this and use it to free the buffer's callback context. More...

Enumerations
enum	_VVBufferType { VVBufferType_None = 0, VVBufferType_RB, VVBufferType_FBO, VVBufferType_Tex }
	These are the different kinds of VVBuffers. More...
enum	_VVBufferIntFormat {   VVBufferIF_None = 0, VVBufferIF_Lum8 = GL_LUMINANCE8, VVBufferIF_LumFloat = GL_LUMINANCE32F_ARB, VVBufferIF_R = GL_RED,   VVBufferIF_RGB = GL_RGB, VVBufferIF_RGBA = GL_RGBA, VVBufferIF_RGBA8 = GL_RGBA8, VVBufferIF_Depth24 = GL_DEPTH_COMPONENT24,   VVBufferIF_RGBA32F = GL_RGBA32F_ARB, VVBufferIF_RGB_DXT1 = GL_COMPRESSED_RGB_S3TC_DXT1_EXT, VVBufferIF_RGBA_DXT5 = GL_COMPRESSED_RGBA_S3TC_DXT5_EXT, VVBufferIF_YCoCg_DXT5 = GL_COMPRESSED_RGBA_S3TC_DXT5_EXT }
	This desribes the internal format of the GL resource represented by a VVBuffer. More...
enum	_VVBufferPixFormat {   VVBufferPF_None = 0, VVBufferPF_Depth = GL_DEPTH_COMPONENT, VVBufferPF_Lum = GL_LUMINANCE, VVBufferPF_R = GL_RED,   VVBufferPF_RGBA = GL_RGBA, VVBufferPF_BGRA = GL_BGRA, VVBufferPF_YCBCR_422 = GL_YCBCR_422_APPLE }
	This describes the pixel format of the GL resource represented by a VVBuffer. More...
enum	_VVBufferPixType {   VVBufferPT_None = 0, VVBufferPT_Float = GL_FLOAT, VVBufferPT_U_Byte = GL_UNSIGNED_BYTE, VVBufferPT_U_Int_8888_Rev = GL_UNSIGNED_INT_8_8_8_8_REV,   VVBufferPT_U_Short_88 = GL_UNSIGNED_SHORT_8_8_APPLE }
	This describes the pixel type of the GL resource represented by a VVBuffer. More...
enum	_VVBufferCPUBack { VVBufferCPUBack_None = 0, VVBufferCPUBack_Internal, VVBufferCPUBack_External }
	The origin of any CPU-based content. More...
enum	_VVBufferGPUBack { VVBufferGPUBack_None = 0, VVBufferGPUBack_Internal, VVBufferGPUBack_External }
	The origin of any GPU-based content. More...
enum	_VVBufferBackID {   VVBufferBackID_None = 0 , VVBufferBackID_Pixels, VVBufferBackID_CVPixBuf, VVBufferBackID_CVTex,   VVBufferBackID_NSBitImgRep, VVBufferBackID_RemoteIOSrf, VVBufferBackID_External }
	The "VVBufferBackID" is an arbitrary enum that isn't used functionally by this framework. This enum- and VVBuffer's corresponding "backingID" member- exist to help track where a VVBuffer came from (if it was made from pixels, from another object, etc). More...
enum	VVSizingMode { VVSizingModeFit = 0, VVSizingModeFill = 1, VVSizingModeStretch = 2, VVSizingModeCopy = 3 }
	Different sizing modes. More...

Functions
void	VVBufferDescriptorPopulateDefault (VVBufferDescriptor *d)
	Populates the passed VVBufferDescriptor pointer with default values.
void	VVBufferDescriptorCopy (VVBufferDescriptor *src, VVBufferDescriptor *dst)
	Copies the contents of the src to dst.
BOOL	VVBufferDescriptorCompare (VVBufferDescriptor *a, VVBufferDescriptor *b)
	Compares the passed buffers, returns a YES if they are completely identical.
BOOL	VVBufferDescriptorCompareForRecycling (VVBufferDescriptor *a, VVBufferDescriptor *b)
	Compares the passed buffers for the purpose of recycling, returns a YES if they are close enough of a match to be used interchangeably.
unsigned long	VVBufferDescriptorCalculateCPUBackingForSize (VVBufferDescriptor *b, NSSize s)
	Calculates the size (in bytes) that would be required to create a CPU-based backing for a buffer of the passed dimensions matching the passed buffer descriptor.

Detailed Description

Typedef Documentation

typedef enum _VVBufferBackID VVBufferBackID

The "VVBufferBackID" is an arbitrary enum that isn't used functionally by this framework. This enum- and VVBuffer's corresponding "backingID" member- exist to help track where a VVBuffer came from (if it was made from pixels, from another object, etc).

If you want to extend VVBuffer/VVBufferPool to be compatible with other graphics APIs, you can just #define new constants/numbers (start at 100 or something so there aren't any conflicts) and use them to track the additional image types you're working with. The only time this is really used is to determine if the backing is appropriate when calling accessor methods (take a look at the source for -[VVBuffer cvTexRef] for an example).

typedef void(* VVBufferBackingReleaseCallback)(id VVBufferBeingFreed, void *callbackContext)

This is a function pointer- it gets called when the VVBuffer that owns it is being deallocated and needs to deallocate any resources associated with it. If you want to extend the VVBufferPool framework to wrap other APIs, you'll want to write your own callback function similar to this and use it to free the buffer's callback context.

Parameters

VVBufferBeingFreed	This is the instance of VVBuffer which is being freed (this is the buffer that "owns" the callback/callback context)
callbackContext	This is the callback context from VVBufferBeingFreed- this is what you need to free.

Enumeration Type Documentation

enum _VVBufferBackID

The "VVBufferBackID" is an arbitrary enum that isn't used functionally by this framework. This enum- and VVBuffer's corresponding "backingID" member- exist to help track where a VVBuffer came from (if it was made from pixels, from another object, etc).

If you want to extend VVBuffer/VVBufferPool to be compatible with other graphics APIs, you can just #define new constants/numbers (start at 100 or something so there aren't any conflicts) and use them to track the additional image types you're working with. The only time this is really used is to determine if the backing is appropriate when calling accessor methods (take a look at the source for -[VVBuffer cvTexRef] for an example).

Enumerator
VVBufferBackID_None	the buffer was wholly created by this framework- there's no backing
VVBufferBackID_Pixels	the buffer was created from a pointer to pixels which were also allocated by this framework
VVBufferBackID_CVPixBuf	the buffer was created from a CVPixelBufferRef
VVBufferBackID_CVTex	the buffer was created from a CVOpenGLTextureRef
VVBufferBackID_NSBitImgRep	the buffer was created from an NSBitmapImageRep
VVBufferBackID_RemoteIOSrf	the buffer was created from an remote IOSurfaceRef (the IOSurface was generated in another process)
VVBufferBackID_External	the buffer was created from some kind of external pointer passed in from another API (this can be used to work with other APIs without actually extending VVBuffer/VVBufferPool)

enum _VVBufferCPUBack

The origin of any CPU-based content.

Enumerator
VVBufferCPUBack_None	there is no CPU-based backing
VVBufferCPUBack_Internal	buffer backing is CPU-based, and the CPU resource was created by this framework
VVBufferCPUBack_External	buffer backing is CPU-based, and the CPU resource was created outside this framework

enum _VVBufferGPUBack

The origin of any GPU-based content.

Enumerator
VVBufferGPUBack_None	there is no GPU-based resource
VVBufferGPUBack_Internal	the GPU-based resource was created by this framework (and should be deleted by this framework)
VVBufferGPUBack_External	the GPU-based resource was created outside of this framework, and this buffer should be freed immediately when done

enum _VVBufferIntFormat

This desribes the internal format of the GL resource represented by a VVBuffer.

Enumerator
VVBufferIF_None	none/unknown/unused
VVBufferIF_Lum8	single channel, 8 bit per pixel
VVBufferIF_LumFloat	single channel, 32 bit float per pixel
VVBufferIF_R	single channel, 8 bit per pixel
VVBufferIF_RGB	three channel, 8 bit per channel
VVBufferIF_RGBA	four channel, 8 bit per channel
VVBufferIF_RGBA8	four channel, 8 bit per channel. fast on os x, probably most common)
VVBufferIF_Depth24	depth- single channel, 24 bit per pixel
VVBufferIF_RGBA32F	four channel, 32 bit per channel
VVBufferIF_RGB_DXT1	Hap.
VVBufferIF_RGBA_DXT5	Hap Alpha.
VVBufferIF_YCoCg_DXT5	HapQ. not a typo, same as RGBA_DXT5!

enum _VVBufferPixFormat

This describes the pixel format of the GL resource represented by a VVBuffer.

Enumerator
VVBufferPF_None	non/unknown/unused
VVBufferPF_Depth	depth
VVBufferPF_Lum	luminance
VVBufferPF_R	red (same idea as luminance, just seems to be slightly more compatible with stuff)
VVBufferPF_RGBA	RGBA.
VVBufferPF_BGRA	BGRA. faston os x, (probably most common)
VVBufferPF_YCBCR_422	packed YCbCr

enum _VVBufferPixType

This describes the pixel type of the GL resource represented by a VVBuffer.

Enumerator
VVBufferPT_None	none/unknown/unused
VVBufferPT_Float	float- used for rendering high-precision stuff
VVBufferPT_U_Byte	usually used for depth buffer/luminance/single-channel stuff
VVBufferPT_U_Int_8888_Rev	standard four channel/8 bits per channel/unsigned byte format. fast on os x, (probably most common)
VVBufferPT_U_Short_88	two channel/8 bits per channel/unsigned byte format. usually used for YCbCr textures.

enum _VVBufferType

These are the different kinds of VVBuffers.

Enumerator
VVBufferType_None	none/unknown/unused
VVBufferType_RB	renderbuffer
VVBufferType_FBO	FBO.
VVBufferType_Tex	texture (probably most common)

enum VVSizingMode

Different sizing modes.

Enumerator
VVSizingModeFit	the content is made as large as possible, proportionally, without cutting itself off or going outside the bounds of the desired area
VVSizingModeFill	the content is made as large as possible, proportionally, to fill the desired area- some of the content may get cut off
VVSizingModeStretch	the content is scaled to fit perfectly within the desired area- some stretching or squashing may occur, this isn't necessarily proportional
VVSizingModeCopy	the content is copied directly to the desired area- it is not made any larger or smaller