CMBufferQueue Reference

Derived from
Framework
CoreMedia.framework
Declared in
CMBufferQueue.h

Overview

This document describes the API for creating and manipulating CMBufferQueue structs.

CMBufferQueues are Core Foundation objects that implement a queue of timed buffers. These buffers can be of any Core Foundation-based type (CFTypeRef), but must have a concept of duration. During CMBufferQueue creation, a set of callbacks is provided, one of which is a required callback that returns the duration of the Core Foundation-based buffer object. A standard callback struct for CMSampleBuffers is provided as a convenience. These callbacks are called synchronously from within various CMBufferQueue APIs, on the thread that called the API.

CMBufferQueues are designed to be read and written from different threads in a producer/consumer model. While this is generally two threads (one producer/enqueuer, one dequeuer/consumer), CMBufferQueues can service any number of threads enqueueing and/or dequeueing buffers. In the CMBufferQueue APIs, all operations (not just CMBufferQueueEnqueue and CMBufferQueueDequeueAndRetain, but Comparing CMBufferQueue, CMBufferQueueInstallTrigger and so on) are made atomic by use of a single mutex (one mutex per created queue object).

By default, a CMBufferQueue is a FIFO queue, but if a comparison callback is provided, the resulting CMBufferQueue will be sorted based on that callback. For example, one might create a CMBufferQueue where the buffers are enqueued in decode order, and dequeued in presentation order, by providing a comparison callback that sorts by presentation timestamp.

CMBufferQueues retain the enqueued buffer during Enqueue, so the client can release the buffer if it has no further need of the reference. During CMBufferQueueDequeueAndRetain, the buffer is retained on behalf of the client, and released by the queue. The result is that the retain count remains the same, and the ownership of the buffer is transferred from the queue to the client.

If provided with a buffer-readiness callback, CMBufferQueues can check for buffer readiness during CMBufferQueueDequeueIfDataReadyAndRetain. If that callback is not provided, all buffers are assumed to be ready, and there is no difference between CMBufferQueueDequeueAndRetain, and CMBufferQueueDequeueIfDataReadyAndRetain.

CMBufferQueues also implement CMBufferQueueIsEmpty and CMBufferQueueTestTrigger, with the help of optional callbacks that get decode and presentation timestamps from a buffer. If either or both of these callbacks is not provided, kCMTimeInvalid will be returned for the missing timestamp(s).

CMBufferQueues can be marked with an end-of-data (CMBufferQueueMarkEndOfData). Once so marked, further enqueues will fail, and once all the buffers have been dequeued, the queue is permanently empty ("at end of data") until Reset is called. Reset empties the queue and undoes the end-of-data marking.

The current status of a CMBufferQueue can be interrogated. You can test for emptiness (CMBufferQueueCreate), current queue duration (“Comparing CMBufferQueue”), and end-of-data status (CMBufferQueueContainsEndOfData and CMBufferQueueIsAtEndOfData).

You can install trigger callbacks (using CMBufferQueueInstallTrigger) to get notifications of various queue state transitions, such as “duration becomes less than 1 second”. The queue cannot be modified during a trigger callback, but it can be interrogated. Trigger conditions can be tested explicitly as well (CMBufferQueueTestTrigger). Triggers with NULL callbacks can be added to a queue for this type of use, but triggers with callbacks can also have their conditions explicitly tested.

Trigger callbacks may be called from any CMBufferQueue API that modifies the total duration of the queue (such as Enqueue/Dequeue/Reset). Trigger callbacks are called synchronously, on the thread that called the API.

Modifying the state of the queue in any way from within a trigger callback is forbidden, and will fail, returning kCMBufferQueueError_CannotModifyQueueFromTriggerCallback.

An attempt to Enqueue onto a full queue or to Dequeue from an empty queue will not block, but will return immediately with an error (or with a NULL buffer). Triggers should be installed by the client to manage the client's knowledge of queue fullness. The use of repeated retries (polling) is discouraged as an inefficient use of resources.

Functions by Task

Creating CMBufferQueue

Controlling CMBufferQueue

Comparing CMBufferQueue

Accessing CMBufferQueue

Functions

CMBufferQueueCallForEachBuffer

Calls a function for every buffer in a queue.

OSStatus CMBufferQueueCallForEachBuffer (
   CMBufferQueueRef queue,
   OSStatus (*callback)(CMBufferRef buffer, void *refcon),
   void *refcon
);
Parameters
queue

CMBufferQueue that may contain multiple buffers.

refcon

Reference constant supplied to the callback function.

callback

Function to be called for each buffer. The callback may modify buffer attachments but should not modify sort-affecting properties (eg, timestamps). The callback should not make other calls to the buffer queue.

Return Value

A result code. See “Result Codes.”

Discussion

If the callback function returns an error, iteration will stop immediately and the error will be returned.

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

CMBufferQueueContainsEndOfData

Returns whether or not a CMBufferQueue has been marked with EndOfData.

Boolean CMBufferQueueContainsEndOfData (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated..

Return Value

A Boolean indicating whether CMBufferQueue has been marked with EndOfData.

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

CMBufferQueueCreate

Creates a CMBufferQueue object.

OSStatus CMBufferQueueCreate (
   CFAllocatorRef allocator,
   CMItemCount capacity,
   const CMBufferCallbacks *callbacks,
   CMBufferQueueRef *queueOut
);
Parameters
allocator

The allocator to use for allocating the CMBufferQueue object. Pass kCFAllocatorDefault to use the default allocator.

capacity

Maximum number of buffers in the queue. Pass 0 to create a queue that will grow as needed.

callbacks

Callbacks the queue should use to interrogate the buffer objects. This struct is copied internally, so the client can pass a pointer to a temporary struct on the stack.

queueOut

On Output, the newly created CMBufferQueue.

Return Value

A result code. See “Result Codes.”

Discussion

On return, the caller owns the returned CMBufferQueue, and must release it when done with it.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMBufferQueue.h

CMBufferQueueDequeueAndRetain

Dequeues a buffer from a CMBufferQueue.

CMBufferRef CMBufferQueueDequeueAndRetain (
   CMBufferQueueRef queue
);
Parameters
queue

The CMBufferQueue from which to dequeue a buffer.

Return Value

The dequeued buffer. Will be NULL if the queue is empty.

Discussion

The buffer is released by the queue, but it is also retained for the client. Buffer ownership is thereby transferred from queue to client. The client need not retain the buffer, but is responsible to release it when done with it.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMBufferQueue.h

CMBufferQueueDequeueIfDataReadyAndRetain

Dequeues a buffer from a CMBufferQueue if it is ready.

CMBufferRef CMBufferQueueDequeueIfDataReadyAndRetain (
   CMBufferQueueRef queue
);
Parameters
queue

The CMBufferQueue from which to dequeue a buffer (if the buffer is ready).

Return Value

The dequeued buffer. Will be NULL if the queue is empty, or if the buffer to be dequeued is not yet ready.

Discussion

The buffer is released by the queue, but it is also retained for the client. Buffer ownership is thereby transferred from queue to client. The client need not retain the buffer, but is responsible to release it when done with it.

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

CMBufferQueueEnqueue

Enqueues a buffer onto a CMBufferQueue.

OSStatus CMBufferQueueEnqueue (
   CMBufferQueueRef queue,
   CMBufferRef buf
);
Parameters
queue

The CMBufferQueue on which to enqueue the buffer.

buf

The buffer to enqueue.

Return Value

A result code. See “Result Codes.”

Discussion

The buffer is retained by the queue, so the client can safely release the buffer if it has no further use for it. If the compare callback is non-NULL, this API performs an insertion sort using that compare operation. If the validation callback is non-NULL, this API calls it; if it returns a nonzero OSStatus, the buffer will not be enqueued and this API will return the same error OSStatus.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMBufferQueue.h

CMBufferQueueGetBufferCount

Gets the number of buffers in the queue.

CMItemCount CMBufferQueueGetBufferCount (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

Returns the number of buffers in the CMBufferQueue.

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

CMBufferQueueGetCallbacksForUnsortedSampleBuffers

Returns a pointer to a callback struct for unsorted CMSampleBuffers, provided as a convenience.

const CMBufferCallbacks * CMBufferQueueGetCallbacksForUnsortedSampleBuffers (void);
Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMBufferQueue.h

CMBufferQueueGetDuration

Gets the duration of a CMBufferQueue.

CMTime CMBufferQueueGetDuration (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

Returns sum of all the individual buffer durations in the CMBufferQueue.

Discussion

The duration of the CMBufferQueue is the sum of all the individual buffer durations, as reported by the getDuration callback (provided to Creating CMBufferQueue). If there are no buffers in the queue, kCMTimeZero will be returned.

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

CMBufferQueueGetEndPresentationTimeStamp

Gets the greatest end presentation timestamp of a CMBufferQueue.

CMTime CMBufferQueueGetEndPresentationTimeStamp (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

Returns the sum of PresentationTimeStamp and the individual buffer durations.

Discussion

This is the maximum end time (PTS + duration) of buffers in the queue. If the getPresentationTimeStamp callback is NULL, kCMTimeInvalid will be returned.

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

CMBufferQueueGetFirstDecodeTimeStamp

Gets the decode timestamp of the first buffer in a CMBufferQueue.

CMTime CMBufferQueueGetFirstDecodeTimeStamp (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

The decode timestamp of the first buffer in the interrogated CMBufferQueue.

Discussion

This API is is a faster alternative to CMBufferQueueIsEmpty, but only gives the same answer if your queue is in decode order. If the getDecodeTimeStamp callback is NULL, kCMTimeInvalid will be returned.

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

CMBufferQueueGetFirstPresentationTimeStamp

Gets the presentation timestamp of the first buffer in a CMBufferQueue.

CMTime CMBufferQueueGetFirstPresentationTimeStamp (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

The presentation timestamp of the first buffer in the interrogated CMBufferQueue.

Discussion

This API is is a faster alternative to CMBufferQueueTestTrigger, but only works if you know your queue is sorted by presentation timestamp. If the getPresentationTimeStamp callback is NULL, kCMTimeInvalid will be returned.

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

CMBufferQueueGetHead

Retrieves the next-to-dequeue buffer from a CMBufferQueue but leaves it in the queue.

CMBufferRef CMBufferQueueGetHead (    CMBufferQueueRef queue );
Parameters
queue

The CMBufferQueue from which to retrieve a buffer.

Return Value

The buffer. Will be NULL if the queue is empty.

Discussion

This follows Core Foundation "Get" semantics -- it does not retain the returned buffer. Note that with non-FIFO queues it's not guaranteed that the next dequeue will return this particular buffer (if an intervening Enqueue adds a buffer that will dequeue next).

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

CMBufferQueueGetMaxPresentationTimeStamp

Gets the greatest presentation timestamp of a CMBufferQueue.

CMTime CMBufferQueueGetMaxPresentationTimeStamp (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

The greatest presentation timestamp of the interrogated CMBufferQueue.

Discussion

If the getPresentationTimeStamp callback is NULL, kCMTimeInvalid will be returned.

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

CMBufferQueueGetMinDecodeTimeStamp

Gets the earliest decode timestamp of a CMBufferQueue.

CMTime CMBufferQueueGetMinDecodeTimeStamp (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

The earliest decode timestamp of the interrogated CMBufferQueue.

Discussion

The search for earliest decode timstamp is performed in this API. If you know your queue is in decode order, Accessing CMBufferQueue is a faster alternative. If the getDecodeTimeStamp callback is NULL, kCMTimeInvalid will be returned.

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

CMBufferQueueGetMinPresentationTimeStamp

Gets the earliest presentation timestamp of a CMBufferQueue.

CMTime CMBufferQueueGetMinPresentationTimeStamp (
   CMBufferQueueRef queue
);
Parameters
queue

CMBufferQueue being interrogated.

Return Value

The earliest presentation timestamp of the interrogated CMBufferQueue.

Discussion

The search for earliest presentation timstamp is performed in this API. If you know your queue is sorted by presentation time, CMBufferQueueGetBufferCount is a faster alternative. If the getPresentationTimeStamp callback is NULL, kCMTimeInvalid will be returned.

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

CMBufferQueueGetTypeID

Returns the CFTypeID of CMBufferQueue objects.

CFTypeID CMBufferQueueGetTypeID (
   void
);
Return Value

CFTypeID of CMBufferQueue objects.

Discussion

You can check if a CFTypeRef object is actually a CMBufferQueue by comparing CFGetTypeID(object) with CMBufferQueueGetTypeID().

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

CMBufferQueueInstallTrigger

Installs a trigger on a CMBufferQueue.

OSStatus CMBufferQueueInstallTrigger (
   CMBufferQueueRef queue,
   CMBufferQueueTriggerCallback triggerCallback,
   void *triggerRefcon,
   CMBufferQueueTriggerCondition triggerCondition,
   CMTime triggerTime,
   CMBufferQueueTriggerToken *triggerTokenOut
);
Parameters
queue

CMBufferQueue on which the trigger is being set.

triggerCallback

Callback to be called when the trigger condition becomes true. Can be NULL, if client intends only to explicitly test the condition. if triggerTokenOut is NULL this parameter cannot be NULL otherwise the trigger would be meaningless.

triggerRefcon

Refcon to be passed to the triggerCallback. Can be NULL if the callback doesn't need it, or is itself NULL.

triggerCondition

The condition to be tested when evaluating the trigger.

triggerTime

The time value to compare against when evaluating the trigger. Must be numeric (ie. not invalid, indefinite, or infinite), except for certain trigger conditions which ignores it (eg, kCMBufferQueueTrigger_WhenMinPresentationTimeStampChanges).

triggerTokenOut

Address where created trigger token will be written. Can be NULL, if client has no need to explicitly test or remove the trigger. Cannot be NULL when triggerCallback is NULL, since the trigger would be meaningless then.

Return Value

A result code. See “Result Codes”

Discussion

The returned trigger token can be passed to CMBufferQueueTestTrigger and CMBufferQueueRemoveTrigger. The triggerTokenOut parameter can be NULL (client doesn't need to test or remove trigger), and the triggerCallback parameter can be NULL (client doesn't need callbacks, but rather will explicitly test the trigger). One of these two parameters must be non-NULL, however, since an untestable trigger that does not perform a callback is meaningless. If the trigger condition is already true, CMBufferQueueInstallTrigger will call the triggerCallback and will first write the trigger token to *triggerTokenOut.

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

CMBufferQueueInstallTriggerWithIntegerThreshold

Installs a trigger on a CMBufferQueue.

OSStatus CMBufferQueueInstallTriggerWithIntegerThreshold (
   CMBufferQueueRef queue,
   CMBufferQueueTriggerCallback triggerCallback,
   void *triggerRefcon,
   CMBufferQueueTriggerCondition triggerCondition,
   CMItemCount triggerThreshold,
   CMBufferQueueTriggerToken *triggerTokenOut
);
Parameters
queue

CMBufferQueue on which the trigger is being set.

triggerCallback

Callback to be called when the trigger condition becomes true. Can be NULL, if client intends only to explicitly test the condition. Cannot be NULL if triggerTokenOut is NULL, otherwise the trigger would be meaningless.

triggerRefcon

Refcon to be passed to the triggerCallback. Can be NULL if the callback doesn't need it, or is itself NULL

triggerCondition

The condition to be tested when evaluating the trigger. Must be a valid condition for an integer threshold.

triggerThreshold

The integer value to compare against when evaluating the trigger.

triggerTokenOut

Address where created trigger token will be written. Can be NULL, if client has no need to explicitly test or remove the trigger. Cannot be NULL if triggerCallback is NULL, since the trigger would be meaningless then.

Return Value

A result code. See “Result Codes”

Discussion

This function behaves the same way as CMBufferQueueInstallTrigger except the trigger is evaluated against the integer value rather than the time value.

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

CMBufferQueueIsAtEndOfData

Returns whether or not a CMBufferQueue has been marked with EndOfData, and is now empty.

Boolean CMBufferQueueIsAtEndOfData (
   CMBufferQueueRef queue
);
Parameters
queue

The CMBufferQueue being interrogated.

Return Value

A Boolean indicating whether the CMBufferQueue has been marked with EndOfData, and is now empty. If queue is NULL, true is returned (a NULL queue is considered to be empty, and permanently at EndOfData).

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

CMBufferQueueIsEmpty

Returns whether or not a CMBufferQueue is empty.

Boolean CMBufferQueueIsEmpty (
   CMBufferQueueRef queue
);
Parameters
queue

The CMBufferQueue being interrogated.

Return Value

A Boolean indicating whether the CMBufferQueue is empty. If queue is NULL, true is returned.

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

CMBufferQueueMarkEndOfData

Marks a CMBufferQueue with EndOfData.

OSStatus CMBufferQueueMarkEndOfData (
   CMBufferQueueRef queue
);
Parameters
queue

The CMBufferQueue being marked.

Return Value

A result code. See “Result Codes”

Discussion

All subsequent Enqueues will be rejected until CMBufferQueueReset is called. Subsequent Dequeues will succeed as long as the queue is not empty.

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

CMBufferQueueRemoveTrigger

Removes a previously installed trigger from a CMBufferQueue.

OSStatus CMBufferQueueRemoveTrigger (
   CMBufferQueueRef queue,
   CMBufferQueueTriggerToken triggerToken
);
Parameters
queue

CMBufferQueue from which the trigger is to be removed.

triggerToken

Trigger to remove from the queue.

Return Value

A result code. See “Result Codes”

Discussion

Triggers will automatically be removed when a queue is finalized. However, if more than one module has access to a queue, it may be hard for an individual module to know when the queue is finalized since other modules may retain it. To address this concern, modules should remove their triggers before they themselves are finalized.

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

CMBufferQueueReset

Resets a CMBufferQueue. Empties the queue, and clears any EndOfData mark.

OSStatus CMBufferQueueReset (
   CMBufferQueueRef queue
);
Parameters
queue

The CMBufferQueue being reset.

Return Value

A result code. See “Result Codes.”

Discussion

All buffers in the queue are released. Triggers are not removed, however, and will be called appropriately as the queue duration goes to zero.

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

CMBufferQueueResetWithCallback

A function callback that calls a function for every buffer in a queue and then resets the queue.

OSStatus CMBufferQueueResetWithCallback (
   CMBufferQueueRef queue,
   void (*callback)(CMBufferRef buffer, void *refcon),
   void *refcon
);
Parameters
queue

CMBufferQueue being reset, that may contain multiple buffers.

callback

Function to be called for each buffer. The callback should not make other calls to the buffer queue.

refcon

Reference constant to be passed to the callback function.

Return Value

A result code. See “Result Codes.”

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

CMBufferQueueSetValidationCallback

A function callback that sets a function that CMBufferQueueEnqueue will call to validate buffers before adding them to the queue.

OSStatus CMBufferQueueSetValidationCallback (
   CMBufferQueueRef queue,
   CMBufferValidationCallback validationCallback,
   void *validationRefCon
);
Parameters
queue

CMBufferQueue that will use the validation callback.

validationCallback

Callback that will validate each buffer enqueued.

validationRefCon

Context refcon for validation callback.

Return Value

A result code. See “Result Codes.”

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

CMBufferQueueTestTrigger

Tests whether the trigger condition is true fot the given CMBufferQueue.

Boolean CMBufferQueueTestTrigger (
   CMBufferQueueRef queue,
   CMBufferQueueTriggerToken triggerToken
);
Parameters
queue

CMBufferQueue on which the trigger is tested.

triggerToken

Trigger to test.

Return Value

A Boolean indicating whether the trigger condition is True.

Discussion

CMBufferQueueTestTrigger always returns the condition's current status.The trigger callback will only be called when the condition goes from false to true. The triggerToken must be one that has been installed on this queue.

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

Data Types

Opaque Types

CMBufferRef

A reference to a CMBuffer object.

typedef CFTypeRef CMBufferRef;
Discussion

A CMBuffer can be an instance of any Core Foundation type, as long as a getDuration callback can be provided. Commonly-used types are CMSampleBuffer and CVPixelBuffer.

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

CMBufferQueueRef

A reference to a CMBufferQueueRef object.

typedef struct opaqueCMBufferQueue *CMBufferQueueRef;
Discussion

A CMBufferQueue is a Core Foundation object that implements a queue of timed buffers.

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

Callbacks

CMBufferCallbacks

Callbacks provided to Creating CMBufferQueue, for use by the queue in interrogating the buffers that it will see.

typedef struct {     uint32_t                     version;
      void                         *refcon;
      CMBufferGetTimeCallback      getDecodeTimeStamp;
      CMBufferGetTimeCallback      getPresentationTimeStamp;
      CMBufferGetTimeCallback      getDuration;
      CMBufferGetBooleanCallback   isDataReady;
      CMBufferCompareCallback      compare;
      CFStringRef                  dataBecameReadyNotification;
} CMBufferCallbacks;
Fields
version

The callback version.

This must be 0.

refcon

Contextual data to be passed to all callbacks

This can be NULL, if the callbacks don't require it.

getDecodeTimeStamp

This callback is called from CMBufferQueueGetFirstDecodeTimeStamp (once), and from CMBufferQueueGetMinDecodeTimeStamp (multiple times).

It should return the decode timestamp of the buffer. If there are multiple samples in the buffer, this callback should return the minimum decode timestamp in the buffer.

This can be NULL (CMBufferQueueGetFirstDecodeTimeStamp and CMBufferQueueGetMinDecodeTimeStamp will return kCMTimeInvalid).

getPresentationTimeStamp

This callback is called from CMBufferQueueGetFirstPresentationTimeStamp (once), and from CMBufferQueueGetMinPresentationTimeStamp (multiple times).

It should return the presentation timestamp of the buffer. If there are multiple samples in the buffer, this callback should return the minimum presentation timestamp in the buffer.

This can be NULL (CMBufferQueueGetFirstPresentationTimeStamp and CMBufferQueueGetMinPresentationTimeStamp will return kCMTimeInvalid).

getDuration

This callback is called (once) during enqueue and dequeue operations to update the total duration of the queue.

This must not be NULL.

isDataReady

This callback is called from CMBufferQueueDequeueIfDataReadyAndRetain, to ask if the buffer that is about to be dequeued is ready.

This may be NULL (data will be assumed to be ready).

compare

This callback is called (multiple times) from CMBufferQueueEnqueue, to perform an insertion sort.

This may be NULL (queue will be FIFO).

dataBecameReadyNotification

If triggers of type kCMBufferQueueTrigger_WhenDataBecomesReady are installed, the queue will listen for this notification on the head buffer.

This may be NULL (then the queue won't listen for it).

Discussion

With the exception of isDataReady, all these callbacks must always return the same result for the same arguments.

A buffer's duration, timestamps, or position relative to other buffers must not appear to change while it is in the queue. Once isDataReady has returned true for a given CMBuffer, it must always return true for that CMBuffer.

Durations must always be positive.

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

CMBufferValidationCallback

Tests whether a buffer is in a valid state to add to a queue.

typedef OSStatus (*CMBufferValidationCallback)( CMBufferQueueRef queue, CMBufferRef buf, void *validationRefCon );
Fields
queue

The queue requesting validation.

buf

The buffer about to be added.

validationRefCon

Contextual data.

Discussion

CMBufferQueueEnqueue will call this function to validate buffers.

Return noErr if the buffer is in a valid state to add.

Return a nonzero error code if the buffer should be rejected; CMBufferQueueEnqueue will return this error to the caller. If you do not have a more descriptive error code, use kCMBufferQueueError_InvalidBuffer.

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

CMBufferGetTimeCallback

Callback that returns a CMTime from a CMBuffer.

typedef CMTime (*CMBufferGetTimeCallback) (
   CMBufferRef buf,
   void *refcon
);
Fields
buf

The buffer being interrogated.

refcon

The contextual data from the client.

This value can be NULL.

Discussion

There are three callbacks of this type that can be provided to Creating CMBufferQueue: getDuration (required), getDecodeTimeStamp (optional), and getPresentationTimeStamp (optional).

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

CMBufferGetBooleanCallback

Callback that returns a Boolean value from a CMBuffer.

typedef Boolean (*CMBufferGetBooleanCallback) (
   CMBufferRef buf,
   void *refcon
);
Fields
buf

The buffer being interrogated.

refcon

The contextual data from the client.

This value can be NULL.

Discussion

There is one callback of this type that can be provided to Creating CMBufferQueue: isDataReady (optional).

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

CMBufferCompareCallback

Callback that compares one CMBuffer with another.

typedef CFComparisonResult (*CMBufferCompareCallback) (
   CMBufferRef buf1,
   CMBufferRef buf2,
   void *refcon
);
Fields
buf1

The first buffer being compared.

buf2

The second buffer being compared.

refcon

The contextual data from the client.

This value can be NULL.

Discussion

You can use a CFComparatorFunction as a callback.

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

Triggers

A trigger is a callback function that a queue calls every time the triggering condition becomes true. Trigger conditions include things like queue duration, queue buffer count, and so on. Trigger callbacks are called from within CMBufferQueue routines that modify the trigger condition (for example, Enqueue/Dequeue/Reset).

Trigger callbacks cannot modify the queue that called them; they can, however, interrogate it. Trigger callbacks should perform as little processing as possible, preferably arranging for processing to occur by, for example, signaling a semaphore, or rescheduling a runloop timer.

You can install as many triggers as you like. The order in which they are called is non-deterministic.

Triggers with a NULL callback are valid, since even though no trigger callback will be called, the trigger condition can still be explicitly tested.

CMBufferQueueTriggerToken

A reference to a CMBufferQueueTriggerToken object.

typedef struct opaqueCMBufferQueueTriggerToken *CMBufferQueueTriggerToken;
Discussion

The CMBufferQueueTriggerToken is returned from CMBufferQueueInstallTrigger, so you can remove it later if necessary. Triggers will automatically be removed when the queue is finalized. Note that if more than one module has access to a queue, it may be hard for an individual module to know when the queue is finalized since other modules may retain it. To address this concern, modules should remove their triggers before they themselves are finalized.

Special Considerations

A CMBufferQueueTrigger is not a Core Foundation object; you must not CFRetain or CFRelease it.

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

CMBufferQueueTriggerCallback

A callback to be called when a CMBufferQueue trigger condition becomes true.

typedef void (*CMBufferQueueTriggerCallback) (
   void *triggerRefcon,
   CMBufferQueueTriggerToken triggerToken
);
Fields
triggerRefcon

The contextual data.

triggerToken

The trigger whose condition became true.

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

CMBufferQueueTriggerCondition

A type to specify conditions to be associated with a CMBufferQueueTrigger.

typedef int32_t CMBufferQueueTriggerCondition;
Discussion

For possible values, see “Trigger Conditions.”

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

Constants

Trigger Conditions

Conditions to be associated with a CMBufferQueueTrigger.

enum {
   kCMBufferQueueTrigger_WhenDurationBecomesLessThan = 1,
   kCMBufferQueueTrigger_WhenDurationBecomesLessThanOrEqualTo = 2,
   kCMBufferQueueTrigger_WhenDurationBecomesGreaterThan = 3,
   kCMBufferQueueTrigger_WhenDurationBecomesGreaterThanOrEqualTo = 4,
   kCMBufferQueueTrigger_WhenMinPresentationTimeStampChanges = 5,
   kCMBufferQueueTrigger_WhenMaxPresentationTimeStampChanges = 6,
   kCMBufferQueueTrigger_WhenDataBecomesReady = 7,
   kCMBufferQueueTrigger_WhenEndOfDataReached = 8,
   kCMBufferQueueTrigger_WhenReset = 9,
   kCMBufferQueueTrigger_WhenBufferCountBecomesLessThan = 10,
   kCMBufferQueueTrigger_WhenBufferCountBecomesGreaterThan = 11,
};
Constants
kCMBufferQueueTrigger_WhenDurationBecomesLessThan

Trigger fires when queue duration becomes less than the specified duration.

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenDurationBecomesLessThanOrEqualTo

Trigger fires when queue duration becomes less than or equal to the specified duration.

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenDurationBecomesGreaterThan

Trigger fires when queue duration becomes greater than the specified duration.

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenDurationBecomesGreaterThanOrEqualTo

Trigger fires when queue duration becomes greater than or equal to the specified duration.

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenMinPresentationTimeStampChanges

Trigger fires when the minimum presentation timestamp changes (triggerDuration is ignored).

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenMaxPresentationTimeStampChanges

Trigger fires when the maximum presentation timestamp changes (triggerDuration is ignored).

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenDataBecomesReady

Trigger fires when next dequeueable buffer becomes ready (that is, CMBufferQueueDequeueIfDataReadyAndRetain will now succeed). (triggerDuration is ignored.)

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenEndOfDataReached

Trigger fires when CMBufferQueueIsAtEndOfData's condition becomes true. (triggerDuration is ignored.)

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenReset

Trigger fires when CMBufferQueueReset called. (triggerDuration is ignored.)

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenBufferCountBecomesLessThan

Trigger fires when buffer count becomes less than the specified threshold number.

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

kCMBufferQueueTrigger_WhenBufferCountBecomesGreaterThan

Trigger fires when buffer count becomes > the specified threshold number.

Available in iOS 4.0 and later.

Declared in CMBufferQueue.h.

Result Codes

This table lists result codes defined for CMBufferQueue API’s.

Result Code

Value

Description

kCMBufferQueueNoErr

0

No Error.

kCMBufferQueueError_AllocationFailed

-12760

Indicates that allocation failed.

kCMBufferQueueError_RequiredParameterMissing

-12761

Indicates NULL or 0 was passed for a required parameter.

kCMBufferQueueError_InvalidCMBufferCallbacksStruct

-12762

Indicates that Version was not 0, or getDuration was NULL.

kCMBufferQueueError_EnqueueAfterEndOfData

-12763

Indicates that CMBufferQueueEnqueue was attempted after CMBufferQueueMarkEndOfData was called (without a call to CMBufferQueueReset in between).

kCMBufferQueueError_QueueIsFull

-12764

Indicates that CMBufferQueueEnqueue was attempted on a full queue.

kCMBufferQueueError_BadTriggerDuration

-12765

Indicates that the trigger duration was invalid.

Trigger duration must be numeric, and epoch must be zero (non-zero epoch is only for timestamps, not durations).

kCMBufferQueueError_CannotModifyQueueFromTriggerCallback

-12766

Indicates that an attempt was made to modify the queue from a trigger callback.

kCMBufferQueueError_InvalidTriggerCondition

-12767

Indicates that a trigger condition is not a value from the CMBufferQueueTriggerCondition enum, or the trigger condition is not supported by a buffer queue.

kCMBufferQueueError_InvalidTriggerToken

-12768

Indicates that the trigger token is not a trigger that is currently associated with this queue.

kCMBufferQueueError_InvalidBuffer

-12769

Indicates that a buffer was rejected by the CMBufferValidationCallback.