CVBuffer Reference

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

Overview

Core Video buffers serve as an abstract base class that defines how to interact with buffers of data. All the other buffer types are derived from the CVBuffer type (and are typed as such). A CVBuffer object can hold video, audio, or possibly some other type of data. You can use the CVBuffer programming interface on any Core Video buffer.

Functions

Core Video buffer functions operate on all Core Video buffer types, including pixel buffers and OpenGL buffers, as well as OpenGL textures.

CVBufferGetAttachment

Returns a specific attachment of a Core Video buffer.

CFTypeRef CVBufferGetAttachment (
   CVBufferRef buffer,
   CFStringRef key,
   CVAttachmentMode *attachmentMode
);
Parameters
buffer

The Core Video buffer whose attachment you want to obtain.

key

A key in the form of a Core Foundation string identifying the desired attachment.

attachmentMode

On output, attachmentMode points to the mode of the attachment. See “CVBuffer Attachment Modes” for possible values. If the attachment mode is not defined, this parameter returns NULL.

Return Value

If found, the specified attachment.

Discussion

You can attach any Core Foundation object to a Core Video buffer to store additional information by calling CVBufferSetAttachment or CVBufferSetAttachments.

You can find predefined attachment keys in “CVBuffer Attachment Keys” and Image Buffer Attachment Keys.

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

CVBufferGetAttachments

Returns all attachments of a Core Video buffer.

CFDictionaryRef CVBufferGetAttachments (
   CVBufferRef buffer,
   CVAttachmentMode attachmentMode
);
Parameters
buffer

The Core Video buffer whose attachments you want to obtain.

attachmentMode

The mode of the attachments you want to obtain. See “CVBuffer Attachment Modes” for possible values.

Return Value

A Core Foundation dictionary with all buffer attachments identified by keys. If no attachment is present, the dictionary is empty. Returns NULL for an invalid attachment mode.

Discussion

CVBufferGetAttachments is a convenience call that returns all attachments with their corresponding keys in a Core Foundation dictionary.

You can find predefined attachment keys in “CVBuffer Attachment Keys” and Image Buffer Attachment Keys.

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

CVBufferPropagateAttachments

Copies all attachments that can be propagated from one Core Video buffer to another.

void CVBufferPropagateAttachments (
   CVBufferRef sourceBuffer,
   CVBufferRef destinationBuffer
);
Parameters
sourceBuffer

The buffer to copy attachments from.

destinationBuffer

The buffer to copy attachments to.

Discussion

CVBufferPropagateAttachments is a convenience call that copies all attachments with a mode of kCVAttachmentMode_ShouldPropagate from one buffer to another.

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

CVBufferRelease

Releases a Core Video buffer.

void CVBufferRelease (
   CVBufferRef buffer
);
Parameters
buffer

The Core Video buffer that you want to release.

Discussion

Like CFRelease, CVBufferRelease decrements the retain count of a Core Video buffer. If that count consequently becomes zero, the memory allocated to the object is deallocated and the object is destroyed. Unlike CFRelease, CVBufferRelease can be passed NULL without causing a crash.

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

CVBufferRemoveAllAttachments

Removes all attachments of a Core Video buffer.

void CVBufferRemoveAllAttachments (
   CVBufferRef buffer
);
Parameters
buffer

The Core Video buffer whose attachments you want to remove.

Discussion

CVBufferRemoveAllAttachments removes all attachments of a buffer and decrements their reference counts.

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

CVBufferRemoveAttachment

Removes a specific attachment of a Core Video buffer.

void CVBufferRemoveAttachment (
   CVBufferRef buffer,
   CFStringRef key
);
Parameters
buffer

The Core Video buffer containing the attachment to remove.

key

A key in the form of a Core Foundation string identifying the desired attachment.

Discussion

CVBufferRemoveAttachment removes an attachment identified by a key. If found, the attachment is removed and the retain count decremented.

You can find predefined attachment keys in “CVBuffer Attachment Keys” and Image Buffer Attachment Keys.

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

CVBufferRetain

Retains a Core Video buffer.

CVBufferRef CVBufferRetain (
   CVBufferRef buffer
);
Parameters
buffer

The Core Video buffer that you want to retain.

Return Value

For convenience, the same Core Video buffer you wanted to retain.

Discussion

Like CFRetain, CVBufferRetain increments the retain count of a Core Video buffer. Unlike CFRetain, CVBufferRetain can be passed NULL without causing a crash.

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

CVBufferSetAttachment

Sets or adds an attachment of a Core Video buffer.

void CVBufferSetAttachment (
   CVBufferRef buffer,
   CFStringRef key,
   CFTypeRef value,
   CVAttachmentMode attachmentMode
);
Parameters
buffer

The Core Video buffer to add or set the attachment to.

key

The key, in the form of a Core Foundation string, identifying the desired attachment.

value

The attachment in the form of a Core Foundation object. If this parameter is NULL, the function returns an error.

attachmentMode

The attachment mode for this attachment. See “CVBuffer Attachment Modes” for possible values. Any given attachment key may exist in only one mode at a time.

Discussion

You can attach any Core Foundation object to a Core Video buffer to store additional information. If the key doesn't currently exist for the buffer object when you call this function, the new attachment is added. If the key does exist, the existing attachment is replaced. In both cases the retain count of the attachment is incremented. The value can be any CFType. You can find predefined attachment keys in “CVBuffer Attachment Keys” and Image Buffer Attachment Keys.

You can also set attachments when creating a buffer by specifying them in the kCVBufferPropagatedAttachmentsKey or kCVBufferNonPropagatedAttachmentsKey attributes when creating the buffer.

To retrieve attachments, use the CVBufferGetAttachment or CVBufferGetAttachments functions.

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

CVBufferSetAttachments

Sets a set of attachments for a Core Video buffer.

void CVBufferSetAttachments (
   CVBufferRef buffer,
   CFDictionaryRef theAttachments,
   CVAttachmentMode attachmentMode
);
Parameters
buffer

The Core Video buffer to set the attachments to.

theAttachments

The attachments to set, in the form of a Core Foundation dictionary array.

attachmentMode

Specifies which attachment mode is desired for this attachment. A particular attachment key may only exist in a single mode at a time.

Discussion

CVBufferSetAttachments is a convenience call that in turn calls CVBufferSetAttachment for each key and value in the given dictionary. All key-value pairs must be in the root level of the dictionary.

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

Data Types

CVBufferRef

A reference to a Core Video buffer.

typedef struct __CVBuffer *CVBufferRef;
Discussion

CVBuffer objects represent an abstract type from which all Core Video buffers derive.

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

Constants

CVBuffer Attachment Keys

The attachment types for a Core Video buffer.

const CFStringRef kCVBufferMovieTimeKey;
const CFStringRef kCVBufferTimeValueKey;
const CFStringRef kCVBufferTimeScaleKey;
Constants
kCVBufferMovieTimeKey

The movie time associated with the buffer. Generally only available for frames emitted by QuickTime (type CFDictionary containing the kCVBufferTimeValueKey and kCVBufferTimeScaleKey keys).

Available in iOS 4.0 and later.

Declared in CVBuffer.h.

kCVBufferTimeValueKey

The actual time value associated with the movie.

Available in iOS 4.0 and later.

Declared in CVBuffer.h.

kCVBufferTimeScaleKey

The time scale associated with the movie.

Available in iOS 4.0 and later.

Declared in CVBuffer.h.

CVBuffer Attachment Modes

The propagation modes of a Core Video buffer attachment.

enum {
   kCVAttachmentMode_ShouldNotPropagate    = 0,
   kCVAttachmentMode_ShouldPropagate       = 1,
};
typedef uint32_t CVAttachmentMode;
Constants
kCVAttachmentMode_ShouldNotPropagate

Do not propagate this attachment.

Available in iOS 4.0 and later.

Declared in CVBuffer.h.

kCVAttachmentMode_ShouldPropagate

Copy this attachment when using the CVBufferPropagateAttachments function. For example, in most cases, you would want to propagate an attachment bearing a timestamp to each successive buffer.

Available in iOS 4.0 and later.

Declared in CVBuffer.h.

Discussion

You set these attributes when adding attachments to a CVBuffer object.

CVBuffer Attribute Keys

The attributes associated with Core Video buffers.

const CFStringRef kCVBufferPropagatedAttachmentsKey;
const CFStringRef kCVBufferNonPropagatedAttachmentsKey;
Constants
kCVBufferPropagatedAttachmentsKey

Attachments that should be copied when using the CVBufferPropagateAttachments function (type CFDictionary, containing a list of attachments as key-value pairs).

Available in iOS 4.0 and later.

Declared in CVBuffer.h.

kCVBufferNonPropagatedAttachmentsKey

Attachments that should not be copied when using the CVBufferPropagateAttachments function (type CFDictionary, containing a list of attachments as key-value pairs).

Available in iOS 4.0 and later.

Declared in CVBuffer.h.

Discussion

These attributes let you set multiple attachments at the time of buffer creation, rather than having to call CVBufferSetAttachment for each attachment.