xrCreateSpatialAnchorMSFT - Creates a spatial anchor

Parameter Descriptions

Description

Creates an SpatialAnchorMSFT handle representing a spatial anchor that will track a fixed location in the physical world over time. That real-world location is specified by the position and orientation of the specified pose within space at time.

If space cannot be located relative to the environment at the moment of the call to createSpatialAnchorMSFT, the runtime must return ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT.

After the anchor is created, the runtime should then adjust its position and orientation over time relative to other spaces so as to maintain maximum alignment to its original real-world location, even if that changes the anchor’s relationship to the original space used to initialize it.

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling createSpatialAnchorMSFT

• session must be a valid Session handle
• createInfo must be a pointer to a valid SpatialAnchorCreateInfoMSFT structure
• anchor must be a pointer to an SpatialAnchorMSFT handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_INSTANCE_LOST
• ERROR_OUT_OF_MEMORY
• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_POSE_INVALID
• ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT
• ERROR_TIME_INVALID
• ERROR_SESSION_LOST
• SESSION_LOSS_PENDING

See Also

Session, SpatialAnchorCreateInfoMSFT, SpatialAnchorMSFT

A convenience wrapper to make a compatible pair of calls to createSpatialAnchorMSFT and destroySpatialAnchorMSFT

To ensure that destroySpatialAnchorMSFT is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

xrCreateSpatialAnchorSpaceMSFT - Creates a space from a spatial anchor

Parameter Descriptions

Description

Creates an Space handle based on a spatial anchor. Application can provide an Posef to define the position and orientation of the new space’s origin relative to the anchor’s natural origin.

Multiple Space handles may exist for a given SpatialAnchorMSFT simultaneously, up to some limit imposed by the runtime. The Space handle must be eventually freed via the destroySpace function or by destroying the parent SpatialAnchorMSFT handle.

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling createSpatialAnchorSpaceMSFT

• session must be a valid Session handle
• createInfo must be a pointer to a valid SpatialAnchorSpaceCreateInfoMSFT structure
• space must be a pointer to an Space handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_INSTANCE_LOST
• ERROR_OUT_OF_MEMORY
• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_POSE_INVALID
• ERROR_SESSION_LOST
• SESSION_LOSS_PENDING

See Also

Session, Space, SpatialAnchorMSFT, SpatialAnchorSpaceCreateInfoMSFT

A convenience wrapper to make a compatible pair of calls to createSpatialAnchorSpaceMSFT and destroySpace

To ensure that destroySpace is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

xrDestroySpatialAnchorMSFT - Destroys a spatial anchor

Parameter Descriptions

Description

SpatialAnchorMSFT handles are destroyed using destroySpatialAnchorMSFT. By destroying an anchor, the runtime can stop spending resources used to maintain tracking for that anchor’s origin.

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling destroySpatialAnchorMSFT

• anchor must be a valid SpatialAnchorMSFT handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_FUNCTION_UNSUPPORTED

See Also

SpatialAnchorMSFT, createSpatialAnchorMSFT

XrSpatialAnchorCreateInfoMSFT - Information to create a spatial anchor

Valid Usage (Implicit)

• The @@ extension must be enabled prior to using SpatialAnchorCreateInfoMSFT

• type must be TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT
• next must be NULL or a valid pointer to the next structure in a structure chain
• space must be a valid Space handle

See Also

Posef, Space, SpatialAnchorMSFT, StructureType, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrTime, createSpatialAnchorMSFT

XrSpatialAnchorSpaceCreateInfoMSFT - Information to create a space from a spatial anchor

Valid Usage (Implicit)

• The @@ extension must be enabled prior to using SpatialAnchorSpaceCreateInfoMSFT

• type must be TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT
• next must be NULL or a valid pointer to the next structure in a structure chain
• anchor must be a valid SpatialAnchorMSFT handle

See Also

Posef, Space, SpatialAnchorMSFT, StructureType, createSpatialAnchorSpaceMSFT

XrSpatialAnchorMSFT - Represents a spatial anchor

Description

Spatial anchors are often used in combination with an UNBOUNDED_MSFT reference space. UNBOUNDED_MSFT reference spaces adjust their origin as necessary to keep the viewer’s coordinates relative to the space’s origin stable. Such adjustments maintain the visual stability of content currently near the viewer, but may cause content placed far from the viewer to drift in its alignment to the real world by the time the user moves close again. By creating an SpatialAnchorMSFT where a piece of content is placed and then always rendering that content relative to its anchor’s space, an application can ensure that each piece of content stays at a fixed location in the environment.

See Also

SpatialAnchorSpaceCreateInfoMSFT, createSpatialAnchorFromPerceptionAnchorMSFT, createSpatialAnchorMSFT, destroySpatialAnchorMSFT, tryGetPerceptionAnchorFromSpatialAnchorMSFT