Struct Anchor

#[repr(C)]
pub struct Anchor(pub NonNull<_AnchorT>);

An Anchor in StereoKit is a completely virtual pose that is pinned to a real-world location. They are creatable via code, generally can persist across sessions, may provide additional stability beyond the system’s 6dof tracking, and are not physical objects!

This functionality is backed by extensions like the Microsoft Spatial Anchor, or the Facebook Spatial Entity. If a proper anchoring system isn’t present on the device, StereoKit will fall back to a stage- relative anchor. Stage-relative anchors may be a good solution for devices with a consistent stage, but may be troublesome if the user adjusts their stage frequently.

A conceptual guide to Anchors:

• A cloud anchor is an Anchor
• A QR code is not an Anchor (it’s physical)
• That spot around where your coffee usually sits can be an Anchor
• A semantically labeled floor plane is not an Anchor (it’s physical)

https://stereokit.net/Pages/StereoKit/Anchor.html

Examples

use stereokit_rust::{anchor::{Anchor, AnchorCaps}, maths::Pose};

let storable = !(Anchor::get_capabilities() & AnchorCaps::Storable).is_empty();
let stability = !(Anchor::get_capabilities() & AnchorCaps::Stability).is_empty();
if storable || stability {
    // create an anchor in center of the world
    let anchor = Anchor::from_pose(Pose::default()).expect("What?!!!?");
    anchor.try_set_persistent(true);
}

Tuple Fields

0: NonNull<_AnchorT>

Implementations

impl Anchor

pub fn find<S: AsRef<str>>(id: S) -> Result<Anchor, StereoKitError>

Searches the asset list for an anchor with the given Id. https://stereokit.net/Pages/StereoKit/Anchor/Find.html

• id - The Id to search for.

see also anchor_find

Examples

use stereokit_rust::anchor::Anchor;

let my_anchor = Anchor::find("the_anchor that doesn't exist");
assert!(my_anchor.is_err());

pub fn clone_ref(&self) -> Anchor

Creates a clone of the same reference. Basically, the new variable is the same asset. This is what you get by calling find() method. https://stereokit.net/Pages/StereoKit/Anchor/Find.html

see also anchor_find()

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

// create an anchor in center of the world
if let Ok(anchor) = Anchor::from_pose(Pose::default()){;
    let same = anchor.clone_ref();
    assert_eq!(same.get_id(), anchor.get_id());
}

pub fn from_pose(pose: impl Into<Pose>) -> Result<Anchor, StereoKitError>

This creates a new Anchor from a world space pose. https://stereokit.net/Pages/StereoKit/Anchor/FromPose.html

• pose - A world space pose for the new Anchor

see also anchor_create

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

// create an anchor in center of the world
if let Ok(anchor) = Anchor::from_pose(Pose::default()){;
    anchor.try_set_persistent(true);
}

pub fn id<S: AsRef<str>>(&mut self, id: S) -> &mut Self

Gets or sets the unique identifier of this asset resource! This can be helpful for debugging, managing your assets, or finding them later on! This is StereoKit’s asset ID, and not the system’s unique Name for the anchor. https://stereokit.net/Pages/StereoKit/Anchor/Id.html

• id - The new id for this Anchor.

see also anchor_set_id

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

// create an anchor in center of the world
if let Ok(mut anchor) = Anchor::from_pose(Pose::default()){;
    anchor.id("my_anchor");
    assert_eq!(anchor.get_id(), "my_anchor");
}

pub fn clear_store()

This will remove persistence from all Anchors the app knows about, even if they aren’t tracked. https://stereokit.net/Pages/StereoKit/Anchor/ClearStored.html

see also anchor_clear_stored

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

Anchor::clear_store();
assert_eq!(Anchor::anchors().get_count(), 0);
assert_eq!(Anchor::new_anchors().get_count(), 0);

pub fn anchors() -> AnchorIter

Get an iterator of all Anchors that exist in StereoKit at the current moment. https://stereokit.net/Pages/StereoKit/Anchor/Anchors.html

see also anchor_get_count anchor_get_index

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

assert_eq!(Anchor::anchors().get_count(), 0);

pub fn new_anchors() -> AnchorIter

Get an iterator of all Anchors that are new to StereoKit this frame. https://stereokit.net/Pages/StereoKit/Anchor/Anchors.html

see also anchor_get_new_count anchor_get_new_index

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

assert_eq!(Anchor::new_anchors().get_count(), 0);

pub fn try_set_persistent(&self, persistent: bool) -> bool

This will attempt to make or prevent this Anchor from persisting across app sessions. You may want to check if the system is capable of persisting anchors via Anchors.Capabilities, but it’s possible for this to fail on the OpenXR runtime’s side as well. https://stereokit.net/Pages/StereoKit/Anchor/TrySetPersistent.html

see also anchor_try_set_persistent

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

// create an anchor in center of the world
if let Ok(mut anchor) = Anchor::from_pose(Pose::default()){;
    assert_eq!(anchor.get_persistent(), false);
    anchor.try_set_persistent(true);
    assert_eq!(anchor.get_persistent(), true);
}

pub fn get_capabilities() -> AnchorCaps

This describes the anchoring capabilities of the current XR anchoring backend. Some systems like a HoloLens can create Anchors that provide stability, and can persist across multiple sessions. Some like SteamVR might be able to make a persistent Anchor that’s relative to the stage, but doesn’t provide any stability benefits. https://stereokit.net/Pages/StereoKit/Anchor/Capabilities.html

see also anchor_get_capabilities

Examples

use stereokit_rust::{anchor::{Anchor, AnchorCaps}, maths::Pose};

let storable = !(Anchor::get_capabilities() & AnchorCaps::Storable).is_empty();
let stability = !(Anchor::get_capabilities() & AnchorCaps::Stability).is_empty();
if storable || stability {
    // create an anchor in center of the world
    let anchor = Anchor::from_pose(Pose::default()).expect("What?!!!?");
    anchor.try_set_persistent(true);
}

pub fn get_id(&self) -> &str

The id of this anchor. This is StereoKit’s asset ID, and not the system’s unique Name for the anchor. https://stereokit.net/Pages/StereoKit/Anchor/Id.html

see also anchor_get_id see example in Anchor::id

pub fn get_pose(&self) -> Pose

The most recently identified Pose of the Anchor. While an Anchor will generally be in the same position once discovered, it may shift slightly to compensate for drift in the device’s 6dof tracking. Anchor Poses when tracked are more accurate than world-space positions. https://stereokit.net/Pages/StereoKit/Anchor/Pose.html

see also anchor_get_pose

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose};

// create an anchor in center of the world
if let Ok(mut anchor) = Anchor::from_pose(Pose::default()){;
    assert_eq!(anchor.get_pose(), Pose::default());
}

pub fn get_tracked(&self) -> BtnState

Does the device consider this Anchor to be tracked? This doesn’t require the Anchor to be visible, just that the device knows where this Anchor is located. https://stereokit.net/Pages/StereoKit/Anchor/Tracked.html

see also anchor_get_tracked

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose, system::BtnState};

// create an anchor in center of the world
if let Ok(mut anchor) = Anchor::from_pose(Pose::default()){;
    assert_eq!(anchor.get_tracked(), BtnState::Active);
}

pub fn get_persistent(&self) -> bool

Will this Anchor persist across multiple app sessions? You can use TrySetPersistent to change this value. https://stereokit.net/Pages/StereoKit/Anchor/Persistent.html

see also anchor_get_persistent see example in Anchor::try_set_persistent

pub fn get_name(&self) -> &str

A unique system provided name identifying this anchor. This will be the same across sessions for persistent Anchors. https://stereokit.net/Pages/StereoKit/Anchor/Name.html

see also anchor_get_name

Examples

use stereokit_rust::{anchor::Anchor, maths::Pose, system::BtnState};

// create an anchor in center of the world
if let Ok(mut anchor) = Anchor::from_pose(Pose::default()){;
    assert_eq!(anchor.get_name().is_empty(), false);
}

pub fn try_get_perception_anchor<T>(&self) -> Option<*mut T>

Tries to get the underlying perception spatial anchor for platforms using Microsoft spatial anchors. https://stereokit.net/Pages/StereoKit/Anchor/TryGetPerceptionAnchor.html

• 'T' - The type of the spatial anchor. Must corresponds to the the Windows API type of Windows.Perception.Spatial.SpatialAnchor.
• spatial_anchor - The spatial anchor.

returns Some(anchor) if the perception spatial anchor was successfully obtained, false otherwise.

see also anchor_get_name

Trait Implementations

impl AsRef<Anchor> for Anchor

fn as_ref(&self) -> &Anchor

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

impl Debug for Anchor

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

Formats the value using the given formatter.

impl Drop for Anchor

fn drop(&mut self)

Executes the destructor for this type.

impl IAsset for Anchor

fn get_id(&self) -> &str

gets the unique identifier of this asset resource! This can be helpful for debugging, managing your assets, or finding them later on! https://stereokit.net/Pages/StereoKit/IAsset/Id.html

impl PartialEq for Anchor

fn eq(&self, other: &Anchor) -> 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 StructuralPartialEq for Anchor