Core Video Reference

Overview

Core Video is a new pipeline model for digital video in Mac OS X. Partitioning the processing into discrete steps makes it simpler for developers to access and manipulate individual frames without having to worry about translating between data types (QuickTime, OpenGL, and so on) or display synchronization issues.

Core Video is available in:

• Mac OS X v10.4 and later

• Mac OS X v10.3 when QuickTime 7.0 or later is installed

Functions by Task

CVBuffer Functions

Core Video buffer functions operate on all Core Video buffer types, including pixel buffers and OpenGL buffers, as well as OpenGL textures.

• CVBufferGetAttachment
• CVBufferGetAttachments
• CVBufferPropagateAttachments
• CVBufferRelease
• CVBufferRemoveAllAttachments
• CVBufferRemoveAttachment
• CVBufferRetain
• CVBufferSetAttachment
• CVBufferSetAttachments

CVDisplayLink Functions

The main purpose of the CoreVideo display link to provide a separate high-priority thread to notify your application when a given display will need each frame. How often a frame is requested is based on the refresh rate of the display device currently associated with the display link. A CoreVideo display link is represented in code by the CVDisplayLinkRef type. The display link API uses the Core Foundation class system internally to provide reference counting behaviour and other useful properties.

• CVDisplayLinkCreateWithCGDisplay
• CVDisplayLinkCreateWithActiveCGDisplays
• CVDisplayLinkCreateWithCGDisplays
• CVDisplayLinkCreateWithOpenGLDisplayMask
• CVDisplayLinkGetActualOutputVideoRefreshPeriod
• CVDisplayLinkGetCurrentCGDisplay
• CVDisplayLinkGetCurrentTime
• CVDisplayLinkGetNominalOutputVideoRefreshPeriod
• CVDisplayLinkGetOutputVideoLatency
• CVDisplayLinkGetTypeID
• CVDisplayLinkIsRunning
• CVDisplayLinkRelease
• CVDisplayLinkRetain
• CVDisplayLinkSetCurrentCGDisplay
• CVDisplayLinkSetCurrentCGDisplayFromOpenGLContext
• CVDisplayLinkSetOutputCallback
• CVDisplayLinkStart
• CVDisplayLinkStop
• CVDisplayLinkTranslateTime

CVHostTime Functions

• CVGetCurrentHostTime
• CVGetHostClockFrequency
• CVGetHostClockMinimumTimeDelta

CVImageBuffer Functions

The functions in this section operate on Core Video buffers derived from the CVImageBuffer abstract type (CVImageBufferRef ); specifically, pixel buffers, OpenGL buffers, and OpenGL textures.

• CVImageBufferGetCleanRect
• CVImageBufferGetColorSpace
• CVImageBufferGetDisplaySize
• CVImageBufferGetEncodedSize

CVOpenGLBuffer Functions

The Core Video OpenGL buffer (type CVOpenGLBufferRef is a wrapper around the standard OpenGL pbuffer.

• CVOpenGLBufferAttach
• CVOpenGLBufferCreate
• CVOpenGLBufferGetAttributes
• CVOpenGLBufferGetTypeID
• CVOpenGLBufferRelease
• CVOpenGLBufferRetain

CVOpenGLBufferPool Functions

An OpenGL buffer pool is a utility object for managing a set of OpenGL buffer objects for recycling.

• CVOpenGLBufferPoolCreate
• CVOpenGLBufferPoolCreateOpenGLBuffer
• CVOpenGLBufferPoolGetAttributes
• CVOpenGLBufferPoolGetOpenGLBufferAttributes
• CVOpenGLBufferPoolGetTypeID
• CVOpenGLBufferPoolRelease
• CVOpenGLBufferPoolRetain

CVOpenGLTexture Functions

The Core Video OpenGL texture is a wrapper around the standard OpenGL texture type.

• CVOpenGLTextureGetCleanTexCoords
• CVOpenGLTextureGetName
• CVOpenGLTextureGetTarget
• CVOpenGLTextureGetTypeID
• CVOpenGLTextureIsFlipped
• CVOpenGLTextureRelease
• CVOpenGLTextureRetain

CVOpenGLTextureCache Functions

• CVOpenGLTextureCacheCreate
• CVOpenGLTextureCacheCreateTextureFromImage
• CVOpenGLTextureCacheFlush
• CVOpenGLTextureCacheGetTypeID
• CVOpenGLTextureCacheRelease
• CVOpenGLTextureCacheRetain

CVPixelBuffer Functions

A pixel buffer stores an image in main memory

• CVPixelBufferCreate
• CVPixelBufferCreateResolvedAttributesDictionary
• CVPixelBufferCreateWithBytes
• CVPixelBufferCreateWithPlanarBytes
• CVPixelBufferFillExtendedPixels
• CVPixelBufferGetBaseAddress
• CVPixelBufferGetBaseAddressOfPlane
• CVPixelBufferGetBytesPerRow
• CVPixelBufferGetBytesPerRowOfPlane
• CVPixelBufferGetDataSize
• CVPixelBufferGetExtendedPixels
• CVPixelBufferGetHeight
• CVPixelBufferGetHeightOfPlane
• CVPixelBufferGetPixelFormatType
• CVPixelBufferGetPlaneCount
• CVPixelBufferGetTypeID
• CVPixelBufferGetWidth
• CVPixelBufferGetWidthOfPlane
• CVPixelBufferIsPlanar
• CVPixelBufferLockBaseAddress
• CVPixelBufferRelease
• CVPixelBufferRetain
• CVPixelBufferUnlockBaseAddress

CVPixelBufferPool Functions

• CVPixelBufferPoolCreate
• CVPixelBufferPoolCreatePixelBuffer
• CVPixelBufferPoolGetAttributes
• CVPixelBufferPoolGetPixelBufferAttributes
• CVPixelBufferPoolGetTypeID
• CVPixelBufferPoolRelease
• CVPixelBufferPoolRetain

CVPixelFormatDescription Functions

Used only if you are defining a custom pixel format.

• CVPixelFormatDescriptionRegisterDescriptionWithPixelFormatType
• CVPixelFormatDescriptionCreateWithPixelFormatType
• CVPixelFormatDescriptionArrayCreateWithAllPixelFormatTypes

Functions

CVBufferGetAttachment

Returns a specific attachment of a Core Video buffer.

CFTypeRef CVBufferGetAttachment (
   CVBufferRef buffer,
   CFStringRef key,
   CVAttachmentMode *attachmentMode
);

Parameters

buffer

The Core Video buffer whose attachment you want to obtain.

key

A key in the form of a Core Foundation string identifying the desired attachment.

attachmentMode

On return, attachmentMode points to the mode of the attachment. See “CVBuffer Attachment Modes” for possible values. If the attachment mode is not defined, this parameter returns NULL.

Discussion

You can attach any Core Foundation object to a Core Video buffer to store additional information by calling CVBufferSetAttachment or CVBufferSetAttachments.

You can find predefined attachment keys in “CVBuffer Attachment Keys” and “Image Buffer Attachment Keys.”

CVBufferGetAttachments

Returns all attachments of a Core Video buffer.

CFDictionaryRef CVBufferGetAttachments (
   CVBufferRef buffer,
   CVAttachmentMode attachmentMode
);

Parameters

buffer

The Core Video buffer whose attachments you want to obtain.

attachmentMode

The mode of the attachments you want to obtain. See “CVBuffer Attachment Modes” for possible values.

Discussion

CVBufferGetAttachments is a convenience call that returns all attachments with their corresponding keys in a Core Foundation dictionary.

You can find predefined attachment keys in “CVBuffer Attachment Keys” and “Image Buffer Attachment Keys.”

CVBufferPropagateAttachments

Copies all propagatable attachments from one Core Video buffer to another.

void CVBufferPropagateAttachments (
   CVBufferRef sourceBuffer,
   CVBufferRef destinationBuffer
);

Parameters

sourceBuffer

The buffer to copy attachments from.

destinationBuffer

The buffer to copy attachments to.

Discussion

CVBufferPropagateAttachments is a convenience call that copies all attachments with a mode of kCVAttachmentMode_ShouldPropagate from one buffer to another.

CVBufferRelease

Releases a Core Video buffer.

void CVBufferRelease (
   CVBufferRef buffer
);

Parameters

buffer

The Core Video buffer that you want to release.

Discussion

Like CFRelease CVBufferRelease decrements the retain count of a Core Video buffer. If that count consequently becomes zero the memory allocated to the object is deallocated and the object is destroyed. Unlike CFRelease, you can pass NULL to CVBufferRelease without causing a crash.

Related Sample Code

• CaptureAndCompressIPBMovie
• MovieVideoChart
• StillMotion
• VideoViewer

CVBufferRemoveAllAttachments

Removes all attachments of a Core Video buffer.

void CVBufferRemoveAllAttachments (
   CVBufferRef buffer
);

Parameters

buffer

The Core Video buffer whose attachments you want to remove.

Discussion

CVBufferRemoveAllAttachments removes all attachments of a buffer and decrements their reference counts.

CVBufferRemoveAttachment

Removes a specific attachment of a Core Video buffer.

void CVBufferRemoveAttachment (
   CVBufferRef buffer,
   CFStringRef key
);

Parameters

buffer

The Core Video buffer containing the attachment to remove.

key

A key in the form of a Core Foundation string identifying the desired attachment.

Discussion

CVBufferRemoveAttachment removes an attachment identified by a key. If found the attachment is removed and the retain count decremented.

You can find predefined attachment keys in “CVBuffer Attachment Keys” and “Image Buffer Attachment Keys.”

CVBufferRetain

Retains a Core Video buffer.

CVBufferRef CVBufferRetain (
   CVBufferRef buffer
);

Parameters

buffer

The Core Video buffer that you want to retain.

Discussion

Like CFRetain, CVBufferRetain increments the retain count of a Core Video buffer. Unlike CFRetain, you can pass NULL to CVBufferRetain without causing a crash.

Related Sample Code

• CaptureAndCompressIPBMovie
• MovieVideoChart
• StillMotion

CVBufferSetAttachment

Sets or adds an attachment of a Core Video buffer.

void CVBufferSetAttachment (
   CVBufferRef buffer,
   CFStringRef key,
   CFTypeRef value,
   CVAttachmentMode attachmentMode
);

Parameters

buffer

The Core Video buffer to which to add or set the attachment.

key

The key, in the form of a Core Foundation string, identifying the desired attachment.

value

The attachment in the form of a Core Foundation object. If this parameter is NULL, the function returns an error.

attachmentMode

Specifies the attachment mode for this attachment. See “CVBuffer Attachment Modes” for possible values. Any given attachment key may exist in only one mode at a time.

Discussion

You can attach any Core Foundation object to a Core Video buffer to store additional information. If the key doesn't currently exist for the buffer object when you call this function, the new attachment will be added. If the key does exist, the existing attachment will be replaced. In both cases the retain count of the attachment will be incremented. The value can be any CFType. You can find predefined attachment keys in “CVBuffer Attachment Keys” and “Image Buffer Attachment Keys.”

You can also set attachments when creating a buffer by specifying them in the kCVBufferPropagatedAttachmentsKey or kkCVBufferNonpropagatedAttachmentsKey attributes when creating the buffer.

To retrieve attachments, use the CVBufferGetAttachment or CVBufferGetAttachments functions.

CVBufferSetAttachments

Sets a set of attachments for a Core Video buffer.

void CVBufferSetAttachments (
   CVBufferRef buffer,
   CFDictionaryRef theAttachments,
   CVAttachmentMode attachmentMode
);

Parameters

buffer

The Core Video buffer to which to set the attachments.

theAttachments

The attachments to set, in the form of a Core Foundation dictionary array.

attachmentMode

Specifies which attachment mode is desired for this attachment. A particular attachment key may only exist in a single mode at a time.

Discussion

CVBufferSetAttachments is a convenience call that in turn calls CVBufferSetAttachment for each key and value in the given dictionary. All key-value pairs must be in the root level of the dictionary.

CVDisplayLinkCreateWithActiveCGDisplays

Creates a display link capable of being used with all active displays.

CVReturn CVDisplayLinkCreateWithActiveCGDisplays (
   CVDisplayLinkRef *displayLinkOut
);

Parameters

displayLinkOut

On return, displayLinkOut points to the newly created display link.

Discussion

CVDisplayLinkCreateWithActiveCGDisplays determines the displays actively used by the host computer and creates a display link compatible with all of them. For most applications, calling this function is the most convenient way to create a display link. After creation, you can assign the display link to any active display by calling CVDisplayLinkSetCurrentCGDisplay.

Related Sample Code

• QTQuartzPlayer
• VideoViewer

CVDisplayLinkCreateWithCGDisplay

Creates a display link for a single display.

CVReturn CVDisplayLinkCreateWithCGDisplay (
   CGDirectDisplayID displayID,
   CVDisplayLinkRef *displayLinkOut
);

Parameters

displayID

The Core Graphics ID of the target display.

displayLinkOut

On return, displayLinkOut points to the newly created display link.

Discussion

Use this call to create a display link for a single display.

Related Sample Code

• QTCoreImage101
• QTCoreVideo101
• QTCoreVideo102
• QTCoreVideo103
• QTCoreVideo201

CVDisplayLinkCreateWithCGDisplays

Creates a display link for an array of displays.

CVReturn CVDisplayLinkCreateWithCGDisplays (
   CGDirectDisplayID *displayArray,
   CFIndex count,
   CVDisplayLinkRef *displayLinkOut
);

Parameters

displayArray

A pointer to an array of Core Graphics display IDs representing all the active monitors you want to use with this display link.

count

The number of displays in the display array.

displayLisk

On return, displayLinkOut points to the newly created display link.

Discussion

Use this call to create a display link for a set of displays identified by the Core Graphics display IDs.

CVDisplayLinkCreateWithOpenGLDisplayMask

Creates a display link from an OpenGL display mask.

CVReturn CVDisplayLinkCreateWithOpenGLDisplayMask (
   CGOpenGLDisplayMask mask,
   CVDisplayLinkRef *displayLinkOut
);

Parameters

mask

The OpenGL display mask describing the available displays.

displayLinkOut

On return, displayLinkOut points to the newly created display link.

Discussion

Using this function avoids having to call the Core Graphics function CGOpenGLDisplayMaskToDisplayID.

Related Sample Code

• CIColorTracking
• CIVideoDemoGL
• LiveVideoMixer
• LiveVideoMixer2
• LiveVideoMixer3

CVDisplayLinkGetActualOutputVideoRefreshPeriod

Retrieves the actual output refresh period of a display as measured by the host time base.

double CVDisplayLinkGetActualOutputVideoRefreshPeriod (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link to get the refresh period from.

Discussion

This call returns the actual output refresh period (in seconds) as computed relative to the host time base.

CVDisplayLinkGetCurrentCGDisplay

Gets the current display associated with a display link.

CGDirectDisplayID CVDisplayLinkGetCurrentCGDisplay (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link whose current display you want obtain.

Related Sample Code

• DispatchFractal

CVDisplayLinkGetCurrentTime

Retrieves the current (“now”) time of a given display link.

CVReturn CVDisplayLinkGetCurrentTime (
   CVDisplayLinkRef displayLink,
   CVTimeStamp *outTime
);

Parameters

displayLink

The display link whose current time you want to obtain.

outTime

A pointer to a CVTimeStamp structure. Note that yout must set the version in the structure (currently 0) before calling to indicate which version of the timestamp structure you want.

Discussion

You use this call to obtain the timestamp of the frame that is currently being displayed.

CVDisplayLinkGetNominalOutputVideoRefreshPeriod

Retrieves the nominal refresh period of a display link.

CVTime CVDisplayLinkGetNominalOutputVideoRefreshPeriod (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link whose refresh period you want to obtain.

Discussion

This call allows one to retrieve the device's ideal refresh period. For example, an NTSC output device might report 1001/60000 to represent the exact NTSC vertical refresh rate.

CVDisplayLinkGetOutputVideoLatency

Retrieves the nominal latency of a display link.

CVTime CVDisplayLinkGetOutputVideoLatency (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link whose latency value you want to obtain.

Discussion

This call allows you to retrieve the device’s built-in output latency. For example, an NTSC device with one frame of latency might report back 1001/30000 or 2002/60000.

CVDisplayLinkGetTypeID

Obtains the Core Foundation ID for the display link data type.

CFTypeID CVDisplayLinkGetTypeID (
   void
);

CVDisplayLinkIsRunning

Indicates whether a given display link is running.

Boolean CVDisplayLinkIsRunning (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link whose run state you want to determine.

Related Sample Code

• CIColorTracking
• CIVideoDemoGL
• QTCoreVideo101
• QTCoreVideo103
• QTCoreVideo201

CVDisplayLinkRelease

Releases a display link.

void CVDisplayLinkRelease (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link to release. This function is NULL-safe.

Related Sample Code

• LiveVideoMixer3
• QTCoreVideo101
• QTCoreVideo103
• QTCoreVideo201
• QTQuartzPlayer

CVDisplayLinkRetain

Retains a display link.

CVDisplayLinkRef CVDisplayLinkRetain (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link to retain. This function is NULL-safe.

CVDisplayLinkSetCurrentCGDisplay

Sets the current display of a display link.

CVReturn CVDisplayLinkSetCurrentCGDisplay (
   CVDisplayLinkRef displayLink,
   CGDirectDisplayID displayID
);

Parameters

displayLink

The display link whose display you want to set.

displayID

The ID of the display to be set.

Discussion

Although it is safe to call this function on a running display link, a discontinuity may appear in the video timestamp.

Related Sample Code

• CIVideoDemoGL
• LiveVideoMixer3
• QTCoreVideo101
• QTCoreVideo103
• QTQuartzPlayer

CVDisplayLinkSetCurrentCGDisplayFromOpenGLContext

Selects the display link most optimal for the current renderer of an OpenGL context.

CVReturn CVDisplayLinkSetCurrentCGDisplayFromOpenGLContext (
   CVDisplayLinkRef displayLink,
   CGLContextObj cglContext,
   CGLPixelFormatObj cglPixelFormat
);

Parameters

displayLink

The display link for which you want to set the current display.

cglContext

The OpenGL context to retrieve the current renderer from.

cglPixelFormat

The OpenGL pixel format used to create the passed-in OpenGL context.

Discussion

This function chooses the display with the lowest refresh rate.

Related Sample Code

• DispatchFractal
• QTCoreVideo201
• VideoViewer

CVDisplayLinkSetOutputCallback

Set the renderer output callback function.

CVReturn CVDisplayLinkSetOutputCallback (
   CVDisplayLinkRef displayLink,
   CVDisplayLinkOutputCallback callback,
   void *userInfo
);

Parameters

displayLink

The display link whose output callback you want to set.

callback

The callback function to set for this display link. See CVDisplayLinkOutputCallback for more information about implementing this function.

userInfo

A pointer to user data.

Discussion

The display link invokes this callback whenever it wants you to output a frame.

Related Sample Code

• CIVideoDemoGL
• LiveVideoMixer3
• QTCoreVideo103
• QTCoreVideo201
• QTQuartzPlayer

CVDisplayLinkStart

Activates a display link.

CVReturn CVDisplayLinkStart (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link to activate.

Discussion

Calling this function starts the display link thread, which then periodically calls back to your application to request that you display frames. If the specified display link is already running, CVDisplayLinkStart returns an error.

Related Sample Code

• QTCoreVideo101
• QTCoreVideo102
• QTCoreVideo103
• QTCoreVideo201
• QTCoreVideo301

CVDisplayLinkStop

Stops a display link.

CVReturn CVDisplayLinkStop (
   CVDisplayLinkRef displayLink
);

Parameters

displayLink

The display link to stop.

Discussion

If the specified display link is already stopped, CVDisplayLinkStop returns an error.

In Mac OS X v.10.4 and later, the display link thread is automatically stopped if the user employs Fast User Switching. The display link is restarted when switching back to the original user.

Related Sample Code

• QTCoreImage101
• QTCoreVideo101
• QTCoreVideo102
• QTCoreVideo103
• QTCoreVideo201

CVDisplayLinkTranslateTime

Translates the time in the display link’s time base from one representation to another.

CVReturn CVDisplayLinkTranslateTime (
   CVDisplayLinkRef displayLink,
   const CVTimeStamp *inTime,
   CVTimeStamp *outTime
);

Parameters

displayLink

The display link whose time base should be used to do the translation.

inTime

A pointer to a CVTimeStamp structure containing the source time to translate.

outTime

A pointer to a CVTimeStamp structure into which the target time is written. Before calling, you must set the version field (currently 0) to indicate which version of the structure you want. You should also set the flags field to specify which representations to translate to.

Discussion

Note that the display link has to be running for this call to succeed.

CVGetCurrentHostTime

Retrieves the current value of the host time base.

uint64_t CVGetCurrentHostTime

Discussion

In Mac OS X, the host time base for CoreVideo and CoreAudio are identical, so the values returned from either API can be used interchangeably.

Related Sample Code

• iChatTheater

CVGetHostClockFrequency

Retrieve the frequency of the host time base.

double CVGetHostClockFrequency

Discussion

In Mac OS X, the host time base for CoreVideo and CoreAudio are identical, and the values returned from either API can be used interchangeably.

Related Sample Code

• iChatTheater

CVGetHostClockMinimumTimeDelta

Retrieve the smallest possible increment in the host time base.

uint32_t CVGetHostClockMinimumTimeDelta

CVImageBufferGetCleanRect

Returns the source rectangle of a Core Video image buffer that represents the clean aperture of the buffer in encoded pixels.

CGRect CVImageBufferGetCleanRect (
   CVImageBufferRef imageBuffer
);

Parameters

imageBuffer

The image buffer that you want to retrieve the display size from.

Discussion

The clean aperture size is smaller than the full size of the image. For example, an NTSC DV frame would return a CGRect structure with an origin of (8,0) and a size of (704,480). Note that the origin of this rectangle is always in the lower-left corner. This is the same coordinate system as that used by Quartz and Core Image.

Related Sample Code

• iChatTheater

CVImageBufferGetColorSpace

Returns the color space of a Core Video image buffer.

CGColorSpaceRef CVImageBufferGetColorSpace (
   CVImageBufferRef imageBuffer
);

Parameters

imageBuffer

The image buffer that you want to retrieve the color space from.

CVImageBufferGetDisplaySize

Returns the nominal output display size, in square pixels, of a Core Video image buffer.

CGSize CVImageBufferGetDisplaySize (
   CVImageBufferRef imageBuffer
);

Parameters

imageBuffer

The image buffer that you want to retrieve the display size from.

Discussion

For example, for an NTSC DV frame this would be 640 x 480.

CVImageBufferGetEncodedSize

Returns the full encoded dimensions of a Core Video image buffer.

CGSize CVImageBufferGetEncodedSize (
   CVImageBufferRef imageBuffer
);

Parameters

imageBuffer

The image buffer that you want to retrieve the encoded size from.

Discussion

For example, for an NTSC DV frame, the encoded size would be 720 x 480. Note: When creating a Core Image image from a Core Video image buffer, you use this call to retrieve the image size.

CVOpenGLBufferAttach

Attaches an OpenGL context to a Core Video OpenGL buffer.

CVReturn CVOpenGLBufferAttach (
   CVOpenGLBufferRef openGLBuffer,
   CGLContextObj cglContext,
   GLenum face,
   GLint level,
   GLint screen
);

Parameters

openGLBuffer

The buffer you want to attach an OpenGL context to.

cglContext

The OpenGL context you want to attach.

face

The OpenGL face enumeration (0 for noncube maps.)

level

The mipmap level for drawing in the OpenGL context. This value cannot exceed the maximum mipmap level for this buffer.

screen

The virtual screen number you want to use for this context.

Related Sample Code

• iChatTheater

CVOpenGLBufferCreate

Create a new Core Video OpenGL buffer that can be used for OpenGL rendering purposes

CVReturn CVOpenGLBufferCreate (
   CFAllocatorRef allocator,
   size_t width,
   size_t height,
   CFDictionaryRef attributes,
   CVOpenGLBufferRef *bufferOut
);

Parameters

allocator

The allocator to use to create the Core Video OpenGL buffer. Pass NULL to specify the default allocator.

width

The width of the buffer in pixels.

height

The height of the buffer in pixels.

attributes

A Core Foundation dictionary containing other desired attributes of the buffer (texture target, internal format, max mipmap level, etc.). May be NULL. The following attribute values are assumed if you do not explicitly define them:

• kCVOpenGLBufferTarget = GL_TEXTURE_RECTANGLE_EXT

• kCVOpenGLBufferInternalFormat = GL_RGBA

• kCVOpenGLBufferMaximumMipmapLevel = 0

bufferOut

On return, bufferOut points to the newly created OpenGL buffer.

Discussion

CVOpenGLBufferGetAttributes

Obtains the attributes of a Core Video OpenGL buffer.

CFDictionaryRef CVOpenGLBufferGetAttributes (
   CVOpenGLBufferRef openGLBuffer
);

Parameters

openGLBuffer

The OpenGL buffer whose attributes you want to obtain.

CVOpenGLBufferGetTypeID

Obtains the Core Foundation type ID for the OpenGL buffer type.

CFTypeID CVOpenGLBufferGetTypeID (
   void
);

CVOpenGLBufferPoolCreate

Creates a new OpenGL buffer pool.

CVReturn CVOpenGLBufferPoolCreate (
   CFAllocatorRef allocator,
   CFDictionaryRef poolAttributes,
   CFDictionaryRef openGLBufferAttributes,
   CVOpenGLBufferPoolRef *poolOut
);

Parameters

allocator

The allocator to use for allocating this buffer pool. Pass NULL to specify the default allocator.

poolAttributes

A Core Foundation dictionary containing the attributes to be used for the pool itself.

openGLBufferAttributes

A Core Foundation dictionary containing the attributes to be used for creating new OpenGL buffers within the pool.

poolOut

On return, poolOut points to the new OpenGL buffer pool.

CVOpenGLBufferPoolCreateOpenGLBuffer

Creates a new OpenGL buffer from an OpenGL buffer pool.

CVReturn CVOpenGLBufferPoolCreateOpenGLBuffer (
   CFAllocatorRef allocator,
   CVOpenGLBufferPoolRef openGLBufferPool,
   CVOpenGLBufferRef *openGLBufferOut
);

Parameters

allocator

The allocator to use for creating the buffer. May be NULL to specify the default allocator.

openGLBufferPool

The OpenGL buffer pool that should create the new OpenGL buffer.

openGLBufferOut

On return, OpenGLBufferOut points to the new OpenGL buffer.

Discussion

The function creates a new OpenGL buffer using the OpenGL buffer attributes specified in the CVOpenGLBufferPoolCreate call. This buffer has default attachments as specified in the openGLBufferAttributes parameter of CVOpenGLBufferPoolCreate (using either the kCVBufferPropagatedAttachmentsKey or kCVBufferNonPropagatedAttachmentsKey attributes).

CVOpenGLBufferPoolGetAttributes

Returns the pool attributes dictionary for an Open GL buffer pool.

CFDictionaryRef CVOpenGLBufferPoolGetAttributes (
   CVOpenGLBufferPoolRef pool
);

Parameters

pool

The OpenGL buffer pool to retrieve the attributes from.

CVOpenGLBufferPoolGetOpenGLBufferAttributes

Returns the attributes of OpenGL buffers that will be created from a buffer pool.

CFDictionaryRef CVOpenGLBufferPoolGetOpenGLBufferAttributes (
   CVOpenGLBufferPoolRef pool
);

Parameters

pool

The OpenGL buffer pool to retrieve the attributes from.

Discussion

You can use this function to obtain information about the OpenGL buffers that will be created from the buffer pool.

CVOpenGLBufferPoolGetTypeID

Obtains the Core Foundation ID for the OpenGL buffer pool type.

CFTypeID CVOpenGLBufferPoolGetTypeID (
   void
);

CVOpenGLBufferPoolRelease

Releases an OpenGL buffer pool.

void CVOpenGLBufferPoolRelease (
   CVOpenGLBufferPoolRef openGLBufferPool
);

Parameters

openGLBufferPool

The OpenGL buffer pool that you want to release.

Discussion

This function is equivalent to CFRelease, but NULL safe.

CVOpenGLBufferPoolRetain

Retains an OpenGL buffer pool.

CVOpenGLBufferPoolRef CVOpenGLBufferPoolRetain (
   CVOpenGLBufferPoolRef openGLBufferPool
);

Parameters

openGLBufferPool

The OpenGL buffer pool that you want to retain.

Discussion

This function is equivalent to CFRetain, but NULL safe.

CVOpenGLBufferRelease

Releases a Core Video OpenGL buffer.

void CVOpenGLBufferRelease (
   CVOpenGLBufferRef buffer
);

Parameters

buffer

The OpenGL buffer that you want to release.

Discussion

This function is equivalent to CFRelease, but NULL safe.

CVOpenGLBufferRetain

Retains a Core Video OpenGL buffer.

CVOpenGLBufferRef CVOpenGLBufferRetain (
   CVOpenGLBufferRef buffer
);

Parameters

buffer

The OpenGL Buffer that you want to retain.

Discussion

This function is equivalent to CFRetain, but NULL safe.

CVOpenGLTextureCacheCreate

Creates an OpenGL texture cache.

CVReturn CVOpenGLTextureCacheCreate (
   CFAllocatorRef allocator,
   CFDictionaryRef cacheAttributes,
   CGLContextObj cglContext,
   CGLPixelFormatObj cglPixelFormat,
   CFDictionaryRef textureAttributes,
   CVOpenGLTextureCacheRef *cacheOut
);

Parameters

allocator

The allocator to use for allocating the cache. Pass NULL to specify the default allocator.

cacheAttributes

A Core Foundation dictionary containing the attributes of the cache itself. Pass NULL to specify no attributes.

cglContext

The OpenGL context into which the texture objects will be created.

cglPixelFormat

The OpenGL pixel format used to create the OpenGL context specified in cglContext.

textureAttributes

A Core Foundation dictionary containing the attributes to be used for creating the OpenGL texture objects. Pass NULL to specify no attributes.

cacheOut

On return, cacheOut points to the newly created texture cache.

CVOpenGLTextureCacheCreateTextureFromImage

Creates an OpenGL texture object from an existing image buffer.

CVReturn CVOpenGLTextureCacheCreateTextureFromImage (
   CFAllocatorRef allocator,
   CVOpenGLTextureCacheRef textureCache,
   CVImageBufferRef sourceImage,
   CFDictionaryRef attributes,
   CVOpenGLTextureRef *textureOut
);

Parameters

allocator

The allocator to use for allocating the OpenGL texture object. May be NULL to specify the default allocator.

textureCache

The OpenGL texture cache to be used to manage the texture.

sourceImage

The image buffer from which you want to create an OpenGL texture.

attributes

The desired buffer attributes for the OpenGL texture.

textureOut

On return, textureOut points to the newly created texture object.

Discussion

This function copies all image buffer attachments designated as propagatable to the newly-created texture.

CVOpenGLTextureCacheFlush

Flushes the OpenGL texture cache.

void CVOpenGLTextureCacheFlush (
   CVOpenGLTextureCacheRef textureCache,
   CVOptionFlags options
);

Parameters

textureCache

The texture cache to flush.

options

Currently unused; pass 0.

Discussion

You must call this function periodically to allow the texture cache to perform housekeeping operations.

CVOpenGLTextureCacheGetTypeID

Returns the Core Foundation ID of the texture cache type.

CFTypeID CVOpenGLTextureCacheGetTypeID (
   void
);

CVOpenGLTextureCacheRelease

Releases an OpenGL texture cache.

void CVOpenGLTextureCacheRelease (
   CVOpenGLTextureCacheRef textureCache
);

Parameters

textureCache

The OpenGL texture cache that you want to release.

Discussion

This function is equivalent to CFRelease, but NULL safe.

CVOpenGLTextureCacheRetain

Retains an OpenGL texture cache.

CVOpenGLTextureCacheRef CVOpenGLTextureCacheRetain (
   CVOpenGLTextureCacheRef textureCache
);

Parameters

textureCache

The OpenGL texture cache that you want to retain.

Discussion

This function is equivalent to CFRetain, but NULL safe.

CVOpenGLTextureGetCleanTexCoords

Returns the texture coordinates for the part of the image that should be displayed.

void CVOpenGLTextureGetCleanTexCoords (
   CVOpenGLTextureRef image,
   GLfloat lowerLeft[2],
   GLfloat lowerRight[2],
   GLfloat upperRight[2],
   GLfloat upperLeft[2]
);

Parameters

image

The Core Video OpenGL texture whose clean tex coordinates you want to obtain.

lowerLeft

On return, the GLFloat array hold the s and t texture coordinates of the lower-left corner of the image.

lowerRight

On return, the GLFloat array hold the s and t texture coordinates of the lower-right corner of the image.

upperRight

On return, the GLFloat array hold the s and t texture coordinates of the upper-right corner of the image.

upperLeft

On return, the GLFloat array hold the s and t texture coordinates of the upper-left corner of the image.

Discussion

This function automatically takes into account whether or not the texture is flipped.

Related Sample Code

• LiveVideoMixer3
• QTCoreVideo101
• QTCoreVideo102
• QTCoreVideo103
• QTQuartzPlayer

CVOpenGLTextureGetName

Returns the texture target name of a CoreVideo OpenGL texture.

GLuint CVOpenGLTextureGetName (
   CVOpenGLTextureRef image
);

Parameters

image

The Core Video OpenGL texture whose texture target name you want to obtain.

Discussion

See the OpenGL specification for more information about texture targets.

Related Sample Code

• LiveVideoMixer
• LiveVideoMixer2
• LiveVideoMixer3
• QTCoreVideo201
• QTCoreVideo301

CVOpenGLTextureGetTarget

Returns the texture target (for example, GL_TEXTURE_2D) of an OpenGL texture.

GLenum CVOpenGLTextureGetTarget (
   CVOpenGLTextureRef image
);

Parameters

image

The Core Video OpenGL texture whose target you want to obtain.

Discussion

See the OpenGL specification for more information about texture targets.

Related Sample Code

• LiveVideoMixer
• LiveVideoMixer2
• LiveVideoMixer3
• QTCoreVideo101
• QTCoreVideo301

CVOpenGLTextureGetTypeID

Obtains the Core Foundation ID for the Core Video OpenGL texture type.

CFTypeID CVOpenGLTextureGetTypeID (
   void
);

Related Sample Code

• QTQuartzPlayer

CVOpenGLTextureIsFlipped

Determines whether or not an OpenGL texture is flipped vertically.

Boolean CVOpenGLTextureIsFlipped (
   CVOpenGLTextureRef image
);

Parameters

image

The Core Video OpenGL texture whose orientation you want to determine.

Discussion

Quartz assumes a lower-left origin.

Related Sample Code

• QTCoreVideo201

CVOpenGLTextureRelease

Releases a Core Video OpenGL texture.

void CVOpenGLTextureRelease (
   CVOpenGLTextureRef texture
);

Parameters

texture

The Core Video OpenGL texture that you want to release.

Discussion

This function is equivalent to CFRelease, but NULL safe.

Related Sample Code

• CIVideoDemoGL
• QTCoreImage101
• QTCoreVideo101
• QTCoreVideo201
• QTQuartzPlayer

CVOpenGLTextureRetain

Retains a Core Video OpenGL texture.

CVOpenGLTextureRef CVOpenGLTextureRetain (
   CVOpenGLTextureRef texture
);

Parameters

texture

The Core Video OpenGL texture that you want to retain.

Discussion

This function is equivalent to CFRetain, but NULL safe.

Related Sample Code

• QTCoreVideo201

CVPixelBufferCreate

Creates a single pixel buffer for a given size and pixel format.

CVReturn CVPixelBufferCreate (
   CFAllocatorRef allocator,
   size_t width,
   size_t height,
   OSType pixelFormatType,
   CFDictionaryRef pixelBufferAttributes,
   CVPixelBufferRef *pixelBufferOut
);

Parameters

allocator

The allocator to use to create the pixel buffer. Pass NULL to specify the default allocator.

width

Width of the pixel buffer, in pixels.

height

Height of the pixel buffer, in pixels.

pixelFormatType

The pixel format identified by its respective four-character code (type OSType).

pixelBufferAttributes

A dictionary with additonal attributes for a pixel buffer. This parameter is optional. See “Pixel Buffer Attribute Keys” for more details.

pixelBufferOut

On return, pixelBufferOut points to the newly created pixel buffer.

Discussion

This function allocates the necessary memory based on the pixel dimensions, format, and extended pixels described in the pixel buffer’s attributes.

Some of the parameters specified in this call override equivalent pixel buffer attributes. For example, if you define the kCVPixelBufferWidth and kCVPixelBufferHeight keys in the pixel buffer attributes parameter (pixelBufferAttributes), these values are overriden by the width and height parameters.

CVPixelBufferCreateResolvedAttributesDictionary

Takes an array of CFDictionary objects describing various pixel buffer attributes and tries to resolve them into a single dictionary.

CVReturn CVPixelBufferCreateResolvedAttributesDictionary (
   CFAllocatorRef allocator,
   CFArrayRef attributes,
   CFDictionaryRef *resolvedDictionaryOut
);

Parameters

allocator

The allocator to use to create the pixel buffer. Pass NULL to specify the default allocator.

attributes

An array of Core Foundation dictionaries containing pixel buffer attribute key-value pairs.

resolvedDictionaryOut

On return, resolvedDictionaryOut points to the consolidated dictionary.

Discussion

This call is useful when you need to resolve requirements between several potential clients of a buffer.

If two or more dictionaries contain the same key but different values, errors may occur. For example, the width and height attributes must match, but if the bytes-per-row (rowBytes) attributes differ, the least common multiple is taken. Mismatches in pixel format allocators or callbacks also cause an error.

CVPixelBufferCreateWithBytes

Creates a pixel buffer for a given size and pixel format containing data specified by a memory location.

CVReturn CVPixelBufferCreateWithBytes (
   CFAllocatorRef allocator,
   size_t width,
   size_t height,
   OSType pixelFormatType,
   void *baseAddress,
   size_t bytesPerRow,
   CVPixelBufferReleaseBytesCallback releaseCallback,
   void *releaseRefCon,
   CFDictionaryRef pixelBufferAttributes,
   CVPixelBufferRef *pixelBufferOut
);

Parameters

allocator

The allocator to use to create this buffer. Pass NULL to specify the default allocator.

width

Width of the pixel buffer, in pixels.

height

Height of the pixel buffer, in pixels.

pixelFormatType

Pixel format indentified by its respective four character code (type OSType).

baseAddress

A pointer to the base address of the memory storing the pixels.

bytesPerRow

Row bytes of the pixel storage memory.

releaseCallback

The callback function to be called when the pixel buffer is destroyed. This callback allows the owner of the pixels to free the memory. See CVPixelBufferReleaseBytesCallback for more information.

releaseRefCon

User data identifying the pixel buffer. This value is passed to your pixel buffer release callback.

pixelBufferAttributes

A Core Foundation dictionary with additonal attributes for a a pixel buffer. This parameter is optional. See “Pixel Buffer Attribute Keys” for more details.

pixelBufferOut

On return, pixelBufferOut points to the newly created pixel buffer.

Discussion

Some of the parameters specified in this call override equivalent pixel buffer attributes. For example, if you define the kCVPixelBufferWidth and kCVPixelBufferHeight keys in the pixel buffer attributes parameter (pixelBufferAttributes), these values are overriden by the width and height parameters.

CVPixelBufferCreateWithPlanarBytes

Creates a single pixel buffer in planar format for a given size and pixel format containing data specified by a memory location.

CVReturn CVPixelBufferCreateWithPlanarBytes (
   CFAllocatorRef allocator,
   size_t width,
   size_t height,
   OSType pixelFormatType,
   void *dataPtr,
   size_t dataSize,
   size_t numberOfPlanes,
   void *planeBaseAddress[],
   size_t planeWidth[],
   size_t planeHeight[],
   size_t planeBytesPerRow[],
   CVPixelBufferReleasePlanarBytesCallback releaseCallback,
   void *releaseRefCon,
   CFDictionaryRef pixelBufferAttributes,
   CVPixelBufferRef *pixelBufferOut
);

Parameters

allocator

The allocator to use to create this buffer. Pass NULL to specify the default allocator.

width

Width of the pixel buffer, in pixels.

height

Height of the pixel buffer, in pixels.

pixelFormatType

Pixel format indentified by its respective four-character code (type OSType).

dataPtr

A pointer to a plane descriptor block if applicable, or NULL if not.

dataSize

The size of the memory if the planes are contiguous, or NULL if not.

numberOfPlanes

The number of planes.

planeBaseAddress

The array of base addresses for the planes.

planeWidth

The array of plane widths.

planeHeight

The array of plane heights.

planeBytesPerRow

Thje array of plane bytes-per-row values.

releaseCallback

The callback function that gets called when the pixel buffer is destroyed. This callback allows the owner of the pixels to free the memory. See CVPixelBufferReleaseBytesCallback for more information.

releaseRefCon

A pointer to user data identifying the pixel buffer. This value is passed to your pixel buffer release callback.

pixelBufferAttributes

A dictionary with additonal attributes for a a pixel buffer. This parameter is optional. See “Pixel Buffer Attribute Keys” for more details.

pixelBufferOut

On return, pixelBufferOut points to the newly created pixel buffer.

Discussion

Some of the parameters specified in this call override equivalent pixel buffer attributes. For example, if you define the kCVPixelBufferWidth and kCVPixelBufferHeight keys in the pixel buffer attributes parameter (pixelBufferAttributes), these values are overriden by the width and height parameters.

CVPixelBufferFillExtendedPixels

Fills the extended pixels of the pixel buffer.

CVReturn CVPixelBufferFillExtendedPixels (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose extended pixels you want to fill.

Discussion

This function replicates edge pixels to fill the entire extended region of the image.

CVPixelBufferGetBaseAddress

Returns the base address of the pixel buffer.

void * CVPixelBufferGetBaseAddress (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose base address you want to obtain.

Discussion

Retrieving the base address for a pixel buffer requires that the buffer base address be locked via a successful call to CVPixelBufferLockBaseAddress.

Related Sample Code

• CaptureAndCompressIPBMovie
• From A View to A Movie
• MovieVideoChart
• OpenGLCaptureToMovie
• Quartz Composer QCTV

CVPixelBufferGetBaseAddressOfPlane

Returns the base address of the plane at the specified plane index.

void * CVPixelBufferGetBaseAddressOfPlane (
   CVPixelBufferRef pixelBuffer,
   size_t planeIndex
);

Parameters

pixelBuffer

The pixel buffer containing the plane whose base address you want to obtain.

planeIndex

The index of the plane.

Discussion

Retrieving the base address for a pixel buffer requires that the buffer base address be locked by a successful call to CVPixelBufferLockBaseAddress.

CVPixelBufferGetBytesPerRow

Returns the number of bytes per row of the pixel buffer.

size_t CVPixelBufferGetBytesPerRow (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose bytes-per-row value you want to obtain.

Related Sample Code

• CaptureAndCompressIPBMovie
• From A View to A Movie
• From A View to A Picture
• MovieVideoChart
• Quartz Composer QCTV

CVPixelBufferGetBytesPerRowOfPlane

Returns the number of bytes per row for a plane at the specified index in the pixel buffer.

size_t CVPixelBufferGetBytesPerRowOfPlane (
   CVPixelBufferRef pixelBuffer,
   size_t planeIndex
);

Parameters

pixelBuffer

The pixel buffer containing the plane.

planeIndex

The index of the plane whose bytes-per-row value you want to obtain.

CVPixelBufferGetDataSize

Returns the data size for contiguous planes of the pixel buffer.

size_t CVPixelBufferGetDataSize (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose data size you want to obtain.

CVPixelBufferGetExtendedPixels

Returns the amount of extended pixel padding in the pixel buffer.

void CVPixelBufferGetExtendedPixels (
   CVPixelBufferRef pixelBuffer,
   size_t *extraColumnsOnLeft,
   size_t *extraColumnsOnRight,
   size_t *extraRowsOnTop,
   size_t *extraRowsOnBottom
);

Parameters

pixelBuffer

The pixel buffer whose extended pixel size you want to obtain.

extraColumnsOnLeft

Returns the pixel row padding to the left. May be NULL.

extraColumnsOnRight

Returns the pixel row padding to the right. May be NULL.

extraRowsOnTop

Returns the pixel row padding to the top. May be NULL.

extraRowsOnBottom

The pixel row padding to the bottom. May be NULL.

Discussion

CVPixelBufferGetHeight

Returns the height of the pixel buffer.

size_t CVPixelBufferGetHeight (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose height you want to obtain.

Related Sample Code

• CaptureAndCompressIPBMovie
• From A View to A Movie
• From A View to A Picture
• MovieVideoChart
• QTPixelBufferVCToCGImage

CVPixelBufferGetHeightOfPlane

Returns the height of the plane at planeIndex in the pixel buffer.

size_t CVPixelBufferGetHeightOfPlane (
   CVPixelBufferRef pixelBuffer,
   size_t planeIndex
);

Parameters

pixelBuffer

The pixel buffer whose plane height you want to obtain.

planeIndex

The index of the plane.

CVPixelBufferGetPixelFormatType

Returns the pixel format type of the pixel buffer.

OSType CVPixelBufferGetPixelFormatType (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose format type you want to obtain.

Discussion

Related Sample Code

• QTPixelBufferVCToCGImage

CVPixelBufferGetPlaneCount

Returns number of planes of the pixel buffer.

size_t CVPixelBufferGetPlaneCount (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose plane count you want to obtain..

CVPixelBufferGetTypeID

Returns the Core Foundation ID of the pixel buffer type.

CFTypeID CVPixelBufferGetTypeID (
   void
);

CVPixelBufferGetWidth

Returns the width of the pixel buffer.

size_t CVPixelBufferGetWidth (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer whose width you want to obtain.

Related Sample Code

• CaptureAndCompressIPBMovie
• From A View to A Movie
• From A View to A Picture
• MovieVideoChart
• QTPixelBufferVCToCGImage

CVPixelBufferGetWidthOfPlane

Returns the width of the plane at a given index in the pixel buffer.

size_t CVPixelBufferGetWidthOfPlane (
   CVPixelBufferRef pixelBuffer,
   size_t planeIndex
);

Parameters

pixelBuffer

The pixel buffer whose plane width you want to obtain.

planeIndex

The index of the plane at which to obtain the width.

CVPixelBufferIsPlanar

Determine if the pixel buffer is planar.

Boolean CVPixelBufferIsPlanar (
   CVPixelBufferRef pixelBuffer
);

Parameters

pixelBuffer

The pixel buffer to check.

CVPixelBufferLockBaseAddress

Locks the base address of the pixel buffer.

CVReturn CVPixelBufferLockBaseAddress (
   CVPixelBufferRef pixelBuffer,
   CVOptionFlags lockFlags
);

Parameters

pixelBuffer

The pixel buffer whose base address you want to lock.

lockFlags

No options currently defined; pass 0.

Related Sample Code

• CaptureAndCompressIPBMovie
• From A View to A Movie
• From A View to A Picture
• MovieVideoChart
• Quartz Composer QCTV

CVPixelBufferPoolCreate

Creates a pixel buffer pool.

CVReturn CVPixelBufferPoolCreate (
   CFAllocatorRef allocator,
   CFDictionaryRef poolAttributes,
   CFDictionaryRef pixelBufferAttributes,
   CVPixelBufferPoolRef *poolOut
);

Parameters

allocator

The allocator to use for allocating this buffer pool. Pass NULL to specify the default allocator.

poolAttributes

A Core Foundation dictionary containing the attributes for this pixel buffer pool.

pixelBufferAttributes

A Core Foundation dictionary containing the attributes to be used for creating new pixel buffers within the pool.

poolOut

On return, poolOut points to the newly created pixel buffer pool.

Related Sample Code

• OpenGLCaptureToMovie
• Quartz Composer QCTV

CVPixelBufferPoolCreatePixelBuffer

Creates a pixel buffer from a pixel buffer pool.

CVReturn CVPixelBufferPoolCreatePixelBuffer (
   CFAllocatorRef allocator,
   CVPixelBufferPoolRef pixelBufferPool,
   CVPixelBufferRef *pixelBufferOut
);

Parameters

allocator

The allocator to use for creating the pixel buffer. Pass NULL to specify the default allocator.

pixelBufferPool

The pixel buffer pool for creating the new pixel buffer.

pixelBufferOut

On return, pixelBufferOut points to the newly created pixel buffer.

Discussion

This function creates a new pixel buffer using the pixel buffer attributes specifed during pool creation. This buffer has default attachments as specified in the pixelBufferAttributes parameter of CVPixelBufferPoolCreate (using either the kCVBufferPropagatedAttachmentsKey or kCVBufferNonPropagatedAttachmentsKey attributes).

Related Sample Code

• OpenGLCaptureToMovie
• Quartz Composer QCTV

CVPixelBufferPoolGetAttributes

Returns the pool attributes dictionary for a pixel buffer pool.

CFDictionaryRef CVPixelBufferPoolGetAttributes (
   CVPixelBufferPoolRef pool
);

Parameters

pool

The pixel buffer pool to retrieve the attributes from.

Discussion

CVPixelBufferPoolGetPixelBufferAttributes

Returns the attributes of pixel buffers that will be created from this pool.

CFDictionaryRef CVPixelBufferPoolGetPixelBufferAttributes (
   CVPixelBufferPoolRef pool
);

Parameters

pool

The pixel buffer pool to retrieve the attributes from.

Discussion

This function is provided for those cases where you may need to know some information about the buffers that will be created for you .

CVPixelBufferPoolGetTypeID

Returns the Core Foundation ID of the pixel buffer pool type.

CFTypeID CVPixelBufferPoolGetTypeID (
   void
);

CVPixelBufferPoolRelease

Releases a pixel buffer pool.

void CVPixelBufferPoolRelease (
   CVPixelBufferPoolRef pixelBufferPool
);

Parameters

pixelBufferPool

The pixel buffer pool that you want to release.

Discussion

This function is equivalent to CFRelease, but NULL safe.

Related Sample Code

• OpenGLCaptureToMovie
• Quartz Composer QCTV

CVPixelBufferPoolRetain

Retains a pixel buffer pool.

CVPixelBufferPoolRef CVPixelBufferPoolRetain (
   CVPixelBufferPoolRef pixelBufferPool
);

Parameters

buffer

The pixel buffer pool that you want to retain.

Discussion

This function is equivalent to CFRetain, but NULL safe.

CVPixelBufferRelease

Releases a pixel buffer.

void CVPixelBufferRelease (
   CVPixelBufferRef texture
);

Parameters

buffer

The pixel buffer that you want to release.

Discussion

This function is equivalent to CFRelease, but NULL safe.

Related Sample Code

• OpenGLCaptureToMovie
• QTCoreVideo103
• QTCoreVideo202
• QTPixelBufferVCToCGImage

CVPixelBufferRetain

Retains a pixel buffer.

CVPixelBufferRef CVPixelBufferRetain (
   CVPixelBufferRef texture
);

Parameters

buffer

The pixel buffer that you want to retain.

Discussion

This function is equivalent to CFRetain, but NULL safe.

CVPixelBufferUnlockBaseAddress

Unlocks the base address of the pixel buffer.

CVReturn CVPixelBufferUnlockBaseAddress (
   CVPixelBufferRef pixelBuffer,
   CVOptionFlags unlockFlags
);

Parameters

pixelBuffer

The pixel buffer whose base address you want to unlock.

unlockFlags

No options currently defined; pass 0.

Discussion

Related Sample Code

• CaptureAndCompressIPBMovie
• From A View to A Movie
• From A View to A Picture
• MovieVideoChart
• Quartz Composer QCTV

CVPixelFormatDescriptionArrayCreateWithAllPixelFormatTypes

Returns all the pixel format descriptions known to Core Video.

CFArrayRef CVPixelFormatDescriptionArrayCreateWithAllPixelFormatTypes (
   CFAllocatorRef allocator
);

Parameters

allocator

The allocator to use when creating the description. Pass NULL to specify the default allocator.

CVPixelFormatDescriptionCreateWithPixelFormatType

Creates a pixel format description from a given OSType identifier.

CFDictionaryRef CVPixelFormatDescriptionCreateWithPixelFormatType (
   CFAllocatorRef allocator,
   OSType pixelFormat
);

Parameters

allocator

The allocator to use when creating the description. Pass NULL to specify the default allocator.

pixelFormat

A four-character code that identifies the pixel format you want to obtain.

CVPixelFormatDescriptionRegisterDescriptionWithPixelFormatType

Registers a pixel format description with Core Video.

void CVPixelFormatDescriptionRegisterDescriptionWithPixelFormatType (
   CFDictionaryRef description,
   OSType pixelFormat
);

Parameters

description

A Core Foundation dictionary containing the pixel format description. See “Pixel Format Description Keys” for a list of required and optional keys.

pixelFormat

The four-character code (type OSType) identifier for this pixel format.

Discussion

If you are using a custom pixel format, you must register the format with Core Video using this function. See Technical Q&A 1401: Registering Custom Pixel Formats with QuickTime and Core Video for more details.

Callbacks

CVDisplayLinkOutputCallback

Defines a pointer to a display link output callback function, which is called whenever the display link wants the application to output a frame.

typedef CVReturn (*CVDisplayLinkOutputCallback)(
   CVDisplayLinkRef displayLink,
   const CVTimeStamp *inNow,
   const CVTimeStamp *inOutputTime,
   CVOptionFlags flagsIn,
   CVOptionFlags *flagsOut,
   void *displayLinkContext
   );

You would declare a display link output callback function named MyDisplayLinkCallback like this:

CVReturn MyDisplayLinkCallback (
   CVDisplayLinkRef displayLink,
   const CVTimeStamp *inNow,
   const CVTimeStamp *inOutputTime,
   CVOptionFlags flagsIn,
   CVOptionFlags *flagsOut,
   void *displayLinkContext
   );

Parameters

displayLink

The display link requesting the frame.

inNow

A pointer to the current time.

inOutputTime

A pointer to the time that the frame will be displayed.

flagsIn

Currently unused. Pass 0.

flagsOut

Currently unused. Pass 0.

displayLinkContext

A pointer to application-defined data. This is the pointer you passed into the CVDisplayLinkSetOutputCallback function when registering your callback.

Discussion

For a given display link, you must register a display link output callback using CVDisplayLinkSetOutputCallback so that you can process and output the requested frame.

You callback must retrieve the frame with the timestamp specified by the (inOutputTime parameter, manipulate it if desired (for example, apply color correction or map into onto a surface), and then output it to the display.

CVFillExtendedPixelsCallBack

Defines a pointer to a custom extended pixel-fill function, which is called whenever the system needs to pad a buffer holding your custom pixel format.

typedef Boolean (*CVFillExtendedPixelsCallBack)(
   CVPixelBufferRef pixelBuffer,
   void *refCon
   );

Here is how you would declare a custom fill function named MyExtendedPixelFillFunc

Boolean MyExtendedPixelFillFunc (
   CVPixelBufferRef pixelBuffer,
   void *refCon
   );

Parameters

pixelBuffer

The pixel buffer to be padded.

refCon

A pointer to application-defined data. This is the same value you stored in the CVFillExtendedPixelsCallbackData structure.

Discussion

For more information on implementing a custom extended pixel-fill callback, see Technical Q&A 1440: Implementing a CVFillExtendedPixelsCallback.

CVPixelBufferReleaseBytesCallback

Defines a pointer to a pixel buffer release callback function, which is called when a pixel buffer created by CVPixelBufferCreateWithBytes is released.

typedef void (*CVPixelBufferReleaseBytesCallback)(
   void *releaseRefCon,
   const void *baseAddress
   );

You would declare a pixel buffer release callback named MyPixelBufferReleaseCallback like this:

void MyPixelBufferReleaseCallback(
   void *releaseRefCon,
   const void *baseAddress
   );

Parameters

releaseRefCon

A pointer to application-defined data. This pointer is the same as that passed in the releaseRefCon parameter of CVPixelBufferCreateWithBytes.

baseAddress

A pointer to the base address of the memory holding the pixels. This pointer is the same as that passed in the baseAddress parameter of CVPixelBufferCreateWithBytes.

Discussion

You use this callback to release the pixels and perform any other cleanup when a pixel buffer is released.

CVPixelBufferReleasePlanarBytesCallback

Defines a pointer to a pixel buffer release callback function, which is called when a pixel buffer created by CVPixelBufferCreateWithPlanarBytes is released.

typedef void (*CVPixelBufferReleasePlanarBytesCallback)(
   void *releaseRefCon,
   const void *dataPtr,
   size_t dataSize,
   size_t numberOfPlanes,
   const void *planeAddresses[]
   );

You would declare a callback named MyPixelBufferReleasePlanarBytes like this:

void MyPixelBufferReleasePlanarBytes)(
   void *releaseRefCon,
   const void *dataPtr,
   size_t dataSize,
   size_t numberOfPlanes,
   const void *planeAddresses[]
   );

Parameters

releaseRefCon

A pointer to application-defined data. This pointer is the same as that passed in the releaseRefCon parameter of CVPixelBufferCreateWithPlanarBytes.

dataPtr

A pointer to a plane descriptor block. This is the same pointer you passed to CVPixelBufferCreateWithPlanarBytes in the dataPtr parameter.

dataSize

The size value you passed to CVPixelBufferCreateWithPlanarBytes in the dataSize parameter.

numberOfPlanes

The number of planes value you passed to CVPixelBufferCreateWithPlanarBytes in the numberOfPlanes parameter.

planeAddresses

A pointer to the base plane address you passed to CVPixelBufferCreateWithPlanarBytes in the basePlaneAddress parameter.

Discussion

You use this callback to release the pixels and perform any other cleanup when a pixel buffer is released.

Data Types

CVBufferRef

Defines the base type for all Core Video buffers.

typedef struct __CVBuffer *CVBufferRef;

Discussion

CVBuffers represent an abstract type from which all Core Video buffers derive.

CVDisplayLinkRef

Defines a display link.

typedef struct __CVDisplayLink *CVDisplayLinkRef;

CVFillExtendedPixelsCallbackData

Holds information describing a custom extended pixel fill algorithm.

typedef struct {
CFIndex version;
CVFillExtendedPixelsCallBack    fillCallBack;
void *refCon;
} CVFillExtendedPixelsCallBackData;

Fields

version

The version of this fill algorithm.

fillCallback

A pointer to a custom pixel fill function.

refCon

A pointer to application-defined data that is passed to your custom pixel fill function.

Discussion

You must fill out this structure and store it as part of your pixel format description Core Foundation dictionary (key: kCVPixelFormatFillExtendedPixelsCallback, type: CFData). However, if your custom pixel format never needs the functionality of CVPixelBufferFillExtendedPixels, you don’t need to add this key or implement the associated callback.

For more information about defining a custom pixel format, see “Pixel Format Description Keys.”

CVImageBufferRef

Defines a Core Video image buffer.

typedef CVBufferRef CVImageBufferRef;

Discussion

An image buffer is an abstract type representing Core Video buffers that hold images. In Core Video, pixel buffers, OpenGL buffers, and OpenGL textures all derive from the image buffer type.

CVOptionFlags

Define flags to be used for the display link output callback function.

typedef uint64_t CVOptionFlags;

Discussion

No flags are currently defined.

CVOpenGLBufferRef

Defines a Core Video OpenGL buffer.

typedef CVImageBufferRef CVOpenGLBufferRef;

Discussion

The Core Video OpenGL buffer (type CVOpenGLBufferRef is a wrapper around the standard OpenGL pbuffer.

CVOpenGLBufferPoolRef

Defines an OpenGL buffer pool.

typedef struct _CVOpenGLBufferPool *CVOpenGLBufferPoolRef;

CVOpenGLTextureRef

Defines an OpenGL texture-based image buffer.

typedef CVImageBufferRef CVOpenGLTextureRef;

Discussion

The Core Video OpenGL texture (type CVOpenGLTextureRef is a wrapper around the standard OpenGL texture.

CVOpenGLTextureCacheRef

Defines a CoreVideo OpenGL texture cache.

typedef struct __CVOpenGLTextureCache *CVOpenGLTextureCacheRef;

CVPixelBufferRef

Defines a Core Video pixel buffer.

typedef CVImageBufferRef CVPixelBufferRef;

Discussion

The pixel buffer stores an image in main memory.

CVPixelBufferPoolRef

Defines a pixel buffer pool.

typedef struct _CVPixelBufferPool *CVPixelBufferPoolRef;

CVReturn

Defines the return error code for Core Video functions.

typedef int32_t CVReturn;

Discussion

See “Result Codes” for possible values.

CVSMPTETime

A structure for holding a SMPTE time.

struct CVSMPTETime    {
   SInt16  subframes;
   SInt16  subframeDivisor;
   UInt32  counter;
   UInt32  type;
   UInt32  flags;
   SInt16  hours;
   SInt16  minutes;
   SInt16  seconds;
   SInt16  frames;
;}
typedef struct CVSMPTETime CVSMPTETime;

Fields

subframes

The number of subframes in the full message.

subframeDivisor

The number of subframes per frame (typically, 80).

counter

The total number of messages received.

type

The kind of SMPTE time type. See “SMPTE Time Types” for a list of possible values.

flags

A set of flags that indicate the SMPTE state. See “SMPTE State Flags” for possible values.

hours

The number of hours in the full message.

minutes

The number of minutes in the full message.

seconds

The number of seconds in the full message.

frames

The number of frames in the full message.

CVTime

A structure for reporting Core Video time values.

typedef struct {
int64_t     timeValue;
int64_t     timeScale;
int32_t     flags;
} CVTime;

Fields

timeValue

The time value.

timeScale

The time scale for this value.

flags

Flags associated with the CVTime value. See “CVTime Constants” for possible values. If kCVTimeIsIndefinite is set, you should not use any of the other fields in this structure.

Discussion

This structure is equivalent to the QuickTime QTTime structure.

CVTimeStamp

A structure for defining a display timestamp.

typedef struct {
uint32_t    version;
int32_t     videoTimeScale;
int64_t     videoTime;
uint64_t    hostTime;
double      rateScalar;
int64_t     videoRefreshPeriod;
CVSMPTETime smpteTime;
uint64_t    flags;
uint64_t    reserved;
} CVTimeStamp;

Fields

version

The current CVTimeStamp structure is version 0. Some functions require you to specify a version when passing in a timestamp structure to be filled.

videoTimeScale

The scale (in units per second) of the videoTimeScale and videoRefreshPeriod fields.

videoTime

The start of a frame (or field for interlaced video).

hostTime

The host root time base time.

rateScalar

The current rate of the device as measured by the timestamps, divided by the nominal rate

videoPeriod

The nominal update period of the current output device.

smpteTime

The SMPTE time representation of the timestamp.

flags

A bit field containing additional information about the timestamp. See “CVTimeStamp Flags” for a list of possible values. .

reserved

Reserved. Do not use.

Discussion

This structure is designed to be very similar to the audio time stamp defined in the Core Audio framework. However, unlike the audio timestamps, floating-point values are not used to represent the video equivalent of sample times. This was done partly to avoid precision issues, and partly because QuickTime still uses integers for time values and time scales. In the actual implementation it has turned out to be very convenient to use integers, and we can represent frame rates like NTSC (30000/1001 fps) exactly. The mHostTime structure field uses the same Mach absolute time base used in Core Audio, so that clients of the Core Video API can synchronize between the two subsystems.

Constants

CVBuffer Attachment Keys

Specify an attachment type for a Core Video buffer.

const CFStringRef kCVBufferMovieTimeKey;
const CFStringRef kCVBufferTimeValueKey;
const CFStringRef kCVBufferTimeScaleKey;

Constants

kCVBufferMovieTimeKey

The movie time associated with the buffer. Generally only available for frames emitted by QuickTime (type CFDictionary containing the kCVBufferTimeValueKey and kCVBufferTimeScaleKey keys).

Available in Mac OS X v10.4 and later.

Declared in CVBuffer.h.

kCVBufferTimeValueKey

The actual time value associated with the movie.

Available in Mac OS X v10.4 and later.

Declared in CVBuffer.h.

kCVBufferTimeScaleKey

The time scale associated with the movie.

Available in Mac OS X v10.4 and later.

Declared in CVBuffer.h.

CVBuffer Attachment Modes

Specify the propagation mode of a Core Video buffer attachment.

enum {
   kCVAttachmentMode_ShouldNotPropagate    = 0,
   kCVAttachmentMode_ShouldPropagate       = 1,
};
typedef uint32_t CVAttachmentMode;

Constants

kCVAttachmentMode_ShouldNotPropagate

Do not propagate this attachment.

Available in Mac OS X v10.3 and later.

Declared in CVBuffer.h.

kCVAttachmentMode_ShouldPropagate

Copy this attachment when using the CVBufferPropagateAttachments function. For example, in most cases, you would want to propagate an attachment bearing a timestamp to each successive buffer.

Available in Mac OS X v10.3 and later.

Declared in CVBuffer.h.

Discussion

You set these attributes when adding attachments to a CVBuffer object.

CVBuffer Attribute Keys

Specify attributes associated with Core Video buffers.

const CFStringRef kCVBufferPropagatedAttachmentsKey;
const CFStringRef kCVBufferNonPropagatedAttachmentsKey;

Constants

kCVBufferPropagatedAttachmentsKey

Attachments that should be copied when using the CVBufferPropagateAttachments function (type CFDictionary, containing a list of attachments as key-value pairs).

Available in Mac OS X v10.4 and later.

Declared in CVBuffer.h.

kCVBufferNonPropagatedAttachmentsKey

Attachments that should not be copied when using the CVBufferPropagateAttachments function (type CFDictionary, containing a list of attachments as key-value pairs).

Available in Mac OS X v10.4 and later.

Declared in CVBuffer.h.

Discussion

These attributes let you set multiple attachments at the time of buffer creation, rather than having to call CVBufferSetAttachment for each attachment.

CVTime Constants

Specify flags for the CVTime structure.

enum {
kCVTimeIsIndefinite = 1 << 0
};

Constants

kCVTimeIsIndefinite

The time value is unknown.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

CVTime Values

Indicate specific CVTime values.

const CVTime kCVZeroTime;
const CVTime kCVIndefiniteTime;

Constants

kCVZeroTime

Zero time or duration. For example, CVDisplayLinkGetOutputVideoLatency returns kCVZeroTime for zero video latency.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVIndefiniteTime

An unknown or indefinite time. For example, CVDisplayLinkGetNominalOutputVideoRefreshPeriod returns kCVIndefiniteTime if the display link specified is not valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

CVTimeStamp Flags

Specify flags for the CVTimeStamp structure.

enum
{
   kCVTimeStampVideoTimeValid              = (1L << 0),
   kCVTimeStampHostTimeValid               = (1L << 1),
   kCVTimeStampSMPTETimeValid              = (1L << 2),
   kCVTimeStampVideoRefreshPeriodValid     = (1L << 3),
   kCVTimeStampRateScalarValid             = (1L << 4),
   kCVTimeStampTopField                    = (1L << 16),
   kCVTimeStampBottomField                 = (1L << 17)
};
enum
{
   kCVTimeStampVideoHostTimeValid   =
   (kCVTimeStampVideoTimeValid | kCVTimeStampHostTimeValid),
   kCVTimeStampIsInterlaced             =
   (kCVTimeStampTopField | kCVTimeStampBottomField)
};

Constants

kCVTimeStampVideoTimeValid

The value in the video time field is valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampHostTimeValid

The value in the host time field is valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampSMPTETimeValid

The value in the SMPTE time field is valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampVideoRefreshPeriodValid

The value in the video refresh period field is valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampRateScalarValid

The value in the rate scalar field is valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampTopField

The timestamp represents the top lines of an interlaced image.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampBottomField

The timestamp represents the bottom lines of an interlaced image.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampVideoHostTimeValid

A convenience constant indicating that both the video time and host time fields are valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampIsInterlaced

A convenience constant indicating that the timestamp is for an interlaced image.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

Discussion

These flags indicate which fields in the CVTimeStamp structure contain valid information.

Image Buffer Attachment Keys

Specify attachment types associated with image buffers.

const CFStringRef kCVImageBufferCGColorSpaceKey;
const CFStringRef kCVImageBufferGammaLevelKey;
const CFStringRef kCVImageBufferCleanApertureKey;
const CFStringRef kCVImageBufferPreferredCleanApertureKey;
const CFStringRef kCVImageBufferCleanApertureWidthKey;
const CFStringRef kCVImageBufferCleanApertureHeightKey;
const CFStringRef kCVImageBufferCleanApertureHorizontalOffsetKey;
const CFStringRef kCVImageBufferCleanApertureVerticalOffsetKey;
const CFStringRef kCVImageBufferFieldCountKey;
const CFStringRef kCVImageBufferFieldDetailKey;
const CFStringRef kCVImageBufferFieldDetailTemporalTopFirst;
const CFStringRef kCVImageBufferFieldDetailTemporalBottomFirst;
const CFStringRef kCVImageBufferFieldDetailSpatialFirstLineEarly;
const CFStringRef kCVImageBufferFieldDetailSpatialFirstLineLate;
const CFStringRef kCVImageBufferPixelAspectRatioKey;
const CFStringRef kCVImageBufferPixelAspectRatioHorizontalSpacingKey;
const CFStringRef kCVImageBufferPixelAspectRatioVerticalSpacingKey;
const CFStringRef kCVImageBufferDisplayDimensionsKey;
const CFStringRef kCVImageBufferDisplayWidthKey;
const CFStringRef kCVImageBufferDisplayHeightKey;
const CFStringRef kCVImageBufferYCbCrMatrixKey;
const CFStringRef kCVImageBufferYCbCrMatrix_ITU_R_709_2;
const CFStringRef kCVImageBufferYCbCrMatrix_ITU_R_601_4;
const CFStringRef kCVImageBufferYCbCrMatrix_SMPTE_240M_1995;

Constants

kCVImageBufferCGColorSpaceKey

The color space for the buffer (type CGColorSpaceRef).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferGammaLevelKey

The gamma level for this buffer (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureKey

The clean aperture for the buffer (type CFDictionary , containing the clean aperture width, height, and horizontal and vertical offset key-value pairs).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPreferredCleanApertureKey

The preferred clean aperture for the buffer (type CFDictionary , containing the clean aperture width, height, and horizontal and vertical offset key-value pairs).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureWidthKey

The clean aperture width (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureHeightKey

The clean aperture height (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureHorizontalOffsetKey

The clean aperture horizontal offset (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureVerticalOffsetKey

The clean aperture vertical offset (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldCountKey

The field count for the buffer (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailKey

Specific information about the field of a video frame in the buffer (type CFDictionary, containing the temporal bottom first and top first and spacial first-line-early and first-line-late keys).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailTemporalTopFirst

(type CFString).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailTemporalBottomFirst

(type CFString).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailSpatialFirstLineEarly

(type CFString).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailSpatialFirstLineLate

(type CFString).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPixelAspectRatioKey

The pixel aspect ratio of the buffer (type CFDictionary, containing the horizontal and vertical spacing keys).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPixelAspectRatioHorizontalSpacingKey

The horizontal component of the buffer aspect ratio (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPixelAspectRatioVerticalSpacingKey

The vertical component of the buffer aspect ratio (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferDisplayDimensionsKey

The buffer display dimensions (type CFDictionary containing the buffer display width and height keys).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferDisplayWidthKey

The buffer display width (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferDisplayHeightKey

The buffer display height (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferYCbCrMatrixKey

The type of conversion matrix used for this buffer when converting from YCbCr to RGB images (type CFString). The value for this key should be one of the following constants: kCVImageBufferYCbCrMatrix_ITU_R_709_2, kCVImageBufferYCbCrMatrix_ITU_R_601_4, or kCVImageBufferYCbCrMatrix_SMPTE_240M_1995.

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferYCbCrMatrix_ITU_R_709_2

Specifies the YCbCr to RGB conversion matrix for HDTV digital television (ITU R 709) images.

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferYCbCrMatrix_ITU_R_601_4

Specifies the YCbCr to RGB conversion matrix for standard digital television ( ITU R 601) images.

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferYCbCrMatrix_SMPTE_240M_1995

Specifies the YCbCR to RGB conversion matrix for 1920 x 1135 HDTV (SMPTE 240M 1995).

Available in Mac OS X v10.4 and later.

Declared in CVImageBuffer.h.

Discussion

Image buffer attachment keys are stored in a Core Foundation dictionary associated with an image buffer. Note that some of these keys are stored in subdictionaries keyed by a higher-level attribute. For example, the kCVImageBufferDisplayWidthKey and kCVImageBufferDisplayHeightKey attributes are stored in a Core Foundation dictionary keyed to the kCVImageBufferDisplayDimensionsKey attribute.

OpenGL Buffer Attribute Keys

Specify attributes of an OpenGL buffer.

const CFStringRef kCVOpenGLBufferWidth;
const CFStringRef kCVOpenGLBufferHeight;
const CFStringRef kCVOpenGLBufferTarget;
const CFStringRef kCVOpenGLBufferInternalFormat;
const CFStringRef kCVOpenGLBufferMaximumMipmapLevel;

Constants

kCVOpenGLBufferWidth

The width of the buffer.

Available in Mac OS X v10.4 and later.

Declared in CVOpenGLBuffer.h.

kCVOpenGLBufferHeight

The height of the buffer.

Available in Mac OS X v10.4 and later.

Declared in CVOpenGLBuffer.h.

kCVOpenGLBufferTarget

The OpenGL target for this buffer.

Available in Mac OS X v10.4 and later.

Declared in CVOpenGLBuffer.h.

kCVOpenGLBufferInternalFormat

The OpenGL internal format of this buffer.

Available in Mac OS X v10.4 and later.

Declared in CVOpenGLBuffer.h.

kCVOpenGLBufferMaximumMipmapLevel

The maximum mipmap level for this buffer.

Available in Mac OS X v10.4 and later.

Declared in CVOpenGLBuffer.h.

OpenGL Buffer Pool Attribute Keys

Specify attributes associated with an OpenGL buffer pool.

const CFStringRef kCVOpenGLBufferPoolMinimumBufferCountKey;
const CFStringRef kCVOpenGLBufferPoolMaximumBufferAgeKey;

Constants

kCVOpenGLBufferPoolMinimumBufferCountKey

Indicates the minimum number of buffers to keep in the pool (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVOpenGLBufferPool.h.

kCVOpenGLBufferPoolMaximumBufferAgeKey

Indicates how long unused buffers should be kept before they are deallocated (type CFAbsoluteTime).

Available in Mac OS X v10.4 and later.

Declared in CVOpenGLBufferPool.h.

Discussion

You specify these keys in a Core Foundation dictionary when calling functions such as CVOpenGLBufferPoolCreate.

Pixel Buffer Attribute Keys

Specify attributes associated with a pixel buffer.

const CFStringRef kCVPixelBufferPixelFormatTypeKey;
   const CFStringRef kCVPixelBufferMemoryAllocatorKey;
   const CFStringRef kCVPixelBufferWidthKey;
   const CFStringRef kCVPixelBufferHeightKey;
   const CFStringRef kCVPixelBufferExtendedPixelsLeftKey;
   const CFStringRef kCVPixelBufferExtendedPixelsTopKey;
   const CFStringRef kCVPixelBufferExtendedPixelsRightKey;
   const CFStringRef kCVPixelBufferExtendedPixelsBottomKey;
   const CFStringRef kCVPixelBufferBytesPerRowAlignmentKey;
   const CFStringRef kCVPixelBufferCGBitmapContextCompatibilityKey;
   const CFStringRef kCVPixelBufferCGImageCompatibilityKey;
   const CFStringRef kCVPixelBufferOpenGLCompatibilityKey;

Constants

kCVPixelBufferPixelFormatTypeKey

The pixel format for this buffer (type CFNumber, or type CFArray containing an array of CFNumber types (actually type OSType)). For a listing of common pixel formats, see the QuickTime Ice Floe Dispatch 20.

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferMemoryAllocatorKey

The allocator used with this buffer (type CFAllocatorRef).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferWidthKey

The width of the pixel buffer (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferHeightKey

The height of the pixel buffer (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferExtendedPixelsLeftKey

The number of pixels padding the left of the image (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferExtendedPixelsTopKey

The number of pixels padding the top of the image (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferExtendedPixelsRightKey

The number of pixels padding the right of the image (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferExtendedPixelsBottomKey

The number of pixels padding the bottom of the image (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferBytesPerRowAlignmentKey

Indicates the number of bytes per row in the pixel buffer (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferCGBitmapContextCompatibilityKey

Indicates whether the pixel buffer is compatible with Core Graphics bitmap contexts (type CFBoolean).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferCGImageCompatibilityKey

Indicates whether the pixel buffer is compatible with CGImage types (type CFBoolean).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferOpenGLCompatibilityKey

Indicates whether the pixel buffer is compatible with OpenGL contexts (type CFBoolean).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBuffer.h.

Discussion

You specify these keys in a Core Foundation dictionary when calling functions such as CVPixelBufferCreate.

Pixel Buffer Pool Attribute Keys

Specify attributes associated with a pixel buffer pool.

const CFStringRef kCVPixelBufferPoolMinimumBufferCountKey;
const CFStringRef kCVPixelBufferPoolMaximumBufferAgeKey;

Constants

kCVPixelBufferPoolMinimumBufferCountKey

The minimum number of buffers allowed in the pixel buffer pool (type CFNumber).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBufferPool.h.

kCVPixelBufferPoolMaximumBufferAgeKey

The maximum allowable age for a buffer in the pixel buffer pool (type CFAbsoluteTime).

Available in Mac OS X v10.4 and later.

Declared in CVPixelBufferPool.h.

Discussion

You specify these keys in a Core Foundation dictionary when calling functions such as CVPixelBufferPoolCreate.

Pixel Format Description Keys

Specify attributes of a pixel format.

const CFStringRef kCVPixelFormatName;
const CFStringRef kCVPixelFormatConstant;
const CFStringRef kCVPixelFormatCodecType;
const CFStringRef kCVPixelFormatFourCC;
const CFStringRef kCVPixelFormatPlanes;
const CFStringRef kCVPixelFormatBlockWidth;
const CFStringRef kCVPixelFormatBlockHeight;
const CFStringRef kCVPixelFormatBitsPerBlock;
const CFStringRef kCVPixelFormatBlockHorizontalAlignment;
const CFStringRef kCVPixelFormatBlockVerticalAlignment;
const CFStringRef kCVPixelFormatHorizontalSubsampling;
const CFStringRef kCVPixelFormatVerticalSubsampling;
   
const CFStringRef kCVPixelFormatOpenGLFormat;
const CFStringRef kCVPixelFormatOpenGLType;
const CFStringRef kCVPixelFormatOpenGLInternalFormat;
   
const CFStringRef kCVPixelFormatCGBitmapInfo;
   
const CFStringRef kCVPixelFormatQDCompatibility;
const CFStringRef kCVPixelFormatCGBitmapContextCompatibility;
const CFStringRef kCVPixelFormatCGImageCompatibility;
const CFStringRef kCVPixelFormatOpenGLCompatibility;
   
const CFStringRef kCVPixelFormatFillExtendedPixelsCallback;

Constants

kCVPixelFormatName

The name of the pixel format (type CFString). This should be the same as the codec name you would use in QuickTime.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatConstant

The pixel format constant for QuickTime.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCodecType

The codec type (type CFString). For example, '2vuy' or k422YpCbCr8CodecType.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatFourCC

The Microsoft FourCC equivalent code for this pixel format (type CFString).

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatPlanes

The number of image planes associated with this format (type CFNumber. Each plane may contain a single component or an interleaved set of components. Note that if your pixel format is not planar, you can put the required format keys at the top-level dictionary.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockWidth

The width, in pixels, of the smallest byte-addressable group of pixels (type CFNumber. Used to assist with allocating memory for pixel formats that don't have an integer value for bytes per pixel. Assumed to be 1 if this key is not present. Here are some examples of block widths for standard pixel formats:

• 8-bit luminance only, block width is 1, the bits per block value is 8.

• 16-bit 1555 RGB, block width is 1, the bits per block value is 16.

• 32-bit 8888 ARGB, block width is 1, the bits per block value is 32.

• 2vuy (CbYCrY), block width is 2, the bits per block value is 32.

• 1-bit bitmap, block width is 8, the bits per block value is 8.

• v210, block width is 6, the bits per block value is 128 .

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockHeight

The height, in pixels, of the smallest byte-addressable group of pixels (type CFNumber). Assumed to be one if this key is not present.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBitsPerBlock

The number of bits per block. For simple pixel formats, this value is the same as the traditional bits-per-pixel value. This key is mandatory in pixel format descriptions. See the description for kCVPixelFormatBlockWidth for examples of bits-per-block values.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockHorizontalAlignment

The horizontal alignment requirements of this format (type CFNumber). For example,the alignment for v210 would be '8' here for the horizontal case to match the standard v210 row alignment value of 48. Assumed to be 1 if this key is not present.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockVerticalAlignment

The vertical alignment requirements of this format (type CFNumber). Assumed to be 1 if this key is not present.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatHorizontalSubsampling

Horizontal subsampling information for this plane (type CFNumber). Assumed to be 1 if this key is not present.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatVerticalSubsampling

Vertical subsampling information for this plane (type CFNumber). Assumed to be 1 if this key is not present.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLFormat

The OpenGL format used to describe this image plane (if applicable). See the OpenGL specification for possible values.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLType

The OpenGL type to describe this image plane (if applicable). See the OpenGL specification for possible values.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLInternalFormat

The OpenGL internal format for this pixel format (if applicable). See the OpenGL specification for possible values.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCGBitmapInfo

The Core Graphics bitmap information for this pixel format (if applicable).

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatQDCompatibility

Indicates whether this format is compatible with QuickDraw (type CFBoolean).

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCGBitmapContextCompatibility

Indicates whether this format is compatible with Core Graphics bitmap contexts(type CFBoolean).

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCGImageCompatibility

Indicates whether this format is compatible with the CGImage type (type CFBoolean).

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLCompatibility

Indicates whether this format is compatible with OpenGL (type CFBoolean).

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatFillExtendedPixelsCallback

Specifies a custom extended pixel fill algorithm (type CFData). See CVFillExtendedPixelsCallBack and CVFillExtendedPixelsCallbackData for more information.

Available in Mac OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

Discussion

If you need to define a custom pixel format, you must specify these keys in a Core Foundation dictionary. For information about registering your pixel format, see Technical Q&A 1401: Registering Custom Pixel Formats with QuickTime and Core Video.

In most cases you do not need to specify your own pixel format.

SMPTE State Flags

Flags that describe the SMPTE time state.

enum{
   kCVSMPTETimeValid     = (1L << 0),
   kCVSMPTETimeRunning   = (1L << 1)
};

Constants

kCVSMPTETimeValid

The full time is valid.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeRunning

Time is running.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

Discussion

You use these values in the CVSMPTETime structure.

SMPTE Time Types

Constants that describe the type of SMPTE time.

enum{
   kCVSMPTETimeType24        = 0,
   kCVSMPTETimeType25        = 1,
   kCVSMPTETimeType30Drop    = 2,
   kCVSMPTETimeType30        = 3,
   kCVSMPTETimeType2997      = 4,
   kCVSMPTETimeType2997Drop  = 5,
   kCVSMPTETimeType60        = 6,
   kCVSMPTETimeType5994      = 7
};

Constants

kCVSMPTETimeType24

24 frames per second (standard film).

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType25

25 frames per second (standard PAL).

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType30Drop

30 drop frame.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType30

30 frames per second.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType2997

29.97 frames per second (standard NTSC).

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType2997Drop

29.97 drop frame.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType60

60 frames per second.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType5994

59.94 frames per second.

Available in Mac OS X v10.3 and later.

Declared in CVBase.h.

Discussion

You use these values in the CVSMPTETime structure.

Result Codes

The table below lists the result codes returned for Core Video. Note that these result codes are of type CVReturn, not type OSErr.

---