C Specification

The xrEnumerateInteractionRenderModelIdsEXT function is defined as:

// Provided by XR_EXT_interaction_render_model
XrResult xrEnumerateInteractionRenderModelIdsEXT(
    XrSession                                   session,
    const XrInteractionRenderModelIdsEnumerateInfoEXT* getInfo,
    uint32_t                                    renderModelIdCapacityInput,
    uint32_t*                                   renderModelIdCountOutput,
    XrRenderModelIdEXT*                         renderModelIds);

Parameters

Parameter Descriptions

  • session is an XrSession in which the render model will be valid.

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

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

  • renderModelIdCountOutput is a pointer to the count of renderModelIds written, or a pointer to the required capacity in the case that renderModelIdCapacityInput is insufficient.

  • renderModelIds is an array of XrRenderModelIdEXT that will be populated with IDs for devices that are associated with actions.

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

Description

This function returns render model IDs associated with any device associated with actions, in any action set attached with session by xrAttachSessionActionSets. There is no specific meaning for array position. A runtime may return values in any order, although the enumerated array must remain constant between calls to xrSyncActions. An application should not assume any meaning based on array order. Note that a runtime may shuffle the order of IDs returned each time that the list changes, to aid application developers in avoiding accidental dependence on enumeration order.

An application must not assume any given size of this array based on suggested bindings: compatibility and user preference may result in more models being associated with actions than described in the suggested bindings. The runtime may return more models than the number of top level user paths in the suggested bindings due to user configuration and compatibility rebinding. The runtime should continue to return model IDs corresponding to any devices that has recently become inactive or disconnected, if they are reasonably expected to be used again soon, to minimize the need for applications to re-enumerate models and load assets. Similarly, the runtime may return model IDs for devices expected to be used, even if they are not yet connected or active.

The runtime must return render model IDs reflecting the actual hardware used, which must be independent of the currently active interaction profile. Accordingly, as long as the same actions within an XrInstance have suggested bindings, changing suggested bindings by adding or removing suggested bindings for an interaction profile must not change the underlying assets. Furthermore, provided that identical actions within an XrInstance are associated with suggested bindings for a specified list of glTF extensions, the runtime must return an identical collection of render model asset UUIDs.

The application can monitor for the XrEventDataInteractionRenderModelsChangedEXT event to get notified when interaction render models need to be re-enumerated.

Changes to the collection of models enumerated (for example, due to device change) must only occur during a call to xrSyncActions. If the collection of models changes, the XrEventDataInteractionRenderModelsChangedEXT event must be queued during that call to xrSyncActions to signal the need for re-enumeration. This implies that a runtime must enumerate no models prior to the first call to xrSyncActions in a session.

Note that the UUIDs associated with the enumerated render model IDs for a given system and list of glTF extensions may change between instances due to runtime changes. Additionally, as with all atom types like XrRenderModelIdEXT, the enumerated render model ID values associated with a logical device may change between sessions as render model ID atoms inherently only have meaning within the single XrSession they are enumerated from.

If an XrRenderModelIdEXT was enumerated during a call to xrEnumerateInteractionRenderModelIdsEXT during the current session, but the set of interaction render models has now changed and that XrRenderModelIdEXT would not enumerated by a call to xrEnumerateInteractionRenderModelIdsEXT after that change, a call to xrCreateRenderModelEXT with that XrRenderModelIdEXT must return XR_ERROR_RENDER_MODEL_ID_INVALID_EXT. (Note that a change in the set of interaction render models only occurs during calls to xrSyncActions, and queues an XrEventDataInteractionRenderModelsChangedEXT event if it occurs.) That is, if an ID was previously enumerated with this function during the current session, but is no longer enumerated due to a change in interaction render models during an xrSyncActions call, it is no longer valid to create a XrRenderModelEXT from that XrRenderModelIdEXT.

Existing XrRenderModelEXT handles already created from an ID that is no longer enumerated remain valid, but "inactive" and effectively useless.

  • Locating an associated render model space must report untracked/unlocatable, and therefore the model is not to be rendered.

  • Calls to xrGetRenderModelStateEXT may stop providing updated data, as they are assumed to not be rendered and thus the model state is irrelevant.

  • The runtime may return XR_ERROR_RENDER_MODEL_ASSET_UNAVAILABLE_EXT from xrCreateRenderModelAssetEXT if called with the cache UUID of that render model, if no other active render model uses the same asset UUID.

Runtimes must not enumerate a render model ID that they previously enumerated, then no longer enumerated. That is, if a render model ID is made inactive, it will never again become active. If the associated device returns, it will use a new render model ID.

A render model XrRenderModelEXT created from an XrRenderModelIdEXT enumerated by this function must not be visible/locatable when located by xrCreateRenderModelSpaceEXT if the session state is not XR_SESSION_STATE_FOCUSED, to ensure render models are only being rendered once per frame.

If the session is not running, the runtime must return XR_ERROR_SESSION_NOT_RUNNING.

A render model XrRenderModelEXT created from an XrRenderModelIdEXT enumerated by this function must be locatable and visible if the corresponding device is locatable and there exists some action in any action set with which the render model is associated. This avoids having interaction render models disappear during corner cases of application interaction, e.g. when a "menu" button present on only one controller is the only active input. If an application wishes to only show models for which there are active actions, use the output of xrEnumerateRenderModelSubactionPathsEXT which enumerates subaction paths per model for the active action sets only.

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_SESSION_NOT_RUNNING

See Also

XR_EXT_interaction_render_model, XrInteractionRenderModelIdsEnumerateInfoEXT, XrRenderModelEXT, XrRenderModelIdEXT, XrSession

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.