C Specification

The XrActionCreateInfo structure is defined as:

typedef struct XrActionCreateInfo {
    XrStructureType             type;
    const void* XR_MAY_ALIAS    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 an extension-specific structure.

  • 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_INVALID:

  • Each path provided is one of:

    • /user/head

    • /user/hand/left

    • /user/hand/right

    • /user/gamepad

    • /user

  • No path appears in the list more than once

Including /user in the list of subaction paths creates an 'other' bucket for action data to be filtered into. When /user is included in the list passed to xrGetActionState* the runtime must include data for all devices which are not included in the other subaction paths into the /user bucket. Extensions may append additional top level user paths to the above list.

The runtime must return XR_ERROR_PATH_INVALID 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. 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. 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

  • 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, countSubactionPaths must be a valid uint32_t value

  • If countSubactionPaths is not 0, subactionPaths must be a pointer to an array of countSubactionPaths 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 at URL

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

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.