Struct ARSession 

pub struct ARSession { /* private fields */ }

Available on crate features ARSession and objc2 only.

The ARSession class configures and runs different Augmented Reality techniques on a device.

See also Apple’s documentation

Implementations

impl ARSession

pub unsafe fn identifier(&self) -> Retained<NSUUID>

Available on crate feature objc2-foundation only.

Unique identifier of the running session.

The identifier may change after calling runWithConfiguration.

pub unsafe fn delegate( &self, ) -> Option<Retained<ProtocolObject<dyn ARSessionDelegate>>>

A delegate for receiving ARSession updates.

pub unsafe fn setDelegate( &self, delegate: Option<&ProtocolObject<dyn ARSessionDelegate>>, )

Setter for delegate.

This is a weak property.

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

Available on crate feature dispatch2 only.

The dispatch queue on which the delegate calls are performed.

If not provided or nil, delegate calls will be performed on the main queue.

pub unsafe fn setDelegateQueue(&self, delegate_queue: Option<&DispatchQueue>)

Available on crate feature dispatch2 only.

Setter for delegateQueue.

Safety

delegate_queue possibly has additional threading requirements.

pub unsafe fn currentFrame(&self) -> Option<Retained<ARFrame>>

Available on crate feature ARFrame only.

The current frame of the session.

pub unsafe fn configuration(&self) -> Option<Retained<ARConfiguration>>

Available on crate feature ARConfiguration only.

The configuration currently being used by the session.

pub unsafe fn runWithConfiguration(&self, configuration: &ARConfiguration)

Available on crate feature ARConfiguration only.

Runs the session with the provided configuration.

Calling run on a session that has already started will transition immediately to using the new configuration.

Parameter configuration: The configuration to use.

pub unsafe fn runWithConfiguration_options( &self, configuration: &ARConfiguration, options: ARSessionRunOptions, )

Available on crate feature ARConfiguration only.

Runs the session with the provided configuration and options.

Calling run on a session that has already started will transition immediately to using the new configuration. Options can be used to alter the default behavior when transitioning configurations.

Parameter configuration: The configuration to use.

Parameter options: The run options to use.

pub unsafe fn pause(&self)

Pauses the session.

Once paused, no more updates will be received from the session until run is called again.

pub unsafe fn addAnchor(&self, anchor: &ARAnchor)

Available on crate feature ARAnchor only.

Adds an anchor to the session.

The anchor will be added in the next frame update.

Parameter anchor: The anchor to add.

pub unsafe fn removeAnchor(&self, anchor: &ARAnchor)

Available on crate feature ARAnchor only.

Removes an anchor from the session.

The anchor will be removed from subsequent frame updates.

Parameter anchor: The anchor to remove.

pub unsafe fn getCurrentWorldMapWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut ARWorldMap, *mut NSError)>, )

Available on crate features ARWorldMap and block2 and objc2-foundation only.

Copies the current state of the world being tracked by the session.

A world map is only provided when running an ARWorldTrackingConfiguration.

Parameter completionHandler: The completion handler to call when the get has completed. This handler is executed on the session’s delegate queue. The completion handler takes the following parameters: worldMap - The current world map or nil if unavailable. error - An error that indicates why the world map is unavailable, or nil if a world map was provided.

pub unsafe fn raycast( &self, query: &ARRaycastQuery, ) -> Retained<NSArray<ARRaycastResult>>

Available on crate features ARRaycastQuery and ARRaycastResult and objc2-foundation only.

Perform a raycast.

Parameter query: Raycast query used for raycasting.

Returns: List of raycast results, sorted from nearest to farthest (in distance from the camera). The results could be empty if raycast fails.

pub unsafe fn trackedRaycast_updateHandler( &self, query: &ARRaycastQuery, update_handler: &DynBlock<dyn Fn(NonNull<NSArray<ARRaycastResult>>)>, ) -> Option<Retained<ARTrackedRaycast>>

Available on crate features ARRaycastQuery and ARRaycastResult and ARTrackedRaycast and block2 and objc2-foundation only.

Perform a tracked raycast.

The session performs continuous raycasting and calls the update handler with the updated results. The ARTrackedRaycast object returned can be used to update the raycast with a new raycast query or stop raycasting.

Parameter query: Raycast query used for raycasting.

Parameter updateHandler: update handler where updated list of results, sorted from nearest to farthest (in distance from the camera) are delivered. updateHandler will be called on session’s delegate queue.

Returns: Tracked raycast object used to update or stop raycasting. This could be nil if the raycast fails or if the configuration is not ARWorldTrackingConfiguration or its subclasses.

pub unsafe fn updateWithCollaborationData( &self, collaboration_data: &ARCollaborationData, )

Available on crate feature ARCollaborationData only.

Update session with collaboration data.

Use this to update the session with collaboration data received from other participants.

Parameter collaborationData: Collaboration data for updating the session.

See: ARCollaborationData

pub unsafe fn captureHighResolutionFrameWithCompletion( &self, completion: &DynBlock<dyn Fn(*mut ARFrame, *mut NSError)>, )

Available on crate features ARFrame and block2 and objc2-foundation only.

Requests a single, high resolution frame to be captured.

Some video formats do not support a significantly higher still image resolution than the streaming camera resolution. Use the isRecommendedForHighResolutionFrameCapturingmethod on the video format to check if the format is recommended.

See: -[ARVideoFormat isRecommendedForHighResolutionFrameCapturing]

Parameter completion: Block being called when the call completes.

pub unsafe fn captureHighResolutionFrameUsingPhotoSettings_completion( &self, photo_settings: Option<&AVCapturePhotoSettings>, completion: &DynBlock<dyn Fn(*mut ARFrame, *mut NSError)>, )

Available on crate features ARFrame and block2 and objc2-av-foundation and objc2-foundation only.

Requests a single, high resolution frame to be captured.

Some video formats do not support a significantly higher still image resolution than the streaming camera resolution. Use the isRecommendedForHighResolutionFrameCapturingmethod on the video format to check if the format is recommended. For passing customized photo settings to this method, obtain a defaultPhotoSettingsobject from the video format and modify it.

See: -[ARVideoFormat isRecommendedForHighResolutionFrameCapturing]

See: -[ARVideoFormat defaultPhotoSettings]

Parameter photoSettings: Custom AVCapturePhotoSettings to be used.

Parameter completion: Block being called when the call completes.

impl ARSession

Methods declared on superclass NSObject.

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

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

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<ARSession> for ARSession

fn as_ref(&self) -> &Self

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

impl AsRef<AnyObject> for ARSession

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for ARSession

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for ARSession

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for ARSession

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for ARSession

const NAME: &'static str = "ARSession"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = <<ARSession 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 ARSession

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

Formats the value using the given formatter.

impl Deref for ARSession

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for ARSession

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 ARSession

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for ARSession

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 ARSession

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 ARSession

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

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

impl DowncastTarget for ARSession

impl Eq for ARSession