C Specification

The xrGetBoundSourcesForAction function is defined as:

XrResult xrGetBoundSourcesForAction(
    XrAction                                    action,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrPath*                                     sources);

Parameters

Parameter Descriptions

  • action is the XrAction being queried.

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

  • sourceCountOutput is a pointer to the count of action sources, or a pointer to the required capacity in the case that sourceCapacityInput is 0.

  • sources is a pointer to an application-allocated array that will be filled with the XrPath values for all sources. It can be NULL if sourceCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required sources size.

Description

An application can use the xrGetBoundSourcesForAction and xrGetInputSourceLocalizedName calls to prompt the user which physical inputs to use in order to perform an action. A source is the physical control that the action is bound to. An action may be bound to multiple sources at one time, for example an action named hold could be bound to both the X and A buttons.

If an action is unbound, xrGetBoundSourcesForAction will assign 0 to the value pointed-to by sourceCountOutput and not modify the array.

Once the semantic paths for the action’s source are obtained, the application can gather additional information about the source. xrGetInputSourceLocalizedName returns a localized human-readable string describing the source, e.g. 'A Button'.

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

Valid Usage (Implicit)

  • action must be a valid XrAction handle

  • If sourceCapacityInput is not 0, sourceCapacityInput must be a valid uint32_t value

  • If sourceCountOutput is not NULL, sourceCountOutput must be a pointer to a uint32_t value

  • If sourceCapacityInput is not 0, sources must be a pointer to an array of sourceCapacityInput XrPath values

Return Codes
On success, this command returns

  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_SESSION_NOT_RUNNING

See Also

XrAction, XrPath

Document Notes

For more information, see the OpenXR Specification at URL

https://www.khronos.org/registry/openxr/specs/1.0-extensions/html/xrspec.html#xrGetBoundSourcesForAction

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

Copyright

Copyright (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.