Package org.lwjgl.openxr

Class MSFTControllerModel

java.lang.Object

org.lwjgl.openxr.MSFTControllerModel

public class MSFTControllerModel
extends Object

The XR_MSFT_controller_model extension.

This extension provides a mechanism to load a GLTF model for controllers. An application can render the controller model using the real time pose input from controller’s grip action pose and animate controller parts representing the user’s interactions, such as pressing a button, or pulling a trigger.

This extension supports any controller interaction profile that supports subpathname:/grip/pose. The returned controller model represents the physical controller held in the user’s hands, and it may be different from the current interaction profile.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT	Extends XrResult.
static final int	XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT	XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT
static final String	XR_MSFT_CONTROLLER_MODEL_EXTENSION_NAME	The extension name.
static final int	XR_MSFT_controller_model_SPEC_VERSION	The extension specification version.
static final long	XR_NULL_CONTROLLER_MODEL_KEY_MSFT	API Constants
static final int	XR_TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT	Extends XrStructureType.
static final int	XR_TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT	Extends XrStructureType.
static final int	XR_TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT	Extends XrStructureType.
static final int	XR_TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT	Extends XrStructureType.
static final int	XR_TYPE_CONTROLLER_MODEL_STATE_MSFT	Extends XrStructureType.

Method Summary

Modifier and Type	Method	Description
static int	nxrGetControllerModelKeyMSFT(XrSession session, long topLevelUserPath, long controllerModelKeyState)	Unsafe version of: GetControllerModelKeyMSFT
static int	nxrGetControllerModelPropertiesMSFT(XrSession session, long modelKey, long properties)	Unsafe version of: GetControllerModelPropertiesMSFT
static int	nxrGetControllerModelStateMSFT(XrSession session, long modelKey, long state)	Unsafe version of: GetControllerModelStateMSFT
static int	nxrLoadControllerModelMSFT(XrSession session, long modelKey, int bufferCapacityInput, long bufferCountOutput, long buffer)	Unsafe version of: LoadControllerModelMSFT
static int	xrGetControllerModelKeyMSFT(XrSession session, long topLevelUserPath, XrControllerModelKeyStateMSFT controllerModelKeyState)	Retrieve the model key for the controller.
static int	xrGetControllerModelPropertiesMSFT(XrSession session, long modelKey, XrControllerModelPropertiesMSFT properties)	Get controller model properties.
static int	xrGetControllerModelStateMSFT(XrSession session, long modelKey, XrControllerModelStateMSFT state)	Get controller model state.
static int	xrLoadControllerModelMSFT(XrSession session, long modelKey, IntBuffer bufferCountOutput, @Nullable ByteBuffer buffer)	Load controller render model.

Methods inherited from class java.lang.Object

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

Field Details

XR_MSFT_controller_model_SPEC_VERSION

public static final int XR_MSFT_controller_model_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

XR_MSFT_CONTROLLER_MODEL_EXTENSION_NAME

public static final String XR_MSFT_CONTROLLER_MODEL_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT

public static final int XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT

XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT

See Also:

• Constant Field Values

XR_TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT

public static final int XR_TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT

Extends XrStructureType.

Enum values:

• TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT
• TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT
• TYPE_CONTROLLER_MODEL_STATE_MSFT

See Also:

• Constant Field Values

XR_TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT

public static final int XR_TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT

Extends XrStructureType.

Enum values:

• TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT
• TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT
• TYPE_CONTROLLER_MODEL_STATE_MSFT

See Also:

• Constant Field Values

XR_TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT

public static final int XR_TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT

Extends XrStructureType.

Enum values:

• TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT
• TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT
• TYPE_CONTROLLER_MODEL_STATE_MSFT

See Also:

• Constant Field Values

XR_TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT

public static final int XR_TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT

Extends XrStructureType.

Enum values:

• TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT
• TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT
• TYPE_CONTROLLER_MODEL_STATE_MSFT

See Also:

• Constant Field Values

XR_TYPE_CONTROLLER_MODEL_STATE_MSFT

public static final int XR_TYPE_CONTROLLER_MODEL_STATE_MSFT

Extends XrStructureType.

Enum values:

• TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT
• TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT
• TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT
• TYPE_CONTROLLER_MODEL_STATE_MSFT

See Also:

• Constant Field Values

XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

public static final int XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

Extends XrResult.

See Also:

• Constant Field Values

XR_NULL_CONTROLLER_MODEL_KEY_MSFT

public static final long XR_NULL_CONTROLLER_MODEL_KEY_MSFT

API Constants

See Also:

• Constant Field Values

Method Details

nxrGetControllerModelKeyMSFT

public static int nxrGetControllerModelKeyMSFT(XrSession session,
 long topLevelUserPath,
 long controllerModelKeyState)

Unsafe version of: GetControllerModelKeyMSFT

xrGetControllerModelKeyMSFT

public static int xrGetControllerModelKeyMSFT(XrSession session,
 long topLevelUserPath,
 XrControllerModelKeyStateMSFT controllerModelKeyState)

Retrieve the model key for the controller.

C Specification

GetControllerModelKeyMSFT retrieves the XrControllerModelKeyMSFT for a controller. This model key may later be used to retrieve the model data.

The GetControllerModelKeyMSFT function is defined as:

 XrResult xrGetControllerModelKeyMSFT(
     XrSession                                   session,
     XrPath                                      topLevelUserPath,
     XrControllerModelKeyStateMSFT*              controllerModelKeyState);

Valid Usage (Implicit)

• The XR_MSFT_controller_model extension must be enabled prior to calling GetControllerModelKeyMSFT
• session must be a valid XrSession handle
• controllerModelKeyState must be a pointer to an XrControllerModelKeyStateMSFT structure

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_PATH_UNSUPPORTED
• ERROR_PATH_INVALID
• ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

See Also

XrControllerModelKeyStateMSFT

Parameters:

session - the specified XrSession.

topLevelUserPath - the top level user path corresponding to the controller render model being queried (e.g. pathname:/user/hand/left or pathname:/user/hand/right).

controllerModelKeyState - a pointer to the XrControllerModelKeyStateMSFT to write the model key state to.

nxrLoadControllerModelMSFT

public static int nxrLoadControllerModelMSFT(XrSession session,
 long modelKey,
 int bufferCapacityInput,
 long bufferCountOutput,
 long buffer)

Unsafe version of: LoadControllerModelMSFT

Parameters:

bufferCapacityInput - the capacity of the buffer array, or 0 to indicate a request to retrieve the required capacity.

xrLoadControllerModelMSFT

public static int xrLoadControllerModelMSFT(XrSession session,
 long modelKey,
 IntBuffer bufferCountOutput,
 @Nullable ByteBuffer buffer)

Load controller render model.

C Specification

The LoadControllerModelMSFT function loads the controller model as a byte buffer containing a binary form of glTF (a.k.a GLB file format) for the controller. The binary glTF data must conform to glTF 2.0 format defined at https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html.

 XrResult xrLoadControllerModelMSFT(
     XrSession                                   session,
     XrControllerModelKeyMSFT                    modelKey,
     uint32_t                                    bufferCapacityInput,
     uint32_t*                                   bufferCountOutput,
     uint8_t*                                    buffer);

Description

The LoadControllerModelMSFT function may be a slow operation and therefore should be invoked from a non-timing critical thread.

If the input modelKey is invalid, i.e. it is NULL_CONTROLLER_MODEL_KEY_MSFT or not a key returned from XrControllerModelKeyStateMSFT, the runtime must return ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

Valid Usage (Implicit)

• The XR_MSFT_controller_model extension must be enabled prior to calling LoadControllerModelMSFT
• session must be a valid XrSession handle
• bufferCountOutput must be a pointer to a uint32_t value
• If bufferCapacityInput is not 0, buffer must be a pointer to an array of bufferCapacityInput uint8_t values

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_SIZE_INSUFFICIENT
• ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

Parameters:

session - the specified XrSession.

modelKey - the model key corresponding to the controller render model being queried.

bufferCountOutput - filled in by the runtime with the count of elements in buffer array, or returns the required capacity in the case that bufferCapacityInput is insufficient.

buffer - a pointer to an application-allocated array of the model for the device that will be filled with the uint8_t values by the runtime. It can be NULL if bufferCapacityInput is 0.

nxrGetControllerModelPropertiesMSFT

public static int nxrGetControllerModelPropertiesMSFT(XrSession session,
 long modelKey,
 long properties)

Unsafe version of: GetControllerModelPropertiesMSFT

xrGetControllerModelPropertiesMSFT

public static int xrGetControllerModelPropertiesMSFT(XrSession session,
 long modelKey,
 XrControllerModelPropertiesMSFT properties)

Get controller model properties.

C Specification

The GetControllerModelPropertiesMSFT function returns the controller model properties for a given modelKey.

 XrResult xrGetControllerModelPropertiesMSFT(
     XrSession                                   session,
     XrControllerModelKeyMSFT                    modelKey,
     XrControllerModelPropertiesMSFT*            properties);

Description

The runtime must return the same data in XrControllerModelPropertiesMSFT for a valid modelKey. Therefore, the application can cache the returned XrControllerModelPropertiesMSFT using modelKey and reuse the data for each frame.

If the input modelKey is invalid, i.e. it is NULL_CONTROLLER_MODEL_KEY_MSFT or not a key returned from XrControllerModelKeyStateMSFT, the runtime must return ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

Valid Usage (Implicit)

• The XR_MSFT_controller_model extension must be enabled prior to calling GetControllerModelPropertiesMSFT
• session must be a valid XrSession handle
• properties must be a pointer to an XrControllerModelPropertiesMSFT structure

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_SIZE_INSUFFICIENT
• ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

See Also

XrControllerModelPropertiesMSFT

Parameters:

session - the specified XrSession.

modelKey - a valid model key obtained from XrControllerModelKeyStateMSFT

properties - an XrControllerModelPropertiesMSFT returning the properties of the controller model

nxrGetControllerModelStateMSFT

public static int nxrGetControllerModelStateMSFT(XrSession session,
 long modelKey,
 long state)

Unsafe version of: GetControllerModelStateMSFT

xrGetControllerModelStateMSFT

public static int xrGetControllerModelStateMSFT(XrSession session,
 long modelKey,
 XrControllerModelStateMSFT state)

Get controller model state.

C Specification

The GetControllerModelStateMSFT function returns the current state of the controller model representing user’s interaction to the controller, such as pressing a button or pulling a trigger.

 XrResult xrGetControllerModelStateMSFT(
     XrSession                                   session,
     XrControllerModelKeyMSFT                    modelKey,
     XrControllerModelStateMSFT*                 state);

Description

The runtime may return different state for a model key after each call to SyncActions, which represents the latest state of the user interactions.

If the input modelKey is invalid, i.e. it is NULL_CONTROLLER_MODEL_KEY_MSFT or not a key returned from XrControllerModelKeyStateMSFT, the runtime must return ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

Valid Usage (Implicit)

• The XR_MSFT_controller_model extension must be enabled prior to calling GetControllerModelStateMSFT
• session must be a valid XrSession handle
• state must be a pointer to an XrControllerModelStateMSFT structure

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_CONTROLLER_MODEL_KEY_INVALID_MSFT

See Also

XrControllerModelStateMSFT

Parameters:

session - the specified XrSession.

modelKey - the model key corresponding to the controller model being queried.

state - a pointer to XrControllerModelNodeStateMSFT returns the current controller model state.