CVPixelFormatDescription Reference

Framework	System/Library/Frameworks/QuartzCore.framework
Companion guide	Core Video Programming Guide
Declared in	CVPixelBuffer.h CVPixelFormatDescription.h

Overview

The Core Video pixel format description API defines functions and types for defining custom pixel formats. You should only use pixel format descriptions if you need to define a custom pixel format.

Functions

CVPixelFormatDescriptionArrayCreateWithAllPixelFormatTypes

Returns all the pixel format descriptions known to Core Video.

CFArrayRef CVPixelFormatDescriptionArrayCreateWithAllPixelFormatTypes (
   CFAllocatorRef allocator
);

Parameters

allocator: The allocator to use when creating the description. Pass NULL to specify the default allocator.

Return Value

An array of Core Foundation dictionaries, each containing a pixel format description. See “Pixel Format Description Keys” for a list of keys relevant to the format description.

Availability

Available in OS X v10.4 and later.

Declared In

CVPixelFormatDescription.h

CVPixelFormatDescriptionCreateWithPixelFormatType

Creates a pixel format description from a given OSType identifier.

CFDictionaryRef CVPixelFormatDescriptionCreateWithPixelFormatType (
   CFAllocatorRef allocator,
   OSType pixelFormat
);

Parameters

allocator: The allocator to use when creating the description. Pass NULL to specify the default allocator.
pixelFormat: A four-character code that identifies the pixel format you want to obtain.

Return Value

A Core Foundation dictionary containing the pixel format description. See “Pixel Format Description Keys” for a list of keys relevant to the format description.

Availability

Available in OS X v10.4 and later.

Declared In

CVPixelFormatDescription.h

CVPixelFormatDescriptionRegisterDescriptionWithPixelFormatType

Registers a pixel format description with Core Video.

void CVPixelFormatDescriptionRegisterDescriptionWithPixelFormatType (
   CFDictionaryRef description,
   OSType pixelFormat
);

Parameters

description: A Core Foundation dictionary containing the pixel format description. See “Pixel Format Description Keys” for a list of required and optional keys.
pixelFormat: The four-character code (type OSType) identifier for this pixel format.

Discussion

If you are using a custom pixel format, you must register the format with Core Video using this function. See Technical Q&A 1401: Registering Custom Pixel Formats with QuickTime and Core Video for more details.

Availability

Available in OS X v10.4 and later.

Declared In

CVPixelFormatDescription.h

Callbacks

CVFillExtendedPixelsCallBack

Defines a pointer to a custom extended pixel-fill function, which is called whenever the system needs to pad a buffer holding your custom pixel format.

typedef Boolean (*CVFillExtendedPixelsCallBack)(
   CVPixelBufferRef pixelBuffer,
   void *refCon
   );

Here is how you would declare a custom fill function named MyExtendedPixelFillFunc

Boolean MyExtendedPixelFillFunc (
   CVPixelBufferRef pixelBuffer,
   void *refCon
   );

Parameters

pixelBuffer: The pixel buffer to be padded.
refCon: A pointer to application-defined data. This is the same value you stored in the CVFillExtendedPixelsCallBackData structure.

Return Value

If true, the padding was successful; otherwise, false.

Discussion

For more information on implementing a custom extended pixel-fill callback, see Technical Q&A 1440: Implementing a CVFillExtendedPixelsCallback.

Availability

Available in OS X v10.3 and later.

Declared In

CVPixelFormatDescription.h

Data Types

CVFillExtendedPixelsCallBackData

A structure for holding information that describes a custom extended pixel fill algorithm.

typedef struct {
   CFIndex version;
   CVFillExtendedPixelsCallBack    fillCallBack;
   void *refCon;
} CVFillExtendedPixelsCallBackData;

Fields

version: The version of this fill algorithm.
fillCallback: A pointer to a custom pixel fill function.
refCon: A pointer to application-defined data that is passed to your custom pixel fill function.

Discussion

You must fill out this structure and store it as part of your pixel format description Core Foundation dictionary (key: kCVPixelFormatFillExtendedPixelsCallback, type: CFData). However, if your custom pixel format never needs the functionality of CVPixelBufferFillExtendedPixels, you don’t need to add this key or implement the associated callback.

For more information about defining a custom pixel format, see “Pixel Format Description Keys.”

Availability

Available in OS X v10.3 and later.

Declared In

CVPixelFormatDescription.h

Constants

Pixel Format Description Keys

The attributes of a pixel format.

const CFStringRef kCVPixelFormatName;
const CFStringRef kCVPixelFormatConstant;
const CFStringRef kCVPixelFormatCodecType;
const CFStringRef kCVPixelFormatFourCC;
const CFStringRef kCVPixelFormatContainsAlpha;
const CFStringRef kCVPixelFormatPlanes;
const CFStringRef kCVPixelFormatBlockWidth;
const CFStringRef kCVPixelFormatBlockHeight;
const CFStringRef kCVPixelFormatBitsPerBlock;
const CFStringRef kCVPixelFormatBlockHorizontalAlignment;
const CFStringRef kCVPixelFormatBlockVerticalAlignment;
const CFStringRef kCVPixelFormatBlackBlock;
const CFStringRef kCVPixelFormatHorizontalSubsampling;
const CFStringRef kCVPixelFormatVerticalSubsampling;
   
const CFStringRef kCVPixelFormatOpenGLFormat;
const CFStringRef kCVPixelFormatOpenGLType;
const CFStringRef kCVPixelFormatOpenGLInternalFormat;
   
const CFStringRef kCVPixelFormatCGBitmapInfo;
   
const CFStringRef kCVPixelFormatQDCompatibility;
const CFStringRef kCVPixelFormatCGBitmapContextCompatibility;
const CFStringRef kCVPixelFormatCGImageCompatibility;
const CFStringRef kCVPixelFormatOpenGLCompatibility;
   
const CFStringRef kCVPixelFormatFillExtendedPixelsCallback;

Constants

kCVPixelFormatName

The name of the pixel format (type CFString). This should be the same as the codec name you would use in QuickTime.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatConstant

The pixel format constant for QuickTime.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCodecType

The codec type (type CFString). For example, '2vuy' or k422YpCbCr8CodecType.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatFourCC

The Microsoft FourCC equivalent code for this pixel format (type CFString).

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatContainsAlpha

A Boolean value where kCFBooleanTrue indicates that the format contains alpha and some images may be considered transparent; kCFBooleanFalse indicates that there is no alpha and images are always opaque.

Available in OS X v10.7 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatPlanes

The number of image planes associated with this format (type CFNumber). Each plane may contain a single component or an interleaved set of components. Note that if your pixel format is not planar, you can put the required format keys at the top-level dictionary.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockWidth

The width, in pixels, of the smallest byte-addressable group of pixels (type CFNumber). Used to assist with allocating memory for pixel formats that don’t have an integer value for bytes per pixel. Assumed to be 1 if this key is not present. Here are some examples of block widths for standard pixel formats:

8-bit luminance only, block width is 1, the bits per block value is 8.
16-bit 1555 RGB, block width is 1, the bits per block value is 16.
32-bit 8888 ARGB, block width is 1, the bits per block value is 32.
2vuy (CbYCrY), block width is 2, the bits per block value is 32.
1-bit bitmap, block width is 8, the bits per block value is 8.
v210, block width is 6, the bits per block value is 128 .

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockHeight

The height, in pixels, of the smallest byte-addressable group of pixels (type CFNumber). Assumed to be 1 if this key is not present.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBitsPerBlock

The number of bits per block. For simple pixel formats, this value is the same as the traditional bits-per-pixel value. This key is mandatory in pixel format descriptions. See the description for kCVPixelFormatBlockWidth for examples of bits-per-block values.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockHorizontalAlignment

The horizontal alignment requirements of this format (type CFNumber). For example,the alignment for v210 would be 8 here for the horizontal case to match the standard v210 row alignment value of 48. Assumed to be 1 if this key is not present.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlockVerticalAlignment

The vertical alignment requirements of this format (type CFNumber). Assumed to be 1 if this key is not present.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatBlackBlock

The bit pattern for a block of black pixels (type CFData. If this key is absent, black is assumed to be all zeros. If present, this should be bitsPerPixel bits long; if bitsPerPixel is less than a byte, repeat the bit pattern for the full byte.

Available in OS X v10.6 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatHorizontalSubsampling

Horizontal subsampling information for this plane (type CFNumber). Assumed to be 1 if this key is not present.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatVerticalSubsampling

Vertical subsampling information for this plane (type CFNumber). Assumed to be 1 if this key is not present.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLFormat

The OpenGL format used to describe this image plane (if applicable). See the OpenGL specification for possible values.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLType

The OpenGL type to describe this image plane (if applicable). See the OpenGL specification for possible values.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLInternalFormat

The OpenGL internal format for this pixel format (if applicable). See the OpenGL specification for possible values.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCGBitmapInfo

The Core Graphics bitmap information for this pixel format (if applicable).

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatQDCompatibility

If true, this format is compatible with QuickDraw (type CFBoolean).

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCGBitmapContextCompatibility

If true, this format is compatible with Core Graphics bitmap contexts(type CFBoolean).

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatCGImageCompatibility

If true, this format is compatible with the CGImage type (type CFBoolean).

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatOpenGLCompatibility

If true, this format is compatible with OpenGL (type CFBoolean).

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

kCVPixelFormatFillExtendedPixelsCallback

A custom extended pixel fill algorithm (type CFData). See CVFillExtendedPixelsCallBack and CVFillExtendedPixelsCallBackData for more information.

Available in OS X v10.4 and later.

Declared in CVPixelFormatDescription.h.

Discussion

If you need to define a custom pixel format, you must specify these keys in a Core Foundation dictionary. For information about registering your pixel format, see Technical Q&A 1401: Registering Custom Pixel Formats with QuickTime and Core Video.

In most cases you do not need to specify your own pixel format.

Pixel Format Types

Core Video does not provide support for all of these formats; this list defines only their names.

enum {
   kCVPixelFormatType_1Monochrome    = 0x00000001,
   kCVPixelFormatType_2Indexed       = 0x00000002,
   kCVPixelFormatType_4Indexed       = 0x00000004,
   kCVPixelFormatType_8Indexed       = 0x00000008,
   kCVPixelFormatType_1IndexedGray_WhiteIsZero = 0x00000021,
   kCVPixelFormatType_2IndexedGray_WhiteIsZero = 0x00000022,
   kCVPixelFormatType_4IndexedGray_WhiteIsZero = 0x00000024,
   kCVPixelFormatType_8IndexedGray_WhiteIsZero = 0x00000028,
   kCVPixelFormatType_16BE555        = 0x00000010,
   kCVPixelFormatType_16LE555        = 'L555',
   kCVPixelFormatType_16LE5551       = '5551',
   kCVPixelFormatType_16BE565        = 'B565',
   kCVPixelFormatType_16LE565        = 'L565',
   kCVPixelFormatType_24RGB          = 0x00000018,
   kCVPixelFormatType_24BGR          = '24BG',
   kCVPixelFormatType_32ARGB         = 0x00000020,
   kCVPixelFormatType_32BGRA         = 'BGRA',
   kCVPixelFormatType_32ABGR         = 'ABGR',
   kCVPixelFormatType_32RGBA         = 'RGBA',
   kCVPixelFormatType_64ARGB         = 'b64a',
   kCVPixelFormatType_48RGB          = 'b48r',
   kCVPixelFormatType_32AlphaGray    = 'b32a',
   kCVPixelFormatType_16Gray         = 'b16g',
   kCVPixelFormatType_30RGB          = 'R10k',
   kCVPixelFormatType_422YpCbCr8     = '2vuy',
   kCVPixelFormatType_4444YpCbCrA8   = 'v408',
   kCVPixelFormatType_4444YpCbCrA8R  = 'r408',
   kCVPixelFormatType_4444AYpCbCr8   = 'y408',
   kCVPixelFormatType_4444AYpCbCr16  = 'y416',
   kCVPixelFormatType_444YpCbCr8     = 'v308',
   kCVPixelFormatType_422YpCbCr16    = 'v216',
   kCVPixelFormatType_422YpCbCr10    = 'v210',
   kCVPixelFormatType_444YpCbCr10    = 'v410',
   kCVPixelFormatType_420YpCbCr8Planar = 'y420',
   kCVPixelFormatType_420YpCbCr8PlanarFullRange    = 'f420',
   kCVPixelFormatType_422YpCbCr_4A_8BiPlanar = 'a2vy',
   kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange = '420v',
   kCVPixelFormatType_420YpCbCr8BiPlanarFullRange  = '420f',
   kCVPixelFormatType_422YpCbCr8_yuvs = 'yuvs',
   kCVPixelFormatType_422YpCbCr8FullRange = 'yuvf',
   kCVPixelFormatType_OneComponent8  = 'L008',
   kCVPixelFormatType_TwoComponent8  = '2C08',
};