iOS Developer Library

Developer

CoreMedia Framework Reference CMBlockBuffer Reference

Options
Deployment Target:

On This Page
Language:

CMBlockBuffer Reference

This document describes the Core Media objects that you use to move blocks of memory through a processing system.

A CMBlockBuffer is a CFType object that represents a contiguous range of data offsets (from zero to CMBlockBufferGetDataLength) across a possibly noncontiguous memory region. The memory region is composed of memory blocks and buffer references. The buffer references can in turn refer to additional regions. CMBlockBuffer uses CMAttachment protocol to propagate memory blocks.

Functions

  • Accesses potentially noncontiguous data in a CMBlockBuffer.

    Declaration

    Swift

    func CMBlockBufferAccessDataBytes(_ theBuffer: CMBlockBuffer!, _ offset: UInt, _ length: UInt, _ temporaryBlock: UnsafeMutablePointer<Void>, _ returnedPointer: UnsafeMutablePointer<UnsafeMutablePointer<Int8>>) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferAccessDataBytes ( CMBlockBufferRef theBuffer, size_t offset, size_t length, void *temporaryBlock, char **returnedPointer );

    Parameters

    theBuffer

    CMBlockBuffer to operate on. Must not be NULL.

    offset

    Offset within the CMBlockBuffer's offset range.

    length

    Desired number of bytes to access at offset.

    temporaryBlock

    A piece of memory, assumed to be at least length bytes in size. Must not be NULL

    returnedPointer

    Receives NULL if the desired amount of data could not be accessed at the given offset. Receives non-NULL if it could. The value returned is either a direct pointer into the CMBlockBuffer or to the temporaryBlock. Must not be NULL.

    Return Value

    Returns kCMBlockBufferNoErr if the desired amount of data could be accessed at the given offset.

    Discussion

    This routine is use for accessing contiguous and noncontiguous data. If the data is contiguous, the routine will return a pointer to the given CMBlockBuffer. If the data is not contiguous, the routine will copy the data into a temporary block and a pointer to this block will be returned.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Adds a CMBlockBuffer reference to an existing CMBlockBuffer.

    Declaration

    Swift

    func CMBlockBufferAppendBufferReference(_ theBuffer: CMBlockBuffer!, _ targetBBuf: CMBlockBuffer!, _ offsetToData: UInt, _ dataLength: UInt, _ flags: CMBlockBufferFlags) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferAppendBufferReference ( CMBlockBufferRef theBuffer, CMBlockBufferRef targetBBuf, size_t offsetToData, size_t dataLength, CMBlockBufferFlags flags );

    Parameters

    theBuffer

    The existing CMBlockBuffer. The target CMBlockBuffer will be added to the memory being managed by theBuffer (the existing CMBlockBuffer). Must not be NULL.

    targetBBuf

    The target CMBlockBuffer. The target CMBlockBuffer will be added to the memory managed by the theBuffer (the existingCMBlockBuffer).This parameter must not be NULL. Unless the kCMBlockBufferPermitEmptyReferenceFlag is passed, the target CMBlockBuffer must not be empty and it must have a data length at least large enough to supply the data subset specified (i.e. offsetToData+dataLength bytes).

    offsetToData

    The reference maintained by the existing CMBlockBuffer will begin after this offset within the target CMBlockBuffer.

    dataLength

    Number of relevant data bytes, starting at offsetToData, within the target CMBlockBuffer. If zero, the target buffer's total available dataLength (starting at offsetToData) will be referenced.

    flags

    Feature and control flags.

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Discussion

    Adds a buffer reference of (a possibly subset portion of) another CMBlockBuffer, the target CMBlockBuffer, to an existing CMBlockBuffer. The existing CMBlockBuffer's total data length will be increased by the specified dataLength. Note that append operations are not thread safe, so care must be taken when appending to block buffers that are used by multiple threads.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Adds a memory block to an existing CMBlockBuffer.

    Declaration

    Swift

    func CMBlockBufferAppendMemoryBlock(_ theBuffer: CMBlockBuffer!, _ memoryBlock: UnsafeMutablePointer<Void>, _ blockLength: UInt, _ blockAllocator: CFAllocator!, _ customBlockSource: UnsafePointer<CMBlockBufferCustomBlockSource>, _ offsetToData: UInt, _ dataLength: UInt, _ flags: CMBlockBufferFlags) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferAppendMemoryBlock ( CMBlockBufferRef theBuffer, void *memoryBlock, size_t blockLength, CFAllocatorRef blockAllocator, const CMBlockBufferCustomBlockSource *customBlockSource, size_t offsetToData, size_t dataLength, CMBlockBufferFlags flags );

    Parameters

    theBuffer

    The existing CMBlockBuffer to which the new memoryBlock will be added. Must not be NULL

    memoryBlock

    Block of memory to hold buffered data. If NULL, a memory block will be allocated when needed (via a call to CMBlockBufferAssureBlockMemory()) using the provided blockAllocator or customBlockSource. If non-NULL, the block will be used and will be deallocated when the CMBlockBuffer is finalized (i.e. released for the last time).

    blockLength

    Overall length of the memory block in bytes. Must not be zero. This is the size of the supplied memoryBlock or the size to allocate if memoryBlock is NULL.

    blockAllocator

    Allocator to be used for allocating the memoryBlock, if memoryBlock is NULL. If memoryBlock is non-NULL, this allocator will be used to deallocate it, if provided. Passing NULL will cause the default allocator (as set at the time of the call) to be used. Pass kCFAllocatorNull if no deallocation is desired.

    customBlockSource

    If non-NULL, it will be used for the allocation and freeing of the memory block (the blockAllocator parameter is ignored). If provided, and the memoryBlock parameter is NULL, its AllocateBlock()) routine must be non-NULL. Allocate will be called once, if successful, when the memoryBlock is allocated. FreeBlock() will be called once when the CMBlockBuffer is disposed.

    offsetToData

    The reference maintained by the existing CMBlockBuffer will begin after this offset within the memoryBlock .

    dataLength

    Number of relevant data bytes, starting at offsetToData, within the memory block.

    flags

    Feature and control flags

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Discussion

    Adds a memoryBlock to an existing CMBlockBuffer. The memory block may be statically allocated, dynamically allocated using the given allocator or not yet allocated. The CMBlockBuffer's total data length will be increased by the specified dataLength. If the kCMBlockBufferAssureMemoryNowFlag is set in the flags parameter, the memory block is allocated immediately using the blockAllocator or customBlockSource. Note that append operations are not thread safe, so care must be taken when appending to block buffers that are used by multiple threads.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Assures all memory blocks in a CMBlockBuffer are allocated.

    Declaration

    Swift

    func CMBlockBufferAssureBlockMemory(_ theBuffer: CMBlockBuffer!) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferAssureBlockMemory ( CMBlockBufferRef theBuffer );

    Parameters

    theBuffer

    CMBlockBuffer to operate on. Must not be NULL

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Discussion

    Traverses the possibly complex CMBlockBuffer, allocating the memory for any constituent memory blocks that are not yet allocated.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Copies bytes from a CMBlockBuffer into a provided memory area.

    Declaration

    Swift

    func CMBlockBufferCopyDataBytes(_ theSourceBuffer: CMBlockBuffer!, _ offsetToData: UInt, _ dataLength: UInt, _ destination: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferCopyDataBytes ( CMBlockBufferRef theSourceBuffer, size_t offsetToData, size_t dataLength, void *destination );

    Parameters

    theSourceBuffer

    The buffer from which data will be copied into the destination.

    offsetToData

    Offset within the source CMBlockBuffer at which the copy should begin.

    dataLength

    Number of bytes to copy, starting at offsetToData, within the source CMBlockBuffer. Must not be zero.

    destination

    Memory into which the data should be copied.

    Return Value

    Returns kCMBlockBufferNoErr if the copy succeeded, returns an error otherwise.

    Discussion

    This function is used to copy bytes out of a CMBlockBuffer into a provided piece of memory. It deals with the possibility of the desired range of data being noncontiguous. The function assumes that the memory at the destination is sufficient to hold the data. If dataLength bytes of data are not available in the CMBlockBuffer, an error is returned and the contents of the destination are undefined.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Produces a CMBlockBuffer containing a contiguous copy of or reference to the data specified by the parameters.

    Declaration

    Swift

    func CMBlockBufferCreateContiguous(_ structureAllocator: CFAllocator!, _ sourceBuffer: CMBlockBuffer!, _ blockAllocator: CFAllocator!, _ customBlockSource: UnsafePointer<CMBlockBufferCustomBlockSource>, _ offsetToData: UInt, _ dataLength: UInt, _ flags: CMBlockBufferFlags, _ newBBufOut: UnsafeMutablePointer<Unmanaged<CMBlockBuffer>?>) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferCreateContiguous ( CFAllocatorRef structureAllocator, CMBlockBufferRef sourceBuffer, CFAllocatorRef blockAllocator, const CMBlockBufferCustomBlockSource *customBlockSource, size_t offsetToData, size_t dataLength, CMBlockBufferFlags flags, CMBlockBufferRef *newBBufOut );

    Parameters

    structureAllocator

    Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

    sourceBuffer

    CMBlockBuffer from which data will be copied or referenced. Must not be NULL nor empty.

    blockAllocator

    Allocator to be used for allocating the memory block if a contiguous copy of the data is to be made. Passing NULL will cause the default allocator (as set at the time of the call) to be used.

    customBlockSource

    If non-NULL, it will be used for the allocation and freeing of the memory block (the blockAllocator parameter is ignored). If provided, and the parameter kCMBlockBufferAlwaysCopyDataFlag is set, customBlockSource’s AllocateBlock() routine must be non-NULL. Allocate will be called once, if successful, when the memory block is allocated. FreeBlock() will be called once when the CMBlockBuffer is disposed.

    offsetToData

    Offset within the source CMBlockBuffer at which the new CMBlockBuffer should obtain data.

    dataLength

    Number of relevant data bytes, starting at offsetToData, within the source CMBlockBuffer. If zero, the target buffer's total available dataLength (starting at offsetToData) will be referenced.

    flags

    Feature and control flags.

    newBBufOut

    Receives newly-created CMBlockBuffer object with a retain count of 1. Must not be NULL.

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Discussion

    Produces a CMBlockBuffer containing a contiguous copy of or reference to the data specified by the parameters. The resulting new CMBlockBuffer may contain an allocated copy of the data, or may contain a contiguous CMBlockBuffer reference. If the kCMBlockBufferAlwaysCopyDataFlag is set in the flags parameter, the resulting CMBlockBuffer will contain an allocated copy of the data rather than a reference to the SourceBuffer.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Creates an empty CMBlockBuffer.

    Declaration

    Swift

    func CMBlockBufferCreateEmpty(_ structureAllocator: CFAllocator!, _ subBlockCapacity: UInt32, _ flags: CMBlockBufferFlags, _ newBBufOut: UnsafeMutablePointer<Unmanaged<CMBlockBuffer>?>) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferCreateEmpty ( CFAllocatorRef structureAllocator, uint32_t subBlockCapacity, CMBlockBufferFlags flags, CMBlockBufferRef *newBBufOut );

    Parameters

    structureAllocator

    Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

    subBlockCapacity

    Number of sub-blocks the new CMBlockBuffer shall accommodate before expansion occurs. A value of zero means "do the reasonable default".

    flags

    Feature and control flags.

    newBBufOut

    Receives newly-created empty CMBlockBuffer object with retain count of 1. Must not be NULL.

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Discussion

    Creates an empty CMBlockBuffer, i.e. one which has no memory block nor reference to a CMBlockBuffer supplying bytes to it. It is ready to be populated using CMBlockBufferAppendMemoryBlock() and/or CMBlockBufferAppendBufferReference(). CMBlockBufferGetDataLength() will return zero for an empty CMBlockBuffer and CMBlockBufferGetDataPointer() and CMBlockBufferAssureBufferMemory() will fail.The memory for the CMBlockBuffer object will be allocated using the given allocator. If NULL is passed for the allocator, the default allocator is used.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Creates a new CMBlockBuffer that refers to another CMBlockBuffer.

    Declaration

    Swift

    func CMBlockBufferCreateWithBufferReference(_ structureAllocator: CFAllocator!, _ targetBuffer: CMBlockBuffer!, _ offsetToData: UInt, _ dataLength: UInt, _ flags: CMBlockBufferFlags, _ newBBufOut: UnsafeMutablePointer<Unmanaged<CMBlockBuffer>?>) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferCreateWithBufferReference ( CFAllocatorRef structureAllocator, CMBlockBufferRef targetBuffer, size_t offsetToData, size_t dataLength, CMBlockBufferFlags flags, CMBlockBufferRef *newBBufOut );

    Parameters

    structureAllocator

    Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

    targetBuffer

    The target CMBlockBuffer. This parameter must not be NULL. Unless the kCMBlockBufferPermitEmptyReferenceFlag is passed, it must not be empty and it must have a data length at least large enough to supply the data subset specified (i.e. offsetToData+dataLength bytes).

    offsetToData

    Offset within the target CMBlockBuffer at which the new CMBlockBuffer should refer to data.

    dataLength

    Number of relevant data bytes, starting at offsetToData, within the target CMBlockBuffer.

    flags

    Feature and control flags.

    newBBufOut

    Receives newly-created CMBlockBuffer object with a retain count of 1. Must not be NULL.

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Discussion

    Creates a new CMBlockBuffer that refers to (a possibly subset portion of) another CMBlockBuffer. The returned CMBlockBuffer may be further expanded using CMBlockBufferAppendMemoryBlock() and/or CMBlockBufferAppendBufferReference().

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Creates a new CMBlockBuffer backed by a memory block (or promise thereof).

    Declaration

    Swift

    func CMBlockBufferCreateWithMemoryBlock(_ structureAllocator: CFAllocator!, _ memoryBlock: UnsafeMutablePointer<Void>, _ blockLength: UInt, _ blockAllocator: CFAllocator!, _ customBlockSource: UnsafePointer<CMBlockBufferCustomBlockSource>, _ offsetToData: UInt, _ dataLength: UInt, _ flags: CMBlockBufferFlags, _ newBBufOut: UnsafeMutablePointer<Unmanaged<CMBlockBuffer>?>) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferCreateWithMemoryBlock ( CFAllocatorRef structureAllocator, void *memoryBlock, size_t blockLength, CFAllocatorRef blockAllocator, const CMBlockBufferCustomBlockSource *customBlockSource, size_t offsetToData, size_t dataLength, CMBlockBufferFlags flags, CMBlockBufferRef *newBBufOut );

    Parameters

    structureAllocator

    Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

    memoryBlock

    Block of memory to hold buffered data. If NULL, a memory block will be allocated when needed (via a call to CMBlockBufferAssureBlockMemory()) using the provided blockAllocator or customBlockSource. If non-NULL, the block will be used and will be deallocated when the new CMBlockBuffer is finalized (i.e. released for the last time).

    blockLength

    Overall length of the memory block in bytes. Must not be zero. This is the size of the supplied memory block or the size to allocate if memoryBlock is NULL.

    blockAllocator

    Allocator to be used for allocating the memoryBlock, if memoryBlock is NULL. If memoryBlock is non-NULL, this allocator will be used to deallocate it if provided. Passing NULL will cause the default allocator (as set at the time of the call) to be used. Pass kCFAllocatorNull if no deallocation is desired.

    customBlockSource

    If non-NULL, it will be used for the allocation and freeing of the memory block (the blockAllocator parameter is ignored). If provided, and the memoryBlock parameter is NULL, its AllocateBlock() routine must be non-NULL. Allocate will be called once, if successful, when the memoryBlock is allocated. FreeBlock() will be called once when the CMBlockBuffer is disposed.

    offsetToData

    Offset within the memoryBlock at which the CMBlockBuffer should refer to data.

    dataLength

    Number of relevant data bytes, starting at offsetToData, within the memory block.

    flags

    Feature and control flags.

    newBBufOut

    Receives newly-created CMBlockBuffer object with a retain count of 1. Must not be NULL.

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Discussion

    Creates a new CMBlockBuffer backed by a memory block. The memory block may be statically allocated, dynamically allocated using the given allocator (or customBlockSource) or not yet allocated. The returned CMBlockBuffer may be further expanded using CMBlockBufferAppendMemoryBlock() and/or CMBlockBufferAppendBufferReference().

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Fills the destination buffer with the specified data byte.

    Declaration

    Swift

    func CMBlockBufferFillDataBytes(_ fillByte: Int8, _ destinationBuffer: CMBlockBuffer!, _ offsetIntoDestination: UInt, _ dataLength: UInt) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferFillDataBytes ( char fillByte, CMBlockBufferRef destinationBuffer, size_t offsetIntoDestination, size_t dataLength );

    Parameters

    fillByte

    The data byte with which to fill the destination buffer.

    destinationBuffer

    CMBlockBuffer into which the data bytes are filled.

    offsetIntoDestination

    Start of data area for the buffer.

    dataLength

    Length of the valid data area for the buffer.

    Return Value

    Returns kCMBlockBufferNoErr if successful.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Obtains the total length of data reachable via a CMBlockBuffer.

    Declaration

    Swift

    func CMBlockBufferGetDataLength(_ theBuffer: CMBlockBuffer!) -> UInt

    Objective-C

    size_t CMBlockBufferGetDataLength ( CMBlockBufferRef theBuffer );

    Parameters

    theBuffer

    CMBlockBuffer to examine.

    Return Value

    Returns the total data length available via this CMBlockBuffer, or zero if it is empty, NULL if invalid.

    Discussion

    Obtains the total data length reachable via a CMBlockBuffer. This total is the sum of the dataLengths of the CMBlockBuffer's memoryBlocks and buffer references. Note that the dataLengths are the portions of those constituents that this CMBlockBuffer subscribes to. This CMBlockBuffer presents a contiguous range of offsets from zero to its totalDataLength as returned by this routine.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Gains access to the data represented by a CMBlockBuffer.

    Declaration

    Swift

    func CMBlockBufferGetDataPointer(_ theBuffer: CMBlockBuffer!, _ offset: UInt, _ lengthAtOffset: UnsafeMutablePointer<UInt>, _ totalLength: UnsafeMutablePointer<UInt>, _ dataPointer: UnsafeMutablePointer<UnsafeMutablePointer<Int8>>) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferGetDataPointer ( CMBlockBufferRef theBuffer, size_t offset, size_t *lengthAtOffset, size_t *totalLength, char **dataPointer );

    Parameters

    theBuffer

    CMBlockBuffer to operate on. Must not be NULL

    offset

    Offset within the buffer's offset range.

    lengthAtOffset

    On return, contains the amount of data available at the specified offset. May be NULL.

    totalLength

    On return, contains the block buffer's total data length (from offset 0). May be NULL.

    dataPointer

    On return, contains a pointer to the data byte at the specified offset; lengthAtOffset bytes are available at this address. May be NULL.

    Return Value

    Returns kCMBlockBufferNoErr if data was accessible at the specified offset within the given CMBlockBuffer. Returns an error otherwise.

    Discussion

    Gains access to the data represented by a CMBlockBuffer. A pointer into a memory block is returned which corresponds to the offset within the CMBlockBuffer. If lengthAtOffset is non NULL, the number of bytes addressable at the pointer is returned. This length-at-offset may be smaller than the number of bytes actually available starting at the offset if the dataLength of the CMBlockBuffer is covered by multiple memory blocks (a noncontiguous CMBlockBuffer). The caller can compare (offset+lengthAtOffset) with totalLength to determine whether the entire CMBlockBuffer has been referenced and whether it is possible to access the CMBlockBuffer's data with a contiguous reference. The data pointer returned will remain valid as long as the original CMBlockBuffer is referenced - once the CMBlockBuffer is released for the last time, any pointers into it will be invalid.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Obtains the CoreFoundation type ID for the CMBlockBuffer type.

    Declaration

    Swift

    func CMBlockBufferGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CMBlockBufferGetTypeID ( void );

    Return Value

    Returns the CFTypeID corresponding to CMBlockBuffer.

    Discussion

    Obtains the CoreFoundation type ID for the CMBlockBuffer type.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Determines whether the given CMBlockBuffer is empty.

    Declaration

    Swift

    func CMBlockBufferIsEmpty(_ theBuffer: CMBlockBuffer!) -> Boolean

    Objective-C

    Boolean CMBlockBufferIsEmpty ( CMBlockBufferRef theBuffer );

    Parameters

    theBuffer

    CMBlockBuffer to examine. Must not be NULL.

    Return Value

    False if the CMBlockBuffer is NULL.

    Discussion

    Determines whether the given CMBlockBuffer is empty, i.e., devoid of any memoryBlocks or CMBlockBuffer references. Note that a CMBlockBuffer containing a not-yet allocated memoryBlock is not considered empty.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Determines whether the specified range within the given CMBlockBuffer is contiguous.

    Declaration

    Swift

    func CMBlockBufferIsRangeContiguous(_ theBuffer: CMBlockBuffer!, _ offset: UInt, _ length: UInt) -> Boolean

    Objective-C

    Boolean CMBlockBufferIsRangeContiguous ( CMBlockBufferRef theBuffer, size_t offset, size_t length );

    Parameters

    theBuffer

    CMBlockBuffer to examine. Must not be NULL.

    offset

    Offset within the buffer's offset range.

    length

    Desired number of bytes to access at offset. If zero, the number of bytes available at offset (dataLength – offset), contiguous or not, is used.

    Return Value

    Returns true if the specified range is contiguous within the CMBlockBuffer, false otherwise. Also returns false if the CMBlockBuffer is NULL or empty.

    Discussion

    Determines whether the specified range within the given CMBlockBuffer is contiguous. If CMBlockBufferGetDataPointer() were called with the same parameters, the returned pointer would address the desired number of bytes.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Copies bytes from a given memory block into a CMBlockBuffer, replacing bytes in the underlying data blocks.

    Declaration

    Swift

    func CMBlockBufferReplaceDataBytes(_ sourceBytes: UnsafePointer<Void>, _ destinationBuffer: CMBlockBuffer!, _ offsetIntoDestination: UInt, _ dataLength: UInt) -> OSStatus

    Objective-C

    OSStatus CMBlockBufferReplaceDataBytes ( const void *sourceBytes, CMBlockBufferRef destinationBuffer, size_t offsetIntoDestination, size_t dataLength );

    Parameters

    sourceBytes

    Memory block from which bytes are copied into the destination CMBlockBuffer.

    destinationBuffer

    CMBlockBuffer whose range of bytes will be replaced by the sourceBytes.

    offsetIntoDestination

    Offset within the destination CMBlockBuffer at which replacement should begin.

    dataLength

    Number of bytes to be replaced, starting at offsetIntoDestination, in the destinationBuffer.

    Return Value

    Returns kCMBlockBufferNoErr if the replacement succeeded, returns an error otherwise.

    Discussion

    This function is used to replace bytes in a CMBlockBuffer's memory blocks with those from a provided piece of memory. It deals with the possibility of the destination range of data being noncontiguous. CMBlockBufferAssureBlockMemory() is called on the given CMBlockBuffer. If desired range is subsequently not accessible in the CMBlockBuffer, an error is returned and the contents of the CMBlockBuffer are untouched.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

Data Types

Miscellaneous

  • A reference to a CMBlockBuffer object.

    Declaration

    Swift

    typealias CMBlockBufferRef = CMBlockBuffer

    Objective-C

    typedef struct OpaqueCMBlockBuffer *CMBlockBufferRef;

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Type used for parameters containing CMBlockBuffer feature and control flags.

    Declaration

    Swift

    typealias CMBlockBufferFlags = UInt32

    Objective-C

    typedef uint32_t CMBlockBufferFlags;

    Discussion

    For possible values, see CMBlockBuffer Flags.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

  • Structure to support custom memory allocation and/or deallocation for the block used in a CMBlockBuffer.

    Declaration

    Swift

    struct CMBlockBufferCustomBlockSource { var version: UInt32 var AllocateBlock: CFunctionPointer<((UnsafeMutablePointer<Void>, UInt) -> UnsafeMutablePointer<Void>)> var FreeBlock: CFunctionPointer<((UnsafeMutablePointer<Void>, UnsafeMutablePointer<Void>, UInt) -> Void)> var refCon: UnsafeMutablePointer<Void> }

    Objective-C

    typedef struct { uint32_t version; void *(*AllocateBlock)(void *refCon, size_t sizeInBytes); void (*FreeBlock)(void *refCon, void *doomedMemoryBlock, size_t sizeInBytes); void *refCon; } CMBlockBufferCustomBlockSource;

    Discussion

    This structure allows a client to provide a custom facility for obtaining the memory block to be used in a CMBlockBuffer. You use this structure with functions that accept a memory block allocator.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later.

Constants

  • Provides the custom block source version used in a CMBlockBuffer.

    Declaration

    Swift

    var kCMBlockBufferCustomBlockSourceVersion: Int { get }

    Objective-C

    enum { kCMBlockBufferCustomBlockSourceVersion = 0 };

    Constants

    • kCMBlockBufferCustomBlockSourceVersion

      kCMBlockBufferCustomBlockSourceVersion

      The value is the block source version.

      Available in iOS 4.0 and later.

  • Flags controlling behaviors and features of CMBlockBuffer APIs.

    Declaration

    Swift

    var kCMBlockBufferAssureMemoryNowFlag: Int { get } var kCMBlockBufferAlwaysCopyDataFlag: Int { get } var kCMBlockBufferDontOptimizeDepthFlag: Int { get } var kCMBlockBufferPermitEmptyReferenceFlag: Int { get }

    Objective-C

    enum { kCMBlockBufferAssureMemoryNowFlag = (1L<<0), kCMBlockBufferAlwaysCopyDataFlag = (1L<<1), kCMBlockBufferDontOptimizeDepthFlag = (1L<<2), kCMBlockBufferPermitEmptyReferenceFlag = (1L<<3) };

    Constants

    • kCMBlockBufferAssureMemoryNowFlag

      kCMBlockBufferAssureMemoryNowFlag

      When passed to routines that accept block allocators, causes the memory block to be allocated immediately.

      Available in iOS 4.0 and later.

    • kCMBlockBufferAlwaysCopyDataFlag

      kCMBlockBufferAlwaysCopyDataFlag

      Used with CMBlockBufferCreateContiguous to cause it to always produce an allocated copy of the desired data.

      Available in iOS 4.0 and later.

    • kCMBlockBufferDontOptimizeDepthFlag

      kCMBlockBufferDontOptimizeDepthFlag

      Passed to CMBlockBufferAppendBufferReference and CMBlockBufferCreateWithBufferReference to suppress reference depth optimization.

      Available in iOS 4.0 and later.

    • kCMBlockBufferPermitEmptyReferenceFlag

      kCMBlockBufferPermitEmptyReferenceFlag

      Passed to CMBlockBufferAppendBufferReference and CMBlockBufferCreateWithBufferReference to allow references into a CMBlockBuffer that may not yet be populated.

      Available in iOS 4.0 and later.

Result Codes

This table lists result codes defined for CMBlockBuffer APIs.

Result Code

Value

Description

kCMBlockBufferNoErr

0

Indicates the operation completed successfully.

kCMBlockBufferStructureAllocationFailedErr

-12700

Indicates that CMBlockBuffer-creating API received a failure from the CFAllocator provided for CMBlockBuffer construction.

kCMBlockBufferBlockAllocationFailedErr

-12701

Indicates that the allocator provided to allocate a memory block (as distinct from CMBlockBuffer structures) failed.

kCMBlockBufferBadCustomBlockSourceErr

-12702

Indicates that the custom block source’s AllocateBlock() routine was NULL when an allocation was attempted.

kCMBlockBufferBadOffsetParameterErr

-12703

Indicates that the offset provided to an API is out of the range of the relevant CMBlockBuffer.

kCMBlockBufferBadLengthParameterErr

-12704

Indicates that the length provided to an API is out of the range of the relevant CMBlockBuffer, or is not allowed to be zero.

kCMBlockBufferBadPointerParameterErr

-12705

Indicates that a pointer parameter (for example, a CMBlockBuffer reference, or destination memory) is NULL or otherwise invalid.

kCMBlockBufferEmptyBBufErr

-12706

Indicates that an empty CMBlockBuffer was received unexpectedly.

kCMBlockBufferUnallocatedBlockErr

-12707

Indicates that an unallocated memory block was encountered.