Struct AVCaptureMultiCamSession 

pub struct AVCaptureMultiCamSession { /* private fields */ }

Available on crate feature AVCaptureSession only.

A subclass of AVCaptureSession which supports simultaneous capture from multiple inputs of the same media type.

AVCaptureMultiCamSession’s sessionPreset is always AVCaptureSessionPresetInputPriority and may not be set to any other value. Each input’s device.activeFormat must be set manually to achieve the desired quality of service.

AVCaptureMultiCamSession supports dynamic enabling and disabling of individual camera inputs without interrupting preview. In order to stop an individual camera input, set the enabled property on all of its connections or connected ports to NO. When the last active connection or port is disabled, the source camera stops streaming to save power and bandwidth. Other inputs streaming data through the session are unaffected.

Prior to iOS 26, AVCaptureMultiCamSession requires all input devices to have an activeFormat where multiCamSupported returns YES. In applications linked on or after iOS 26, this requirement is not enforced when only a single input device is used.

See also Apple’s documentation

Implementations

impl AVCaptureMultiCamSession

pub unsafe fn isMultiCamSupported() -> bool

Indicates whether multicam session is supported on this platform.

AVCaptureMultiCamSession is intended to be used with multiple cameras and is only supported on platforms with sufficient hardware bandwidth, system memory, and thermal performance. For single-camera use cases, AVCaptureSession should be used instead.

pub unsafe fn hardwareCost(&self) -> c_float

Indicates the percentage of the session’s available hardware budget currently in use.

The value of this property is a float from 0.0 => 1.0 indicating how much of the session’s available hardware is in use as a percentage, given the currently connected inputs and outputs and the features for which you’ve opted in. When your hardwareCost is greater than 1.0, the capture session cannot run your desired configuration due to hardware constraints, so you receive an AVCaptureSessionRuntimeErrorNotification when attempting to start it running. Default value is 0.

Contributors to hardwareCost include:

• Whether the source devices’ active formats use the full sensor (4:3) or a crop (16:9). Cropped formats require lower hardware bandwidth, and therefore lower the cost.
• The max frame rate supported by the source devices’ active formats. The higher the max frame rate, the higher the cost.
• Whether the source devices’ active formats are binned or not. Binned formats require substantially less hardware bandwidth, and therefore result in a lower cost.
• The number of sources configured to deliver streaming disparity / depth via AVCaptureDepthDataOutput. The higher the number of cameras configured to produce depth, the higher the cost. In order to reduce hardwareCost, consider picking a sensor-cropped activeFormat, or a binned format. You may also use AVCaptureDeviceInput’s videoMinFrameDurationOverride property to artificially limit the max frame rate (which is the reciprocal of the min frame duration) of a source device to a lower value. By doing so, you only pay the hardware cost for the max frame rate you intend to use.

pub unsafe fn systemPressureCost(&self) -> c_float

Indicates the system pressure cost of your current configuration.

The value of this property is a float whose nominal range is 0.0 => 1.0 indicating the system pressure cost of your current configuration. When your systemPressureCost is greater than 1.0, the capture session cannot run sustainably. It may be able to run for a brief period before needing to stop due to high system pressure. While running in an unsustainable configuration, you may monitor the session’s systemPressureState and reduce pressure by reducing the frame rate, throttling your use of the GPU, etc. When the session reaches critical system pressure state, it must temporarily shut down, and you receive an AVCaptureSessionWasInterruptedNotification indicating the reason your session needed to stop. When system pressure alleviates, the session interruption ends.

impl AVCaptureMultiCamSession

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

Methods from Deref<Target = AVCaptureSession>

pub unsafe fn canSetSessionPreset( &self, preset: &AVCaptureSessionPreset, ) -> bool

Available on crate feature AVCaptureSessionPreset only.

Returns whether the receiver can be configured with the given preset.

Parameter preset: An AVCaptureSession preset.

Returns: YES if the receiver can be set to the given preset, NO otherwise.

An AVCaptureSession instance can be associated with a preset that configures its inputs and outputs to fulfill common use cases. This method can be used to determine if the receiver supports the desired preset given its current input and output configuration. The receiver’s sessionPreset property may only be set to a certain preset if this method returns YES for that preset.

pub unsafe fn sessionPreset(&self) -> Retained<AVCaptureSessionPreset>

Available on crate feature AVCaptureSessionPreset only.

Indicates the session preset currently in use by the receiver.

The value of this property is an AVCaptureSessionPreset indicating the current session preset in use by the receiver. The sessionPreset property may be set while the receiver is running.

pub unsafe fn setSessionPreset(&self, session_preset: &AVCaptureSessionPreset)

Available on crate feature AVCaptureSessionPreset only.

Setter for sessionPreset.

This is copied when set.

pub unsafe fn inputs(&self) -> Retained<NSArray<AVCaptureInput>>

Available on crate feature AVCaptureInput only.

An NSArray of AVCaptureInputs currently added to the receiver.

The value of this property is an NSArray of AVCaptureInputs currently added to the receiver. Clients can add AVCaptureInputs to a session by calling -addInput:.

pub unsafe fn canAddInput(&self, input: &AVCaptureInput) -> bool

Available on crate feature AVCaptureInput only.

Returns whether the proposed input can be added to the receiver.

Parameter input: An AVCaptureInput instance.

Returns: YES if the proposed input can be added to the receiver, NO otherwise.

An AVCaptureInput instance can only be added to a session using -addInput: if -canAddInput: returns YES, otherwise an NSInvalidArgumentException is thrown.

pub unsafe fn addInput(&self, input: &AVCaptureInput)

Available on crate feature AVCaptureInput only.

Adds an AVCaptureInput to the session.

Parameter input: An AVCaptureInput instance.

An AVCaptureInput instance can only be added to a session using -addInput: if -canAddInput: returns YES, otherwise an NSInvalidArgumentException is thrown. -addInput: may be called while the session is running.

pub unsafe fn removeInput(&self, input: &AVCaptureInput)

Available on crate feature AVCaptureInput only.

Removes an AVCaptureInput from the session.

Parameter input: An AVCaptureInput instance.

-removeInput: may be called while the session is running.

pub unsafe fn outputs(&self) -> Retained<NSArray<AVCaptureOutput>>

Available on crate feature AVCaptureOutputBase only.

An NSArray of AVCaptureOutputs currently added to the receiver.

The value of this property is an NSArray of AVCaptureOutputs currently added to the receiver. Clients can add AVCaptureOutputs to a session by calling -addOutput:.

pub unsafe fn canAddOutput(&self, output: &AVCaptureOutput) -> bool

Available on crate feature AVCaptureOutputBase only.

Returns whether the proposed output can be added to the receiver.

Parameter output: An AVCaptureOutput instance.

Returns: YES if the proposed output can be added to the receiver, NO otherwise.

An AVCaptureOutput instance can only be added to a session using -addOutput: if -canAddOutput: returns YES, otherwise an NSInvalidArgumentException is thrown.

On iOS and Mac Catalyst, some limitations to adding combinations of different types of outputs apply:

• A maximum of one output of each type may be added. For applications linked on or after iOS 16.0, this restriction no longer applies to AVCaptureVideoDataOutputs. When adding more than one AVCaptureVideoDataOutput, AVCaptureSession.hardwareCost must be taken into account.
• A session cannot contain both an AVCaptureStillImageOutput and an AVCapturePhotoOutput at the same time.
• Prior to iOS 16.0, an AVCaptureVideoDataOutput and an AVCaptureMovieFileOutput may be added to the same session, but only one may have its connection active. When both have their connections enabled, the AVCaptureMovieFileOutput “wins” and the AVCaptureVideoDataOutput’s connection becomes inactive. For applications linked on or after iOS 16.0, this restriction has been lifted. When adding multiple AVCaptureVideoDataOutputs or a combination of AVCaptureVideoDataOutputs and an AVCaptureMovieFileOutput, AVCaptureSession.hardwareCost must be taken into account.
• Similarly, prior to iOS 16.0, an AVCaptureAudioDataOutput and an AVCaptureMovieFileOutput may be added to the same session, but only one may have its connection active. When both have their connections enabled, the AVCaptureMovieFileOutput “wins” and the AVCaptureAudioDataOutput’s connection becomes inactive. For applications linked on or after iOS 16.0, this restriction has been lifted.

pub unsafe fn addOutput(&self, output: &AVCaptureOutput)

Available on crate feature AVCaptureOutputBase only.

Adds an AVCaptureOutput to the session.

Parameter output: An AVCaptureOutput instance.

An AVCaptureOutput instance can only be added to a session using -addOutput: if -canAddOutput: returns YES, otherwise an NSInvalidArgumentException is thrown. -addOutput: may be called while the session is running.

pub unsafe fn removeOutput(&self, output: &AVCaptureOutput)

Available on crate feature AVCaptureOutputBase only.

Removes an AVCaptureOutput from the session.

Parameter output: An AVCaptureOutput instance.

-removeOutput: may be called while the session is running.

pub unsafe fn addInputWithNoConnections(&self, input: &AVCaptureInput)

Available on crate feature AVCaptureInput only.

Adds an AVCaptureInput to the session without forming any connections.

Parameter input: An AVCaptureInput instance.

An AVCaptureInput instance can only be added to a session using -addInputWithNoConnections: if -canAddInput: returns YES, otherwise an NSInvalidArgumentException is thrown. -addInputWithNoConnections: may be called while the session is running. The -addInput: method is the preferred method for adding an input to an AVCaptureSession. -addInputWithNoConnections: may be called if you need fine-grained control over which inputs are connected to which outputs.

pub unsafe fn addOutputWithNoConnections(&self, output: &AVCaptureOutput)

Available on crate feature AVCaptureOutputBase only.

Adds an AVCaptureOutput to the session without forming any connections.

Parameter output: An AVCaptureOutput instance.

An AVCaptureOutput instance can only be added to a session using -addOutputWithNoConnections: if -canAddOutput: returns YES, otherwise an NSInvalidArgumentException is thrown. -addOutputWithNoConnections: may be called while the session is running. The -addOutput: method is the preferred method for adding an output to an AVCaptureSession. -addOutputWithNoConnections: may be called if you need fine-grained control over which inputs are connected to which outputs.

pub unsafe fn connections(&self) -> Retained<NSArray<AVCaptureConnection>>

An NSArray of AVCaptureConnections currently added to the receiver.

The value of this property is an NSArray of AVCaptureConnections currently added to the receiver. Connections are formed implicitly by the receiver when a client calls -addInput: or -addOutput:. Connections are formed explicitly when a client calls -addConnection:.

pub unsafe fn canAddConnection(&self, connection: &AVCaptureConnection) -> bool

Returns whether the proposed connection can be added to the receiver.

Parameter connection: An AVCaptureConnection instance.

An AVCaptureConnection instance can only be added to a session using -addConnection: if -canAddConnection: returns YES, otherwise an NSInvalidArgumentException is thrown. When using -addInput: or -addOutput:, connections are formed automatically between all compatible inputs and outputs. Manually adding connections is only necessary when adding an input or output with no connections.

pub unsafe fn addConnection(&self, connection: &AVCaptureConnection)

Adds an AVCaptureConnection to the session.

Parameter connection: An AVCaptureConnection instance.

An AVCaptureConnection instance can only be added to a session using -addConnection: if canAddConnection: returns YES, otherwise an NSInvalidArgumentException is thrown. When using -addInput: or -addOutput:, connections are formed automatically between all compatible inputs and outputs. Manually adding connections is only necessary when adding an input or output with no connections. -addConnection: may be called while the session is running.

pub unsafe fn removeConnection(&self, connection: &AVCaptureConnection)

Removes an AVCaptureConnection from the session.

Parameter connection: An AVCaptureConnection instance.

-removeConnection: may be called while the session is running.

pub unsafe fn supportsControls(&self) -> bool

Indicates whether session controls are supported on this platform.

AVCaptureControls are only supported on platforms with necessary hardware.

pub unsafe fn maxControlsCount(&self) -> NSInteger

Specifies the maximum number of controls that can be added to a session.

pub unsafe fn setControlsDelegate_queue( &self, controls_delegate: Option<&ProtocolObject<dyn AVCaptureSessionControlsDelegate>>, controls_delegate_callback_queue: Option<&DispatchQueue>, )

Available on crate feature dispatch2 only.

Sets the receiver’s controls delegate that receives events about the session’s controls and the dispatch queue on which the delegate is called.

Parameter controlsDelegate: An object conforming to the AVCaptureSessionControlsDelegate protocol that receives events about the session’s controls.

Parameter controlsDelegateCallbackQueue: A dispatch queue on which all delegate methods are called.

Users can interact with an AVCaptureSession’s controls by performing specific gestures to enable their visibility. A delegate may be specified to be informed when the controls can be interacted with and are dismissed. All delegate methods will be called on the specified dispatch queue.

A serial dispatch queue must be used to guarantee that delegate callbacks will be delivered in order. The controlsDelegateCallbackQueue parameter may not be NULL, except when setting the controlsDelegate to nil otherwise -setControlsDelegate:queue: throws an NSInvalidArgumentException.

Safety

controls_delegate_callback_queue possibly has additional threading requirements.

pub unsafe fn controlsDelegate( &self, ) -> Option<Retained<ProtocolObject<dyn AVCaptureSessionControlsDelegate>>>

The receiver’s controls delegate.

The value of this property is an object conforming to the AVCaptureSessionControlsDelegate protocol that receives events about the session’s controls. The delegate is set using the -setControlsDelegate:queue: method.

A controls delegate must be specified for controls to become active.

pub unsafe fn controlsDelegateCallbackQueue( &self, ) -> Option<Retained<DispatchQueue>>

Available on crate feature dispatch2 only.

The dispatch queue on which all controls delegate methods will be called.

The value of this property is a dispatch_queue_t. The queue is set using the -setControlsDelegate:queue: method.

pub unsafe fn controls(&self) -> Retained<NSArray<AVCaptureControl>>

Available on crate feature AVCaptureControl only.

An NSArray of AVCaptureControls currently added to the session.

The value of this property is an NSArray of AVCaptureControls currently added to the session. Clients can add AVCaptureControls to a session by calling -addControl:.

pub unsafe fn canAddControl(&self, control: &AVCaptureControl) -> bool

Available on crate feature AVCaptureControl only.

Returns whether the proposed control can be added to the session.

Parameter control: An AVCaptureControl instance.

Returns: YES if the proposed control can be added to the session, NO otherwise.

An AVCaptureControl instance can only be added to a session using -addControl: if -canAddControl: returns YES. For example, some platforms do not support controls. Instances of AVCaptureSlider, AVCaptureToggle and AVCaptureIndexPicker must have an action and an action queue set before being added to a session.

pub unsafe fn addControl(&self, control: &AVCaptureControl)

Available on crate feature AVCaptureControl only.

Adds an AVCaptureControl instance to the session.

Parameter control: An AVCaptureControl instance.

An AVCaptureControl instance can only be added to a session using -addControl: if -canAddControl: returns YES, otherwise an NSInvalidArgumentException is thrown. -addControl: may be called while the session is running.

For an AVCaptureControl instance to become active, an AVCaptureSessionControlsDelegate must be set on the session.

pub unsafe fn removeControl(&self, control: &AVCaptureControl)

Available on crate feature AVCaptureControl only.

Removes an AVCaptureControl instance from the session.

Parameter control: An AVCaptureControl instance.

-removeControl: may be called while the session is running.

pub unsafe fn beginConfiguration(&self)

When paired with commitConfiguration, allows a client to batch multiple configuration operations on a running session into atomic updates.

-beginConfiguration / -commitConfiguration are AVCaptureSession’s mechanism for batching multiple configuration operations on a running session into atomic updates. After calling [session beginConfiguration], clients may add or remove outputs, alter the sessionPreset, or configure individual AVCaptureInput or Output properties. All changes will be pended until the client calls [session commitConfiguration], at which time they will be applied together. -beginConfiguration / -commitConfiguration pairs may be nested, and will only be applied when the outermost commit is invoked. If you’ve called -beginConfiguration, you must call -commitConfiguration before invoking -startRunning or -stopRunning, otherwise an NSGenericException is thrown.

pub unsafe fn commitConfiguration(&self)

When preceded by beginConfiguration, allows a client to batch multiple configuration operations on a running session into atomic updates.

-beginConfiguration / -commitConfiguration are AVCaptureSession’s mechanism for batching multiple configuration operations on a running session into atomic updates. After calling [session beginConfiguration], clients may add or remove outputs, alter the sessionPreset, or configure individual AVCaptureInput or Output properties. All changes will be pended until the client calls [session commitConfiguration], at which time they will be applied together. -beginConfiguration / -commitConfiguration pairs may be nested, and will only be applied when the outermost commit is invoked. If you’ve called -beginConfiguration, you must call -commitConfiguration before invoking -startRunning or -stopRunning, otherwise an NSGenericException is thrown.

pub unsafe fn isRunning(&self) -> bool

Indicates whether the session is currently running.

The value of this property is a BOOL indicating whether the receiver is running. Clients can key value observe the value of this property to be notified when the session automatically starts or stops running.

pub unsafe fn isInterrupted(&self) -> bool

Indicates whether the session is being interrupted.

The value of this property is a BOOL indicating whether the receiver is currently being interrupted, such as by a phone call or alarm. Clients can key value observe the value of this property to be notified when the session ceases to be interrupted and again has access to needed hardware resources.

pub unsafe fn isMultitaskingCameraAccessSupported(&self) -> bool

Returns whether the session can be configured to use the camera while multitasking.

This property can be used to determine whether multitaskingCameraAccessEnabled may be set to YES. When this property changes from YES to NO, multitaskingCameraAccessEnabled also reverts to NO.

Prior to iOS 18, this property returns YES on iPads that support Stage Manager with an extended display. In applications linked on or after iOS 18, this property returns YES for video conferencing applications (apps that use “voip” as one of their UIBackgroundModes).

This property also returns YES for iOS applications that have the com.apple.developer.avfoundation.multitasking-camera-access entitlement.

This property returns YES on Apple TV.

This property is key-value observable.

pub unsafe fn isMultitaskingCameraAccessEnabled(&self) -> bool

Indicates whether the session is configured to use the camera while multitasking.

The default value is NO. This property may only be set if -isMultitaskingCameraAccessSupported returns YES. This property must be set before the session starts running.

AVCaptureSessions that are configured to use the camera while multitasking will not be interrupted with AVCaptureSessionInterruptionReasonVideoDeviceNotAvailableWithMultipleForegroundApps.

For applications that have the com.apple.developer.avfoundation.multitasking-camera-access entitlement, this property defaults to YES if -isMultitaskingCameraAccessSupported returns YES.

To learn about best practices for using the camera while multitasking, refer to the Accessing the Camera While Multitasking article on developer.apple.com. See https://developer.apple.com/documentation/avkit/accessing_the_camera_while_multitasking .

This property is key-value observable.

pub unsafe fn setMultitaskingCameraAccessEnabled( &self, multitasking_camera_access_enabled: bool, )

Setter for isMultitaskingCameraAccessEnabled.

pub unsafe fn usesApplicationAudioSession(&self) -> bool

Indicates whether the receiver will use the application’s AVAudioSession for recording.

The value of this property is a BOOL indicating whether the receiver is currently using the application’s AVAudioSession (see AVAudioSession.h). Prior to iOS 7, AVCaptureSession uses its own audio session, which can lead to unwanted interruptions when interacting with the application’s audio session. In applications linked on or after iOS 7, AVCaptureSession shares the application’s audio session, allowing for simultaneous play back and recording without unwanted interruptions. Clients desiring the pre-iOS 7 behavior may opt out by setting usesApplicationAudioSession to NO. The default value is YES.

pub unsafe fn setUsesApplicationAudioSession( &self, uses_application_audio_session: bool, )

Setter for usesApplicationAudioSession.

pub unsafe fn automaticallyConfiguresApplicationAudioSession(&self) -> bool

Indicates whether the receiver should configure the application’s audio session for recording.

The value of this property is a BOOL indicating whether the receiver should configure the application’s audio session when needed for optimal recording. When set to YES, the receiver ensures the application’s audio session is set to the PlayAndRecord category, and picks an appropriate microphone and polar pattern to match the video camera being used. When set to NO, and -usesApplicationAudioSession is set to YES, the receiver will use the application’s audio session, but will not change any of its properties. If the session is not set up correctly for input, audio recording may fail. The default value is YES.

pub unsafe fn setAutomaticallyConfiguresApplicationAudioSession( &self, automatically_configures_application_audio_session: bool, )

Setter for automaticallyConfiguresApplicationAudioSession.

pub unsafe fn configuresApplicationAudioSessionToMixWithOthers(&self) -> bool

Indicates whether the receiver should configure the application’s audio session to mix with others.

The value of this property is a BOOL indicating whether the receiver should configure the application’s audio session to mix with, instead of interrupting, any ongoing audio sessions. It has no effect when usesApplicationAudioSession is set to NO. It also has no effect on Live Photo movie complement capture (where music is always mixed with). The default value is NO.

pub unsafe fn setConfiguresApplicationAudioSessionToMixWithOthers( &self, configures_application_audio_session_to_mix_with_others: bool, )

Setter for configuresApplicationAudioSessionToMixWithOthers.

pub unsafe fn configuresApplicationAudioSessionForBluetoothHighQualityRecording( &self, ) -> bool

Indicates whether the receiver should configure the application’s audio session for bluetooth high quality recording.

The value of this property is a BOOL indicating whether the receiver should configure the application’s audio session for bluetooth high quality recording (AirPods as a high quality microphone). When this property is set to true, the AVCaptureSession will opt in for high quality bluetooth recording, allowing users of your app to select AirPods as the active mic source for capture. This property has no effect when usesApplicationAudioSession is set to false. The default value is false.

pub unsafe fn setConfiguresApplicationAudioSessionForBluetoothHighQualityRecording( &self, configures_application_audio_session_for_bluetooth_high_quality_recording: bool, )

Setter for configuresApplicationAudioSessionForBluetoothHighQualityRecording.

pub unsafe fn automaticallyConfiguresCaptureDeviceForWideColor(&self) -> bool

Indicates whether the receiver automatically configures its video device’s activeFormat and activeColorSpace properties, preferring wide color for photos.

The default value is YES. By default, the receiver automatically adjusts its source video AVCaptureDevice’s activeFormat and activeColorSpace properties based on the supportedColorSpaces of the device’s formats and the current AVCaptureSession topology. Wide color spaces are preferred over sRGB if an AVCapturePhotoOutput is present in the session. If you wish to set AVCaptureDevice’s activeColorSpace manually, and prevent the AVCaptureSession from undoing your work, you must set automaticallyConfiguresCaptureDeviceForWideColor to NO. If the receiver’s sessionPreset is set to AVCaptureSessionPresetInputPriority, the session will not alter the capture device’s activeFormat, but might still alter its activeColorSpace.

pub unsafe fn setAutomaticallyConfiguresCaptureDeviceForWideColor( &self, automatically_configures_capture_device_for_wide_color: bool, )

Setter for automaticallyConfiguresCaptureDeviceForWideColor.

pub unsafe fn startRunning(&self)

Starts an AVCaptureSession instance running.

Clients invoke -startRunning to start the flow of data from inputs to outputs connected to the AVCaptureSession instance. This call blocks until the session object has completely started up or failed. A failure to start running is reported through the AVCaptureSessionRuntimeErrorNotification mechanism. If you’ve called -beginConfiguration, you must call -commitConfiguration before invoking -startRunning, otherwise an NSGenericException is thrown.

pub unsafe fn stopRunning(&self)

Stops an AVCaptureSession instance that is currently running.

Clients invoke -stopRunning to stop the flow of data from inputs to outputs connected to the AVCaptureSession instance. This call blocks until the session object has completely stopped. -stopRunning may not be called while the session is being configured. If you’ve called -beginConfiguration, you must call -commitConfiguration before invoking -stopRunning, otherwise an NSGenericException is thrown.

pub unsafe fn synchronizationClock(&self) -> Option<Retained<CMClock>>

Available on crate feature objc2-core-media only.

Provides the clock being used for synchronization.

synchronizationClock is readonly. Use synchronizationClock to synchronize AVCaptureOutput data with external data sources (e.g motion samples). All capture output sample buffer timestamps are on the synchronizationClock timebase.

For example, if you want to reverse synchronize the output timestamps to the original timestamps, you can do the following: In captureOutput:didOutputSampleBuffer:fromConnection:

AVCaptureInputPort *port = [[connection inputPorts] objectAtIndex:0]; CMClockRef originalClock = [port clock];

CMTime syncedPTS = CMSampleBufferGetPresentationTime( sampleBuffer ); CMTime originalPTS = CMSyncConvertTime( syncedPTS, [session synchronizationClock], originalClock );

This property is key-value observable.

pub unsafe fn masterClock(&self) -> Option<Retained<CMClock>>

👎Deprecated

Available on crate feature objc2-core-media only.

Provides the clock being used for synchronization.

Deprecated. Please use synchronizationClock instead.

pub unsafe fn hardwareCost(&self) -> c_float

Indicates the percentage of the session’s available hardware budget currently in use.

The value of this property is a float from 0.0 => 1.0 indicating how much of the session’s available hardware is in use as a percentage, given the currently connected inputs and outputs and the features for which you’ve opted in. When your hardwareCost is greater than 1.0, the capture session cannot run your desired configuration due to hardware constraints, so you receive an AVCaptureSessionRuntimeErrorNotification when attempting to start it running. Default value is 0.

Contributors to hardwareCost include:

• Whether the source device’s active format uses the full sensor (4:3) or a crop (16:9). Cropped formats require lower hardware bandwidth, and therefore lower the cost.
• The max frame rate supported by the source device’s active format. The higher the max frame rate, the higher the cost.
• Whether the source device’s active format is binned or not. Binned formats require substantially less hardware bandwidth, and therefore result in a lower cost.
• The number of sources configured to deliver streaming disparity / depth via AVCaptureDepthDataOutput. The higher the number of cameras configured to produce depth, the higher the cost. For AVCaptureMultiCamSessions, all of the source devices’ active formats contribute to hardwareCost. In order to reduce hardwareCost, consider picking a sensor-cropped activeFormat, or a binned format. You may also use AVCaptureDeviceInput’s videoMinFrameDurationOverride property to artificially limit the max frame rate (which is the reciprocal of the min frame duration) of a source device to a lower value. By doing so, you only pay the hardware cost for the max frame rate you intend to use.

AVCaptureMultiCamSessions always computes this hardwareCost. AVCaptureSessions only computes a non-zero hardwareCost when multiple AVCaptureVideoDataOutputs or an AVCaptureMovieFileOutput and one or more AVCaptureVideoDataOutputs are added to the session.

pub unsafe fn isManualDeferredStartSupported(&self) -> bool

A BOOL value that indicates whether the session supports manually running deferred start.

Deferred Start is a feature that allows you to control, on a per-output basis, whether output objects start when or after the session is started. The session defers starting an output when its deferredStartEnabled property is set to true, and starts it after the session is started.

You can only set the automaticallyRunsDeferredStart property value to false if the session supports manual deferred start.

pub unsafe fn automaticallyRunsDeferredStart(&self) -> bool

A BOOL value that indicates whether deferred start runs automatically.

Deferred Start is a feature that allows you to control, on a per-output basis, whether output objects start when or after the session is started. The session defers starting an output when its AVCaptureOutput/deferredStartEnabled property is set to true, and starts it after the session is started.

When this value is true, AVCaptureSession automatically runs deferred start. If only AVCaptureVideoPreviewLayer objects have AVCaptureVideoPreviewLayer/deferredStartEnabled set to false, the session runs deferred start a short time after displaying the first frame. If there are AVCaptureOutput objects that have AVCaptureOutput/deferredStartEnabled set to false, then the session waits until each output that provides streaming data to your app sends its first frame.

If you set this value to false, call runDeferredStartWhenNeeded to indicate when to run deferred start.

By default, for apps that are linked on or after iOS 26, this value is true.

• Note: If manualDeferredStartSupported is false, setting this property value to false results in the session throwing an NSInvalidArgumentException.

• Note: Set this value before committing the configuration.

pub unsafe fn setAutomaticallyRunsDeferredStart( &self, automatically_runs_deferred_start: bool, )

Setter for automaticallyRunsDeferredStart.

pub unsafe fn runDeferredStartWhenNeeded(&self)

Tells the session to run deferred start when appropriate.

For best perceived startup performance, call this after displaying the first frame, so that deferred start processing doesn’t interfere with other initialization operations. For example, if using a <doc ://com.apple.documentation/documentation/quartzcore/cametallayer> to draw camera frames, add a presentHandler (using <doc ://com.apple.documentation/metal/mtldrawable/addpresentedhandler>) to the first drawable and call runDeferredStartWhenNeeded from there.

If one or more outputs need to start to perform a capture operation, and runDeferredStartWhenNeeded has not run yet, the session runs the deferred start on your app’s behalf. Only call this method once for each configuration commit - after the first call, subsequent calls to runDeferredStartWhenNeeded have no effect. The deferred start runs asynchronously, so this method returns immediately.

• Note: You can only call this when automaticallyRunsDeferredStart is false. Otherwise, the session throws an NSInvalidArgumentException.

• Important: To avoid blocking your app’s UI, don’t call this method from the application’s main actor or queue.

pub unsafe fn deferredStartDelegate( &self, ) -> Option<Retained<ProtocolObject<dyn AVCaptureSessionDeferredStartDelegate>>>

A delegate object that observes events about deferred start.

Call the setDeferredStartDelegate:deferredStartDelegateCallbackQueue: method to set the deferred start delegate for a session.

pub unsafe fn deferredStartDelegateCallbackQueue( &self, ) -> Option<Retained<DispatchQueue>>

Available on crate feature dispatch2 only.

The dispatch queue on which the session calls deferred start delegate methods.

Call the setDeferredStartDelegate:deferredStartDelegateCallbackQueue: method to specify the dispatch queue on which to call the deferred start delegate methods.

pub unsafe fn setDeferredStartDelegate_deferredStartDelegateCallbackQueue( &self, deferred_start_delegate: Option<&ProtocolObject<dyn AVCaptureSessionDeferredStartDelegate>>, deferred_start_delegate_callback_queue: Option<&DispatchQueue>, )

Available on crate feature dispatch2 only.

Sets a delegate object for the session to call when performing deferred start.

This delegate receives a call to the AVCaptureSessionDeferredStartDelegate/sessionWillRunDeferredStart: method when deferred start is about to run. It is non-blocking, so by the time this method is called, the deferred start may already be underway. If you want your app to perform initialization (potentially) concurrently with deferred start (e.g. user-facing camera features that are not needed to display the first preview frame, but are available to the user as soon as possible) it may be done in the delegate’s AVCaptureSessionDeferredStartDelegate/sessionWillRunDeferredStart: method. To wait until deferred start is finished to perform some remaining initialization work, use the AVCaptureSessionDeferredStartDelegate/sessionDidRunDeferredStart: method instead.

The delegate receives a call to the AVCaptureSessionDeferredStartDelegate/sessionDidRunDeferredStart: method when the deferred start finishes running. This allows you to run less-critical application initialization code. For example, if you’ve deferred an AVCapturePhotoOutput by setting its AVCaptureOutput/deferredStartEnabled property to true, and you’d like to do some app-specific initialization related to still capture, here might be a good place to put it.

If the delegate is non-nil, the session still calls the AVCaptureSessionDeferredStartDelegate/sessionWillRunDeferredStart: and AVCaptureSessionDeferredStartDelegate/sessionDidRunDeferredStart: methods regardless of the value of the session’s automaticallyRunsDeferredStart property.

To minimize the capture session’s startup latency, defer all unnecessary work until after the session starts. This delegate provides callbacks for you to schedule deferred work without impacting session startup performance.

To perform initialization prior to deferred start but after the user interface displays, set automaticallyRunsDeferredStart to false, and then run the custom initialization prior to calling runDeferredStartWhenNeeded.

If deferredStartDelegate is not NULL, the session throws an exception if deferredStartDelegateCallbackQueue is nil.

• Parameter deferredStartDelegate: An object conforming to the AVCaptureSessionDeferredStartDelegate protocol that receives events about deferred start.
• Parameter deferredStartDelegateCallbackQueue: A dispatch queue on which deferredStart delegate methods are called.

Safety

deferred_start_delegate_callback_queue possibly has additional threading requirements.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

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

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AVCaptureMultiCamSession> for AVCaptureMultiCamSession

fn as_ref(&self) -> &Self

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

impl AsRef<AVCaptureSession> for AVCaptureMultiCamSession

fn as_ref(&self) -> &AVCaptureSession

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

impl AsRef<AnyObject> for AVCaptureMultiCamSession

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for AVCaptureMultiCamSession

fn as_ref(&self) -> &NSObject

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

impl Borrow<AVCaptureSession> for AVCaptureMultiCamSession

fn borrow(&self) -> &AVCaptureSession

Immutably borrows from an owned value.

impl Borrow<AnyObject> for AVCaptureMultiCamSession

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for AVCaptureMultiCamSession

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for AVCaptureMultiCamSession

const NAME: &'static str = "AVCaptureMultiCamSession"

The name of the Objective-C class that this type represents.

type Super = AVCaptureSession

The superclass of this class.

type ThreadKind = <<AVCaptureMultiCamSession as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for AVCaptureMultiCamSession

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

Formats the value using the given formatter.

impl Deref for AVCaptureMultiCamSession

type Target = AVCaptureSession

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for AVCaptureMultiCamSession

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 AVCaptureMultiCamSession

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for AVCaptureMultiCamSession

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for AVCaptureMultiCamSession

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 AVCaptureMultiCamSession

const ENCODING_REF: Encoding = <AVCaptureSession as ::objc2::RefEncode>::ENCODING_REF

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

impl DowncastTarget for AVCaptureMultiCamSession

impl Eq for AVCaptureMultiCamSession