C Specification

The xrStringToPath function is defined as:

XrResult xrStringToPath(
    XrInstance                                  instance,
    const char*                                 pathString,
    XrPath*                                     path);

Parameters

Parameter Descriptions

  • instance is an instance previously created.

  • pathString is the path name string to retrieve the associated XrPath for.

  • path is the output parameter, which must point to an XrPath. Given a well-formed path name string, this will be populated with an opaque value that is constant for that path string during the lifetime of that instance.

Description

xrStringToPath retrieves the 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 XrInstance, one must be assigned at this point. All calls to this function with the same XrInstance and path string must retrieve the same XrPath value. Upon failure, xrStringToPath must return an appropriate XrResult, and may set the output parameter to XR_NULL_PATH. See Path Atom Type for the conditions under which an error may be returned when this function is given a valid XrInstance and a well-formed path string.

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

A return value of XR_SUCCESS from xrStringToPath 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 XrPath maps to the given path string within and during the lifetime of the XrInstance given.
Valid Usage (Implicit)

  • instance must be a valid XrInstance handle

  • pathString must be a null-terminated UTF-8 string

  • path must be a pointer to an XrPath value

Return Codes
On success, this command returns

  • XR_SUCCESS

On failure, this command returns

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_PATH_FORMAT_INVALID

  • XR_ERROR_PATH_COUNT_EXCEEDED

  • XR_ERROR_VALIDATION_FAILURE

See Also

XrInstance, XrPath, xrPathToString

Document Notes

For more information, see the OpenXR Specification at URL

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

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.