Vuo  2.3.2
Classes | Macros | Typedefs | Enumerations | Functions
VuoGlPool.h File Reference

Description

VuoGlPool interface.

Definition in file VuoGlPool.h.

Go to the source code of this file.

Classes

struct  VuoGlProgram
 Information about a pooled GL Program Object. More...
 

Macros

#define VuoGlPool_retain(glBufferName)   VuoGlPool_retainF(glBufferName, __FILE__, __LINE__, __func__);
 Increments the reference count for glBufferName. More...
 
#define VuoGlPool_release(type, size, glBufferName)   VuoGlPool_releaseF(type, size, glBufferName, __FILE__, __LINE__, __func__);
 Decrements the reference count for glBufferName. More...
 

Typedefs

typedef void * VuoIoSurface
 A container for a Mac OS X IOSurface. More...
 

Enumerations

enum  VuoGlPoolType { VuoGlPool_ArrayBuffer , VuoGlPool_ElementArrayBuffer }
 Types of OpenGL objects supported by Vuo's GL object pool. More...
 
enum  VuoGlTexturePoolAllocation { VuoGlTexturePool_NoAllocation , VuoGlTexturePool_Allocate , VuoGlTexturePool_AllocateIOSurface }
 Types of OpenGL texture allocations. More...
 

Functions

GLuint VuoGlPool_use (VuoGlContext glContext, VuoGlPoolType type, unsigned long size)
 Returns an OpenGL Buffer Object of type type. More...
 
void VuoGlPool_retainF (GLuint glBufferName, const char *file, unsigned int linenumber, const char *func)
 Helper for VuoGlPool_retain. More...
 
void VuoGlPool_releaseF (VuoGlPoolType type, unsigned long size, GLuint glBufferName, const char *file, unsigned int linenumber, const char *func)
 Helper for VuoGlPool_release. More...
 
GLuint VuoGlTexturePool_use (VuoGlContext glContext, VuoGlTexturePoolAllocation allocation, GLenum target, GLenum internalformat, unsigned short width, unsigned short height, GLenum format, void *ioSurfaceRef)
 Returns an OpenGL texture. More...
 
void VuoGlTexturePool_disuse (VuoGlTexturePoolAllocation allocation, GLenum target, GLenum internalformat, unsigned short width, unsigned short height, GLuint name)
 Indicates that the caller is done using the OpenGL texture name. More...
 
GLuint VuoGlTexture_getType (GLuint format)
 Returns the OpenGL texture data type corresponding with OpenGL texture format. More...
 
unsigned char VuoGlTexture_getChannelCount (GLuint format)
 Returns the number of color+alpha channels in the specified OpenGL texture format. More...
 
unsigned char VuoGlTexture_getBytesPerPixel (GLuint internalformat, GLuint format)
 Returns the number of bytes required to store each pixel of the specified OpenGL texture format. More...
 
unsigned char VuoGlTexture_getBytesPerPixelForInternalFormat (GLuint internalformat)
 Returns the number of bytes required to store each pixel of the specified OpenGL texture format. More...
 
bool VuoGlTexture_formatHasAlphaChannel (GLuint format)
 Returns true if the specified OpenGL texture format has an alpha channel. More...
 
unsigned long VuoGlTexture_getMaximumTextureBytes (VuoGlContext glContext)
 Returns the maximum number of bytes in Video RAM that a texture can occupy. More...
 
void VuoGlTexture_retain (GLuint glTextureName, VuoImage_freeCallback freeCallback, void *freeCallbackContext)
 Increments the reference count for glTextureName. More...
 
void VuoGlTexture_release (VuoGlTexturePoolAllocation allocation, GLuint glTextureTarget, GLenum internalformat, unsigned short width, unsigned short height, GLuint glTextureName)
 Decrements the reference count for glTextureName. More...
 
void VuoGlTexture_disown (GLuint glTextureName)
 Removes glTextureName from Vuo's reference count table (without deleting it like VuoGlTexture_release does). More...
 
VuoIoSurface VuoIoSurfacePool_use (VuoGlContext glContext, unsigned short pixelsWide, unsigned short pixelsHigh, GLuint *outputTexture)
 Returns an IOSurface (backed by outputTexture) with the specified dimensions. More...
 
uint32_t VuoIoSurfacePool_getId (VuoIoSurface vis)
 Returns the IOSurface's interprocess ID. More...
 
void * VuoIoSurfacePool_getIOSurfaceRef (VuoIoSurface vis)
 Returns the IOSurface. More...
 
unsigned short VuoIoSurfacePool_getWidth (VuoIoSurface vis)
 Returns the IOSurface's width in pixels. More...
 
unsigned short VuoIoSurfacePool_getHeight (VuoIoSurface vis)
 Returns the IOSurface's height in pixels. More...
 
GLuint VuoIoSurfacePool_getTexture (VuoIoSurface vis)
 Returns the IOSurface's OpenGL texture name. More...
 
void VuoIoSurfacePool_disuse (VuoIoSurface vis, bool quarantine)
 Called by the sending end of an IOSurface texture transfer to indicate that it is finished using the IOSurface's texture. More...
 
void VuoIoSurfacePool_signal (void *ioSurface)
 Called by the receiving end of an IOSurface texture transfer to indicate that it is finished using the IOSurface's texture. More...
 
GLuint VuoGlShader_use (VuoGlContext glContext, GLenum type, const char *source, void *outIssues)
 Returns an OpenGL Shader Object representing the specified source, or 0 if the shader couldn't be compiled. More...
 
VuoGlProgram VuoGlProgram_use (VuoGlContext glContext, const char *description, GLuint vertexShaderName, GLuint geometryShaderName, GLuint fragmentShaderName, VuoMesh_ElementAssemblyMethod assemblyMethod, unsigned int expectedOutputPrimitiveCount, void *outIssues)
 Links shaders together into a program (or finds an existing program if one already exists for the given shaders, element assembly method, and output primitive count), and returns the GL Program Object. More...
 
int VuoGlProgram_getUniformLocation (VuoGlProgram program, const char *uniformIdentifier)
 Returns the location (suitable for use with glUniform*()) for a given uniform identifier, or -1 if the uniform isn't found. More...
 
char * VuoGl_stringForConstant (GLenum constant)
 Returns a string for the specified OpenGL constant. More...
 
void VuoGlPool_logVRAMAllocated (unsigned long bytesAllocated)
 Updates the process-wide VRAM count to include bytesAllocated. More...
 
void VuoGlPool_logVRAMFreed (unsigned long bytesFreed)
 Updates the process-wide VRAM count to no longer include bytesAllocated. More...
 

Class Documentation

◆ VuoGlProgram

struct VuoGlProgram
Class Members
GLuint programName
void * uniforms

Macro Definition Documentation

◆ VuoGlPool_release

#define VuoGlPool_release (   type,
  size,
  glBufferName 
)    VuoGlPool_releaseF(type, size, glBufferName, __FILE__, __LINE__, __func__);

Decrements the reference count for glBufferName.

This function may be called from any thread.

Changed in Vuo 2.0.0:
Removed glContext argument.

Definition at line 51 of file VuoGlPool.h.

◆ VuoGlPool_retain

#define VuoGlPool_retain (   glBufferName)    VuoGlPool_retainF(glBufferName, __FILE__, __LINE__, __func__);

Increments the reference count for glBufferName.

This function may be called from any thread.

Definition at line 42 of file VuoGlPool.h.

Typedef Documentation

◆ VuoIoSurface

typedef void* VuoIoSurface

A container for a Mac OS X IOSurface.

Definition at line 79 of file VuoGlPool.h.

Enumeration Type Documentation

◆ VuoGlPoolType

Types of OpenGL objects supported by Vuo's GL object pool.

Definition at line 26 of file VuoGlPool.h.

◆ VuoGlTexturePoolAllocation

Types of OpenGL texture allocations.

Definition at line 57 of file VuoGlPool.h.

Function Documentation

◆ VuoGl_stringForConstant()

char* VuoGl_stringForConstant ( GLenum  constant)

Returns a string for the specified OpenGL constant.

The caller is responsible for freeing the string returned by this function.

Definition at line 1618 of file VuoGlPool.cc.

◆ VuoGlPool_logVRAMAllocated()

void VuoGlPool_logVRAMAllocated ( unsigned long  bytesAllocated)

Updates the process-wide VRAM count to include bytesAllocated.

This function is automatically called by other VuoGlPool functions, so you should only call this if you're directly making OpenGL calls that allocate VRAM.

This function may be called from any thread.

Changed in Vuo 2.0.0:
New.

Definition at line 780 of file VuoGlPool.cc.

◆ VuoGlPool_logVRAMFreed()

void VuoGlPool_logVRAMFreed ( unsigned long  bytesFreed)

Updates the process-wide VRAM count to no longer include bytesAllocated.

This function is automatically called by other VuoGlPool functions, so you should only call this if you're directly making OpenGL calls that deallocate VRAM.

This function may be called from any thread.

Changed in Vuo 2.0.0:
New.

Definition at line 801 of file VuoGlPool.cc.

◆ VuoGlPool_releaseF()

void VuoGlPool_releaseF ( VuoGlPoolType  type,
unsigned long  size,
GLuint  glBufferName,
const char *  file,
unsigned int  linenumber,
const char *  func 
)

Helper for VuoGlPool_release.

Definition at line 140 of file VuoGlPool.cc.

◆ VuoGlPool_retainF()

void VuoGlPool_retainF ( GLuint  glBufferName,
const char *  file,
unsigned int  linenumber,
const char *  func 
)

Helper for VuoGlPool_retain.

Definition at line 120 of file VuoGlPool.cc.

◆ VuoGlPool_use()

GLuint VuoGlPool_use ( VuoGlContext  glContext,
VuoGlPoolType  type,
unsigned long  size 
)

Returns an OpenGL Buffer Object of type type.

If an existing, unused buffer of the specified type and size is available, it is returned. Otherwise, a new buffer is created.

The returned buffer's storage is will be preallocated (so the caller can efficiently upload data using glBufferSubData).

This function may be called from any thread. (However, the caller is responsible for ensuring that the GL context is not used simultaneously on multiple threads.)

Definition at line 54 of file VuoGlPool.cc.

◆ VuoGlProgram_getUniformLocation()

int VuoGlProgram_getUniformLocation ( VuoGlProgram  program,
const char *  uniformIdentifier 
)

Returns the location (suitable for use with glUniform*()) for a given uniform identifier, or -1 if the uniform isn't found.

Definition at line 1597 of file VuoGlPool.cc.

◆ VuoGlProgram_use()

VuoGlProgram VuoGlProgram_use ( VuoGlContext  glContext,
const char *  description,
GLuint  vertexShaderName,
GLuint  geometryShaderName,
GLuint  fragmentShaderName,
VuoMesh_ElementAssemblyMethod  assemblyMethod,
unsigned int  expectedOutputPrimitiveCount,
void *  outIssues 
)

Links shaders together into a program (or finds an existing program if one already exists for the given shaders, element assembly method, and output primitive count), and returns the GL Program Object.

vertexShaderName must be nonzero, but it's OK for geometryShaderName and/or fragmentShaderName to be 0 (same rules as VuoShader_addSource).

description is used just to print errors/warnings; it is not used for cache matching.

Do not call glDeleteShaders() on the returned program; it's expected to persist throughout the lifetime of the process.

If outIssues is non-NULL, it is expected to be a VuoShaderIssues instance, and compilation warnings/errors will be added to it. In this case, the cache is not used.

Changed in Vuo 2.0.0:
Added outIssues argument.

Definition at line 1435 of file VuoGlPool.cc.

◆ VuoGlShader_use()

GLuint VuoGlShader_use ( VuoGlContext  glContext,
GLenum  type,
const char *  source,
void *  outIssues 
)

Returns an OpenGL Shader Object representing the specified source, or 0 if the shader couldn't be compiled.

To improve performance, this function keeps a cache of precompiled shaders. If a precompiled shader exists for the specified source, that shader is returned. Otherwise, source is passed off to OpenGL to be compiled.

Do not call glDeleteShaders() on the returned shader; it's expected to persist throughout the lifetime of the process.

If outIssues is non-NULL, it is expected to be a VuoShaderIssues instance, and compilation warnings/errors will be added to it. In this case, the cache is not used.

Changed in Vuo 2.0.0:
Added outIssues argument.

Definition at line 1349 of file VuoGlPool.cc.

◆ VuoGlTexture_disown()

void VuoGlTexture_disown ( GLuint  glTextureName)

Removes glTextureName from Vuo's reference count table (without deleting it like VuoGlTexture_release does).

glTextureName must have a reference count of exactly 1 (i.e., a texture being used in multiple places throughout Vuo cannot be disowned).

After Vuo disowns the texture, the caller is responsible for eventually deleting it.

This function may be called from any thread.

Definition at line 721 of file VuoGlPool.cc.

◆ VuoGlTexture_formatHasAlphaChannel()

bool VuoGlTexture_formatHasAlphaChannel ( GLuint  format)

Returns true if the specified OpenGL texture format has an alpha channel.

Changed in Vuo 2.0.0:
New.

Definition at line 361 of file VuoGlPool.cc.

◆ VuoGlTexture_getBytesPerPixel()

unsigned char VuoGlTexture_getBytesPerPixel ( GLuint  internalformat,
GLuint  format 
)

Returns the number of bytes required to store each pixel of the specified OpenGL texture format.

Definition at line 282 of file VuoGlPool.cc.

◆ VuoGlTexture_getBytesPerPixelForInternalFormat()

unsigned char VuoGlTexture_getBytesPerPixelForInternalFormat ( GLuint  internalformat)

Returns the number of bytes required to store each pixel of the specified OpenGL texture format.

Changed in Vuo 2.0.0:
New.

Definition at line 318 of file VuoGlPool.cc.

◆ VuoGlTexture_getChannelCount()

unsigned char VuoGlTexture_getChannelCount ( GLuint  format)

Returns the number of color+alpha channels in the specified OpenGL texture format.

Definition at line 247 of file VuoGlPool.cc.

◆ VuoGlTexture_getMaximumTextureBytes()

unsigned long VuoGlTexture_getMaximumTextureBytes ( VuoGlContext  glContext)

Returns the maximum number of bytes in Video RAM that a texture can occupy.

Definition at line 381 of file VuoGlPool.cc.

◆ VuoGlTexture_getType()

GLuint VuoGlTexture_getType ( GLuint  format)

Returns the OpenGL texture data type corresponding with OpenGL texture format.

Definition at line 219 of file VuoGlPool.cc.

◆ VuoGlTexture_release()

void VuoGlTexture_release ( VuoGlTexturePoolAllocation  allocation,
GLuint  glTextureTarget,
GLenum  internalformat,
unsigned short  width,
unsigned short  height,
GLuint  glTextureName 
)

Decrements the reference count for glTextureName.

This function may be called from any thread.

Changed in Vuo 2.0.0:
Added allocation argument; reordered glTextureTarget argument.

Definition at line 676 of file VuoGlPool.cc.

◆ VuoGlTexture_retain()

void VuoGlTexture_retain ( GLuint  glTextureName,
VuoImage_freeCallback  freeCallback,
void *  freeCallbackContext 
)

Increments the reference count for glTextureName.

This function may be called from any thread.

Definition at line 653 of file VuoGlPool.cc.

◆ VuoGlTexturePool_disuse()

void VuoGlTexturePool_disuse ( VuoGlTexturePoolAllocation  allocation,
GLenum  target,
GLenum  internalformat,
unsigned short  width,
unsigned short  height,
GLuint  name 
)

Indicates that the caller is done using the OpenGL texture name.

The texture is returned to the pool, so other callers can use it (which is more efficient than deleting and re-generating textures).

Typically you should use VuoGlTexture_retain and VuoGlTexture_retain instead.

This function may be called from any thread.

Definition at line 589 of file VuoGlPool.cc.

◆ VuoGlTexturePool_use()

GLuint VuoGlTexturePool_use ( VuoGlContext  glContext,
VuoGlTexturePoolAllocation  allocation,
GLenum  target,
GLenum  internalformat,
unsigned short  width,
unsigned short  height,
GLenum  format,
void *  ioSurfaceRef 
)

Returns an OpenGL texture.

If an existing, unused texture matching the specified target, internalformat, width, and height is available, it is returned. Otherwise, a new texture is created.

The texturing properties are set to the defaults:

  • wrapping: clamp to border
  • filtering: linear

See glTexImage2D for information about internalformat and format.

If allocation is VuoGlTexturePool_Allocate, the returned texture's storage is preallocated (so the caller can efficiently upload data using glTexSubImage2D). If VuoGlTexturePool_AllocateIOSurface, the returned texture is backed by the specified ioSurfaceRef. In any case, this function calls VuoGlPool_logVRAMAllocated, so you doesn't need to.

ioSurfaceRef should be NULL unless allocation is VuoGlTexturePool_AllocateIOSurface.

Returns 0 if the texture would be too large to fit in Video RAM.

This function may be called from any thread. (However, the caller is responsible for ensuring that the GL context is not used simultaneously on multiple threads.)

Changed in Vuo 2.0.0:
Added allocation, target, ioSurfaceRef arguments.

Definition at line 479 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_disuse()

void VuoIoSurfacePool_disuse ( VuoIoSurface  vis,
bool  quarantine 
)

Called by the sending end of an IOSurface texture transfer to indicate that it is finished using the IOSurface's texture.

This enables the IOSurface to be reused for another texture transfer (once the receiving end indicates it is done with it, via VuoIoSurfacePool_signal()).

quarantine should typically be true — this indicates that the IOSurface should be placed in the quarantine, meaning that it will not be reused until the receiver signals it. If you're sure both sides are immediately finished using the IOSurface (e.g., during texture transfer within a process), you can set quarantine to false, which will allow reusing it sooner (saving some VRAM). You still need to call VuoIoSurfacePool_signal though (since the IOSurface might be recycled and later require quarantine).

Changed in Vuo 2.0.0:
Added quarantine argument.

Definition at line 1122 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_getHeight()

unsigned short VuoIoSurfacePool_getHeight ( VuoIoSurface  vis)

Returns the IOSurface's height in pixels.

Definition at line 1095 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_getId()

uint32_t VuoIoSurfacePool_getId ( VuoIoSurface  vis)

Returns the IOSurface's interprocess ID.

Definition at line 1068 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_getIOSurfaceRef()

void* VuoIoSurfacePool_getIOSurfaceRef ( VuoIoSurface  vis)

Returns the IOSurface.

Definition at line 1077 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_getTexture()

GLuint VuoIoSurfacePool_getTexture ( VuoIoSurface  vis)

Returns the IOSurface's OpenGL texture name.

Definition at line 1104 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_getWidth()

unsigned short VuoIoSurfacePool_getWidth ( VuoIoSurface  vis)

Returns the IOSurface's width in pixels.

Definition at line 1086 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_signal()

void VuoIoSurfacePool_signal ( void *  ios)

Called by the receiving end of an IOSurface texture transfer to indicate that it is finished using the IOSurface's texture.

This enables the sender to reuse the IOSurface for another texture transfer.

Definition at line 1145 of file VuoGlPool.cc.

◆ VuoIoSurfacePool_use()

VuoIoSurface VuoIoSurfacePool_use ( VuoGlContext  glContext,
unsigned short  pixelsWide,
unsigned short  pixelsHigh,
GLuint *  outputTexture 
)

Returns an IOSurface (backed by outputTexture) with the specified dimensions.

Uses an IOSurface from the pool, if possible. If not, creates a new IOSurface.

Definition at line 997 of file VuoGlPool.cc.