xrStringToPath - Converts a string to a semantic path

Parameter Descriptions

Description

stringToPath retrieves the https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath value for a well-formed path string. If such a value had not yet been assigned by the runtime to the provided path string in this Instance, one must be assigned at this point. All calls to this function with the same Instance and path string must retrieve the same https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath value. Upon failure, stringToPath must return an appropriate Result, and may set the output parameter to NULL_PATH. See Path Atom Type for the conditions under which an error may be returned when this function is given a valid Instance and a well-formed path string.

If the runtime’s resources are exhausted and it cannot create the path, a return value of ERROR_PATH_COUNT_EXCEEDED must be returned. If the application specifies a string that is not a well-formed path string, ERROR_PATH_FORMAT_INVALID must be returned.

A return value of SUCCESS from stringToPath may not necessarily imply that the runtime has a component or other source of data that will be accessible through that semantic path. It only means that the path string supplied was well-formed and that the retrieved https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath maps to the given path string within and during the lifetime of the Instance given.

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_PATH_FORMAT_INVALID
• ERROR_PATH_COUNT_EXCEEDED
• ERROR_VALIDATION_FAILURE

See Also

Instance, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath, pathToString

xrPathToString - Converts a semantic path to a string

Parameter Descriptions

• instance is an instance previously created.

• path is the valid https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath value to retrieve the path string for.
• bufferCapacityInput is the capacity of the buffer, or 0 to indicate a request to retrieve the required capacity.
• bufferCountOutput is a pointer to the count of characters written (including the terminating '\0'), or a pointer to the required capacity in the case that bufferCapacityInput is 0.
• buffer is a pointer to an application-allocated buffer that will be filled with the semantic path string. It can be NULL if bufferCapacityInput is 0.
• See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

Description

pathToString retrieves the path name string associated with an https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath, in the context of a given Instance, in the form of a NULL terminated string placed into a caller-allocated buffer. Since the mapping between a well-formed path name string and an https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath is bijective, there will always be exactly one string for each valid https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath value. This can be useful if the calling application receives an https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath value that they had not previously retrieved via stringToPath. During the lifetime of the given Instance, the path name string retrieved by this function for a given valid https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath will not change. For invalid paths, including NULL_PATH, ERROR_PATH_INVALID must be returned.

Valid Usage (Implicit)

• instance must be a valid Instance handle

• bufferCountOutput must be a pointer to a uint32_t value
• If bufferCapacityInput is not 0, buffer must be a pointer to an array of bufferCapacityInput char values

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_PATH_INVALID
• ERROR_SIZE_INSUFFICIENT
• ERROR_VALIDATION_FAILURE

See Also

Instance, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath, stringToPath

XrPath - A semantic path

Description

The https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath is an atom that connects an application with a single path, within the context of a single instance. There is a bijective mapping between well-formed path strings and atoms in use. This atom is used — in place of the path name string it corresponds to — to retrieve state and perform other operations.

As an https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath is only shorthand for a well-formed path string, they have no explicit life cycle.

Lifetime is implicitly managed by the Instance. An https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath must not be used unless it is received at execution time from the runtime in the context of a particular Instance. Therefore, with the exception of NULL_PATH, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath values must not be specified as constant values in applications: the corresponding path string should be used instead. During the lifetime of a given Instance, the https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath associated with that instance with any given well-formed path must not vary, and similarly the well-formed path string that corresponds to a given https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath in that instance must not vary. An https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrPath that is received from one Instance may not be used with another. Such an invalid use may be detected and result in an error being returned, or it may result in undefined behavior.

See Also

NULL_PATH, ActionCreateInfo, ActionSpaceCreateInfo, ActionStateGetInfo, ActionSuggestedBinding, ActiveActionSet, HapticActionInfo, InputSourceLocalizedNameGetInfo, InteractionProfileAnalogThresholdVALVE, InteractionProfileState, InteractionProfileSuggestedBinding, enumerateBoundSourcesForAction, getControllerModelKeyMSFT, getCurrentInteractionProfile, pathToString, xrSetInputDeviceActiveEXT, xrSetInputDeviceLocationEXT, xrSetInputDeviceStateBoolEXT, xrSetInputDeviceStateFloatEXT, xrSetInputDeviceStateVector2fEXT, stringToPath