xrGetControllerModelKeyMSFT - Retrieve the model key for the controller

Valid Usage (Implicit)

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

• session must be a valid Session handle
• controllerModelKeyState must be a pointer to an ControllerModelKeyStateMSFT structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_INSTANCE_LOST
• ERROR_OUT_OF_MEMORY
• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT
• ERROR_HANDLE_INVALID
• ERROR_SESSION_LOST
• SESSION_LOSS_PENDING
• ERROR_PATH_UNSUPPORTED
• ERROR_PATH_INVALID

See Also

ControllerModelKeyStateMSFT, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath, Session

xrLoadControllerModelMSFT - Load controller render model

Parameter Descriptions

• session is the specified Session.

• modelKey is the model key corresponding to the controller render model being queried.
• bufferCapacityInput is the capacity of the buffer array, or 0 to indicate a request to retrieve the required capacity.
• 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 0.
• buffer is 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.
• See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

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 ControllerModelKeyStateMSFT, the runtime must return ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

Valid Usage (Implicit)

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

• session must be a valid Session 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

Success

• SUCCESS

Failure

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

See Also

https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrControllerModelKeyMSFT, Session

xrGetControllerModelPropertiesMSFT - Get controller model properties

Parameter Descriptions

Description

The runtime must return the same data in ControllerModelPropertiesMSFT for a valid modelKey. Therefore, the application can cache the returned ControllerModelPropertiesMSFT 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 ControllerModelKeyStateMSFT, the runtime must return ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

Valid Usage (Implicit)

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

• session must be a valid Session handle
• properties must be a pointer to an ControllerModelPropertiesMSFT structure

Return Codes

Success

• SUCCESS

Failure

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

See Also

https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrControllerModelKeyMSFT, ControllerModelPropertiesMSFT, Session

xrGetControllerModelStateMSFT - Get controller model state

Parameter Descriptions

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 ControllerModelKeyStateMSFT, the runtime must return ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

Valid Usage (Implicit)

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

• session must be a valid Session handle
• state must be a pointer to an ControllerModelStateMSFT structure

Return Codes

Success

• SUCCESS

Failure

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

See Also

https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrControllerModelKeyMSFT, ControllerModelStateMSFT, Session

XrControllerModelKeyMSFT - Controller renderable model key

Description

The controller model key used to retrieve the data for the renderable controller model and associated properties and state.

See Also

NULL_CONTROLLER_MODEL_KEY_MSFT, ControllerModelKeyStateMSFT, getControllerModelPropertiesMSFT, getControllerModelStateMSFT, loadControllerModelMSFT

XrControllerModelKeyStateMSFT - The model key state for a controller

Parameter Descriptions

Description

The modelKey value for the session represents a unique controller model that can be retrieved from loadControllerModelMSFT function. Therefore, the application can use modelKey to cache the returned data from loadControllerModelMSFT for the session.

A modelKey value of NULL_CONTROLLER_MODEL_KEY_MSFT, represents an invalid model key and indicates there is no controller model yet available. The application should keep calling getControllerModelKeyMSFT because the model may become available at a later point.

Valid Usage (Implicit)

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

• type must be TYPE_CONTROLLER_MODEL_KEY_STATE_MSFT
• next must be NULL or a valid pointer to the next structure in a structure chain

See Also

https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrControllerModelKeyMSFT, StructureType, getControllerModelKeyMSFT

XrControllerModelNodePropertiesMSFT - Describes the controller model node properties

Parameter Descriptions

Description

The node can be located in the glTF node hierarchy by finding the node(s) with the matching node name and parent node name. If the parentNodeName is empty, the matching will be solely based on the nodeName.

If there are multiple nodes in the glTF file matches the condition above, the first matching node using depth-first traversal in the glTF scene should be animated and the rest should be ignored.

The runtime must not return any nodeName or parentName that doesn’t match any gltTF nodes in the corresponding controller model.

Valid Usage (Implicit)

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

• type must be TYPE_CONTROLLER_MODEL_NODE_PROPERTIES_MSFT
• next must be NULL or a valid pointer to the next structure in a structure chain
• parentNodeName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT
• nodeName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT

See Also

ControllerModelPropertiesMSFT, StructureType, getControllerModelPropertiesMSFT, loadControllerModelMSFT

XrControllerModelPropertiesMSFT - Describes the properties of a controller model

Parameter Descriptions

• type is the StructureType of this structure.

• next is NULL or a pointer to the next structure in a structure chain.
• nodeCapacityInput is the capacity of the nodeProperties array, or 0 to indicate a request to retrieve the required capacity.
• nodeCountOutput filled in by the runtime with the count of elements in nodeProperties array, or returns the required capacity in the case that nodeCapacityInput is 0.
• nodeProperties is a pointer to an application-allocated array that will be filled with the ControllerModelNodePropertiesMSFT values. It can be NULL if nodeCapacityInput is 0.
• See Buffer Size Parameters chapter for a detailed description of retrieving the required nodeProperties size.

Valid Usage (Implicit)

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

• type must be TYPE_CONTROLLER_MODEL_PROPERTIES_MSFT
• next must be NULL or a valid pointer to the next structure in a structure chain
• If nodeCapacityInput is not 0, nodeProperties must be a pointer to an array of nodeCapacityInput ControllerModelNodePropertiesMSFT structures

See Also

ControllerModelNodePropertiesMSFT, StructureType, getControllerModelPropertiesMSFT, loadControllerModelMSFT

XrControllerModelNodeStateMSFT - Describes the state of a node in a controller model

Parameter Descriptions

Description

The state is corresponding to the glTF node identified by the nodeName and nodeParentName of the node property at the same array index in the nodeProperties in ControllerModelPropertiesMSFT.

The nodePose is based on the user’s interaction on the controller at the latest syncActions, represented as the Posef of the node in it’s parent node space.

Valid Usage (Implicit)

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

• type must be TYPE_CONTROLLER_MODEL_NODE_STATE_MSFT
• next must be NULL or a valid pointer to the next structure in a structure chain

See Also

ControllerModelStateMSFT, Posef, StructureType, getControllerModelStateMSFT

XrControllerModelStateMSFT - Describes the state of a controller model

Parameter Descriptions

• type is the StructureType of this structure.

• next is NULL or a pointer to the next structure in a structure chain.
• nodeCapacityInput is the capacity of the nodeStates array, or 0 to indicate a request to retrieve the required capacity.
• nodeCountOutput filled in by the runtime with the count of elements in nodeStates array, or returns the required capacity in the case that nodeCapacityInput is 0.
• nodeStates is a pointer to an application-allocated array that will be filled with the ControllerModelNodeStateMSFT values. It can be NULL if sourceCapacityInput is 0.
• See Buffer Size Parameters chapter for a detailed description of retrieving the required nodeStates size.

Valid Usage (Implicit)

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

• type must be TYPE_CONTROLLER_MODEL_STATE_MSFT
• next must be NULL or a valid pointer to the next structure in a structure chain
• If nodeCapacityInput is not 0, nodeStates must be a pointer to an array of nodeCapacityInput ControllerModelNodeStateMSFT structures

See Also

ControllerModelNodeStateMSFT, StructureType, getControllerModelStateMSFT

XR_NULL_CONTROLLER_MODEL_KEY_MSFT - The value representing an invalid model key

Description

NULL_CONTROLLER_MODEL_KEY_MSFT defines an invalid model key value.

See Also

https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrControllerModelKeyMSFT