C Specification

The xrEnumerateRenderModelSubactionPathsEXT function is defined as:

// Provided by XR_EXT_interaction_render_model
XrResult xrEnumerateRenderModelSubactionPathsEXT(
    XrRenderModelEXT                            renderModel,
    const XrInteractionRenderModelSubactionPathInfoEXT* info,
    uint32_t                                    pathCapacityInput,
    uint32_t*                                   pathCountOutput,
    XrPath*                                     paths);

Description

Parameter Description

  • renderModel is a render model handle created from an XrRenderModelIdEXT value retrieved from this extension.

  • info exists for extensibility purposes, it is NULL or a pointer to a valid XrInteractionRenderModelSubactionPathInfoEXT structure.

  • pathCapacityInput is the capacity of the paths array, or 0 to indicate a request to retrieve the required capacity.

  • pathCountOutput is a pointer to the count of paths written, or a pointer to the required capacity in the case that pathCapacityInput is insufficient.

  • paths is a pointer to an array of XrPath atoms, but can be NULL if pathCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required paths size.

xrEnumerateRenderModelSubactionPathsEXT allows the application to associate an interaction-related render model with the associated subaction paths according to the exposed current interaction profile and active action sets.

If renderModel is valid but was not created from a render model ID from a call to xrEnumerateInteractionRenderModelIdsEXT earlier in the current session, the runtime must return XR_ERROR_NOT_INTERACTION_RENDER_MODEL_EXT.

The array enumerated by this function for a given render model must not change except during calls to xrSyncActions.

A given subaction path must be reported for a model if and only if both of the following are true:

  • That path appears in the corresponding XrActionCreateInfo::subactionPaths for some action or actions associated with it in the active action sets.

  • That path is used as a top-level user path for some suggested binding of at least one such action in the current interaction profile.

This paragraph describes implications and clarifications of the preceding requirement. If a given path is used as a top-level user path for a suggested binding to an action with no subaction paths specified, or without that specific subaction path specified, it is not sufficient to require enumerating that path. The runtime must only enumerate subaction paths that are included in the reported current interaction profile and mentioned in the corresponding suggested bindings, even if one of the models is logically better described by a path not used by the application. For example, a treadmill-like interaction device with its input mapped to actions suggested for left and right hands enumerates the paths /user/hand/left and /user/hand/right even though /user/treadmill is defined in the specification. This also implies that a runtime must return no subaction paths prior to the first call to xrSyncActions in a session, or when the most recent call to xrSyncActions did not specify any active action sets. Additionally, the runtime must return no subaction paths when a given render model provides input only for actions that do not have a list of subaction paths specified in XrActionCreateInfo::subactionPaths.

This function is intended for identifying models currently associated with any actions in an active action set, as well as identifying the subaction paths associated with the bound input. To identify which top-level /user path is most closely associated with the overall pose of any given interaction render model, see xrGetRenderModelPoseTopLevelUserPathEXT. The description of that function contains a further discussion of the differences with this function.

Important: The order of values returned from this function is not meaningful, and the entire array should be iterated and treated uniformly by the application. An application should always be prepared for this function to return a list of any length, up to the total number of subaction paths used in suggested bindings. Most functionality in OpenXR is defined to operate as if the hardware corresponding to the current interaction profile were in use according to the suggested bindings. However, this function, and this extension in general, allows the application to access aspects of the user’s actual input configuration, to provide accurate and realistic feedback to the user. Special care is required to ensure that application code using this function is maximally general.

Valid Usage (Implicit)
Return Codes
On success, this command returns

  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns

  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_NOT_INTERACTION_RENDER_MODEL_EXT

See Also

XR_EXT_interaction_render_model, XrInteractionRenderModelSubactionPathInfoEXT, XrPath, XrRenderModelEXT, xrGetRenderModelPoseTopLevelUserPathEXT

Document Notes

For more information, see the OpenXR Specification

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

This work is licensed under a Creative Commons Attribution 4.0 International License.