CVPixelBufferPool Reference

Derived from
CFType Reference
Framework
System/Library/Frameworks/QuartzCore.framework
Companion guide
Core Video Programming Guide
Declared in
CVImageBuffer.h
CVPixelBuffer.h
CVPixelBufferPool.h

Overview

A pixel buffer pool is a utility object for managing a set of pixel buffer objects for repeated use. Pixel buffer pools allocate a number of buffers in main memory that can be reused as needed, avoiding repeated allocations and deallocations, which hurt performance.

Functions

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 output, poolOut points to the newly created pixel buffer pool.

Return Value

A Core Video result code. See Core Video Constants Reference for possible values.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVPixelBufferPool.h

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 output, pixelBufferOut points to the newly created pixel buffer.

Return Value

A Core Video result code. See Core Video Constants Reference for possible values.

Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
CVPixelBufferPool.h

CVPixelBufferPoolCreatePixelBufferWithAuxAttributes

Creates a new pixel buffer with some auxiliary attributes from the pool.

CVReturn CVPixelBufferPoolCreatePixelBufferWithAuxAttributes (
CFAllocatorRef allocator,
CVPixelBufferPoolRef pixelBufferPool,
CFDictionaryRef auxAttributes,
CVPixelBufferRef *pixelBufferOut
);
Parameters
allocator

The CFAllocatorRef to use for creating the new pixel buffer. This parameter may be NULL.

pixelBufferPool

The CVPixelBufferPool that should create the new CVPixelBufferRef object.

auxAttributes

A dictionary of auxiliary attributes describing this specific allocation request. This parameter may be NULL. For a list of possible keys, see “Pixel Buffer Pool Auxiliary Attribute Keys.”

pixelBufferOut

A reference to a CVPixelBufferRef where the newly created pixel buffer will be placed.

Return Value

A Core Video result code. See Core Video Constants Reference for possible values.

Discussion

This function creates a new CVPixelBufferRef object using the pixel buffer attributes specified during pool creation and the attributes specified in the auxAttributes parameter.

Availability
  • Available in OS X v10.7 and later.
Declared In
CVPixelBufferPool.h

CVPixelBufferPoolGetAttributes

Returns the pool attributes dictionary for a pixel buffer pool.

CFDictionaryRef CVPixelBufferPoolGetAttributes (
   CVPixelBufferPoolRef pool
);
Parameters
pool

The pixel buffer pool whose attributes are to be retrieved.

Return Value

A Core Foundation dictionary containing the pool attributes, or NULL on failure.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVPixelBufferPool.h

CVPixelBufferPoolGetPixelBufferAttributes

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

CFDictionaryRef CVPixelBufferPoolGetPixelBufferAttributes (
   CVPixelBufferPoolRef pool
);
Parameters
pool

The pixel buffer pool whose attributes are to be retrieved.

Return Value

A Core Foundation dictionary containing the pixel buffer attributes, or NULL on failure.

Discussion

Use this function to obtain information about the buffers that will be created for you .

Availability
  • Available in OS X v10.4 and later.
Declared In
CVPixelBufferPool.h

CVPixelBufferPoolGetTypeID

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

CFTypeID CVPixelBufferPoolGetTypeID (
   void
);
Return Value

The Core Foundation ID for this type.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVPixelBufferPool.h

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 is NULL safe.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVPixelBufferPool.h

CVPixelBufferPoolRetain

Retains a pixel buffer pool.

CVPixelBufferPoolRef CVPixelBufferPoolRetain (
   CVPixelBufferPoolRef pixelBufferPool
);
Parameters
buffer

The pixel buffer pool that you want to retain.

Return Value

For convenience, the same pixel buffer pool that you wanted to retain.

Discussion

This function is equivalent to CFRetain, but is NULL safe.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVPixelBufferPool.h

Data Types

CVPixelBufferPoolRef

A reference to a pixel buffer pool object.

typedef struct _CVPixelBufferPool *CVPixelBufferPoolRef;
Availability
  • Available in OS X v10.3 and later.
Declared In
CVPixelBufferPool.h

CVPlanarComponentInfo

A structure for describing planar components.

struct CVPlanarComponentInfo {
   int32_t             offset;
   uint32_t            rowBytes;
};
typedef struct CVPlanarComponentInfo CVPlanarComponentInfo;
Fields
offset

The offset from the main base address to the base address of this plane. (big-endian)

rowBytes

The number of bytes per row of this plane. (big-endian)

Discussion

Planar pixel buffers have this descriptor at their base address. Clients should generally use CVPixelBufferGetBaseAddressOfPlane and CVPixelBufferGetBytesPerRowOfPlane instead of accessing CVPlanarComponentInfo directly.

Availability
  • Available in OS X v10.5 and later.
Declared In
CVPixelBuffer.h

CVPlanarPixelBufferInfo

A structure for describing planar buffers.

struct CVPlanarPixelBufferInfo {
   CVPlanarComponentInfo  componentInfo[1];
};
typedef struct CVPlanarPixelBufferInfo CVPlanarPixelBufferInfo;
Fields
componentInfo

An array containing a CVPlanarComponentInfo struct for each plane of the buffer.

Availability
  • Available in OS X v10.5 and later.
Declared In
CVPixelBuffer.h

CVPlanarPixelBufferInfo_YCbCrPlanar

A structure for describing YCbCr planar buffers.

struct CVPlanarPixelBufferInfo_YCbCrPlanar {
   CVPlanarComponentInfo  componentInfoY;
   CVPlanarComponentInfo  componentInfoCb;
   CVPlanarComponentInfo  componentInfoCr;
};
typedef struct CVPlanarPixelBufferInfo_YCbCrPlanar CVPlanarPixelBufferInfo_YCbCrPlanar;
Fields
componentInfoY

A CVPlanarComponentInfo containing information on the Y component of the buffer.

componentInfoCb

A CVPlanarComponentInfo containing information on the Cb component of the buffer.

componentInfoCr

A CVPlanarComponentInfo containing information on the Cr component of the buffer.

Availability
  • Available in OS X v10.5 and later.
Declared In
CVPixelBuffer.h

Constants

Pixel Buffer Pool Attribute Keys

The attributes associated with a pixel buffer pool.

const CFStringRef kCVPixelBufferPoolMinimumBufferCountKey;
const CFStringRef kCVPixelBufferPoolMaximumBufferAgeKey;
const CFStringRef kCVImageBufferChromaLocationTopFieldKey;
const CFStringRef kCVImageBufferChromaLocationBottomFieldKey;
const CFStringRef kCVImageBufferChromaLocation_Left;
const CFStringRef kCVImageBufferChromaLocation_Center;
const CFStringRef kCVImageBufferChromaLocation_TopLeft;
const CFStringRef kCVImageBufferChromaLocation_Top;
const CFStringRef kCVImageBufferChromaLocation_BottomLeft;
const CFStringRef kCVImageBufferChromaLocation_Bottom;
const CFStringRef kCVImageBufferChromaLocation_DV420;
Constants
kCVPixelBufferPoolMinimumBufferCountKey

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

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

Declared in CVPixelBufferPool.h.

kCVImageBufferChromaLocationTopFieldKey

The location of the chroma sample in the top field. This key has one of the following values:

  • kCVImageBufferChromaLocation_Left

  • kCVImageBufferChromaLocation_Center

  • kCVImageBufferChromaLocation_TopLeft

  • kCVImageBufferChromaLocation_Top

  • kCVImageBufferChromaLocation_BottomLeft

  • kCVImageBufferChromaLocation_Bottom

  • kCVImageBufferChromaLocation_DV420

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocationBottomFieldKey

The location of the chroma sample in the bottom field. This key has one of the following values:

  • kCVImageBufferChromaLocation_Left

  • kCVImageBufferChromaLocation_Center

  • kCVImageBufferChromaLocation_TopLeft

  • kCVImageBufferChromaLocation_Top

  • kCVImageBufferChromaLocation_BottomLeft

  • kCVImageBufferChromaLocation_Bottom

  • kCVImageBufferChromaLocation_DV420

For progressive images, only kCVImageBufferChromaLocationTopFieldKey is used.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_Left

The chroma sample is horizontally co-sited with the left column of luma samples, but centered vertically.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_Center

The chroma sample is fully centered.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_TopLeft

The chroma sample is co-sited with the top-left luma sample.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_Top

The chroma sample is horizontally centered, but is co-sited with the top row of luma samples.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_BottomLeft

The chroma sample is co-sited with the bottom-left luma sample.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_Bottom

The chroma sample is horizontally centered, but is co-sited with the bottom row of luma samples.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_DV420

The Cr and Cb samples are alternately co-sited with the left luma samples of the same field.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

Discussion

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

Pixel Buffer Pool Auxiliary Attribute Keys

The auxiliary attributes used when allocating new pixel buffers using the CVPixelBufferPoolCreatePixelBufferWithAuxAttributes function.

const CFStringRef kCVPixelBufferPoolAllocationThresholdKey;
Constants
kCVPixelBufferPoolAllocationThresholdKey

When set, the value associated with this key indicates that a new pixel buffer should not be allocated if the pool already has this many or more pixel buffers allocated. This doesn’t prevent buffers that have already been allocated from being recycled. If this key causes CVPixelBufferPoolCreatePixelBufferWithAuxAttributes to fail, it will return kCVReturnWouldExceedAllocationThreshold. (type CFNumberRef)

Available in OS X v10.7 and later.

Declared in CVPixelBufferPool.h.

Notifications

The notifications posted by pixel buffer pools.

const CFStringRef kCVPixelBufferPoolFreeBufferNotification;
Constants
kCVPixelBufferPoolFreeBufferNotification

This notification is posted if a buffer becomes available after the CVPixelBufferPoolCreatePixelBufferWithAuxAttributes function has failed due to the value of the kCVPixelBufferPoolAllocationThresholdKey key. This notification will not be posted by the pool if a value for the kCVPixelBufferPoolAllocationThresholdKey key has never been passed to the CVPixelBufferPoolCreatePixelBufferWithAuxAttributes function.

Available in OS X v10.7 and later.

Declared in CVPixelBufferPool.h.



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-12-13)

Did this document help you? Yes It's good, but... Not helpful...