CVImageBuffer Reference

Derived from
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 clean aperture 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 iOS 4.0 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 iOS 4.0 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. When creating a CIImage object from a Core Video image buffer, you use this call to retrieve the image size.

Availability
  • Available in iOS 4.0 and later.
Declared In
CVImageBuffer.h

CVImageBufferIsFlipped

Returns a Boolean value indicating whether the image is flipped vertically.

Boolean CVImageBufferIsFlipped(
   CVImageBufferRef imageBuffer
);
Parameters
imageBuffer

The image buffer of interest.

Return Value

Returns true if {0,0} represents the upper left of the image, or false if {0,0} represents the lower left of the image.

Availability
  • Available in iOS 4.0 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 iOS 4.0 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 kCVImageBufferPreferredCleanApertureKey;
const CFStringRef kCVImageBufferCleanApertureKey;
const CFStringRef kCVImageBufferFieldCountKey;
const CFStringRef kCVImageBufferFieldDetailKey;
const CFStringRef kCVImageBufferPixelAspectRatioKey;
const CFStringRef kCVImageBufferDisplayDimensionsKey;
const CFStringRef kCVImageBufferICCProfileKey;
const CFStringRef kCVImageBufferYCbCrMatrixKey;
const CFStringRef kCVImageBufferColorPrimariesKey;
const CFStringRef kCVImageBufferTransferFunctionKey;
const CFStringRef kCVImageBufferChromaLocationTopFieldKey;
const CFStringRef kCVImageBufferChromaLocationBottomFieldKey;
const CFStringRef kCVImageBufferChromaSubsamplingKey;
Constants
kCVImageBufferCGColorSpaceKey

The color space for the buffer (type CGColorSpaceRef).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureKey

A dictionary describing the clean aperture for the buffer using the keys in “Image Buffer Clean Aperture Keys” (type CFDictionary).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPreferredCleanApertureKey

A dictionary describing the preferred clean aperture for the buffer using the keys in “Image Buffer Clean Aperture Keys” (type CFDictionary).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldCountKey

The field count for the buffer (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailKey

One of the values in “Image Buffer Field Detail Constants,” indicating the ordering of interlaced video data in the buffer (type CSString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPixelAspectRatioKey

A dictionary describing the pixel aspect ratio for the buffer using the keys in “Image Buffer Display Dimensions Keys” (type CFDictionary).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferDisplayDimensionsKey

A dictionary describing the display dimensions for the buffer using the keys in “Image Buffer Display Dimensions Keys” (type CFDictionary).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferGammaLevelKey

The gamma level for this buffer (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferICCProfileKey

A representation of the ICC color profile (type CFData).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferYCbCrMatrixKey

One of the values in “Image Buffer YCbCr Matrix Constants,” indicating the type of conversion matrix used when converting image buffer data from the YCbCr color space to the RGB color space (type CSString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferColorPrimariesKey

One of the values in “Image Buffer Color Primaries Constants,” indicating the color primaries gamut for the image buffer (type CSString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferTransferFunctionKey

One of the values in “Image Buffer Transfer Function Constants,” indicating the transfer function for the image buffer (type CSString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocationTopFieldKey

One of the values in “Image Buffer Chroma Location Constants,” indicating the location of chroma information in the image buffer (type CSString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocationBottomFieldKey

One of the values in “Image Buffer Chroma Location Constants,” indicating the location of chroma information in the image buffer (type CSString).

This key only applies to interlaced image data. For progressive-scan image data, only the kCVImageBufferChromaLocationTopFieldKey applies.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaSubsamplingKey

One of the values in “Image Buffer Chroma Subsampling Constants,” indicating the original format of subsampled data in the image buffer (type CSString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

Image buffer attachment keys are stored in a Core Foundation dictionary associated with an image buffer. To read and write buffer attachments, use the CVBufferGetAttachment and CVBufferSetAttachment functions or other CVBuffer functions. (See CVBuffer Reference.)

Image Buffer Clean Aperture Keys

Keys describing the clean aperture of an image buffer.

const CFStringRef kCVImageBufferCleanApertureWidthKey;
const CFStringRef kCVImageBufferCleanApertureHeightKey;
const CFStringRef kCVImageBufferCleanApertureHorizontalOffsetKey;
const CFStringRef kCVImageBufferCleanApertureVerticalOffsetKey;
Constants
kCVImageBufferCleanApertureWidthKey

The clean aperture width (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureHeightKey

The clean aperture height (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureHorizontalOffsetKey

The clean aperture horizontal offset from the center of the image buffer (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferCleanApertureVerticalOffsetKey

The clean aperture vertical offset from the center of the image buffer (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

These keys are stored in a Core Fundation dictionary attached to an image buffer using the kCVImageBufferCleanApertureKey or kCVImageBufferPreferredCleanApertureKey key. An image’s clean aperture is a region of video free from transition artifacts caused by the encoding of the signal. This is the region of video that should be displayed.

Image Buffer Field Detail Constants

Constants indicating the field ordering of interlaced video in an image buffer.

const CFStringRef kCVImageBufferFieldDetailTemporalTopFirst;
const CFStringRef kCVImageBufferFieldDetailTemporalBottomFirst;
const CFStringRef kCVImageBufferFieldDetailSpatialFirstLineEarly;
const CFStringRef kCVImageBufferFieldDetailSpatialFirstLineLate;
Constants
kCVImageBufferFieldDetailTemporalTopFirst

The image buffer contains complete fields in alternating order, with the top (or odd-numbered) fields containing image data captured at an earlier time than bottom (or even-numbered) fields (type CFString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailTemporalBottomFirst

The image buffer contains complete fields in alternating order, with the bottom (or even-numbered) fields containing image data captured at an earlier time than top (or odd-numbered) fields (type CFString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailSpatialFirstLineEarly

The image buffer contains interleaved fields, with the first line of image data corresponding to the first top (odd-numbered) field (type CFString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferFieldDetailSpatialFirstLineLate

The image buffer contains interleaved fields, with the first line of image data corresponding to the first bottom (even-numbered) field (type CFString).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

One of these values is attached to an image buffer using the kCVImageBufferFieldDetailKey key.

Image Buffer Pixel Aspect Ratio Keys

Keys describing the pixel aspect ratio of an image buffer.

const CFStringRef kCVImageBufferPixelAspectRatioHorizontalSpacingKey;
const CFStringRef kCVImageBufferPixelAspectRatioVerticalSpacingKey;
Constants
kCVImageBufferPixelAspectRatioHorizontalSpacingKey

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

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferPixelAspectRatioVerticalSpacingKey

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

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

These keys are stored in a Core Fundation dictionary attached to an image buffer using the kCVImageBufferPixelAspectRatioKey key.

Image Buffer Display Dimensions Keys

Keys describing the display dimensions of an image buffer.

const CFStringRef kCVImageBufferDisplayWidthKey;
const CFStringRef kCVImageBufferDisplayHeightKey;
Constants
kCVImageBufferDisplayWidthKey

The buffer display width (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferDisplayHeightKey

The buffer display height (type CFNumber).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

These keys are stored in a Core Fundation dictionary attached to an image buffer using the kCVImageBufferPixelAspectRatioKey key.

Image Buffer YCbCr Matrix Constants

Constants indicating the type of conversion matrix used when converting image buffer data from the YCbCr color space to the RGB color space.

const CFStringRef kCVImageBufferYCbCrMatrix_ITU_R_709_2;
const CFStringRef kCVImageBufferYCbCrMatrix_ITU_R_601_4;
const CFStringRef kCVImageBufferYCbCrMatrix_SMPTE_240M_1995;
Constants
kCVImageBufferYCbCrMatrix_ITU_R_709_2

The conversion matrix for HDTV digital television images (following the ITU R 709 standard).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferYCbCrMatrix_ITU_R_601_4

The conversion matrix for standard digital television images (following the ITU R 601 standard).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferYCbCrMatrix_SMPTE_240M_1995

The conversion matrix for 1920 x 1135 HDTV images (following the SMPTE 240M 1995 standard).

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

One of these values is attached to an image buffer using the kCVImageBufferYCbCrMatrixKey key.

Image Buffer Color Primaries Constants

Constants indicating the color primaries gamut for the image buffer.

const CFStringRef kCVImageBufferColorPrimaries_ITU_R_709_2;
const CFStringRef kCVImageBufferColorPrimaries_EBU_3213;
const CFStringRef kCVImageBufferColorPrimaries_SMPTE_C;
const CFStringRef kCVImageBufferColorPrimaries_P22;
Constants
kCVImageBufferColorPrimaries_ITU_R_709_2

The color primaries gamut for HD video.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferColorPrimaries_EBU_3213

The color primaries gamut for PAL video.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferColorPrimaries_SMPTE_C

The color primaries gamut for standard-definition video.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferColorPrimaries_P22

The color primaries gamut for sRGB video.

Available in iOS 6.0 and later.

Declared in CVImageBuffer.h.

Discussion

One of these values is attached to an image buffer using the kCVImageBufferColorPrimariesKey key. The color primaries gamut describes the rendering intent of an image and is used for color matching operations, along with a transfer function (see “Image Buffer Transfer Function Constants”).

Image Buffer Transfer Function Constants

Constants indicating the transfer function for the image buffer.

const CFStringRef kCVImageBufferTransferFunction_ITU_R_709_2;
const CFStringRef kCVImageBufferTransferFunction_SMPTE_240M_1995;
const CFStringRef kCVImageBufferTransferFunction_UseGamma;
Constants
kCVImageBufferTransferFunction_ITU_R_709_2

The transfer function for high-definition and standard-definition video. Most apps should use this constant.

Available in iOS 4.0 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 iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferTransferFunction_UseGamma

The transfer function is defined by the value of the kCVImageBufferGammaLevelKey key.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

One of these values is attached to an image buffer using the kCVImageBufferTransferFunctionKey key. The transfer function describes the tonality of an image and is used for color matching operations, along with a color primaries gamut (see “Image Buffer Color Primaries Constants”). Most apps should specify the kCVImageBufferTransferFunction_ITU_R_709_2 transfer function.

Image Buffer Chroma Location Constants

Constants indicating locations for chroma samples in the image buffer.

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
kCVImageBufferChromaLocation_Left

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

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_Center

The chroma sample is fully centered.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_TopLeft

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

Available in iOS 4.0 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 iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaLocation_BottomLeft

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

Available in iOS 4.0 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 iOS 4.0 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 iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

For progressive-scan images, one of these values is attached to an image buffer using the kCVImageBufferChromaLocationTopFieldKey key. For interlaced images, one of these values is attached using the kCVImageBufferChromaLocationTopFieldKey key and another using the kCVImageBufferChromaLocationBottomFieldKey key.

Image Buffer Chroma Subsampling Constants

Constants indicating the original format of subsampled data in the image buffer before conversion to 422/2vuy format.

const CFStringRef kCVImageBufferChromaSubsampling_420;
const CFStringRef kCVImageBufferChromaSubsampling_422;
const CFStringRef kCVImageBufferChromaSubsampling_411;
Constants
kCVImageBufferChromaSubsampling_420

The original chroma-subsampled data used 4:2:0 formatting. Each pixel has a Y value, and U and V values are shared within a square of 4 pixels.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaSubsampling_422

The original chroma-subsampled data used 4:2:2 formatting. Each pixel has a Y value, and U and V values are shared horizontally between 2 neighboring pixels.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

kCVImageBufferChromaSubsampling_411

The original chroma-subsampled data used 4:1:1 formatting. Each pixel has a Y value, and U and V values are shared along a horizontal line of 4 pixels.

Available in iOS 4.0 and later.

Declared in CVImageBuffer.h.

Discussion

One of these values is attached to an image buffer using the kCVImageBufferChromaSubsamplingKey key. To use these tags, the image buffer data must have been converted to 4:2:2 format using simple pixel replication.