xrCreateSpatialAnchorFromPerceptionAnchorMSFT - Create a SpatialAnchorMSFT from a Windows SpatialAnchor pointer

Parameter Descriptions

Description

The input perceptionAnchor must support successful QueryInterface to Windows.Perception.Spatial.SpatialAnchor , otherwise the runtime must return ERROR_VALIDATION_FAILURE.

If the function successfully returned, the output anchor must be a valid handle. This also increments the refcount of the perceptionAnchor object.

When application is done with the anchor handle, it can be destroyed using destroySpatialAnchorMSFT function. This also decrements the refcount of underlying windows perception anchor object.

Valid Usage (Implicit)

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

• session must be a valid Session handle
• perceptionAnchor must be a pointer to an IUnknown value
• 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_SESSION_LOST
• SESSION_LOSS_PENDING

See Also

Session, SpatialAnchorMSFT

A convenience wrapper to make a compatible pair of calls to createSpatialAnchorFromPerceptionAnchorMSFT 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.

xrTryGetPerceptionAnchorFromSpatialAnchorMSFT - Convert a SpatialAnchorMSFT to a Windows SpatialAnchor

Parameter Descriptions

Description

If the runtime can convert the anchor to a Windows.Perception.Spatial.SpatialAnchor object, this function must return SUCCESS, and the output IUnknown in the pointer of perceptionAnchor must be not NULL. This also increments the refcount of the object. The application can then use QueryInterface to get the pointer for Windows.Perception.Spatial.SpatialAnchor object. The application should release the COM pointer after done with the object, or attach it to a smart COM pointer such as winrt::com_ptr.

If the runtime cannot convert the anchor to a Windows.Perception.Spatial.SpatialAnchor object, the function must return SUCCESS, and the output IUnknown in the pointer of perceptionAnchor must be NULL.

Valid Usage (Implicit)

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

• session must be a valid Session handle
• anchor must be a valid SpatialAnchorMSFT handle
• perceptionAnchor must be a pointer to a pointer to an IUnknown value
• anchor must have been created, allocated, or retrieved from session

Return Codes

Success

• SUCCESS

Failure

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

See Also

Session, SpatialAnchorMSFT

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

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