Skip to content

openxr-spatial.md

Latest commit

 

History

History
112 lines (88 loc) · 4.29 KB

openxr-spatial.md

File metadata and controls

112 lines (88 loc) · 4.29 KB
Raw

OpenXR Spatial Entities Compiler

Compiles HoloScript spatial anchoring definitions to the OpenXR Spatial Entities extension — the Khronos standard for persistent, world-locked AR anchors across platforms.

Overview

The OpenXR Spatial Entities compiler (--target openxr-spatial) generates C++ or JSON configuration for the OpenXR XR_EXT_spatial_entity and XR_MSFT_scene_understanding extensions. These are the standard mechanisms for:

  • Persistent world anchors — objects that stay stuck to real surfaces across sessions
  • Plane detection — horizontal and vertical surface tracking
  • Scene understanding — semantic labels on detected surfaces (floor, wall, table, ceiling)
  • Cross-device persistence — anchors shared between users on Meta Quest, HoloLens, PICO, and Magic Leap
holoscript compile anchors.holo --target openxr-spatial --output ./xr/

Spatial Anchor Traits

HoloScript Trait OpenXR Extension Behaviour
@anchor XR_EXT_spatial_entity Create + persist spatial anchor
@world_locked XrSpatialEntityFlagsEXT Lock to physical world position
@plane_detected XR_MSFT_scene_understanding Snap to detected plane
@tracked XrSpaceLocationFlags Track with 6DOF pose
@hand_tracked XR_EXT_hand_tracking Hand joint anchor
@eye_tracked XR_EXT_eye_gaze_interaction Gaze-stabilized anchor
@persistent xrSaveSpaceXR_EXT_spatial_entity Save anchor UUID across sessions

Example

composition "PersistentARNotes" {
  template "StickyNote" {
    @anchor
    @world_locked
    @persistent

    geometry: "plane"
    scale: [0.2, 0.15, 0.01]
    color: "#ffff88"

    state {
      uuid: ""
      text: "Note content here"
    }

    on_place {
      this.uuid = spatial.createAnchor(this.position, this.rotation)
      spatial.saveAnchor(this.uuid)
    }

    on_load {
      spatial.loadAnchor(this.uuid)
    }
  }

  logic {
    on_plane_detected(plane) {
      if (plane.label == "table") {
        spawn "StickyNote" at plane.center
      }
    }
  }
}

Output

xr/
  anchors.h            # C++ OpenXR extension calls
  anchor_config.json   # Anchor UUIDs and poses
  spatial_mesh.json    # Detected planes / mesh

Generated C++ (excerpt):

// Create persistent spatial anchor
XrSpatialEntityFlagsEXT flags = XR_SPATIAL_ENTITY_PERSIST_BIT_EXT;
XrCreateSpatialEntityInfoMSFT createInfo{XR_TYPE_CREATE_SPATIAL_ENTITY_INFO_MSFT};
createInfo.pose = anchorPose;
xrCreateSpatialEntityMSFT(session, &createInfo, &spatialAnchor);
xrSaveSpatialEntityMSFT(session, &saveInfo);  // Persist across sessions

Supported Runtimes

Runtime Device Required Extension
Meta OpenXR Quest 2/3/Pro XR_FB_spatial_entity
Microsoft OpenXR HoloLens 2 XR_MSFT_spatial_anchor
PICO OpenXR PICO 4 XR_EXT_spatial_entity
Magic Leap OpenXR Magic Leap 2 XR_ML_localization_map
SteamVR Index / Vive XR_EXT_spatial_entity (limited)

Compiler Options

Option Default Description
--oxr-runtime generic Target runtime: meta, msft, pico, ml
--oxr-persistence true Enable cross-session anchor persistence
--oxr-plane-detection true Enable plane detection
--oxr-scene-mesh false Enable full environment mesh
--oxr-sharing false Enable anchor sharing between users

See Also