C Specification

The xrLocateViews function is defined as:

XrResult xrLocateViews(
    XrSession                                   session,
    const XrViewLocateInfo*                     viewLocateInfo,
    XrViewState*                                viewState,
    uint32_t                                    viewCapacityInput,
    uint32_t*                                   viewCountOutput,
    XrView*                                     views);

Parameters

Parameter Descriptions

  • session is a handle to the provided XrSession.

  • viewLocateInfo is a pointer to a valid XrViewLocateInfo structure.

  • viewState is the output structure with the viewer state information.

  • viewCapacityInput is an input parameter which specifies the capacity of the views array. The required capacity is no more than XrSystemGraphicsProperties::maxViewCount

  • viewCountOutput is an output parameter which identifies the valid count of views.

  • views is an array of XrView.

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

Description

Valid Usage

  • displayTime should be a valid time in the future.

The function xrLocateViews returns the view and projection info for a particular display time. This time is typically the XrFrameState::predictedDisplayTime for a given frame. Repeatedly calling xrLocateViews with the same time may not necessarily return the same result. Instead the prediction gets increasingly accurate as the function is called closer to the given time for which a prediction is made. This allows an application to get the predicted views as late as possible in its pipeline to get the least amount of latency and prediction error.

xrLocateViews returns an array of XrView elements, one for each view of the running session’s active view configuration, along with an XrViewState containing additional state data shared across all views for the primary viewer. The eye each view corresponds to is statically defined in XrViewConfigurationType in case the application wants to apply eye-specific rendering traits. The XrViewState and XrView member data may change on subsequent calls to xrLocateViews, and so applications must not assume it to be constant.

Valid Usage (Implicit)

  • session must be a valid XrSession handle

  • viewLocateInfo must be a pointer to a valid XrViewLocateInfo structure

  • viewState must be a pointer to an XrViewState structure

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

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

  • If viewCapacityInput is not 0, views must be a pointer to an array of viewCapacityInput XrView structures

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

See Also

XrSession, XrView, XrViewLocateInfo, XrViewState

Document Notes

For more information, see the OpenXR Specification at URL

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

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.