CVPixelBufferPool Reference

Derived from
Framework
System/Library/Frameworks/QuartzCore.framework
Companion guide
Declared in
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. (See “Pixel Buffer Pool Attribute Keys”.)

pixelBufferAttributes

A Core Foundation dictionary containing the attributes to be used for creating new pixel buffers within the pool. (See Pixel Buffer Attribute Keys.)

poolOut

On output, the newly created pixel buffer pool. Ownership follows the “The Create Rule” in Memory Management Programming Guide for Core Foundation.

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, the newly created pixel buffer. Ownership follows the “The Create Rule” in Memory Management Programming Guide for Core Foundation.

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 type identifier of the pixel buffer pool type.

CFTypeID CVPixelBufferPoolGetTypeID (
   void
);
Return Value

The Core Foundation type identifier 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

Constants

Pixel Buffer Pool Attribute Keys

The 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 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.

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.