C Specification
The xrGetRenderModelPoseTopLevelUserPathEXT function is defined as:
// Provided by XR_EXT_interaction_render_model
XrResult xrGetRenderModelPoseTopLevelUserPathEXT(
XrRenderModelEXT renderModel,
const XrInteractionRenderModelTopLevelUserPathGetInfoEXT* info,
XrPath* topLevelUserPath);Parameters
Description
This function returns the top level /user path most closely
associated with the pose of a given render model, if any, and if that path
is present in the list passed in info.
A runtime must return:
* the top level /user path from the list in info that is
most closely associated with the model pose as a physical reality (e.g.
a device currently held in the user’s left hand returns
/user/hand/left), if one exists.
Note that this requirement does provide fallback behavior.
That is, if a model pose is related to more than one top level
/user path, the runtime returns the path from info with the
closest association, even if it is less closely related than some other
path not included in info.
* XR_NULL_PATH if no such path can be determined (e.g. the
corresponding device is currently not held by or attached to the user, or
no path associated with the model pose was provided in info).
Note that unlike xrGetCurrentInteractionProfile, more than one model may report being most closely associated with a given top level /user path. For example, a runtime may represent a single controller as two render models, or a user may have both a handheld device and a wrist-mounted tracker.
Changes to the top level /user path state of each render model must only occur during a call to xrSyncActions.
If renderModel is valid but was not retrieved from a call to
xrEnumerateInteractionRenderModelIdsEXT earlier in the current
session, the runtime must return
XR_ERROR_NOT_INTERACTION_RENDER_MODEL_EXT.
This function differs from xrEnumerateRenderModelSubactionPathsEXT by emphasizing poses and being broadly distinct from actions. xrGetRenderModelPoseTopLevelUserPathEXT focuses solely on poses related to a top level /user path and returning only most applicable result. Contrast with xrEnumerateRenderModelSubactionPathsEXT, which reports all top level /user paths being used as subaction paths that are associated with actions in an active action set. That function is meant more for e.g. highlighting models providing input, especially non-pose input, associated with a subaction path. For example, the right hand might have a pie menu related action set active, and an application could show the devices that can interact with that menu in a highlighted way, while dimming the other models.
Important: An application should always be prepared for this function
to return any top-level /user path in their list or
XR_NULL_PATH for any of the interaction render models.
Many systems will not report XR_NULL_PATH for any models, provided
that both /user/hand/left and /user/hand/right are
included on the list in info, but application code must be prepared
to handle this and that code path should be tested manually.
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.
See Also
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.