Skip to main content
Version: 12 Dec 2024

Reference Space Overview

Reference Spaces are different methods of defining the origin and orientation of the coordinate system used by the device within your application. They affect how the device tracks the position and rotation of the user and the environment. Different modes are suitable for various types of applications and experiences.

The Magic Leap 2 Reference Space OpenXR Feature allows developers to change the tracking origin via Unity's XR Origin Component. The following modes are supported:

  • Device: Mapped to Local Space. The origin is at the initial position and orientation of the device when the application starts.
  • Floor: Mapped to Stage Space. The XR Origin is at the initial position of the user’s device, but on the floor level. The y-axis of the XR Origin is aligned with the gravity vector provided by the XR system.
  • Unbounded: The origin is at the position where the device began or regained tracking.
caution

This feature requires the OpenXR Magic Leap 2 Reference Space Feature to be enabled in your project's OpenXR Settings (Window > XR Plugin Manager > OpenXR Settings).

tip

Some tracking origin options, such as unbounded space, are not visible in the inspector and must be set programmatically. See the Querying Supported Reference Spaces or Using Unbounded Space examples.

OpenXR Mapping​

The Magic Leap 2 Reference Space feature uses OpenXR XRSpaces Specification.

Unity OpenXR Feature: MagicLeapReferenceSpaceFeature

Supported Spaces:

  • XR_REFERENCE_SPACE_TYPE_VIEW - View locked, origin inside the headset at all times, content will move with the view.
  • XR_REFERENCE_SPACE_TYPE_LOCAL - World locked, origin at application startup head pose position.
  • XR_REFERENCE_SPACE_TYPE_STAGE - World locked, origin at floor level.
  • XR_REFERENCE_SPACE_TYPE_LOCAL_FLOOR_EXT - World locked, origin under application startup head pose on the floor.
  • XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT - World locked, origin at headset startup head pose position, or re-localized position.

Unity XRInputSubsystem Mapping​

The Tracking Origin Mode of the XRInputSubsystem maps to the corresponding OpenXR reference spaces.

Tracking Origin ModeOpenXR Equivalent
DeviceXR_REFERENCE_SPACE_TYPE_LOCAL
FloorXR_REFERENCE_SPACE_TYPE_STAGE
UnboundedXR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT

The XR Origin component is where you normally specify your desired Tracking Origin Mode. Unity will attempt to assign your selection to the XRInputSubsystem when the scene loads.

If you leave the XR Origin’s Tracking Origin Mode as “Not Specified”, Unity defaults to Floor. This is because the OpenXR Plugin attempts to attach the Stage Space where possible.