C Specification

The XrActionCreateInfo structure is defined as:

typedef struct XrActionCreateInfo {
    XrStructureType    type;
    const void*        next;
    char               actionName[XR_MAX_ACTION_NAME_SIZE];
    XrActionType       actionType;
    uint32_t           countSubactionPaths;
    const XrPath*      subactionPaths;
    char               localizedActionName[XR_MAX_LOCALIZED_ACTION_NAME_SIZE];
} XrActionCreateInfo;

Members

Member Descriptions

  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.

  • actionName is an array containing a NULL terminated string with the name of this action.

  • actionType is the XrActionType of the action to be created.

  • countSubactionPaths is the number of elements in the subactionPaths array. If subactionPaths is NULL, this parameter must be 0.

  • subactionPaths is an array of XrPath or NULL. If this array is specified, it contains one or more subaction paths that the application intends to query action state for.

  • localizedActionName is an array containing a NULL terminated UTF-8 string that can be presented to the user as a description of the action. This string should be in the system’s current active locale.

Description

Subaction paths are a mechanism that enables applications to use the same action name and handle on multiple devices. Applications can query action state using subaction paths that differentiate data coming from each device. This allows the runtime to group logically equivalent actions together in system UI. For instance, an application could create a single pick_up action with the /user/hand/left and /user/hand/right subaction paths and use the subaction paths to independently query the state of pick_up_with_left_hand and pick_up_with_right_hand.

Applications can create actions with or without the subactionPaths set to a list of paths. If this list of paths is omitted (i.e. subactionPaths is set to NULL, and countSubactionPaths is set to 0), the application is opting out of filtering action results by subaction paths and any call to get action data must also omit subaction paths.

If subactionPaths is specified and any of the following conditions are not satisfied, the runtime must return XR_ERROR_PATH_UNSUPPORTED:

  • Each path provided is one of:

    • /user/head

    • /user/hand/left

    • /user/hand/right

    • /user/gamepad

  • No path appears in the list more than once

Extensions may append additional top level user paths to the above list.

Note

Earlier revisions of the spec mentioned /user but it could not be implemented as specified and was removed as errata.

The runtime must return XR_ERROR_PATH_UNSUPPORTED in the following circumstances:

  • The application specified subaction paths at action creation and the application called xrGetActionState* or a haptic function with an empty subaction path array.

  • The application called xrGetActionState* or a haptic function with a subaction path that was not specified when the action was created.

If actionName or localizedActionName are empty strings, the runtime must return XR_ERROR_NAME_INVALID or XR_ERROR_LOCALIZED_NAME_INVALID respectively. If actionName or localizedActionName are duplicates of the corresponding field for any existing action in the specified action set, the runtime must return XR_ERROR_NAME_DUPLICATED or XR_ERROR_LOCALIZED_NAME_DUPLICATED respectively. If the conflicting action is destroyed, the conflicting field is no longer considered duplicated. If actionName contains characters which are not allowed in a single level of a well-formed path string, the runtime must return XR_ERROR_PATH_FORMAT_INVALID.

Valid Usage (Implicit)

  • type must be XR_TYPE_ACTION_CREATE_INFO

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

  • actionName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_ACTION_NAME_SIZE

  • actionType must be a valid XrActionType value

  • If countSubactionPaths is not 0, subactionPaths must be a pointer to an array of countSubactionPaths valid XrPath values

  • localizedActionName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_LOCALIZED_ACTION_NAME_SIZE

See Also

XrAction, XrActionType, XrPath, XrStructureType, xrCreateAction, xrCreateActionSet

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-2024, The Khronos Group Inc.

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