Struct CMSampleBuffer 

pub struct CMSampleBuffer { /* private fields */ }

Available on crate feature CMSampleBuffer only.

A reference to a CMSampleBuffer, a CF object containing zero or more compressed (or uncompressed) samples of a particular media type (audio, video, muxed, etc).

See also Apple’s documentation

Implementations

impl CMSampleBuffer

pub unsafe fn create( allocator: Option<&CFAllocator>, data_buffer: Option<&CMBlockBuffer>, data_ready: bool, make_data_ready_callback: CMSampleBufferMakeDataReadyCallback, make_data_ready_refcon: *mut c_void, format_description: Option<&CMFormatDescription>, num_samples: CMItemCount, num_sample_timing_entries: CMItemCount, sample_timing_array: *const CMSampleTimingInfo, num_sample_size_entries: CMItemCount, sample_size_array: *const usize, sample_buffer_out: NonNull<*mut CMSampleBuffer>, ) -> i32

Available on crate features CMBase and CMBlockBuffer and CMFormatDescription and CMTime only.

Creates a CMSampleBuffer.

Array parameters (sampleSizeArray, sampleTimingArray) should have only one element if that same element applies to all samples. All parameters are copied; on return, the caller can release them, free them, reuse them or whatever. On return, the caller owns the returned CMSampleBuffer, and must release it when done with it.

Example of usage for in-display-order video frames:

dataBuffer: contains 7 Motion JPEG frames
• dataFormatDescription: describes Motion JPEG video
• numSamples: 7
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {duration = 1001/30000, presentationTimeStamp = 0/30000, decodeTimeStamp = invalid }
• numSampleSizeEntries: 7
• sampleSizeArray: {105840, 104456, 103464, 116460, 100412, 94808, 120400}

Example of usage for out-of-display-order video frames:

dataBuffer: contains 6 H.264 frames in decode order (P2,B0,B1,I5,B3,B4)
• dataFormatDescription: describes H.264 video
• numSamples: 6
• numSampleTimingEntries: 6
• sampleTimingArray: 6 entries = {
  {duration = 1001/30000, presentationTimeStamp = 12012/30000, decodeTimeStamp = 10010/30000},
  • {duration = 1001/30000, presentationTimeStamp = 10010/30000, decodeTimeStamp = 11011/30000},
  • {duration = 1001/30000, presentationTimeStamp = 11011/30000, decodeTimeStamp = 12012/30000},
  • {duration = 1001/30000, presentationTimeStamp = 15015/30000, decodeTimeStamp = 13013/30000},
  • {duration = 1001/30000, presentationTimeStamp = 13013/30000, decodeTimeStamp = 14014/30000},
  • {duration = 1001/30000, presentationTimeStamp = 14014/30000, decodeTimeStamp = 15015/30000}}
• numSampleSizeEntries: 6
• sampleSizeArray: {10580, 1234, 1364, 75660, 1012, 988}

Example of usage for compressed audio:

dataBuffer: contains 24 compressed AAC packets
• dataFormatDescription: describes 44.1kHz AAC audio
• numSamples: 24
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {
  {duration = 1024/44100, presentationTimeStamp = 0/44100, decodeTimeStamp = invalid }}
• numSampleSizeEntries: 24
• sampleSizeArray:
  {191, 183, 208, 213, 202, 206, 209, 206, 204, 192, 202, 277,
  • 282, 240, 209, 194, 193, 197, 196, 198, 168, 199, 171, 194}

Example of usage for uncompressed interleaved audio:

dataBuffer: contains 24000 uncompressed interleaved stereo frames, each containing 2 Float32s =
{{L,R},
• {L,R},
• {L,R}, ...}
• dataFormatDescription: describes 48kHz Float32 interleaved audio
• numSamples: 24000
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {
  {duration = 1/48000, presentationTimeStamp = 0/48000, decodeTimeStamp = invalid }}
• numSampleSizeEntries: 1
• sampleSizeArray: {8}

Example of usage for uncompressed non-interleaved audio:

dataBuffer: contains 24000 uncompressed non-interleaved stereo frames, each containing 2 (non-contiguous) Float32s =
{{L,L,L,L,L,...},
• {R,R,R,R,R,...}}
• dataFormatDescription: describes 48kHz Float32 non-interleaved audio
• numSamples: 24000
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {duration = 1/48000, presentationTimeStamp = 0/48000, decodeTimeStamp = invalid }
• numSampleSizeEntries: 0
• sampleSizeArray: NULL (because the samples are not contiguous)

Safety

• make_data_ready_callback must be implemented correctly.
• make_data_ready_refcon must be a valid pointer or null.
• sample_timing_array must be a valid pointer or null.
• sample_size_array must be a valid pointer or null.
• sample_buffer_out must be a valid pointer.

pub unsafe fn create_with_make_data_ready_handler( allocator: Option<&CFAllocator>, data_buffer: Option<&CMBlockBuffer>, data_ready: bool, format_description: Option<&CMFormatDescription>, num_samples: CMItemCount, num_sample_timing_entries: CMItemCount, sample_timing_array: *const CMSampleTimingInfo, num_sample_size_entries: CMItemCount, sample_size_array: *const usize, sample_buffer_out: NonNull<*mut CMSampleBuffer>, make_data_ready_handler: CMSampleBufferMakeDataReadyHandler, ) -> i32

Available on crate features CMBase and CMBlockBuffer and CMFormatDescription and CMTime and block2 only.

Creates a CMSampleBuffer.

See CMSampleBufferCreate; this variant allows for passing a block to make the data ready.

Safety

• sample_timing_array must be a valid pointer or null.
• sample_size_array must be a valid pointer or null.
• sample_buffer_out must be a valid pointer.
• make_data_ready_handler must be a valid pointer or null.

pub unsafe fn create_ready( allocator: Option<&CFAllocator>, data_buffer: Option<&CMBlockBuffer>, format_description: Option<&CMFormatDescription>, num_samples: CMItemCount, num_sample_timing_entries: CMItemCount, sample_timing_array: *const CMSampleTimingInfo, num_sample_size_entries: CMItemCount, sample_size_array: *const usize, sample_buffer_out: NonNull<*mut CMSampleBuffer>, ) -> i32

Available on crate features CMBase and CMBlockBuffer and CMFormatDescription and CMTime only.

Creates a CMSampleBuffer.

Array parameters (sampleSizeArray, sampleTimingArray) should have only one element if that same element applies to all samples. All parameters are copied; on return, the caller can release them, free them, reuse them or whatever. On return, the caller owns the returned CMSampleBuffer, and must release it when done with it. CMSampleBufferCreateReady is identical to CMSampleBufferCreate except that dataReady is always true, and so no makeDataReadyCallback or refcon needs to be passed.

Example of usage for in-display-order video frames:

dataBuffer: contains 7 Motion JPEG frames
• dataFormatDescription: describes Motion JPEG video
• numSamples: 7
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {duration = 1001/30000, presentationTimeStamp = 0/30000, decodeTimeStamp = invalid }
• numSampleSizeEntries: 7
• sampleSizeArray: {105840, 104456, 103464, 116460, 100412, 94808, 120400}

Example of usage for out-of-display-order video frames:

dataBuffer: contains 6 H.264 frames in decode order (P2,B0,B1,I5,B3,B4)
• dataFormatDescription: describes H.264 video
• numSamples: 6
• numSampleTimingEntries: 6
• sampleTimingArray: 6 entries = {
  {duration = 1001/30000, presentationTimeStamp = 12012/30000, decodeTimeStamp = 10010/30000},
  • {duration = 1001/30000, presentationTimeStamp = 10010/30000, decodeTimeStamp = 11011/30000},
  • {duration = 1001/30000, presentationTimeStamp = 11011/30000, decodeTimeStamp = 12012/30000},
  • {duration = 1001/30000, presentationTimeStamp = 15015/30000, decodeTimeStamp = 13013/30000},
  • {duration = 1001/30000, presentationTimeStamp = 13013/30000, decodeTimeStamp = 14014/30000},
  • {duration = 1001/30000, presentationTimeStamp = 14014/30000, decodeTimeStamp = 15015/30000}}
• numSampleSizeEntries: 6
• sampleSizeArray: {10580, 1234, 1364, 75660, 1012, 988}

Example of usage for compressed audio:

dataBuffer: contains 24 compressed AAC packets
• dataFormatDescription: describes 44.1kHz AAC audio
• numSamples: 24
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {
  {duration = 1024/44100, presentationTimeStamp = 0/44100, decodeTimeStamp = invalid }}
• numSampleSizeEntries: 24
• sampleSizeArray:
  {191, 183, 208, 213, 202, 206, 209, 206, 204, 192, 202, 277,
  • 282, 240, 209, 194, 193, 197, 196, 198, 168, 199, 171, 194}

Example of usage for uncompressed interleaved audio:

dataBuffer: contains 24000 uncompressed interleaved stereo frames, each containing 2 Float32s =
{{L,R},
• {L,R},
• {L,R}, ...}
• dataFormatDescription: describes 48kHz Float32 interleaved audio
• numSamples: 24000
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {
  {duration = 1/48000, presentationTimeStamp = 0/48000, decodeTimeStamp = invalid }}
• numSampleSizeEntries: 1
• sampleSizeArray: {8}

Example of usage for uncompressed non-interleaved audio:

dataBuffer: contains 24000 uncompressed non-interleaved stereo frames, each containing 2 (non-contiguous) Float32s =
{{L,L,L,L,L,...},
• {R,R,R,R,R,...}}
• dataFormatDescription: describes 48kHz Float32 non-interleaved audio
• numSamples: 24000
• numSampleTimingEntries: 1
• sampleTimingArray: one entry = {duration = 1/48000, presentationTimeStamp = 0/48000, decodeTimeStamp = invalid }
• numSampleSizeEntries: 0
• sampleSizeArray: NULL (because the samples are not contiguous)

Safety

• sample_timing_array must be a valid pointer or null.
• sample_size_array must be a valid pointer or null.
• sample_buffer_out must be a valid pointer.

impl CMSampleBuffer

pub unsafe fn create_for_image_buffer( allocator: Option<&CFAllocator>, image_buffer: &CVImageBuffer, data_ready: bool, make_data_ready_callback: CMSampleBufferMakeDataReadyCallback, make_data_ready_refcon: *mut c_void, format_description: &CMVideoFormatDescription, sample_timing: NonNull<CMSampleTimingInfo>, sample_buffer_out: NonNull<*mut CMSampleBuffer>, ) -> i32

Available on crate features CMFormatDescription and CMTime and objc2-core-video only.

Creates a CMSampleBuffer that contains a CVImageBuffer instead of a CMBlockBuffer.

Unlike a CMBlockBuffer which can reference many samples, a CVImageBuffer is defined to reference only one sample; therefore this routine has fewer parameters then CMSampleBufferCreate.

Sample timing information, which is a vector for CMSampleBufferCreate, consists of only one value for this routine.

The concept of sample size does not apply to CVImageBuffers. As such, CMSampleBufferGetSampleSizeArray will return kCMSampleBufferError_BufferHasNoSampleSizes, and CMSampleBufferGetSampleSize will return 0.

Because CVImageBuffers hold visual data, the format description provided is a CMVideoFormatDescription. The format description must be consistent with the attributes and formatting information attached to the CVImageBuffer. The width, height, and codecType must match (for CVPixelBuffers the codec type is given by CVPixelBufferGetPixelFormatType(pixelBuffer); for other CVImageBuffers, the codecType must be 0). The format description extensions must match the image buffer attachments for all the keys in the list returned by CMVideoFormatDescriptionGetExtensionKeysCommonWithImageBuffers (if absent in either they must be absent in both).

Safety

• make_data_ready_callback must be implemented correctly.
• make_data_ready_refcon must be a valid pointer or null.
• sample_timing must be a valid pointer.
• sample_buffer_out must be a valid pointer.

pub unsafe fn create_for_image_buffer_with_make_data_ready_handler( allocator: Option<&CFAllocator>, image_buffer: &CVImageBuffer, data_ready: bool, format_description: &CMVideoFormatDescription, sample_timing: NonNull<CMSampleTimingInfo>, sample_buffer_out: NonNull<*mut CMSampleBuffer>, make_data_ready_handler: CMSampleBufferMakeDataReadyHandler, ) -> i32

Available on crate features CMFormatDescription and CMTime and block2 and objc2-core-video only.

Creates a CMSampleBuffer that contains a CVImageBuffer instead of a CMBlockBuffer.

See CMSampleBufferCreateForImageBuffer; this variant allows for passing a block to make the data ready.

Safety

• sample_timing must be a valid pointer.
• sample_buffer_out must be a valid pointer.
• make_data_ready_handler must be a valid pointer or null.

pub unsafe fn create_ready_with_image_buffer( allocator: Option<&CFAllocator>, image_buffer: &CVImageBuffer, format_description: &CMVideoFormatDescription, sample_timing: NonNull<CMSampleTimingInfo>, sample_buffer_out: NonNull<*mut CMSampleBuffer>, ) -> i32

Available on crate features CMFormatDescription and CMTime and objc2-core-video only.

Creates a CMSampleBuffer that contains a CVImageBuffer instead of a CMBlockBuffer.

Unlike a CMBlockBuffer which can reference many samples, a CVImageBuffer is defined to reference only one sample; therefore this routine has fewer parameters then CMSampleBufferCreate.

Sample timing information, which is a vector for CMSampleBufferCreate, consists of only one value for this routine.

The concept of sample size does not apply to CVImageBuffers. As such, CMSampleBufferGetSampleSizeArray will return kCMSampleBufferError_BufferHasNoSampleSizes, and CMSampleBufferGetSampleSize will return 0.

Because CVImageBuffers hold visual data, the format description provided is a CMVideoFormatDescription. The format description must be consistent with the attributes and formatting information attached to the CVImageBuffer. The width, height, and codecType must match (for CVPixelBuffers the codec type is given by CVPixelBufferGetPixelFormatType(pixelBuffer); for other CVImageBuffers, the codecType must be 0). The format description extensions must match the image buffer attachments for all the keys in the list returned by CMVideoFormatDescriptionGetExtensionKeysCommonWithImageBuffers (if absent in either they must be absent in both).

CMSampleBufferCreateReadyWithImageBuffer is identical to CMSampleBufferCreateForImageBuffer except that dataReady is always true, and so no makeDataReadyCallback or refcon needs to be passed.

Safety

• sample_timing must be a valid pointer.
• sample_buffer_out must be a valid pointer.

pub unsafe fn create_copy( allocator: Option<&CFAllocator>, sbuf: &CMSampleBuffer, sample_buffer_out: NonNull<*mut CMSampleBuffer>, ) -> i32

Creates a copy of a CMSampleBuffer.

The copy is shallow: scalar properties (sizes and timing) are copied directly, the data buffer and format description are retained, and the propogatable attachments are retained by the copy’s dictionary. If sbuf’s data is not ready, the copy will be set to track its readiness.

Safety

sample_buffer_out must be a valid pointer.

pub unsafe fn create_copy_with_new_timing( allocator: Option<&CFAllocator>, original_s_buf: &CMSampleBuffer, num_sample_timing_entries: CMItemCount, sample_timing_array: *const CMSampleTimingInfo, sample_buffer_out: NonNull<*mut CMSampleBuffer>, ) -> i32

Available on crate features CMBase and CMTime only.

Creates a CMSampleBuffer with new timing information from another sample buffer.

This emulates CMSampleBufferCreateCopy, but changes the timing. Array parameters (sampleTimingArray) should have only one element if that same element applies to all samples. All parameters are copied; on return, the caller can release them, free them, reuse them or whatever. Any outputPresentationTimestamp that has been set on the original Buffer will not be copied because it is no longer relevant. On return, the caller owns the returned CMSampleBuffer, and must release it when done with it.

Safety

• sample_timing_array must be a valid pointer or null.
• sample_buffer_out must be a valid pointer.

pub unsafe fn copy_sample_buffer_for_range( allocator: Option<&CFAllocator>, sbuf: &CMSampleBuffer, sample_range: CFRange, sample_buffer_out: NonNull<*mut CMSampleBuffer>, ) -> i32

Creates a CMSampleBuffer containing a range of samples from an existing CMSampleBuffer.

Samples containing non-interleaved audio are currently not supported.

Safety

sample_buffer_out must be a valid pointer.

impl CMSampleBuffer

pub unsafe fn set_data_buffer(&self, data_buffer: &CMBlockBuffer) -> i32

Available on crate feature CMBlockBuffer only.

Associates a CMSampleBuffer with its CMBlockBuffer of media data.

If successful, this operation retains the dataBuffer thereafter, so the caller can release the dataBuffer after calling this API, if it has no further need to reference it. This is a write-once operation; it will fail if the CMSampleBuffer already has a dataBuffer. This API allows a CMSampleBuffer to exist, with timing and format information, before the associated data shows up. Example of usage: Some media services may have access to sample size, timing, and format information before the data is read. Such services may create CMSampleBuffers with that information and insert them into queues early, and use this API to attach the CMBlockBuffers later, when the data becomes ready.

pub unsafe fn data_buffer(&self) -> Option<CFRetained<CMBlockBuffer>>

Available on crate feature CMBlockBuffer only.

Returns a CMSampleBuffer’s CMBlockBuffer of media data.

The caller does not own the returned dataBuffer, and must retain it explicitly if the caller needs to maintain a reference to it.

Returns: CMBlockBuffer of media data. The result will be NULL if the CMSampleBuffer does not contain a CMBlockBuffer, if the CMSampleBuffer contains a CVImageBuffer, or if there is some other error.

pub unsafe fn image_buffer(&self) -> Option<CFRetained<CVImageBuffer>>

Available on crate feature objc2-core-video only.

Returns a CMSampleBuffer’s CVImageBuffer of media data.

The caller does not own the returned dataBuffer, and must retain it explicitly if the caller needs to maintain a reference to it.

Returns: CVImageBuffer of media data. The result will be NULL if the CMSampleBuffer does not contain a CVImageBuffer, if the CMSampleBuffer contains a CMBlockBuffer, or if there is some other error.

pub unsafe fn set_data_buffer_from_audio_buffer_list( &self, block_buffer_structure_allocator: Option<&CFAllocator>, block_buffer_block_allocator: Option<&CFAllocator>, flags: u32, buffer_list: NonNull<AudioBufferList>, ) -> i32

Available on crate feature objc2-core-audio-types only.

Creates a CMBlockBuffer containing a copy of the data from the AudioBufferList, and sets that as the CMSampleBuffer’s data buffer. The resulting buffer(s) in the sample buffer will be 16-byte-aligned if kCMSampleBufferFlag_AudioBufferList_Assure16ByteAlignment is passed in.

Safety

buffer_list must be a valid pointer.

pub unsafe fn audio_buffer_list_with_retained_block_buffer( &self, buffer_list_size_needed_out: *mut usize, buffer_list_out: *mut AudioBufferList, buffer_list_size: usize, block_buffer_structure_allocator: Option<&CFAllocator>, block_buffer_block_allocator: Option<&CFAllocator>, flags: u32, block_buffer_out: *mut *mut CMBlockBuffer, ) -> i32

Available on crate features CMBlockBuffer and objc2-core-audio-types only.

Creates an AudioBufferList containing the data from the CMSampleBuffer, and a CMBlockBuffer which references (and manages the lifetime of) the data in that AudioBufferList. The data may or may not be copied, depending on the contiguity and 16-byte alignment of the CMSampleBuffer’s data. The buffers placed in the AudioBufferList are guaranteed to be contiguous. The buffers in the AudioBufferList will be 16-byte-aligned if kCMSampleBufferFlag_AudioBufferList_Assure16ByteAlignment is passed in.

Safety

• buffer_list_size_needed_out must be a valid pointer or null.
• buffer_list_out must be a valid pointer or null.
• block_buffer_out must be a valid pointer or null.

pub unsafe fn audio_stream_packet_descriptions( &self, packet_descriptions_size: usize, packet_descriptions_out: *mut AudioStreamPacketDescription, packet_descriptions_size_needed_out: *mut usize, ) -> i32

Available on crate feature objc2-core-audio-types only.

Creates an array of AudioStreamPacketDescriptions for the variable bytes per packet or variable frames per packet audio data in the provided CMSampleBuffer. Constant bitrate, constant frames-per-packet audio yields a return value of noErr and no packet descriptions. This API is specific to audio format sample buffers, and will return kCMSampleBufferError_InvalidMediaTypeForOperation if called with a non-audio sample buffer.

Safety

• packet_descriptions_out must be a valid pointer or null.
• packet_descriptions_size_needed_out must be a valid pointer or null.

pub unsafe fn audio_stream_packet_descriptions_ptr( &self, packet_descriptions_pointer_out: *mut *const AudioStreamPacketDescription, packet_descriptions_size_out: *mut usize, ) -> i32

Available on crate feature objc2-core-audio-types only.

Returns a pointer to (and size of) a constant array of AudioStreamPacketDescriptions for the variable bytes per packet or variable frames per packet audio data in the provided CMSampleBuffer. The pointer will remain valid as long as the sbuf continues to be retained. Constant bitrate, constant frames-per-packet audio yields a return value of noErr and no packet descriptions. This API is specific to audio format sample buffers, and will return kCMSampleBufferError_InvalidMediaTypeForOperation if called with a non-audio sample buffer.

Safety

• packet_descriptions_pointer_out must be a valid pointer or null.
• packet_descriptions_size_out must be a valid pointer or null.

pub unsafe fn copy_pcm_data_into_audio_buffer_list( &self, frame_offset: i32, num_frames: i32, buffer_list: NonNull<AudioBufferList>, ) -> i32

Available on crate feature objc2-core-audio-types only.

Copies PCM audio data from the given CMSampleBuffer into a pre-populated AudioBufferList. The AudioBufferList must contain the same number of channels and its data buffers must be sized to hold the specified number of frames. This API is specific to audio format sample buffers, and will return kCMSampleBufferError_InvalidMediaTypeForOperation if called with a non-audio sample buffer. It will return an error if the CMSampleBuffer does not contain PCM audio data or if its dataBuffer is not ready.

Safety

buffer_list must be a valid pointer.

pub unsafe fn set_data_ready(&self) -> i32

Marks a CMSampleBuffer’s data as “ready”.

There is no way to undo this operation. The only way to get an “unready” CMSampleBuffer is to call CMSampleBufferCreate with the dataReady parameter set to false. Example of usage: in a read completion routine.

pub unsafe fn data_is_ready(&self) -> bool

Returns whether or not a CMSampleBuffer’s data is ready.

Returns: Whether or not the CMSampleBuffer’s data is ready. True is returned for special marker buffers, even though they have no data. False is returned if there is an error.

pub unsafe fn set_data_failed(&self, status: i32) -> i32

Marks a CMSampleBuffer’s data as “failed”, to indicate that the data will not become ready.

pub unsafe fn has_data_failed(&self, status_out: *mut i32) -> bool

Returns whether or not a CMSampleBuffer’s data loading request has failed.

Safety

status_out must be a valid pointer or null.

pub unsafe fn make_data_ready(&self) -> i32

Makes a CMSampleBuffer’s data ready, by calling the client’s CMSampleBufferMakeDataReadyCallback.

The CMSampleBufferMakeDataReadyCallback is passed in by the client during creation. It must return 0 if successful, and in that case, CMSampleBufferMakeDataReady will set the data readiness of the CMSampleBuffer to true. Example of usage: when it is time to actually use the data. Example of callback routine: a routine to force a scheduled read to complete. If the CMSampleBuffer is not ready, and there is no CMSampleBufferMakeDataReadyCallback to call, kCMSampleBufferError_BufferNotReady will be returned. Similarly, if the CMSampleBuffer is not ready, and the CMSampleBufferMakeDataReadyCallback fails and returns an error, kCMSampleBufferError_BufferNotReady will be returned.

pub unsafe fn track_data_readiness( &self, sample_buffer_to_track: &CMSampleBuffer, ) -> i32

Associates a CMSampleBuffer’s data readiness with another CMSampleBuffer’s data readiness.

After calling this API, if CMSampleBufferDataIsReady(sbuf) is called, it will return sbufToTrack’s data readiness. If CMSampleBufferMakeDataReady(sbuf) is called, it will do it by making sbufToTrack ready. Example of use: This allows bursting a multi-sample CMSampleBuffer into single-sample CMSampleBuffers before the data is ready. The single-sample CMSampleBuffers will all track the multi-sample CMSampleBuffer’s data readiness.

pub unsafe fn invalidate(&self) -> i32

Makes the sample buffer invalid, calling any installed invalidation callback.

An invalid sample buffer cannot be used – all accessors will return kCMSampleBufferError_Invalidated. It is not a good idea to do this to a sample buffer that another module may be accessing concurrently. Example of use: the invalidation callback could cancel pending I/O.

impl CMSampleBuffer

pub unsafe fn set_invalidate_callback( &self, invalidate_callback: CMSampleBufferInvalidateCallback, invalidate_ref_con: u64, ) -> i32

Sets the sample buffer’s invalidation callback, which is called during CMSampleBufferInvalidate.

A sample buffer can only have one invalidation callback. The invalidation callback is NOT called during ordinary sample buffer finalization.

Safety

invalidate_callback must be implemented correctly.

impl CMSampleBuffer

pub unsafe fn set_invalidate_handler( &self, invalidate_handler: CMSampleBufferInvalidateHandler, ) -> i32

Available on crate feature block2 only.

Sets the sample buffer’s invalidation handler block, which is called during CMSampleBufferInvalidate.

A sample buffer can only have one invalidation callback. The invalidation callback is NOT called during ordinary sample buffer finalization.

Safety

invalidate_handler must be a valid pointer.

pub unsafe fn is_valid(&self) -> bool

Queries whether a sample buffer is still valid.

Returns false if sbuf is NULL or CMSampleBufferInvalidate(sbuf) was called, true otherwise. Does not perform any kind of exhaustive validation of the sample buffer.

impl CMSampleBuffer

pub unsafe fn num_samples(&self) -> CMItemCount

Available on crate feature CMBase only.

Returns the number of media samples in a CMSampleBuffer.

Returns: The number of media samples in the CMSampleBuffer. 0 is returned if there is an error.

pub unsafe fn duration(&self) -> CMTime

Available on crate feature CMTime only.

Returns the total duration of a CMSampleBuffer.

If the buffer contains out-of-presentation-order samples, any gaps in the presentation timeline are not represented in the returned duration. The returned duration is simply the sum of all the individual sample durations.

Returns: The duration of the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

pub unsafe fn presentation_time_stamp(&self) -> CMTime

Available on crate feature CMTime only.

Returns the numerically earliest presentation timestamp of all the samples in a CMSampleBuffer.

For in-presentation-order samples, this is the presentation timestamp of the first sample. For out-of-presentation-order samples, this is the presentation timestamp of the sample that will be presented first, which is not necessarily the first sample in the buffer.

Returns: Numerically earliest sample presentation timestamp in the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

pub unsafe fn decode_time_stamp(&self) -> CMTime

Available on crate feature CMTime only.

Returns the numerically earliest decode timestamp of all the samples in a CMSampleBuffer.

The returned decode timestamp is always the decode timestamp of the first sample in the buffer, since even out-of-presentation-order samples are expected to be in decode order in the buffer.

Returns: Numerically earliest sample decode timestamp in the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

pub unsafe fn output_duration(&self) -> CMTime

Available on crate feature CMTime only.

Returns the output duration of a CMSampleBuffer.

The OutputDuration is the duration minus any trimmed duration, all divided by the SpeedMultiplier: (Duration - TrimDurationAtStart - TrimDurationAtEnd) / SpeedMultiplier

Returns: The output duration of the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

pub unsafe fn output_presentation_time_stamp(&self) -> CMTime

Available on crate feature CMTime only.

Returns the output presentation timestamp of the CMSampleBuffer.

The output presentation timestamp is the time at which the decoded, trimmed, stretched and possibly reversed samples should commence being presented. If CMSampleBufferSetOutputPresentationTimeStamp has been called to explicitly set the output PTS, CMSampleBufferGetOutputPresentationTimeStamp returns it. If not, CMSampleBufferGetOutputPresentationTimeStamp calculates its result as (PresentationTimeStamp + TrimDurationAtStart) unless kCMSampleBufferAttachmentKey_Reverse is kCFBooleanTrue, in which case it calculates the result as (PresentationTimeStamp + Duration - TrimDurationAtEnd). These are generally correct for un-stretched, un-shifted playback. For general forward playback in a scaled edit, the OutputPresentationTimeStamp should be set to: ((PresentationTimeStamp + TrimDurationAtStart - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime. For general reversed playback: ((PresentationTimeStamp + Duration - TrimDurationAtEnd - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime.

Returns: kCMTimeInvalid is returned if there is an error.

pub unsafe fn set_output_presentation_time_stamp( &self, output_presentation_time_stamp: CMTime, ) -> i32

Available on crate feature CMTime only.

Sets an output presentation timestamp to be used in place of a calculated value.

The output presentation timestamp is the time at which the decoded, trimmed, stretched and possibly reversed samples should commence being presented. By default, this is calculated by CMSampleBufferGetOutputPresentationTimeStamp. Call CMSampleBufferSetOutputPresentationTimeStamp to explicitly set the value for CMSampleBufferGetOutputPresentationTimeStamp to return. For general forward playback in a scaled edit, the OutputPresentationTimeStamp should be set to: ((PresentationTimeStamp + TrimDurationAtStart - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime. For general reversed playback: ((PresentationTimeStamp + Duration - TrimDurationAtEnd - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime.

pub unsafe fn output_decode_time_stamp(&self) -> CMTime

Available on crate feature CMTime only.

Returns the output decode timestamp of the CMSampleBuffer.

For consistency with CMSampleBufferGetOutputPresentationTimeStamp, this is calculated as: OutputPresentationTimeStamp + ((DecodeTimeStamp - PresentationTimeStamp) / SpeedMultiplier).

Returns: CMInvalidTime is returned if there is an error.

pub unsafe fn sample_timing_info_array( &self, num_sample_timing_entries: CMItemCount, timing_array_out: *mut CMSampleTimingInfo, timing_array_entries_needed_out: *mut CMItemCount, ) -> i32

Available on crate features CMBase and CMTime only.

Returns an array of CMSampleTimingInfo structs, one for each sample in a CMSampleBuffer.

If only one CMSampleTimingInfo struct is returned, it applies to all samples in the buffer. See documentation of CMSampleTimingInfo for details of how a single CMSampleTimingInfo struct can apply to multiple samples. The timingArrayOut must be allocated by the caller, and the number of entries allocated must be passed in timingArrayEntries. If timingArrayOut is NULL, timingArrayEntriesNeededOut will return the required number of entries. Similarly, if timingArrayEntries is too small, kCMSampleBufferError_ArrayTooSmall will be returned, and timingArrayEntriesNeededOut will return the required number of entries. In either case, the caller can then make an appropriately-sized timingArrayOut and call again. For example, the caller might pass the address of a CMSampleTimingInfo struct on the stack (as timingArrayOut), and 1 (as timingArrayEntries). If all samples are describable with a single CMSampleTimingInfo struct (or there is only one sample in the CMSampleBuffer), this call will succeed. If not, it will fail, and will return the number of entries required in timingArrayEntriesNeededOut. Only in this case will the caller actually need to allocate an array.

If there is no timingInfo in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleTimingInfo will be returned, and timingArrayEntriesNeededOut will be set to 0.

Safety

• timing_array_out must be a valid pointer or null.
• timing_array_entries_needed_out must be a valid pointer or null.

pub unsafe fn output_sample_timing_info_array( &self, timing_array_entries: CMItemCount, timing_array_out: *mut CMSampleTimingInfo, timing_array_entries_needed_out: *mut CMItemCount, ) -> i32

Available on crate features CMBase and CMTime only.

Returns an array of output CMSampleTimingInfo structs, one for each sample in a CMSampleBuffer.

If only one CMSampleTimingInfo struct is returned, it applies to all samples in the buffer. See documentation of CMSampleTimingInfo for details of how a single CMSampleTimingInfo struct can apply to multiple samples. The timingArrayOut must be allocated by the caller, and the number of entries allocated must be passed in timingArrayEntries. If timingArrayOut is NULL, timingArrayEntriesNeededOut will return the required number of entries. Similarly, if timingArrayEntries is too small, kCMSampleBufferError_ArrayTooSmall will be returned, and timingArrayEntriesNeededOut will return the required number of entries. In either case, the caller can then make an appropriately-sized timingArrayOut and call again. For example, the caller might pass the address of a CMSampleTimingInfo struct on the stack (as timingArrayOut), and 1 (as timingArrayEntries). If all samples are describable with a single CMSampleTimingInfo struct (or there is only one sample in the CMSampleBuffer), this call will succeed. If not, it will fail, and will return the number of entries required in timingArrayEntriesNeededOut. Only in this case will the caller actually need to allocate an array.

If there is no timingInfo in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleTimingInfo will be returned, and *timingArrayEntriesNeededOut will be set to 0.

Safety

• timing_array_out must be a valid pointer or null.
• timing_array_entries_needed_out must be a valid pointer or null.

pub unsafe fn sample_timing_info( &self, sample_index: CMItemIndex, timing_info_out: NonNull<CMSampleTimingInfo>, ) -> i32

Available on crate features CMBase and CMTime only.

Returns a CMSampleTimingInfo struct describing a specified sample in a CMSampleBuffer.

A sample-specific CMSampleTimingInfo struct will be returned (ie. with a sample-specific presentationTimeStamp and decodeTimeStamp), even if a single CMSampleTimingInfo struct was used during creation to describe all the samples in the buffer. The timingInfo struct must be allocated by the caller. If the sample index is not in the range 0 .. numSamples-1, kCMSampleBufferError_SampleIndexOutOfRange will be returned. If there is no timingInfo in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleTimingInfo will be returned.

Safety

timing_info_out must be a valid pointer.

pub unsafe fn sample_size_array( &self, size_array_entries: CMItemCount, size_array_out: *mut usize, size_array_entries_needed_out: *mut CMItemCount, ) -> i32

Available on crate feature CMBase only.

Returns an array of sample sizes, one for each sample in a CMSampleBuffer.

If only one size entry is returned, all samples in the buffer are of this size. The sizeArrayOut must be allocated by the caller, and the number of entries allocated must be passed in sizeArrayEntries. If sizeArrayOut is NULL, sizeArrayEntriesNeededOut will return the required number of entries. Similarly, if sizeArrayEntries is too small, kCMSampleBufferError_ArrayTooSmall will be returned, and sizeArrayEntriesNeededOut will return the required number of entries. The caller can then make an appropriately-sized sizeArrayOut and call again. For example, the caller might pass the address of a size_t variable on the stack (as sizeArrayOut), and 1 (as sizeArrayEntries). If all samples are the same size (or there is only one sample in the CMSampleBuffer), this call would succeed. If not, it will fail, and will return the number of entries required in sizeArrayEntriesNeededOut. Only in this case (multiple samples of different sizes) will the caller need to allocate an array. 0 entries will be returned if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where the channel values for a single sample are scattered through the buffer).

If there are no sample sizes in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleSizes will be returned, and *sizeArrayEntriesNeededOut will be set to 0. This will be true, for example, if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where the channel values for a single sample are scattered through the buffer), or if this CMSampleBuffer contains a CVImageBuffer.

Safety

• size_array_out must be a valid pointer or null.
• size_array_entries_needed_out must be a valid pointer or null.

pub unsafe fn sample_size(&self, sample_index: CMItemIndex) -> usize

Available on crate feature CMBase only.

Returns the size in bytes of a specified sample in a CMSampleBuffer.

Returns: Size in bytes of the specified sample in the CMSampleBuffer. If the sample index is not in the range 0 .. numSamples-1, a size of 0 will be returned. If there are no sample sizes in this CMSampleBuffer, a size of 0 will be returned. This will be true, for example, if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where the channel values for a single sample are scattered through the buffer), or if this CMSampleBuffer contains a CVImageBuffer.

pub unsafe fn total_sample_size(&self) -> usize

Returns the total size in bytes of sample data in a CMSampleBuffer.

Returns: Total size in bytes of sample data in the CMSampleBuffer. If there are no sample sizes in this CMSampleBuffer, a size of 0 will be returned.

pub unsafe fn format_description( &self, ) -> Option<CFRetained<CMFormatDescription>>

Available on crate feature CMFormatDescription only.

Returns the format description of the samples in a CMSampleBuffer.

On return, the caller does not own the returned formatDesc, and must retain it explicitly if the caller needs to maintain a reference to it.

Returns: The format description of the samples in the CMSampleBuffer. NULL is returned if there is an error.

pub unsafe fn sample_attachments_array( &self, create_if_necessary: bool, ) -> Option<CFRetained<CFArray>>

Returns a reference to a CMSampleBuffer’s immutable array of mutable sample attachments dictionaries (one dictionary per sample in the CMSampleBuffer).

Attachments can then be added/removed directly by the caller, using CF APIs. On return, the caller does not own the returned array of attachments dictionaries, and must retain it if the caller needs to maintain a reference to it. If there are no sample attachments yet, and createIfNecessary is true, a new CFArray containing N empty CFMutableDictionaries is returned (where N is the number of samples in the CMSampleBuffer), so that attachments can be added directly by the caller. If there are no sample attachments yet, and createIfNecessary is false, NULL is returned. Once the CFArray has been created, subsequent calls will return it, even if there are still no sample attachments in the array.

Returns: A reference to the CMSampleBuffer’s immutable array of mutable sample attachments dictionaries (one dictionary per sample in the CMSampleBuffer). NULL is returned if there is an error.

impl CMSampleBuffer

pub unsafe fn call_for_each_sample( &self, callback: unsafe extern "C-unwind" fn(NonNull<CMSampleBuffer>, CMItemCount, *mut c_void) -> i32, refcon: *mut c_void, ) -> i32

Available on crate feature CMBase only.

Calls a function for every individual sample in a sample buffer.

Temporary sample buffers will be created for individual samples, referring to the sample data and containing its timing, size and attachments. The callback function may retain these sample buffers if desired. If the callback function returns an error, iteration will stop immediately and the error will be returned. If there are no sample sizes in the provided sample buffer, kCMSampleBufferError_CannotSubdivide will be returned. This will happen, for example, if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where the channel values for a single sample are scattered through the buffer).

Safety

• callback must be implemented correctly.
• refcon must be a valid pointer or null.

pub unsafe fn call_block_for_each_sample( &self, handler: &DynBlock<dyn Fn(NonNull<CMSampleBuffer>, CMItemCount) -> i32>, ) -> i32

Available on crate features CMBase and block2 only.

Calls a block for every individual sample in a sample buffer.

Temporary sample buffers will be created for individual samples, referring to the sample data and containing its timing, size and attachments. The block may retain these sample buffers if desired. If the block returns an error, iteration will stop immediately and the error will be returned. If there are no sample sizes in the provided sample buffer, kCMSampleBufferError_CannotSubdivide will be returned. This will happen, for example, if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where the channel values for a single sample are scattered through the buffer).

impl CMSampleBuffer

pub unsafe fn tagged_buffer_group( &self, ) -> Option<CFRetained<CMTaggedBufferGroup>>

Available on crate feature CMTaggedBufferGroup only.

Returns a CMSampleBuffer’s TaggedBufferGroup of media data.

Parameter sbuf: CMSampleBuffer being interrogated.

The caller does not own the returned CMTaggedBufferGroup, and must retain it explicitly if the caller needs to maintain a reference to it.

Returns: CMTaggedBufferGroup of media data. The result will be NULL if the CMSampleBuffer does not contain a CMTaggedBufferGroup, or if there is some other error.

Methods from Deref<Target = CFType>

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: ConcreteType,

Available on crate feature CMAttachment only.

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

pub fn retain_count(&self) -> usize

Available on crate feature CMAttachment only.

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.

Trait Implementations

impl AsRef<AnyObject> for CMSampleBuffer

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CFType> for CMSampleBuffer

fn as_ref(&self) -> &CFType

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CMSampleBuffer> for CMSampleBuffer

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for CMSampleBuffer

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for CMSampleBuffer

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for CMSampleBuffer

fn type_id() -> CFTypeID

Returns the CFTypeID of CMSampleBuffer objects.

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

Returns: CFTypeID of CMSampleBuffer objects.

impl Debug for CMSampleBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for CMSampleBuffer

type Target = CFType

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for CMSampleBuffer

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for CMSampleBuffer

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for CMSampleBuffer

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for CMSampleBuffer

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type.

impl Type for CMSampleBuffer

fn retain(&self) -> CFRetained<Self>

where Self: Sized,

Increment the reference count of the receiver.

fn as_concrete_TypeRef(&self) -> &Self

👎Deprecated: this is redundant

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::retain

Helper for easier transition from the core-foundation crate.

fn as_CFTypeRef(&self) -> &CFType

where Self: AsRef<CFType>,

👎Deprecated: this is redundant (CF types deref to CFType)

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::from_raw

Helper for easier transition from the core-foundation crate.

impl Eq for CMSampleBuffer