CVImageBuffer Reference

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

Overview

Core Video image buffers provides a convenient interface for managing different types of image data. Pixel buffers and Core Video OpenGL buffers derive from the Core Video image buffer.

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

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 containing the display size to be retrieved.

Return Value

A CGRect structure returning the nominal display size of the buffer. Returns a rectangle of zero size if called with either a non-CVImageBufferRef type or NULL.

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.

Availability

Available in OS X v10.4 and later.

Declared In

CVImageBuffer.h

CVImageBufferGetColorSpace

Returns the color space of a Core Video image buffer.

CGColorSpaceRef CVImageBufferGetColorSpace (
   CVImageBufferRef imageBuffer
);

Parameters

imageBuffer: The image buffer containing the color space to be retrieved.

Return Value

The color space of the buffer. Returns NULL if called with either a non-CVImageBufferRef type or NULL.

Availability

Available in OS X v10.4 and later.

Declared In

CVImageBuffer.h

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 containing the display size to be retrieved.

Return Value

A CGSize structure defining the nominal display size of the buffer Returns zero size if called with a non-CVImageBufferRef type or NULL.

Discussion

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

Availability

Available in OS X v10.4 and later.

Declared In

CVImageBuffer.h

CVImageBufferGetEncodedSize

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

CGSize CVImageBufferGetEncodedSize (
   CVImageBufferRef imageBuffer
);

Parameters

imageBuffer: The image buffer containing the encoded size to be retrieved.

Return Value

A CGSize structure defining the full encoded size of the buffer. Returns zero size if called with either a non-CVImageBufferRef type or NULL.

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.

Availability

Available in OS X v10.4 and later.

Declared In

CVImageBuffer.h

Data Types

CVImageBufferRef

A reference to 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.

Availability

Available in OS X v10.3 and later.

Declared In

CVImageBuffer.h

Constants

Image Buffer Attachment Keys

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

Declared in CVImageBuffer.h.

kCVImageBufferGammaLevelKey

The gamma level for this buffer (type CFNumber).

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

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureWidthKey

The clean aperture width (type CFNumber).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureHeightKey

The clean aperture height (type CFNumber).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureHorizontalOffsetKey

The clean aperture horizontal offset (type CFNumber).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureVerticalOffsetKey

The clean aperture vertical offset (type CFNumber).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldCountKey

The field count for the buffer (type CFNumber).

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

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailTemporalTopFirst

(type CFString).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailTemporalBottomFirst

(type CFString).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailSpatialFirstLineEarly

(type CFString).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailSpatialFirstLineLate

(type CFString).

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

Declared in CVImageBuffer.h.

kCVImageBufferPixelAspectRatioHorizontalSpacingKey

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

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPixelAspectRatioVerticalSpacingKey

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

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

Declared in CVImageBuffer.h.

kCVImageBufferDisplayWidthKey

The buffer display width (type CFNumber).

Available in OS X v10.4 and later.

Declared in CVImageBuffer.h.

kCVImageBufferDisplayHeightKey

The buffer display height (type CFNumber).

Available in 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 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 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 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 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 sub-dictionaries 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.

Image Buffer Chroma Subsampling Keys

Keys describing the format of the original subsampled data before conversion to 422/2vuy. To use these tags, the data must have been converted to 4:2:2 via simple pixel replication.

const CFStringRef kCVImageBufferChromaSubsamplingKey;
const CFStringRef kCVImageBufferChromaSubsampling_420;
const CFStringRef kCVImageBufferChromaSubsampling_422;
const CFStringRef kCVImageBufferChromaSubsampling_411;

Constants

kCVImageBufferChromaSubsamplingKey

A CFString containing the format of the original image buffer chroma subsampled data. It can have one of the following values:

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaSubsampling_420

Indicates that the original buffer chroma subsampled data was used 420 formatting. In 420 formatting, each pixel has a y value, while u and v values are shared amongst a square of 4 pixels.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaSubsampling_422

Indicates that the original buffer chroma subsampled data was used 422 formatting. In 422 formatting, each pixel has a y value, while u and v values are shared horizontally between 2 neighboring pixels.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaSubsampling_411

Indicates that the original buffer chroma subsampled data was used 411 formatting. In 411 formatting, each pixel has a y value, while u and v values are shared amongst a horizontal line of 4 pixels.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

Image Buffer Color Primaries Keys

The color primaries key is used to describe the rendering intent of the source video. It is used for color matching operations for a given video format or display along with “Image Buffer Transfer Functions”.

const CFStringRef kCVImageBufferColorPrimariesKey;
const CFStringRef kCVImageBufferColorPrimaries_ITU_R_709_2;
const CFStringRef kCVImageBufferColorPrimaries_EBU_3213;
const CFStringRef kCVImageBufferColorPrimaries_SMPTE_C;

Constants

kCVImageBufferColorPrimariesKey

A CFString describing the color primaries gamut. It can have one of the following values:

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferColorPrimaries_ITU_R_709_2

The color primaries gamut for HD video.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferColorPrimaries_EBU_3213

The color primaries gamut for PAL video.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferColorPrimaries_SMPTE_C

The color primaries gamut for standard-definition video.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

Image Buffer Transfer Functions

The transfer function key is used to describe the tonality (sometimes referred to as gamma) of a source video. It is used for color matching operations for a given video format or display along with “Image Buffer Color Primaries Keys”. The vast majority of applications should specify kCVImageBufferTransferFunction_ITU_R_709_2 for the transfer function key.

const CFStringRef kCVImageBufferTransferFunctionKey;
const CFStringRef kCVImageBufferTransferFunction_ITU_R_709_2;
const CFStringRef kCVImageBufferTransferFunction_SMPTE_240M_1995;
const CFStringRef kCVImageBufferTransferFunction_UseGamma;
const CFStringRef kCVImageBufferTransferFunction_EBU_3213;
const CFStringRef kCVImageBufferTransferFunction_SMPTE_C;

Constants

kCVImageBufferTransferFunctionKey

A CFString describing the transfer function. It can have one of the following values:

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferTransferFunction_ITU_R_709_2

The transfer function for high-definition and standard-definition video.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferTransferFunction_SMPTE_240M_1995

The transfer function for HDTV interim video. Most applications should not use this constant.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferTransferFunction_UseGamma

Specifies that the value for kCVImageBufferGammaLevelKey should be used in the transfer function.

Available in OS X v10.5 and later.

Declared in CVImageBuffer.h.

kCVImageBufferTransferFunction_EBU_3213

A transfer function meeting the EBU 3213 standard. Should not be used. (Deprecated. Use kCVImageBufferTransferFunction_ITU_R_709_2 instead.)

Available in OS X v10.5 and later.

Deprecated in OS X v10.6.

Declared in CVImageBuffer.h.

kCVImageBufferTransferFunction_SMPTE_C

A transfer function for standard-definition video. Should not be used. (Deprecated. Use kCVImageBufferTransferFunction_ITU_R_709_2 instead.)

Available in OS X v10.5 and later.

Deprecated in OS X v10.6.

Declared in CVImageBuffer.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.