Struct World

pub struct World;

World contains information about the real world around the user. This includes things like play boundaries, scene understanding, and other various things. https://stereokit.net/Pages/StereoKit/World.html

Implementations

impl World

pub fn occlusion_enabled(enabled: bool)

Off by default. This tells StereoKit to load up and display an occlusion surface that allows the real world to occlude the application’s digital content! Most systems may allow you to customize the visual appearance of this occlusion surface via the World::occlusion_material. Check crate::sk::SystemInfo::get_world_occlusion_present to see if occlusion can be enabled. This will reset itself to false if occlusion isn’t possible. Loading occlusion data is asynchronous, so occlusion may not occur immediately after setting this flag. https://stereokit.net/Pages/StereoKit/World/OcclusionEnabled.html

see also world_set_occlusion_enabled

Examples

use stereokit_rust::{system::World};

let occlusion_is_present = sk.get_system().get_world_occlusion_present();

// By default, occlusion is disabled.
assert_eq!(World::get_occlusion_enabled(), false);

World::occlusion_enabled(true);
if occlusion_is_present {
    assert_eq!(World::get_occlusion_enabled(), true);
} else {
    assert_eq!(World::get_occlusion_enabled(), false);
}

World::occlusion_enabled(false);
assert_eq!(World::get_occlusion_enabled(), false);

pub fn occlusion_material(material: impl AsRef<Material>)

By default, this is a black(0,0,0,0) opaque unlit material that will occlude geometry, but won’t show up as visible anywhere. You can override this with whatever material you would like. https://stereokit.net/Pages/StereoKit/World/OcclusionMaterial.html

see also world_set_occlusion_material

Examples

use stereokit_rust::{system::World, util::named_colors, material::Material};

let occlusion_is_present = sk.get_system().get_world_occlusion_present();

assert_eq!(World::get_occlusion_material().get_id(), "sk/world/material");

let mut material = Material::unlit().copy();
material.color_tint(named_colors::RED);

World::occlusion_enabled(true);
World::occlusion_material(&material);

if occlusion_is_present {
    assert_eq!(World::get_occlusion_enabled(), true);
    assert_eq!(World::get_occlusion_material(), material);
} else {
    assert_eq!(World::get_occlusion_enabled(), false);
    assert_eq!(World::get_occlusion_material(), material);
}

pub fn origin_offset(offset: impl Into<Pose>)

This is relative to the base reference point and is NOT in world space! The origin StereoKit uses is actually a base reference point combined with an offset! You can use this to read or set the offset from the OriginMode reference point. https://stereokit.net/Pages/StereoKit/World/OriginOffset.html

see also world_set_origin_offset crate::sk::SkSettings::origin

Examples

use stereokit_rust::{maths::{Vec3, Pose}, system::World};

assert_eq!(World::get_origin_offset(), Pose::ZERO);

let offset = Pose::new([0.0, 0.0, 0.01], None);
if false {World::origin_offset(offset);}

pub fn raycast_enabled(enabled: bool)

Off by default. This tells StereoKit to load up collision meshes for the environment, for use with World::raycast. Check crate::sk::SystemInfo::get_world_raycast_present to see if raycasting can be enabled. This will reset itself to false if raycasting isn’t possible. Loading raycasting data is asynchronous, so collision surfaces may not be available immediately after setting this flag. https://stereokit.net/Pages/StereoKit/World/RaycastEnabled.html

see also world_set_raycast_enabled

Examples

use stereokit_rust::system::World;

let raycast_is_present = sk.get_system().get_world_raycast_present();

assert_eq!(World::get_raycast_enabled(), false);

World::raycast_enabled(true);

if raycast_is_present {
    assert_eq!(World::get_raycast_enabled(), true);
} else {
    assert_eq!(World::get_raycast_enabled(), false);
}
World::raycast_enabled(false);
assert_eq!(World::get_raycast_enabled(), false);

pub fn refresh_interval(speed: f32)

The refresh interval speed, in seconds. This is only applicable when using WorldRefresh::Timer for the refresh type. Note that the system may not be able to refresh as fast as you wish, and in that case, StereoKit will always refresh as soon as the previous refresh finishes. https://stereokit.net/Pages/StereoKit/World/RefreshInterval.html

see also world_set_refresh_interval

Examples

use stereokit_rust::system::World;

let occlusion_is_present = sk.get_system().get_world_occlusion_present();

World::occlusion_enabled(true);
World:: refresh_interval(0.01);

if occlusion_is_present {
    assert_eq!(World::get_occlusion_enabled(), true);
    assert_eq!(World::get_refresh_interval(), 0.01);
} else {
    assert_eq!(World::get_occlusion_enabled(), false);
    assert_eq!(World::get_refresh_interval(), 0.0);
}

pub fn refresh_radius(distance: f32)

Radius, in meters, of the area that StereoKit should scan for world data. Default is 4. When using the WorldRefresh::Area refresh type, the world data will refresh when the user has traveled half this radius from the center of where the most recent refresh occurred. https://stereokit.net/Pages/StereoKit/World/RefreshRadius.html

see also world_set_refresh_radius

Examples

use stereokit_rust::system::World;

let occlusion_is_present = sk.get_system().get_world_occlusion_present();

World::occlusion_enabled(true);
World:: refresh_radius(3.5);

if occlusion_is_present {
    assert_eq!(World::get_occlusion_enabled(), true);
    assert_eq!(World::get_refresh_radius(), 3.5);
} else {
    assert_eq!(World::get_occlusion_enabled(), false);
    assert_eq!(World::get_refresh_radius(), 0.0);
}

pub fn refresh_type(refresh_type: WorldRefresh)

What information should StereoKit use to determine when the next world data refresh happens? See the WorldRefresh enum for details. https://stereokit.net/Pages/StereoKit/World/RefreshType.html

see also world_set_refresh_type

Examples

use stereokit_rust::system::{World, WorldRefresh};

let occlusion_is_present = sk.get_system().get_world_occlusion_present();

World::occlusion_enabled(true);
World::refresh_type(WorldRefresh::Timer);

if occlusion_is_present {
    assert_eq!(World::get_occlusion_enabled(), true);
    assert_eq!(World::get_refresh_type(), WorldRefresh::Timer);
} else {
    assert_eq!(World::get_occlusion_enabled(), false);
    assert_eq!(World::get_refresh_type(), WorldRefresh::Area);
}

pub fn from_perception_anchor( perception_spatial_anchor: *mut c_void, ) -> Option<Pose>

Converts a Windows.Perception.Spatial.SpatialAnchor’s pose into SteroKit’s coordinate system. This can be great for interacting with some of the UWP spatial APIs such as WorldAnchors.

This method only works on UWP platforms, check Sk.System.perception_bridge_present to see if this is available. https://stereokit.net/Pages/StereoKit/World/FromPerceptionAnchor.html

see also world_from_perception_anchor

pub fn from_spatial_node( spatial_graph_node_id: impl AsRef<str>, spatial_node_type: SpatialNodeType, qpc_time: i64, ) -> Option<Pose>

Converts a Windows Mirage spatial node GUID into a Pose based on its current position and rotation! Check Sk::System::spatial_bridge_present to see if this is available to use. Currently only on HoloLens, good for use with the Windows QR code package. https://stereokit.net/Pages/StereoKit/World/FromSpatialNode.html

• spatial_graph_node_id - A Windows Mirage spatial node GUID acquired from a windows MR API call.
• spatial_node_type - Type of spatial node to locate.
• qpc_time : A windows performance counter timestamp at which the node should be located, obtained from another API or with System.Diagnostics.Stopwatch.GetTimestamp().

see also world_try_from_spatial_graph

Examples

use stereokit_rust::system::{World, SpatialNodeType};

let spatial_bridge_is_present = sk.get_system().get_spatial_bridge_present();

World::refresh_radius(3.5);

if spatial_bridge_is_present {
    World::from_spatial_node("A test", SpatialNodeType::Static, 0);
}

pub fn raycast(ray: impl Into<Ray>) -> Option<Ray>

World::raycast_enabled must be set to true first! Sk::System::world_raycast_present must also be true. This does a ray intersection with whatever represents the environment at the moment! In this case, it’s a watertight collection of low resolution meshes calculated by the Scene Understanding extension, which is only provided by the Microsoft HoloLens runtime. https://stereokit.net/Pages/StereoKit/World/Raycast.html

• ray - A world space ray that you’d like to try intersecting with the world mesh.

Returns The location of the intersection, and direction of the world’s surface at that point if found. see also world_raycast

Examples

use stereokit_rust::{system::{Assets, World}, maths::{Vec3,Ray}};
Assets::block_for_priority(i32::MAX);

let raycast_is_present = sk.get_system().get_world_raycast_present();

assert_eq!(World::get_raycast_enabled(), false);

World::raycast_enabled(true);
let ray = Ray::new(Vec3::ZERO, Vec3::ONE);

if raycast_is_present {
    assert_eq!(World::raycast(ray), None);
} else {
    assert_eq!(World::raycast(ray), None);
}

pub fn get_bounds_pose() -> Pose

This is the orientation and center point of the system’s boundary/guardian. This can be useful to find the floor height! Not all systems have a boundary, so be sure to check World::has_bounds first. https://stereokit.net/Pages/StereoKit/World/BoundsPose.html

see also world_get_bounds_pose

Examples

use stereokit_rust::{system::World, maths::Pose};

let bounds_pose = World::get_bounds_pose();

if World::has_bounds(){
    // These are results for a non OpenXR environment:
    assert_eq!(bounds_pose, Pose::IDENTITY);
} else {
    // These are results for a non OpenXR environment:
    assert_eq!(bounds_pose, Pose::IDENTITY);
}

pub fn get_bounds_size() -> Vec2

This is the size of a rectangle within the play boundary/guardian’s space, in meters if one exists. Check World::get_bounds_pose for the center point and orientation of the boundary, and check World::has_bounds to see if it exists at all! https://stereokit.net/Pages/StereoKit/World/BoundsSize.html

see also world_get_bounds_size

Examples

use stereokit_rust::{system::World, maths::Vec2};

let bounds_size = World::get_bounds_size();

if World::has_bounds(){
    // These are results for a non OpenXR environment:
    assert_ne!(bounds_size, Vec2::ZERO);
} else {
    // These are results for a non OpenXR environment:
    assert_eq!(bounds_size, Vec2::ZERO);
}

pub fn has_bounds() -> bool

This refers to the play boundary, or guardian system that the system may have! Not all systems have this, so it’s always a good idea to check this first! https://stereokit.net/Pages/StereoKit/World/HasBounds.html

see also world_has_bounds see example in World::get_bounds_size World::get_bounds_pose

pub fn get_occlusion_enabled() -> bool

Off by default. This tells StereoKit to load up and display an occlusion surface that allows the real world to occlude the application’s digital content! Most systems may allow you to customize the visual appearance of this occlusion surface via the World::occlusion_material. Check SK::System::world_occlusion_present to see if occlusion can be enabled. This will reset itself to false if occlusion isn’t possible. Loading occlusion data is asynchronous, so occlusion may not occur immediately after setting this flag. https://stereokit.net/Pages/StereoKit/World/OcclusionEnabled.html

see also world_get_occlusion_enabled see example in World::occlusion_enabled

pub fn get_occlusion_material() -> Material

By default, this is a black(0,0,0,0) opaque unlit material that will occlude geometry, but won’t show up as visible anywhere. You can override this with whatever material you would like. https://stereokit.net/Pages/StereoKit/World/OcclusionMaterial.html

see also world_get_occlusion_material see example in World::occlusion_material

pub fn get_origin_mode() -> OriginMode

The mode or “reference space” that StereoKit uses for determining its base origin. This is determined by the initial value provided in [crate::sk::SkSettings.origin], as well as by support from the underlying runtime. The mode reported here will not necessarily be the one requested in initialization, as fallbacks are implemented using different available modes. https://stereokit.net/Pages/StereoKit/World/OriginMode.html

see also world_get_origin_mode

Examples

use stereokit_rust::system::World;

let origin_mode_init = sk.get_settings().origin;

let origin_mode = World::get_origin_mode();

assert_eq!(origin_mode_init, origin_mode);

pub fn get_tracked() -> BtnState

This reports the status of the device’s positional tracking. If the room is too dark, or a hand is covering tracking sensors, or some other similar 6dof tracking failure, this would report as not tracked.

Note that this does not factor in the status of rotational tracking. Rotation is typically done via gyroscopes/accelerometers, which don’t really fail the same way positional tracking system can. https://stereokit.net/Pages/StereoKit/World/Tracked.html

see also world_get_tracked

Examples

use stereokit_rust::system::{World, BtnState};

let is_tracked = World::get_tracked();

assert_eq!(is_tracked, BtnState::Active);

pub fn get_origin_offset() -> Pose

This is relative to the base reference point and is NOT in world space! The origin StereoKit uses is actually a base reference point combined with an offset! You can use this to read or set the offset from the OriginMode reference point. https://stereokit.net/Pages/StereoKit/World/OriginOffset.html

see also world_get_origin_offset see example in World::origin_offset

pub fn get_raycast_enabled() -> bool

Off by default. This tells StereoKit to load up collision meshes for the environment, for use with World::raycast. Check SK::System::world_raycast_present to see if raycasting can be enabled. This will reset itself to false if raycasting isn’t possible. Loading raycasting data is asynchronous, so collision surfaces may not be available immediately after setting this flag. https://stereokit.net/Pages/StereoKit/World/RaycastEnabled.html

see also world_get_raycast_enabled see example in World::raycast_enabled

pub fn get_refresh_interval() -> f32

The refresh interval speed, in seconds. This is only applicable when using WorldRefresh::Timer for the refresh type. Note that the system may not be able to refresh as fast as you wish, and in that case, StereoKit will always refresh as soon as the previous refresh finishes. https://stereokit.net/Pages/StereoKit/World/RefreshInterval.html

see also world_get_refresh_interval see example in World::refresh_interval

pub fn get_refresh_radius() -> f32

Radius, in meters, of the area that StereoKit should scan for world data. Default is 4. When using the WorldRefresh::Area refresh type, the world data will refresh when the user has traveled half this radius from the center of where the most recent refresh occurred. https://stereokit.net/Pages/StereoKit/World/RefreshRadius.html

see also world_get_refresh_radius see example in World::refresh_radius

pub fn get_refresh_type() -> WorldRefresh

What information should StereoKit use to determine when the next world data refresh happens? See the WorldRefresh enum for details. https://stereokit.net/Pages/StereoKit/World/RefreshType.html

see also world_get_refresh_type see example in World::refresh_type