Struct VTCompressionSession 

pub struct VTCompressionSession { /* private fields */ }

Available on crate feature VTCompressionSession only.

A reference to a Video Toolbox Compression Session.

A compression session supports the compression of a sequence of video frames. The session reference is a reference-counted CF object. To create a compression session, call VTCompressionSessionCreate; then you can optionally configure the session using VTSessionSetProperty; then to encode frames, call VTCompressionSessionEncodeFrame. To force completion of some or all pending frames, call VTCompressionSessionCompleteFrames. When you are done with the session, you should call VTCompressionSessionInvalidate to tear it down and CFRelease to release your object reference.

See also Apple’s documentation

Implementations

impl VTCompressionSession

pub unsafe fn create( allocator: Option<&CFAllocator>, width: i32, height: i32, codec_type: CMVideoCodecType, encoder_specification: Option<&CFDictionary>, source_image_buffer_attributes: Option<&CFDictionary>, compressed_data_allocator: Option<&CFAllocator>, output_callback: VTCompressionOutputCallback, output_callback_ref_con: *mut c_void, compression_session_out: NonNull<*mut VTCompressionSession>, ) -> i32

Available on crate features VTErrors and objc2-core-media only.

Creates a session for compressing video frames.

Compressed frames will be emitted through calls to outputCallback.

Parameter allocator: An allocator for the session. Pass NULL to use the default allocator.

Parameter width: The width of frames, in pixels. If the video encoder cannot support the provided width and height it may change them.

Parameter height: The height of frames in pixels.

Parameter codecType: The codec type.

Parameter encoderSpecification: Specifies a particular video encoder that must be used. Pass NULL to let the video toolbox choose a encoder.

Parameter sourceImageBufferAttributes: Required attributes for source pixel buffers, used when creating a pixel buffer pool for source frames. If you do not want the Video Toolbox to create one for you, pass NULL. (Using pixel buffers not allocated by the Video Toolbox may increase the chance that it will be necessary to copy image data.)

Parameter compressedDataAllocator: An allocator for the compressed data. Pass NULL to use the default allocator. Note: on MacOS 10.12 and later, using a compressedDataAllocator may trigger an extra buffer copy.

Parameter outputCallback: The callback to be called with compressed frames. This function may be called asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeFrame. Pass NULL if and only if you will be calling VTCompressionSessionEncodeFrameWithOutputHandler for encoding frames.

Parameter outputCallbackRefCon: Client-defined reference value for the output callback.

Parameter compressionSessionOut: Points to a variable to receive the new compression session.

Safety

• encoder_specification generics must be of the correct type.
• source_image_buffer_attributes generics must be of the correct type.
• output_callback must be implemented correctly.
• output_callback_ref_con must be a valid pointer or null.
• compression_session_out must be a valid pointer.

pub unsafe fn invalidate(&self)

Tears down a compression session.

When you are done with a compression session you created, call VTCompressionSessionInvalidate to tear it down and then CFRelease to release your object reference. When a compression session’s retain count reaches zero, it is automatically invalidated, but since sessions may be retained by multiple parties, it can be hard to predict when this will happen. Calling VTCompressionSessionInvalidate ensures a deterministic, orderly teardown.

impl VTCompressionSession

pub unsafe fn pixel_buffer_pool(&self) -> Option<CFRetained<CVPixelBufferPool>>

Available on crate feature objc2-core-video only.

Returns a pool that can provide ideal source pixel buffers for a compression session.

The compression session creates this pixel buffer pool based on the compressor’s pixel buffer attributes and any pixel buffer attributes passed in to VTCompressionSessionCreate. If the source pixel buffer attributes and the compressor pixel buffer attributes cannot be reconciled, the pool is based on the source pixel buffer attributes and the Video Toolbox converts each CVImageBuffer internally. <BR

While clients can call VTCompressionSessionGetPixelBufferPool once and retain the resulting pool, the call is cheap enough that it’s OK to call it once per frame. If a change of session properties causes the compressor’s pixel buffer attributes to change, it’s possible that VTCompressionSessionGetPixelBufferPool might return a different pool.

pub unsafe fn prepare_to_encode_frames(&self) -> i32

You can optionally call this function to provide the encoder with an opportunity to perform any necessary resource allocation before it begins encoding frames.

This optional call can be used to provide the encoder an opportunity to allocate any resources necessary before it begins encoding frames. If this isn’t called, any necessary resources will be allocated on the first VTCompressionSessionEncodeFrame call. Extra calls to this function will have no effect.

Parameter session: The compression session.

pub unsafe fn encode_frame( &self, image_buffer: &CVImageBuffer, presentation_time_stamp: CMTime, duration: CMTime, frame_properties: Option<&CFDictionary>, source_frame_refcon: *mut c_void, info_flags_out: *mut VTEncodeInfoFlags, ) -> i32

Available on crate features VTErrors and objc2-core-media and objc2-core-video only.

Call this function to present frames to the compression session. Encoded frames may or may not be output before the function returns.

The client should not modify the pixel data after making this call. The session and/or encoder will retain the image buffer as long as necessary.

Parameter session: The compression session.

Parameter imageBuffer: A CVImageBuffer containing a video frame to be compressed. Must have a nonzero reference count.

Parameter presentationTimeStamp: The presentation timestamp for this frame, to be attached to the sample buffer. Each presentation timestamp passed to a session must be greater than the previous one.

Parameter duration: The presentation duration for this frame, to be attached to the sample buffer. If you do not have duration information, pass kCMTimeInvalid.

Parameter frameProperties: Contains key/value pairs specifying additional properties for encoding this frame. Note that some session properties may also be changed between frames. Such changes have effect on subsequently encoded frames.

Parameter sourceFrameRefcon: Your reference value for the frame, which will be passed to the output callback function.

Parameter infoFlagsOut: Points to a VTEncodeInfoFlags to receive information about the encode operation. The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running asynchronously. The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously). Pass NULL if you do not want to receive this information.

Safety

• frame_properties generics must be of the correct type.
• source_frame_refcon must be a valid pointer or null.
• info_flags_out must be a valid pointer or null.

impl VTCompressionSession

pub unsafe fn encode_frame_with_output_handler( &self, image_buffer: &CVImageBuffer, presentation_time_stamp: CMTime, duration: CMTime, frame_properties: Option<&CFDictionary>, info_flags_out: *mut VTEncodeInfoFlags, output_handler: VTCompressionOutputHandler, ) -> i32

Available on crate features VTErrors and block2 and objc2-core-media and objc2-core-video only.

Call this function to present frames to the compression session. Encoded frames may or may not be output before the function returns.

The client should not modify the pixel data after making this call. The session and/or encoder will retain the image buffer as long as necessary. Cannot be called with a session created with a VTCompressionOutputCallback.

Parameter session: The compression session.

Parameter imageBuffer: A CVImageBuffer containing a video frame to be compressed. Must have a nonzero reference count.

Parameter presentationTimeStamp: The presentation timestamp for this frame, to be attached to the sample buffer. Each presentation timestamp passed to a session must be greater than the previous one.

Parameter duration: The presentation duration for this frame, to be attached to the sample buffer. If you do not have duration information, pass kCMTimeInvalid.

Parameter frameProperties: Contains key/value pairs specifying additional properties for encoding this frame. Note that some session properties may also be changed between frames. Such changes have effect on subsequently encoded frames.

Parameter infoFlagsOut: Points to a VTEncodeInfoFlags to receive information about the encode operation. The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running asynchronously. The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously). Pass NULL if you do not want to receive this information.

Parameter outputHandler: The block to be called when encoding the frame is completed. This block may be called asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeFrameWithOutputHandler.

Safety

• frame_properties generics must be of the correct type.
• info_flags_out must be a valid pointer or null.
• output_handler must be a valid pointer.

pub unsafe fn complete_frames( &self, complete_until_presentation_time_stamp: CMTime, ) -> i32

Available on crate feature objc2-core-media only.

Forces the compression session to complete encoding frames.

If completeUntilPresentationTimeStamp is numeric, frames with presentation timestamps up to and including this timestamp will be emitted before the function returns. If completeUntilPresentationTimeStamp is non-numeric, all pending frames will be emitted before the function returns.

impl VTCompressionSession

pub unsafe fn encode_multi_image_frame( &self, tagged_buffer_group: &CMTaggedBufferGroup, presentation_time_stamp: CMTime, duration: CMTime, frame_properties: Option<&CFDictionary>, source_frame_refcon: *mut c_void, info_flags_out: *mut VTEncodeInfoFlags, ) -> i32

Available on crate features VTErrors and objc2-core-media only.

Call this function to present a multi-image frame to the compression session. Encoded frames may or may not be output before the function returns.

The client should not modify the pixel data after making this call. The session and/or encoder will retain the image buffer as long as necessary.

Parameter session: The compression session.

Parameter taggedBufferGroup: A CMTaggedBufferGroup containing the multiple images for a video frame to be compressed.

Parameter presentationTimeStamp: The presentation timestamp for this frame, to be attached to the sample buffer. Each presentation timestamp passed to a session must be greater than the previous one.

Parameter duration: The presentation duration for this frame, to be attached to the sample buffer. If you do not have duration information, pass kCMTimeInvalid.

Parameter frameProperties: Contains key/value pairs specifying additional properties for encoding this frame. Note that some session properties may also be changed between frames. Such changes have effect on subsequently encoded frames.

Parameter sourceFrameRefcon: Your reference value for the frame, which will be passed to the output callback function.

Parameter infoFlagsOut: Points to a VTEncodeInfoFlags to receive information about the encode operation. The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running asynchronously. The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously). Pass NULL if you do not want to receive this information.

Safety

• frame_properties generics must be of the correct type.
• source_frame_refcon must be a valid pointer or null.
• info_flags_out must be a valid pointer or null.

pub unsafe fn encode_multi_image_frame_with_output_handler( &self, tagged_buffer_group: &CMTaggedBufferGroup, presentation_time_stamp: CMTime, duration: CMTime, frame_properties: Option<&CFDictionary>, info_flags_out: *mut VTEncodeInfoFlags, output_handler: VTCompressionOutputHandler, ) -> i32

Available on crate features VTErrors and block2 and objc2-core-media only.

Call this function to present a multi-image frame to the compression session. Encoded frames may or may not be output before the function returns.

The client should not modify the pixel data after making this call. The session and/or encoder will retain the image buffer as long as necessary. Cannot be called with a session created with a VTCompressionOutputCallback.

Parameter session: The compression session.

Parameter taggedBufferGroup: A CMTaggedBufferGroup containing the multiple images for a video frame to be compressed.

Parameter presentationTimeStamp: The presentation timestamp for this frame, to be attached to the sample buffer. Each presentation timestamp passed to a session must be greater than the previous one.

Parameter duration: The presentation duration for this frame, to be attached to the sample buffer. If you do not have duration information, pass kCMTimeInvalid.

Parameter frameProperties: Contains key/value pairs specifying additional properties for encoding this frame. Note that some session properties may also be changed between frames. Such changes have effect on subsequently encoded frames.

Parameter infoFlagsOut: Points to a VTEncodeInfoFlags to receive information about the encode operation. The kVTEncodeInfo_Asynchronous bit may be set if the encode is (or was) running asynchronously. The kVTEncodeInfo_FrameDropped bit may be set if the frame was dropped (synchronously). Pass NULL if you do not want to receive this information.

Parameter outputHandler: The block to be called when encoding the frame is completed. This block may be called asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeMultiImageFrameWithOutputHandler.

Safety

• frame_properties generics must be of the correct type.
• info_flags_out must be a valid pointer or null.
• output_handler must be a valid pointer.

impl VTCompressionSession

pub unsafe fn begin_pass( &self, begin_pass_flags: VTCompressionSessionOptionFlags, reserved: *mut u32, ) -> i32

Call to announce the start of a specific compression pass.

During multi-pass encoding, this function must be called before VTCompressionSessionEncodeFrame. It is an error to call this function when multi-pass encoding has not been enabled by setting kVTCompressionPropertyKey_MultiPassStorage.

Parameter beginPassFlags: Pass kVTCompressionSessionBeginFinalPass to inform the encoder that the pass must be the final pass.

Safety

reserved must be a valid pointer or null.

pub unsafe fn end_pass( &self, further_passes_requested_out: *mut u8, reserved: *mut u32, ) -> i32

Call to announce the end of a pass.

VTCompressionSessionEndPass can take a long time, since the video encoder may perform significant processing between passes. VTCompressionSessionEndPass will indicate via the furtherPassesRequestedOut argument whether the video encoder would like to perform another pass. There is no particular bound on the number of passes the video encoder may request, but the client is free to disregard this request and use the last-emitted set of frames. It is an error to call this function when multi-pass encoding has not been enabled by setting kVTCompressionPropertyKey_MultiPassStorage.

Parameter furtherPassesRequestedOut: Points to a Boolean that will be set to true if the video encoder would like to perform another pass, false otherwise. You may pass NULL to indicate that the client is certain to use this as the final pass, in which case the video encoder can skip that evaluation step.

Safety

• further_passes_requested_out must be a valid pointer or null.
• reserved must be a valid pointer or null.

pub unsafe fn time_ranges_for_next_pass( &self, time_range_count_out: NonNull<CMItemCount>, time_range_array_out: NonNull<*const CMTimeRange>, ) -> i32

Available on crate feature objc2-core-media only.

Retrieves the time ranges for the next pass.

If VTCompressionSessionEndPass sets *furtherPassesRequestedOut to true, call VTCompressionSessionGetTimeRangesForNextPass to find out the time ranges for the next pass. Source frames outside these time ranges should be skipped. Each time range is considered to include any frame at its start time and not to include any frame at its end time. It is an error to call this function when multi-pass encoding has not been enabled by setting kVTCompressionPropertyKey_MultiPassStorage, or when VTCompressionSessionEndPass did not set *furtherPassesRequestedOut to true.

Parameter timeRangeCountOut: Points to a CMItemCount to receive the number of CMTimeRanges.

Parameter timeRangeArrayOut: Points to a const CMTimeRange * to receive a pointer to a C array of CMTimeRanges. The storage for this array belongs to the VTCompressionSession and should not be modified. The pointer will be valid until the next call to VTCompressionSessionEndPass, or until the VTCompressionSession is invalidated or finalized.

Safety

• time_range_count_out must be a valid pointer.
• time_range_array_out must be a valid pointer.

Methods from Deref<Target = CFType>

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

where T: ConcreteType,

Available on crate feature VTSession 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 VTSession 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 VTCompressionSession

fn as_ref(&self) -> &AnyObject

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

impl AsRef<CFType> for VTCompressionSession

fn as_ref(&self) -> &CFType

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

impl AsRef<VTCompressionSession> for VTCompressionSession

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for VTCompressionSession

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for VTCompressionSession

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for VTCompressionSession

fn type_id() -> CFTypeID

Returns the CFTypeID for compression sessions.

impl Debug for VTCompressionSession

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

Formats the value using the given formatter.

impl Deref for VTCompressionSession

type Target = CFType

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for VTCompressionSession

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 VTCompressionSession

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

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for VTCompressionSession

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 VTCompressionSession

const ENCODING_REF: Encoding

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

impl Type for VTCompressionSession

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 VTCompressionSession