C Specification

The xrWaitSwapchainImage function is defined as:

XrResult xrWaitSwapchainImage(
    XrSwapchain                                 swapchain,
    const XrSwapchainImageWaitInfo*             waitInfo);

Parameters

Parameter Descriptions

  • swapchain is the swapchain from which to wait for an image.

  • waitInfo is a pointer to an XrSwapchainImageWaitInfo struct.

Description

Before an application can begin writing to a swapchain image, it must first wait on the image to avoid writing to it before the compositor has finished reading from it. xrWaitSwapchainImage will implicitly wait on the oldest acquired swapchain image which has not yet been successfully waited on. Once a swapchain image has been successfully waited on, it must be released before waiting on the next acquired swapchain image.

This function may block for longer than the timeout specified in XrSwapchainImageWaitInfo due to scheduling or contention.

If the timeout expires without the image becoming available for writing, XR_TIMEOUT_EXPIRED is returned. If xrWaitSwapchainImage returns XR_TIMEOUT_EXPIRED, the next call to xrWaitSwapchainImage will wait on the same image index again until the function succeeds with XR_SUCCESS. Note that this is not an error code; XR_SUCCEEDED(XR_TIMEOUT_EXPIRED) is true.

The runtime must return XR_ERROR_CALL_ORDER_INVALID if no image has been acquired by calling xrAcquireSwapchainImage.

Valid Usage (Implicit)
Return Codes
On success, this command returns

  • XR_SUCCESS

  • XR_TIMEOUT_EXPIRED

  • 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_VALIDATION_FAILURE

  • XR_ERROR_CALL_ORDER_INVALID

See Also

XrSwapchain, XrSwapchainImageWaitInfo, xrAcquireSwapchainImage, xrCreateSwapchain, xrDestroySwapchain, xrEnumerateSwapchainImages, xrReleaseSwapchainImage

Document Notes

For more information, see the OpenXR Specification at URL

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

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.