iOS Developer Library

Developer

CoreMedia Framework Reference CMBufferQueue Reference

Options
Deployment Target:

On This Page
Language:

CMBufferQueue Reference

Inherits From


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreMedia

Objective-C

@import CoreMedia;

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

  • Creates a CMBufferQueue object.

    Declaration

    Swift

    func CMBufferQueueCreate(_ allocator: CFAllocator!, _ capacity: CMItemCount, _ callbacks: UnsafePointer<CMBufferCallbacks>, _ queueOut: UnsafeMutablePointer<Unmanaged<CMBufferQueue>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Calls a function for every buffer in a queue.

    Declaration

    Swift

    func CMBufferQueueCallForEachBuffer(_ queue: CMBufferQueue!, _ refcon: CFunctionPointer<((CMBuffer!, UnsafeMutablePointer<Void>) -> OSStatus)>, _ callback: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Dequeues a buffer from a CMBufferQueue.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Availability

    Available in iOS 4.0 and later

  • Dequeues a buffer from a CMBufferQueue if it is ready.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Availability

    Available in iOS 4.0 and later

  • Enqueues a buffer onto a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueEnqueue(_ queue: CMBufferQueue!, _ buf: CMBuffer!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Installs a trigger on a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueInstallTrigger(_ queue: CMBufferQueue!, _ triggerCallback: CMBufferQueueTriggerCallback, _ triggerRefcon: UnsafeMutablePointer<Void>, _ triggerCondition: CMBufferQueueTriggerCondition, _ triggerTime: CMTime, _ triggerTokenOut: UnsafeMutablePointer<CMBufferQueueTriggerToken>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Installs a trigger on a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueInstallTriggerWithIntegerThreshold(_ queue: CMBufferQueue!, _ triggerCallback: CMBufferQueueTriggerCallback, _ triggerRefcon: UnsafeMutablePointer<Void>, _ triggerCondition: CMBufferQueueTriggerCondition, _ triggerThreshold: CMItemCount, _ triggerTokenOut: UnsafeMutablePointer<CMBufferQueueTriggerToken>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Marks a CMBufferQueue with EndOfData.

    Declaration

    Swift

    func CMBufferQueueMarkEndOfData(_ queue: CMBufferQueue!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Removes a previously installed trigger from a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueRemoveTrigger(_ queue: CMBufferQueue!, _ triggerToken: CMBufferQueueTriggerToken) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueReset(_ queue: CMBufferQueue!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueResetWithCallback(_ queue: CMBufferQueue!, _ callback: CFunctionPointer<((CMBuffer!, UnsafeMutablePointer<Void>) -> Void)>, _ refcon: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueSetValidationCallback(_ queue: CMBufferQueue!, _ validationCallback: CMBufferValidationCallback, _ validationRefCon: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueContainsEndOfData(_ queue: CMBufferQueue!) -> Boolean

    Objective-C

    Boolean CMBufferQueueContainsEndOfData ( CMBufferQueueRef queue );

    Parameters

    queue

    CMBufferQueue being interrogated..

    Return Value

    A Boolean indicating whether CMBufferQueue has been marked with EndOfData.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueIsAtEndOfData(_ queue: CMBufferQueue!) -> Boolean

    Objective-C

    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).

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns whether or not a CMBufferQueue is empty.

    Declaration

    Swift

    func CMBufferQueueIsEmpty(_ queue: CMBufferQueue!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueTestTrigger(_ queue: CMBufferQueue!, _ triggerToken: CMBufferQueueTriggerToken) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Gets the number of buffers in the queue.

    Declaration

    Swift

    func CMBufferQueueGetBufferCount(_ queue: CMBufferQueue!) -> CMItemCount

    Objective-C

    CMItemCount CMBufferQueueGetBufferCount ( CMBufferQueueRef queue );

    Parameters

    queue

    CMBufferQueue being interrogated.

    Return Value

    Returns the number of buffers in the CMBufferQueue.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Gets the greatest presentation timestamp of a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueGetMaxPresentationTimeStamp(_ queue: CMBufferQueue!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueGetCallbacksForUnsortedSampleBuffers() -> UnsafePointer<CMBufferCallbacks>

    Objective-C

    const CMBufferCallbacks * CMBufferQueueGetCallbacksForUnsortedSampleBuffers ( void );

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Gets the duration of a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueGetDuration(_ queue: CMBufferQueue!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Gets the greatest end presentation timestamp of a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueGetEndPresentationTimeStamp(_ queue: CMBufferQueue!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueGetFirstDecodeTimeStamp(_ queue: CMBufferQueue!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Gets the earliest decode timestamp of a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueGetMinDecodeTimeStamp(_ queue: CMBufferQueue!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueGetFirstPresentationTimeStamp(_ queue: CMBufferQueue!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    func CMBufferQueueGetHead(_ queue: CMBufferQueue!) -> Unmanaged<CMBuffer>!

    Objective-C

    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).

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Gets the earliest presentation timestamp of a CMBufferQueue.

    Declaration

    Swift

    func CMBufferQueueGetMinPresentationTimeStamp(_ queue: CMBufferQueue!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns the CFTypeID of CMBufferQueue objects.

    Declaration

    Swift

    func CMBufferQueueGetTypeID() -> CFTypeID

    Objective-C

    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().

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

Data Types

Opaque Types

  • A reference to a CMBuffer object.

    Declaration

    Swift

    typealias CMBufferRef = CMBuffer

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • A reference to a CMBufferQueueRef object.

    Declaration

    Swift

    typealias CMBufferQueueRef = CMBufferQueue

    Objective-C

    typedef struct opaqueCMBufferQueue *CMBufferQueueRef;

    Discussion

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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

Callbacks

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

    Declaration

    Swift

    struct CMBufferCallbacks { var version: UInt32 var refcon: UnsafeMutablePointer<Void> var getDecodeTimeStamp: CMBufferGetTimeCallback var getPresentationTimeStamp: CMBufferGetTimeCallback var getDuration: CMBufferGetTimeCallback var isDataReady: CMBufferGetBooleanCallback var compare: CMBufferCompareCallback var dataBecameReadyNotification: Unmanaged<CFString>! var getSize: CMBufferGetSizeCallback init() init(version version: UInt32, refcon refcon: UnsafeMutablePointer<Void>, getDecodeTimeStamp getDecodeTimeStamp: CMBufferGetTimeCallback, getPresentationTimeStamp getPresentationTimeStamp: CMBufferGetTimeCallback, getDuration getDuration: CMBufferGetTimeCallback, isDataReady isDataReady: CMBufferGetBooleanCallback, compare compare: CMBufferCompareCallback, dataBecameReadyNotification dataBecameReadyNotification: Unmanaged<CFString>!, getSize getSize: CMBufferGetSizeCallback) }

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    typealias CMBufferValidationCallback = CFunctionPointer<((CMBufferQueue!, CMBuffer!, UnsafeMutablePointer<Void>) -> OSStatus)>

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Callback that returns a CMTime from a CMBuffer.

    Declaration

    Swift

    typealias CMBufferGetTimeCallback = CFunctionPointer<((CMBuffer!, UnsafeMutablePointer<Void>) -> CMTime)>

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Callback that returns a Boolean value from a CMBuffer.

    Declaration

    Swift

    typealias CMBufferGetBooleanCallback = CFunctionPointer<((CMBuffer!, UnsafeMutablePointer<Void>) -> Boolean)>

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Callback that compares one CMBuffer with another.

    Declaration

    Swift

    typealias CMBufferCompareCallback = CFunctionPointer<((CMBuffer!, CMBuffer!, UnsafeMutablePointer<Void>) -> CFComparisonResult)>

    Objective-C

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

    Discussion

    You can use a CFComparatorFunction as a callback.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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.

  • A reference to a CMBufferQueueTriggerToken object.

    Declaration

    Swift

    typealias CMBufferQueueTriggerToken = COpaquePointer

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    typealias CMBufferQueueTriggerCallback = CFunctionPointer<((UnsafeMutablePointer<Void>, CMBufferQueueTriggerToken) -> Void)>

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

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

    Declaration

    Swift

    typealias CMBufferQueueTriggerCondition = Int32

    Objective-C

    typedef int32_t CMBufferQueueTriggerCondition;

    Discussion

    For possible values, see Trigger Conditions.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

Constants

  • Conditions to be associated with a CMBufferQueueTrigger.

    Declaration

    Swift

    var kCMBufferQueueTrigger_WhenDurationBecomesLessThan: Int { get } var kCMBufferQueueTrigger_WhenDurationBecomesLessThanOrEqualTo: Int { get } var kCMBufferQueueTrigger_WhenDurationBecomesGreaterThan: Int { get } var kCMBufferQueueTrigger_WhenDurationBecomesGreaterThanOrEqualTo: Int { get } var kCMBufferQueueTrigger_WhenMinPresentationTimeStampChanges: Int { get } var kCMBufferQueueTrigger_WhenMaxPresentationTimeStampChanges: Int { get } var kCMBufferQueueTrigger_WhenDataBecomesReady: Int { get } var kCMBufferQueueTrigger_WhenEndOfDataReached: Int { get } var kCMBufferQueueTrigger_WhenReset: Int { get } var kCMBufferQueueTrigger_WhenBufferCountBecomesLessThan: Int { get } var kCMBufferQueueTrigger_WhenBufferCountBecomesGreaterThan: Int { get }

    Objective-C

    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

      kCMBufferQueueTrigger_WhenDurationBecomesLessThan

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenDurationBecomesLessThanOrEqualTo

      kCMBufferQueueTrigger_WhenDurationBecomesLessThanOrEqualTo

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenDurationBecomesGreaterThan

      kCMBufferQueueTrigger_WhenDurationBecomesGreaterThan

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenDurationBecomesGreaterThanOrEqualTo

      kCMBufferQueueTrigger_WhenDurationBecomesGreaterThanOrEqualTo

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenMinPresentationTimeStampChanges

      kCMBufferQueueTrigger_WhenMinPresentationTimeStampChanges

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenMaxPresentationTimeStampChanges

      kCMBufferQueueTrigger_WhenMaxPresentationTimeStampChanges

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenDataBecomesReady

      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

    • kCMBufferQueueTrigger_WhenEndOfDataReached

      kCMBufferQueueTrigger_WhenEndOfDataReached

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenReset

      kCMBufferQueueTrigger_WhenReset

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenBufferCountBecomesLessThan

      kCMBufferQueueTrigger_WhenBufferCountBecomesLessThan

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

      Available in iOS 4.0 and later

    • kCMBufferQueueTrigger_WhenBufferCountBecomesGreaterThan

      kCMBufferQueueTrigger_WhenBufferCountBecomesGreaterThan

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

      Available in iOS 4.0 and later

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.