Package org.lwjgl.openxr

Class MSFTSpatialAnchor

java.lang.Object

org.lwjgl.openxr.MSFTSpatialAnchor

public class MSFTSpatialAnchor
extends Object

The XR_MSFT_spatial_anchor extension.

This extension allows an application to create a spatial anchor, an arbitrary freespace point in the user’s physical environment that will then be tracked by the runtime. The runtime should then adjust the position and orientation of that anchor’s origin over time as needed, independently of all other spaces and anchors, to ensure that it maintains its original mapping to the real world.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT	Extends XrResult.
static final String	XR_MSFT_SPATIAL_ANCHOR_EXTENSION_NAME	The extension name.
static final int	XR_MSFT_spatial_anchor_SPEC_VERSION	The extension specification version.
static final int	XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT	Extends XrObjectType.
static final int	XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT	Extends XrStructureType.
static final int	XR_TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT	Extends XrStructureType.

Method Summary

Modifier and Type	Method	Description
static int	nxrCreateSpatialAnchorMSFT(XrSession session, long createInfo, long anchor)	Unsafe version of: CreateSpatialAnchorMSFT
static int	nxrCreateSpatialAnchorSpaceMSFT(XrSession session, long createInfo, long space)	Unsafe version of: CreateSpatialAnchorSpaceMSFT
static int	xrCreateSpatialAnchorMSFT(XrSession session, XrSpatialAnchorCreateInfoMSFT createInfo, org.lwjgl.PointerBuffer anchor)	Creates a spatial anchor.
static int	xrCreateSpatialAnchorSpaceMSFT(XrSession session, XrSpatialAnchorSpaceCreateInfoMSFT createInfo, org.lwjgl.PointerBuffer space)	Creates a space from a spatial anchor.
static int	xrDestroySpatialAnchorMSFT(XrSpatialAnchorMSFT anchor)	Destroys a spatial anchor.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

XR_MSFT_spatial_anchor_SPEC_VERSION

public static final int XR_MSFT_spatial_anchor_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

XR_MSFT_SPATIAL_ANCHOR_EXTENSION_NAME

public static final String XR_MSFT_SPATIAL_ANCHOR_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT

public static final int XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT

Extends XrStructureType.

Enum values:

• TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT
• TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT

See Also:

• Constant Field Values

XR_TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT

public static final int XR_TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT

Extends XrStructureType.

Enum values:

• TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT
• TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT

See Also:

• Constant Field Values

XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT

public static final int XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT

Extends XrObjectType.

See Also:

• Constant Field Values

XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT

public static final int XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT

Extends XrResult.

See Also:

• Constant Field Values

Method Details

nxrCreateSpatialAnchorMSFT

public static int nxrCreateSpatialAnchorMSFT(XrSession session,
 long createInfo,
 long anchor)

Unsafe version of: CreateSpatialAnchorMSFT

xrCreateSpatialAnchorMSFT

public static int xrCreateSpatialAnchorMSFT(XrSession session,
 XrSpatialAnchorCreateInfoMSFT createInfo,
 org.lwjgl.PointerBuffer anchor)

Creates a spatial anchor.

C Specification

The CreateSpatialAnchorMSFT function is defined as:

 XrResult xrCreateSpatialAnchorMSFT(
     XrSession                                   session,
     const XrSpatialAnchorCreateInfoMSFT*        createInfo,
     XrSpatialAnchorMSFT*                        anchor);

Description

Creates an XrSpatialAnchorMSFT 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 XrSpatialAnchorCreateInfoMSFT::pose within XrSpatialAnchorCreateInfoMSFT::space at XrSpatialAnchorCreateInfoMSFT::time.

The runtime must avoid long blocking operations such as networking or disk operations for CreateSpatialAnchorMSFT function. The application may safely use this function in UI thread. Though, the created anchor handle may not be ready immediately for certain operations yet. For example, the corresponding anchor space may not return valid location, or its location may not be successfully saved in anchor store.

If XrSpatialAnchorCreateInfoMSFT::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 XrSpatialAnchorCreateInfoMSFT::space used to initialize it.

Valid Usage (Implicit)

• The XR_MSFT_spatial_anchor extension must be enabled prior to calling CreateSpatialAnchorMSFT
• session must be a valid XrSession handle
• createInfo must be a pointer to a valid XrSpatialAnchorCreateInfoMSFT structure
• anchor must be a pointer to an XrSpatialAnchorMSFT handle

Return Codes

On success, this command returns

• SUCCESS
• SESSION_LOSS_PENDING

On failure, this command returns

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

See Also

XrSpatialAnchorCreateInfoMSFT

Parameters:

session - a handle to an XrSession.

createInfo - a pointer to an XrSpatialAnchorCreateInfoMSFT structure containing information about how to create the anchor.

anchor - a pointer to a handle in which the created XrSpatialAnchorMSFT is returned.

nxrCreateSpatialAnchorSpaceMSFT

public static int nxrCreateSpatialAnchorSpaceMSFT(XrSession session,
 long createInfo,
 long space)

Unsafe version of: CreateSpatialAnchorSpaceMSFT

xrCreateSpatialAnchorSpaceMSFT

public static int xrCreateSpatialAnchorSpaceMSFT(XrSession session,
 XrSpatialAnchorSpaceCreateInfoMSFT createInfo,
 org.lwjgl.PointerBuffer space)

Creates a space from a spatial anchor.

C Specification

The CreateSpatialAnchorSpaceMSFT function is defined as:

 XrResult xrCreateSpatialAnchorSpaceMSFT(
     XrSession                                   session,
     const XrSpatialAnchorSpaceCreateInfoMSFT*   createInfo,
     XrSpace*                                    space);

Description

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

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

Valid Usage (Implicit)

• The XR_MSFT_spatial_anchor extension must be enabled prior to calling CreateSpatialAnchorSpaceMSFT
• session must be a valid XrSession handle
• createInfo must be a pointer to a valid XrSpatialAnchorSpaceCreateInfoMSFT structure
• space must be a pointer to an XrSpace handle

Return Codes

On success, this command returns

• SUCCESS
• SESSION_LOSS_PENDING

On failure, this command returns

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

See Also

XrSpatialAnchorSpaceCreateInfoMSFT

Parameters:

session - a handle to an XrSession.

createInfo - a pointer to an XrSpatialAnchorSpaceCreateInfoMSFT structure containing information about how to create the anchor.

space - a pointer to a handle in which the created XrSpace is returned.

xrDestroySpatialAnchorMSFT

public static int xrDestroySpatialAnchorMSFT(XrSpatialAnchorMSFT anchor)

Destroys a spatial anchor.

C Specification

The DestroySpatialAnchorMSFT function is defined as:

 XrResult xrDestroySpatialAnchorMSFT(
     XrSpatialAnchorMSFT                         anchor);

Description

XrSpatialAnchorMSFT 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 XR_MSFT_spatial_anchor extension must be enabled prior to calling DestroySpatialAnchorMSFT
• anchor must be a valid XrSpatialAnchorMSFT handle

Thread Safety

• Access to anchor, and any child handles, must be externally synchronized

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_HANDLE_INVALID

See Also

CreateSpatialAnchorMSFT

Parameters:

anchor - a handle to an XrSpatialAnchorMSFT previously created by CreateSpatialAnchorMSFT.