C Specification

The xrAcquireEnvironmentDepthImageMETA function is defined as:

// Provided by XR_META_environment_depth
XrResult xrAcquireEnvironmentDepthImageMETA(
    XrEnvironmentDepthProviderMETA              environmentDepthProvider,
    const XrEnvironmentDepthImageAcquireInfoMETA* acquireInfo,
    XrEnvironmentDepthImageMETA*                environmentDepthImage);

Parameters

Parameter Descriptions

Description

Acquires the latest available swapchain image that has been generated by the depth provider and ensures it is ready to be accessed by the application. The application may access and queue GPU operations using the acquired image until the next xrEndFrame call, when the image is released and the depth provider may write new depth data into it after completion of all work queued before the xrEndFrame call.

The returned XrEnvironmentDepthImageMETA contains the swapchain index into the array enumerated by xrEnumerateEnvironmentDepthSwapchainImagesMETA. It also contains other information such as the field of view and pose that are necessary to interpret the depth data.

There must be no more than one call to xrAcquireEnvironmentDepthImageMETA between any pair of corresponding xrBeginFrame and xrEndFrame calls in a session.

  • The runtime may block if previously acquired swapchain images are still being used by the graphics API.

  • The runtime must return XR_ERROR_CALL_ORDER_INVALID if xrAcquireEnvironmentDepthImageMETA is called before xrBeginFrame or after xrEndFrame.

  • The runtime must return XR_ERROR_CALL_ORDER_INVALID if xrAcquireEnvironmentDepthImageMETA is called on a stopped XrEnvironmentDepthProviderMETA.

  • The runtime must return XR_ERROR_LIMIT_REACHED if xrAcquireEnvironmentDepthImageMETA is called more than once per frame - i.e. in a running session, after a call to xrBeginFrame that has not had an associated xrEndFrame.

  • Runtimes must return XR_ENVIRONMENT_DEPTH_NOT_AVAILABLE_META if no depth frame is available yet (i.e. the provider was recently started and did not yet have time to compute depth). Note that this is a success code. In this case the output parameters must be unchanged.

  • The application must not utilize the swapchain image in calls to the graphics API after xrEndFrame has been called.

  • A runtime may use the graphics API specific contexts provided to OpenXR. In particular:

    • For OpenGL, a runtime may use the OpenGL context specified in the call to xrCreateSession, which needs external synchronization.

    • For Vulkan, a runtime may use the VkQueue specified in the XrGraphicsBindingVulkan2KHR, which needs external synchronization.

    • For Direct3D12, a runtime may use the ID3D12CommandQueue specified in the XrGraphicsBindingD3D12KHR, which needs external synchronization.

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

  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_ENVIRONMENT_DEPTH_NOT_AVAILABLE_META

On failure, this command returns

  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_TIME_INVALID

  • XR_ERROR_CALL_ORDER_INVALID

See Also

XR_META_environment_depth, XrEnvironmentDepthImageAcquireInfoMETA, XrEnvironmentDepthImageMETA, XrEnvironmentDepthProviderMETA

Document Notes

For more information, see the OpenXR Specification

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

This work is licensed under a Creative Commons Attribution 4.0 International License.