CVOpenGLESTextureCache Reference

Framework
System/Library/Frameworks/CoreVideo.framework
Declared in
CVOpenGLESTextureCache.h

Overview

Core Video OpenGLES texture caches are used to cache and manage CVOpenGLESTextureRef textures. These texture caches provide you with a way to directly read and write buffers with various pixel formats, such as 420v or BGRA, from GLES.

Functions

The functions in this section operate on Core Video texture caches derived from the CVOpenGLESTextureCacheRef type.

CVOpenGLESTextureCacheCreate

Creates a new Core Video texture cache.

CVReturn CVOpenGLESTextureCacheCreate(
CFAllocatorRef allocator,
CFDictionaryRef cacheAttributes,
CVEAGLContext eaglContext,
CFDictionaryRef textureAttributes,
CVOpenGLESTextureCacheRef *cacheOut
);
Parameters
allocator

The CFAllocatorRef to use for allocating the texture cache. This parameter can be NULL.

cacheAttributes

A CFDictionaryRef containing the attributes of the texture cache itself. This parameter can be NULL.

eaglContext

The OpenGLES 2.0 context into which the texture objects will be created. OpenGLES 1.x contexts are not supported.

textureAttributes

A CFDictionaryRef containing the attributes to be used for creating the CVOpenGLESTextureRef objects. This parameter can be NULL.

cacheOut

A pointer to a CVOpenGLESTextureCacheRef where the newly created texture cache will be placed.

Return Value

Upon successful creation of the texture cache, this function returns kCVReturnSuccess.

Availability
  • Available in iOS 5.0 and later.
Declared In
CVOpenGLESTextureCache.h

CVOpenGLESTextureCacheCreateTextureFromImage

Creates a CVOpenGLESTextureRef object from an existing CVImageBufferRef.

CVReturn CVOpenGLESTextureCacheCreateTextureFromImage(
CFAllocatorRef allocator,
CVOpenGLESTextureCacheRef textureCache,
CVImageBufferRef sourceImage,
CFDictionaryRef textureAttributes,
GLenum target,
GLint internalFormat,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
size_t planeIndex,
CVOpenGLESTextureRef *textureOut
);
Parameters
allocator

The CFAllocatorRef to use for allocating the texture object. This parameter can be NULL.

textureCache

The texture cache object that will manage the texture.

sourceImage

The CVImageBufferRef that you want to create a texture from.

textureAttributes

A CFDictionaryRef containing the attributes to be used for creating the CVOpenGLESTextureRef objects. This parameter can be NULL.

target

The target texture. GL_TEXTURE_2D and GL_RENDERBUFFER are the only targets currently supported.

internalFormat

The number of color components in the texture. Examples are GL_RGBA, GL_LUMINANCE, GL_RGBA8_OES, GL_RED, and GL_RG.

width

The width of the texture image.

height

The height of the texture image.

format

The format of the pixel data. Examples are GL_RGBA and GL_LUMINANCE.

type

The data type of the pixel data. One example is GL_UNSIGNED_BYTE.

planeIndex

The plane of the CVImageBufferRef to map bind. Ignored for non-planar CVImageBufferRefs.

textureOut

A pointer to a CVOpenGLESTextureRef where the newly created texture object will be placed.

Return Value

Upon successful creation of the texture, this function returns kCVReturnSuccess.

Discussion

This function either creates a new or returns a cached CVOpenGLESTextureRef texture object mapped to the CVImageBufferRef and associated parameters. This operation creates a live binding between the image buffer and the underlying texture object. The EAGLContext associated with the cache may be modified to create, delete, or bind textures. When used as a source texture or GL_COLOR_ATTACHMENT, the image buffer must be unlocked before rendering. The source or render buffer texture should not be re-used until the rendering has completed. This can be guaranteed by calling glFlush().

Some example mappings can be seen in the following code snippet.

//Mapping a BGRA buffer as a source texture:
CVOpenGLESTextureCacheCreateTextureFromImage(kCFAllocatorDefault, textureCache, pixelBuffer, NULL, GL_TEXTURE_2D, GL_RGBA, width, height, GL_RGBA, GL_UNSIGNED_BYTE, 0, &outTexture);
//Mapping a BGRA buffer as a renderbuffer:
CVOpenGLESTextureCacheCreateTextureFromImage(kCFAllocatorDefault, textureCache, pixelBuffer, NULL, GL_RENDERBUFFER, GL_RGBA8_OES, width, height, GL_RGBA, GL_UNSIGNED_BYTE, 0, &outTexture);
//Mapping the luma plane of a 420v buffer as a source texture:
CVOpenGLESTextureCacheCreateTextureFromImage(kCFAllocatorDefault, textureCache, pixelBuffer, NULL, GL_TEXTURE_2D, GL_LUMINANCE, width, height, GL_LUMINANCE, GL_UNSIGNED_BYTE, 0, &outTexture);
//Mapping the chroma plane of a 420v buffer as a source texture:
CVOpenGLESTextureCacheCreateTextureFromImage(kCFAllocatorDefault, textureCache, pixelBuffer, NULL, GL_TEXTURE_2D, GL_LUMINANCE_ALPHA, width/2, height/2, GL_LUMINANCE_ALPHA, GL_UNSIGNED_BYTE, 1, &outTexture);
//Mapping a yuvs buffer as a source texture (note: yuvs/f and 2vuy are unpacked and resampled -- not colorspace converted)
CVOpenGLESTextureCacheCreateTextureFromImage(kCFAllocatorDefault, textureCache, pixelBuffer, NULL, GL_TEXTURE_2D, GL_RGB_422_APPLE, width, height, GL_RGB_422_APPLE, GL_UNSIGNED_SHORT_8_8_APPLE, 1, &outTexture);
Availability
  • Available in iOS 5.0 and later.
Declared In
CVOpenGLESTextureCache.h

CVOpenGLESTextureCacheFlush

Performs internal housekeeping/recycling operations on a texture cache.

void CVOpenGLESTextureCacheFlush(
CVOpenGLESTextureCacheRef textureCache,
CVOptionFlags options
);
Parameters
textureCache

The texture cache object to flush.

options

Options for the flush operation. This parameter is currently unused and should be set to 0.

Discussion

The texture cache automatically flushes currently unused resources when you call the CVOpenGLESTextureCacheCreateTextureFromImage function, but can you can also flush the cache explicitly by calling this function. The EAGLContext associated with the cache may be used to delete or unbind textures.

Availability
  • Available in iOS 5.0 and later.
Declared In
CVOpenGLESTextureCache.h

CVOpenGLESTextureCacheGetTypeID

Returns the Core Foundation type identifier for a Core Video texture cache.

CFTypeID CVOpenGLESTextureCacheGetTypeID(
void
);
Return Value

The Core Foundation type identifier for the CVOpenGLESTextureCacheRef type.

Availability
  • Available in iOS 5.0 and later.
Declared In
CVOpenGLESTextureCache.h

Data Types

CVOpenGLESTextureCacheRef

A reference to a Core Video OpenGLES texture cache.

typedef struct __CVOpenGLESTextureCache *CVOpenGLESTextureCacheRef;
Availability
  • Available in iOS 5.0 and later.
Declared In
CVOpenGLESTextureCache.h

CVEAGLContext

A type that resolves to an EAGLContext pointer when appropriate.

typedef EAGLContext *CVEAGLContext;
Discussion

Core Video can be included in procedural C projects as well as Objective-C projects, so this type resolves to void * when using the former.

Availability
  • Available in iOS 6.0 and later.
Declared In
CVOpenGLESTextureCache.h

Constants

Cache Attributes

Attributes for the texture cache.

const CFStringRef kCVOpenGLESTextureCacheMaximumTextureAgeKey;
Constants
kCVOpenGLESTextureCacheMaximumTextureAgeKey

By default, textures will age out after one second. Setting a maximum texture age of zero will disable the age-out mechanism completely. The CVOpenGLESTextureCacheFlush function can be used to force eviction in either case.

Available in iOS 5.0 and later.

Declared in CVOpenGLESTextureCache.h.