CVPixelBuffer Reference

Overview

A Core Video pixel buffer is an image buffer that holds pixels in main memory. Applications generating frames, compressing or decompressing video, or using Core Image can all make use of Core Video pixel buffers.

Functions

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
);

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
);

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
);

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
);

CVPixelBufferFillExtendedPixels

Fills the extended pixels of the pixel buffer.

CVReturn CVPixelBufferFillExtendedPixels (
   CVPixelBufferRef pixelBuffer
);

CVPixelBufferGetBaseAddress

Returns the base address of the pixel buffer.

void * CVPixelBufferGetBaseAddress (
   CVPixelBufferRef pixelBuffer
);

CVPixelBufferGetBaseAddressOfPlane

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

void * CVPixelBufferGetBaseAddressOfPlane (
   CVPixelBufferRef pixelBuffer,
   size_t planeIndex
);

CVPixelBufferGetBytesPerRow

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

size_t CVPixelBufferGetBytesPerRow (
   CVPixelBufferRef pixelBuffer
);

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
);

CVPixelBufferGetDataSize

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

size_t CVPixelBufferGetDataSize (
   CVPixelBufferRef pixelBuffer
);

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
);

CVPixelBufferGetHeight

Returns the height of the pixel buffer.

size_t CVPixelBufferGetHeight (
   CVPixelBufferRef pixelBuffer
);

CVPixelBufferGetHeightOfPlane

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

size_t CVPixelBufferGetHeightOfPlane (
   CVPixelBufferRef pixelBuffer,
   size_t planeIndex
);

CVPixelBufferGetPixelFormatType

Returns the pixel format type of the pixel buffer.

OSType CVPixelBufferGetPixelFormatType (
   CVPixelBufferRef pixelBuffer
);

CVPixelBufferGetPlaneCount

Returns number of planes of the pixel buffer.

size_t CVPixelBufferGetPlaneCount (
   CVPixelBufferRef pixelBuffer
);

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
);

CVPixelBufferGetWidthOfPlane

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

size_t CVPixelBufferGetWidthOfPlane (
   CVPixelBufferRef pixelBuffer,
   size_t planeIndex
);

CVPixelBufferIsPlanar

Determines whether the pixel buffer is planar.

Boolean CVPixelBufferIsPlanar (
   CVPixelBufferRef pixelBuffer
);

CVPixelBufferLockBaseAddress

Locks the base address of the pixel buffer.

CVReturn CVPixelBufferLockBaseAddress (
   CVPixelBufferRef pixelBuffer,
   CVOptionFlags lockFlags
);

CVPixelBufferRelease

Releases a pixel buffer.

void CVPixelBufferRelease (
   CVPixelBufferRef texture
);

CVPixelBufferRetain

Retains a pixel buffer.

CVPixelBufferRef CVPixelBufferRetain (
   CVPixelBufferRef texture
);

CVPixelBufferUnlockBaseAddress

Unlocks the base address of the pixel buffer.

CVReturn CVPixelBufferUnlockBaseAddress (
   CVPixelBufferRef pixelBuffer,
   CVOptionFlags unlockFlags
);

Callbacks

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
   );

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[]
   );

Data Types

CVPixelBufferRef

A reference to a Core Video pixel buffer object.

typedef CVImageBufferRef CVPixelBufferRef;

Constants

Pixel Buffer Attribute Keys

The 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;
   const CFStringRef kCVPixelBufferIOSurfacePropertiesKey;
   const CFStringRef kCVPixelBufferPlaneAlignmentKey;

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 OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferMemoryAllocatorKey

The allocator used with this buffer (type CFAllocatorRef).

Available in OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferWidthKey

The width of the pixel buffer (type CFNumber).

Available in OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferHeightKey

The height of the pixel buffer (type CFNumber).

Available in 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 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 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 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 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 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 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 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 OS X v10.4 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferIOSurfacePropertiesKey

Indicates optional properties in the IOSurface framework (type CFDictionary). An empty dictionary indicates default values.

Presence of this key requests allocation via the IOSurface framework.

Available in OS X v10.6 and later.

Declared in CVPixelBuffer.h.

kCVPixelBufferPlaneAlignmentKey

Specifies the alignment of the planes within the buffer. Planes will start on a byte number which is a multiple of this value. (type CFNumber).

Available in OS X v10.5 and later.

Declared in CVPixelBuffer.h.

Pixel Buffer Locking Flags

The flags to pass to CVPixelBufferLockBaseAddress and CVPixelBufferUnlockBaseAddress.

enum CVPixelBufferLockFlags {
   kCVPixelBufferLock_ReadOnly = 0x00000001,
};

Constants

kCVPixelBufferLock_ReadOnly

A read-only buffer.

If you are not going to modify the data while you hold the lock, you should set this flag to avoid potentially invalidating any existing caches of the buffer contents. This flag should be passed to both the lock and the unlock functions. Non symmetrical usage of this flag will result in undefined behavior.

Available in OS X v10.6 and later.

Declared in CVPixelBuffer.h.