// Copyright (c) Meta Platforms, LLC and its affiliates. All rights reserved.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/XR_META_environment_depth.adoc[]

*Last Modified Date*::
    2023-10-09

*IP Status*::
    No known IP claims.

*Contributors*::
    Andreas Selvik, Meta Platforms +
    Cass Everitt, Meta Platforms +
    Daniel Henell, Meta Platforms +
    John Kearney, Meta Platforms +
    Urs Niesen, Meta Platforms +

==== Overview

This extension allows the application to request depth maps of the
real-world environment around the headset.
The depth maps are generated by the runtime and shared with the application
using an slink:XrEnvironmentDepthSwapchainMETA.

==== Inspect System Capability

[open,refpage='XrSystemEnvironmentDepthPropertiesMETA',type='structs',desc='System property for environment depth',xrefs='']
--
The slink:XrSystemEnvironmentDepthPropertiesMETA structure is defined as:

include::{generated}/api/structs/XrSystemEnvironmentDepthPropertiesMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:supportsEnvironmentDepth is an basetype:XrBool32 indicating if
  current system supports environment depth.
* pname:supportsHandRemoval is an basetype:XrBool32 indicating if current
  system supports hand removal.
****

An application can: inspect whether the system is capable of supporting
environment depth by extending the slink:XrSystemProperties with
slink:XrSystemEnvironmentDepthPropertiesMETA structure when calling
flink:xrGetSystemProperties.

If and only if a runtime returns ename:XR_FALSE for
pname:supportsEnvironmentDepth, the runtime must: return
ename:XR_ERROR_FEATURE_UNSUPPORTED from
flink:xrCreateEnvironmentDepthProviderMETA.

If and only if a runtime returns ename:XR_FALSE for
pname:supportsHandRemoval, the runtime must: return
ename:XR_ERROR_FEATURE_UNSUPPORTED from
flink:xrSetEnvironmentDepthHandRemovalMETA.

include::{generated}/validity/structs/XrSystemEnvironmentDepthPropertiesMETA.adoc[]
--

==== Creating and Destroying a Depth Provider


[open,refpage='XrEnvironmentDepthProviderMETA',type='handles',desc='XrEnvironmentDepthProviderMETA',xrefs='xrCreateEnvironmentDepthProviderMETA xrDestroyEnvironmentDepthProviderMETA xrStartEnvironmentDepthProviderMETA xrStopEnvironmentDepthProviderMETA xrCreateEnvironmentDepthSwapchainMETA xrAcquireEnvironmentDepthImageMETA']
--

include::{generated}/api/handles/XrEnvironmentDepthProviderMETA.adoc[]

An slink:XrEnvironmentDepthProviderMETA is a handle to a depth provider.
--

[open,refpage='xrCreateEnvironmentDepthProviderMETA',desc='Creates and initializes a depth provider.',type='protos',xrefs='']
--
The flink:xrCreateEnvironmentDepthProviderMETA function is defined as:

include::{generated}/api/protos/xrCreateEnvironmentDepthProviderMETA.adoc[]

.Parameter Descriptions
****
* pname:session is the slink:XrSession.
* pname:createInfo is a pointer to an
  slink:XrEnvironmentDepthProviderCreateInfoMETA containing creation options
  for the depth provider.
* pname:environmentDepthProvider is the returned
  slink:XrEnvironmentDepthProviderMETA handle for the created depth
  provider.
****

The flink:xrCreateEnvironmentDepthProviderMETA function creates a depth
provider instance.

Creating the depth provider may: allocate resources, but should: not incur
any per-frame compute costs until the provider has been started.

* Runtimes must: create the provider in a stopped state.
* Runtimes may: limit the number of depth providers per slink:XrInstance.
  If flink:xrCreateEnvironmentDepthProviderMETA fails due to reaching this
  limit, the runtime must: return ename:XR_ERROR_LIMIT_REACHED.
* Runtimes must: support at least 1 provider per slink:XrInstance.
* Runtimes may: return ename:XR_ERROR_NOT_PERMITTED_PASSTHROUGH_FB if the
  app permissions have not been granted to the calling app.
* Applications can: call flink:xrStartEnvironmentDepthProviderMETA to start
  the generation of depth maps.

include::{generated}/validity/protos/xrCreateEnvironmentDepthProviderMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthProviderCreateInfoMETA',type='structs',desc='XrEnvironmentDepthProviderCreateInfoMETA',xrefs='']
--
The slink:XrEnvironmentDepthProviderCreateInfoMETA structure is defined as:

include::{generated}/api/structs/XrEnvironmentDepthProviderCreateInfoMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:createFlags is `0` or one or more
  elink:XrEnvironmentDepthProviderCreateFlagBitsMETA.
****

The slink:XrEnvironmentDepthProviderCreateInfoMETA structure provides
creation options for the slink:XrEnvironmentDepthProviderMETA when passed to
flink:xrCreateEnvironmentDepthProviderMETA.

include::{generated}/validity/structs/XrEnvironmentDepthProviderCreateInfoMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthProviderCreateFlagsMETA',desc='Environment depth provider create flags',type='flags',xrefs='XrEnvironmentDepthProviderCreateFlagBitsMETA']
--
The elink:XrEnvironmentDepthProviderCreateFlagsMETA specifies creation
options for slink:XrEnvironmentDepthProviderMETA.

include::{generated}/api/flags/XrEnvironmentDepthProviderCreateFlagsMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthProviderCreateFlagBitsMETA',desc='Environment depth provider create flags',type='enums',xrefs='XrEnvironmentDepthProviderCreateFlagsMETA']
--
Valid bits for elink:XrEnvironmentDepthProviderCreateFlagsMETA are defined
by elink:XrEnvironmentDepthProviderCreateFlagBitsMETA, which is specified
as:

include::{generated}/api/enums/XrEnvironmentDepthProviderCreateFlagBitsMETA.adoc[]

There are currently no flag bits defined.
This is reserved for future use.
--

[open,refpage='xrDestroyEnvironmentDepthProviderMETA',desc='Destroys the depth provider and frees all memory and resources.',type='protos',xrefs='']
--
The flink:xrDestroyEnvironmentDepthProviderMETA function is defined as:

include::{generated}/api/protos/xrDestroyEnvironmentDepthProviderMETA.adoc[]

.Parameter Descriptions
****
* pname:environmentDepthProvider is an slink:XrEnvironmentDepthProviderMETA
  handle for the depth provider.
****

The flink:xrDestroyEnvironmentDepthProviderMETA function destroys the depth
provider.
After this call the runtime may: free all related memory and resources.

include::{generated}/validity/protos/xrDestroyEnvironmentDepthProviderMETA.adoc[]
--

==== Starting and Stopping a Depth Provider

[open,refpage='xrStartEnvironmentDepthProviderMETA',desc='Starts the generation of depth maps.',type='protos',xrefs='']
--
The flink:xrStartEnvironmentDepthProviderMETA function is defined as:

include::{generated}/api/protos/xrStartEnvironmentDepthProviderMETA.adoc[]

.Parameter Descriptions
****
* pname:environmentDepthProvider is an slink:XrEnvironmentDepthProviderMETA
  handle for the depth provider.
****

The flink:xrStartEnvironmentDepthProviderMETA function starts the
asynchronous generation of depth maps.

Starting the depth provider may: use CPU and GPU resources.

Runtimes must: return ename:XR_ERROR_UNEXPECTED_STATE_PASSTHROUGH_FB if
flink:xrStartEnvironmentDepthProviderMETA is called on an already started
slink:XrEnvironmentDepthProviderMETA.

include::{generated}/validity/protos/xrStartEnvironmentDepthProviderMETA.adoc[]
--

[open,refpage='xrStopEnvironmentDepthProviderMETA',desc='Stops the depth feature.',type='protos',xrefs='']
--
The flink:xrStopEnvironmentDepthProviderMETA function is defined as:

include::{generated}/api/protos/xrStopEnvironmentDepthProviderMETA.adoc[]

.Parameter Descriptions
****
* pname:environmentDepthProvider is an slink:XrEnvironmentDepthProviderMETA
  handle for the depth provider.
****

The flink:xrStopEnvironmentDepthProviderMETA function stops the generation
of depth maps.
This stops all per frame computation of environment depth for the
application.

Runtimes must: return ename:XR_ERROR_UNEXPECTED_STATE_PASSTHROUGH_FB if
flink:xrStopEnvironmentDepthProviderMETA is called on an already stopped
slink:XrEnvironmentDepthProviderMETA.

include::{generated}/validity/protos/xrStopEnvironmentDepthProviderMETA.adoc[]
--

==== Hand Removal

Runtimes may: provide functionality to remove hands from the depth map and
filling in estimated background depth values.
This is useful to support other occlusion methods specialized for hands to
coexist with the Environment Depth extension.

[open,refpage='xrSetEnvironmentDepthHandRemovalMETA',desc='Enables/disables hand removal from the depth map.',type='protos',xrefs='']
--
The flink:xrSetEnvironmentDepthHandRemovalMETA function is defined as:

include::{generated}/api/protos/xrSetEnvironmentDepthHandRemovalMETA.adoc[]

.Parameter Descriptions
****
* pname:environmentDepthProvider is an slink:XrEnvironmentDepthProviderMETA
  handle for the depth provider.
* pname:setInfo is a pointer to an
  slink:XrEnvironmentDepthHandRemovalSetInfoMETA containing options for the
  hand removal.
****

The flink:xrSetEnvironmentDepthHandRemovalMETA function sets hand removal
options.

Runtimes should: enable or disable the removal of the hand depths from the
depth map.
If enabled, the corresponding depth pixels should: be replaced with the
estimated background depth behind the hands.
Runtimes must: return ename:XR_ERROR_FEATURE_UNSUPPORTED if and only if
slink:XrSystemEnvironmentDepthPropertiesMETA::pname:supportsHandRemoval is
ename:XR_FALSE.

include::{generated}/validity/protos/xrSetEnvironmentDepthHandRemovalMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthHandRemovalSetInfoMETA',type='structs',desc='XrEnvironmentDepthHandRemovalSetInfoMETA',xrefs='']
--
The slink:XrEnvironmentDepthHandRemovalSetInfoMETA structure is defined as:

include::{generated}/api/structs/XrEnvironmentDepthHandRemovalSetInfoMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:enabled is ename:XR_TRUE or ename:XR_FALSE to enable/disable hand
  removal from the depth map, respectively.
****

This structure contains options passed to
flink:xrSetEnvironmentDepthHandRemovalMETA.

include::{generated}/validity/structs/XrEnvironmentDepthHandRemovalSetInfoMETA.adoc[]
--

==== Creating a Readable Depth Swapchain

The depth data is generated in the runtime and shared to the application
though an slink:XrEnvironmentDepthSwapchainMETA.
This swapchain is different from regular swapchains in that it provides a
data channel from the runtime to the application instead of the other way
around.

[open,refpage='XrEnvironmentDepthSwapchainMETA',type='handles',desc='XrEnvironmentDepthSwapchainMETA',xrefs='xrCreateEnvironmentDepthSwapchainMETA']
--
include::{generated}/api/handles/XrEnvironmentDepthSwapchainMETA.adoc[]

slink:XrEnvironmentDepthSwapchainMETA is a handle to a readable depth
swapchain.
--

[open,refpage='xrCreateEnvironmentDepthSwapchainMETA',desc='Returns a readable depth swapchain.',type='protos',xrefs='']
--
The flink:xrCreateEnvironmentDepthSwapchainMETA function is defined as:

include::{generated}/api/protos/xrCreateEnvironmentDepthSwapchainMETA.adoc[]

.Parameter Descriptions
****
* pname:environmentDepthProvider is an slink:XrEnvironmentDepthProviderMETA
  handle for the depth provider.
* pname:createInfo is a pointer to an
  slink:XrEnvironmentDepthSwapchainCreateInfoMETA containing creation
  options for the swapchain.
* pname:swapchain is the returned slink:XrEnvironmentDepthSwapchainMETA
  handle for the created swapchain.
****

The flink:xrCreateEnvironmentDepthSwapchainMETA function creates a readable
swapchain, which is used for accessing the depth data.

The runtime decides on the resolution and length of the swapchain.
Additional information about the swapchain can: be accessed by calling
flink:xrGetEnvironmentDepthSwapchainStateMETA.

Runtimes must: create a swapchain with array textures of length 2, which map
to a left-eye and right-eye view.
View index 0 must: represent the left eye and view index 1 must: represent
the right eye.
This is the same convention as for
ename:XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO in
elink:XrViewConfigurationType.
Runtimes must: create the swapchain with the following image formats
depending on the graphics API associated with the session:

* OpenGL: ename:GL_DEPTH_COMPONENT16
* Vulkan: ename:VK_FORMAT_D16_UNORM
* Direct3D: ename:DXGI_FORMAT_D16_UNORM

Runtimes must: only allow maximum one swapchain to exist per depth provider
at any given time, and must return ename:XR_ERROR_LIMIT_REACHED if
flink:xrCreateEnvironmentDepthSwapchainMETA is called to create more.
Applications should: destroy the swapchain when no longer needed.
Applications must: be able to handle different swapchain lengths and
resolutions.

include::{generated}/validity/protos/xrCreateEnvironmentDepthSwapchainMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthSwapchainCreateInfoMETA',type='structs',desc='XrEnvironmentDepthSwapchainCreateInfoMETA',xrefs='']
--
The slink:XrEnvironmentDepthSwapchainCreateInfoMETA structure is defined as:

include::{generated}/api/structs/XrEnvironmentDepthSwapchainCreateInfoMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:createFlags is a bitmask of
  elink:XrEnvironmentDepthSwapchainCreateFlagBitsMETA.
****

slink:XrEnvironmentDepthSwapchainCreateInfoMETA contains creation options
for the readable depth swapchain, and is passed to
flink:xrCreateEnvironmentDepthSwapchainMETA.

include::{generated}/validity/structs/XrEnvironmentDepthSwapchainCreateInfoMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthSwapchainCreateFlagsMETA',desc='Environment depth swapchain create flags',type='flags',xrefs='XrEnvironmentDepthSwapchainCreateFlagBitsMETA']
--
The elink:XrEnvironmentDepthSwapchainCreateFlagsMETA specifies creation
options for slink:XrEnvironmentDepthSwapchainCreateInfoMETA.

include::{generated}/api/flags/XrEnvironmentDepthSwapchainCreateFlagsMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthSwapchainCreateFlagBitsMETA',desc='Environment depth swapchain create flags',type='enums',xrefs='XrEnvironmentDepthSwapchainCreateFlagsMETA']
--
Valid bits for elink:XrEnvironmentDepthProviderCreateFlagsMETA are defined
by elink:XrEnvironmentDepthSwapchainCreateFlagBitsMETA, which is specified
as:

include::{generated}/api/enums/XrEnvironmentDepthSwapchainCreateFlagBitsMETA.adoc[]

There are currently no flag bits defined.
This is reserved for future use.
--

[open,refpage='xrGetEnvironmentDepthSwapchainStateMETA',desc='Returns the state of the readable depth swapchain.',type='protos',xrefs='']
--
The flink:xrGetEnvironmentDepthSwapchainStateMETA function is defined as:

include::{generated}/api/protos/xrGetEnvironmentDepthSwapchainStateMETA.adoc[]

.Parameter Descriptions
****
* pname:swapchain is an slink:XrEnvironmentDepthSwapchainMETA handle.
* pname:state is a pointer to an slink:XrEnvironmentDepthSwapchainStateMETA.
****

flink:xrGetEnvironmentDepthSwapchainStateMETA retrieves information about
the slink:XrEnvironmentDepthSwapchainMETA.
This information is constant throughout the lifetime of the
slink:XrEnvironmentDepthSwapchainMETA.

include::{generated}/validity/protos/xrGetEnvironmentDepthSwapchainStateMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthSwapchainStateMETA',type='structs',desc='XrEnvironmentDepthSwapchainStateMETA',xrefs='']
--
The slink:XrEnvironmentDepthSwapchainStateMETA structure is defined as:

include::{generated}/api/structs/XrEnvironmentDepthSwapchainStateMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:width is the width of the image.
* pname:height is the height of the image.
****

include::{generated}/validity/structs/XrEnvironmentDepthSwapchainStateMETA.adoc[]
--

[open,refpage='xrDestroyEnvironmentDepthSwapchainMETA',desc='Destroys a readable depth swapchain.',type='protos',xrefs='']
--
The flink:xrDestroyEnvironmentDepthSwapchainMETA function is defined as:

include::{generated}/api/protos/xrDestroyEnvironmentDepthSwapchainMETA.adoc[]

.Parameter Descriptions
****
* pname:swapchain is the slink:XrEnvironmentDepthSwapchainMETA to be
  destroyed.
****

The flink:xrDestroyEnvironmentDepthSwapchainMETA function destroys a
readable environment depth swapchain.

All submitted graphics API commands that refer to pname:swapchain must: have
completed execution.
Runtimes may: continue to utilize swapchain images after
flink:xrDestroyEnvironmentDepthSwapchainMETA is called.

include::{generated}/validity/protos/xrDestroyEnvironmentDepthSwapchainMETA.adoc[]
--

==== Accessing the Readable Depth Swapchain During Rendering

[open,refpage='xrEnumerateEnvironmentDepthSwapchainImagesMETA',desc='Gets images from a readable depth swapchain.',type='protos',xrefs='']
--
The flink:xrEnumerateEnvironmentDepthSwapchainImagesMETA function is defined
as:

include::{generated}/api/protos/xrEnumerateEnvironmentDepthSwapchainImagesMETA.adoc[]

.Parameter Descriptions
****
* pname:swapchain is the slink:XrEnvironmentDepthSwapchainMETA to get images
  from.
* pname:imageCapacityInput is the capacity of the images array, or 0 to
  indicate a request to retrieve the required capacity.
* pname:imageCountOutput is a pointer to the count of images written, or a
  pointer to the required capacity in the case that pname:imageCapacityInput
  is insufficient.
* pname:images is a pointer to an array of graphics API-specific
  XrSwapchainImage structures, all of the same type, based on
  slink:XrSwapchainImageBaseHeader.
  It can: be ename:NULL if pname:imageCapacityInput is 0.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required pname:images size.
****

flink:xrEnumerateEnvironmentDepthSwapchainImagesMETA fills an array of
graphics API-specific stext:XrSwapchainImage* structures derived from
slink:XrSwapchainImageBaseHeader.
The resources must: be constant and valid for the lifetime of the
slink:XrEnvironmentDepthSwapchainMETA.
This function behaves analogously to flink:xrEnumerateSwapchainImages.

Runtimes must: always return identical buffer contents from this enumeration
for the lifetime of the swapchain.

Note: pname:images is a pointer to an array of structures of graphics
API-specific type, not an array of structure pointers.

The pointer submitted as pname:images will be treated as an array of the
expected graphics API-specific type based on the graphics API used at
session creation time.
If the type member of any array element accessed in this way does not match
the expected value, the runtime must: return
ename:XR_ERROR_VALIDATION_FAILURE.

include::{generated}/validity/protos/xrEnumerateEnvironmentDepthSwapchainImagesMETA.adoc[]
--

[open,refpage='xrAcquireEnvironmentDepthImageMETA',desc='Returns an image index in a readable depth swapchain and associated metadata.',type='protos',xrefs='']
--
The flink:xrAcquireEnvironmentDepthImageMETA function is defined as:

include::{generated}/api/protos/xrAcquireEnvironmentDepthImageMETA.adoc[]

.Parameter Descriptions
****
* pname:environmentDepthProvider is an slink:XrEnvironmentDepthProviderMETA
  handle for the depth provider.
* pname:acquireInfo is an slink:XrEnvironmentDepthImageAcquireInfoMETA
  containing parameters for populating a depth swapchain image.
* pname:environmentDepthImage is the returned
  slink:XrEnvironmentDepthImageMETA containing information about the
  acquired depth image.
****

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 flink: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 flink:xrEndFrame call.


The returned slink:XrEnvironmentDepthImageMETA contains the swapchain index
into the array enumerated by
flink: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
flink:xrAcquireEnvironmentDepthImageMETA between any pair of corresponding
flink:xrBeginFrame and flink: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 ename:XR_ERROR_CALL_ORDER_INVALID if
  flink:xrAcquireEnvironmentDepthImageMETA is called before
  flink:xrBeginFrame or after flink:xrEndFrame.
* The runtime must: return ename:XR_ERROR_CALL_ORDER_INVALID if
  flink:xrAcquireEnvironmentDepthImageMETA is called on a stopped
  slink:XrEnvironmentDepthProviderMETA.
* The runtime must: return ename:XR_ERROR_LIMIT_REACHED if
  flink:xrAcquireEnvironmentDepthImageMETA is called more than once per
  frame - i.e. in a running session, after a call to flink:xrBeginFrame that
  has not had an associated flink:xrEndFrame.
* Runtimes must: return ename: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 flink: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 flink:xrCreateSession, which needs external synchronization.
** For Vulkan, a runtime may: use the sname:VkQueue specified in the
   slink:XrGraphicsBindingVulkan2KHR, which needs external synchronization.
** For Direct3D12, a runtime may: use the sname:ID3D12CommandQueue specified
   in the slink:XrGraphicsBindingD3D12KHR, which needs external
   synchronization.

include::{generated}/validity/protos/xrAcquireEnvironmentDepthImageMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthImageAcquireInfoMETA',type='structs',desc='XrEnvironmentDepthImageAcquireInfoMETA',xrefs='']
--
The slink:XrEnvironmentDepthImageAcquireInfoMETA structure is defined as:

include::{generated}/api/structs/XrEnvironmentDepthImageAcquireInfoMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:space is an slink:XrSpace defining the reference frame of the
  returned pose in slink:XrEnvironmentDepthImageMETA.
* pname:displayTime is an basetype:XrTime specifying the time used to
  compute the pose for the returned pose in
  slink:XrEnvironmentDepthImageMETA.
  Clients should: pass their predicted display time for the current frame.
****

include::{generated}/validity/structs/XrEnvironmentDepthImageAcquireInfoMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthImageViewMETA',type='structs',desc='XrEnvironmentDepthImageViewMETA',xrefs='']
--
The slink:XrEnvironmentDepthImageViewMETA structure is defined as:

include::{generated}/api/structs/XrEnvironmentDepthImageViewMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:fov is an slink:XrFovf specifying the field of view used to generate
  this view.
  The view is never flipped horizontally nor vertically.
* pname:pose is an slink:XrPosef specifying the pose from which the depth
  map was rendered.
  The reference frame is specified in
  slink:XrEnvironmentDepthImageAcquireInfoMETA.
****

include::{generated}/validity/structs/XrEnvironmentDepthImageViewMETA.adoc[]
--

[open,refpage='XrEnvironmentDepthImageMETA',type='structs',desc='XrEnvironmentDepthImageMETA',xrefs='']
--
The slink:XrEnvironmentDepthImageMETA structure is defined as:

include::{generated}/api/structs/XrEnvironmentDepthImageMETA.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:swapchainIndex is the index of the acquired texture in the depth
  swapchain.
* pname:nearZ is the distance to the near Z plane in meters.
* pname:farZ is the distance to the far Z plane in meters.
* pname:views is an array of two slink:XrEnvironmentDepthImageViewMETA, one
  for each eye, where index 0 is left eye and index 1 is the right eye.
****

Depth is provided as textures in the same format as described in the
apiext:XR_KHR_composition_layer_depth extension.

The frustum's Z-planes are placed at pname:nearZ and pname:farZ meters.
When pname:farZ is less than pname:nearZ, an infinite projection matrix is
used.

include::{generated}/validity/structs/XrEnvironmentDepthImageMETA.adoc[]
--

==== Vulkan Swapchain Image Layout

For an application using Vulkan, after a successful call to
flink:xrAcquireEnvironmentDepthImageMETA that does *not* return
ename:XR_ENVIRONMENT_DEPTH_NOT_AVAILABLE_META, the following conditions
apply to the *runtime*:

* The runtime must: ensure the acquired readable depth swapchain image has a
  memory layout compatible with
  ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.
  **Note** that this is different from flink:xrAcquireSwapchainImage which
  guarantees ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL.
* The runtime must: ensure the sname:VkQueue specified in
  slink:XrGraphicsBindingVulkanKHR / slink:XrGraphicsBindingVulkan2KHR has
  ownership of the acquired readable depth swapchain image.

Upon next calling flink:xrEndFrame after such an acquire call, the following
conditions apply to the *application*:

* The application must: ensure that the readable depth swapchain image has a
  memory layout compatible with
  ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.
* The application must: ensure that the readable depth swapchain image is
  owned by the sname:VkQueue specified in slink:XrGraphicsBindingVulkanKHR /
  slink:XrGraphicsBindingVulkan2KHR.

The application is responsible for transitioning the swapchain image back to
the image layout and queue ownership that the OpenXR runtime requires.
If the image is not in a layout compatible with the above specifications,
the runtime may: exhibit undefined behavior.

==== Direct3D 12 Swapchain Image Resource State

For an application using D3D12, after a successful call to
flink:xrAcquireEnvironmentDepthImageMETA that does *not* return
ename:XR_ENVIRONMENT_DEPTH_NOT_AVAILABLE_META, the following conditions
apply to the *runtime*:

* The runtime must: ensure the acquired readable depth swapchain image has a
  resource state match with ename:D3D12_RESOURCE_STATE_ALL_SHADER_RESOURCE.
  **Note** that this is different from flink:xrAcquireSwapchainImage which
  guarantees ename:D3D12_RESOURCE_STATE_DEPTH_WRITE for swapchain images
  with depth formats.
* The runtime must: ensure that the sname:ID3D12CommandQueue specified in
  slink:XrGraphicsBindingD3D12KHR may: read from the acquired readable depth
  swapchain image.

Upon next calling flink:xrEndFrame after such an acquire call, the following
conditions apply to the *application*:

* The application must: ensure that the readable depth swapchain image has a
  resource state match with ename:D3D12_RESOURCE_STATE_ALL_SHADER_RESOURCE.
* The application must: ensure that the readable depth swapchain image is
  available for read/write on the sname:ID3D12CommandQueue specified in
  slink:XrGraphicsBindingD3D12KHR.

The application is responsible for transitioning the swapchain image back to
the resource state and queue availability that the OpenXR runtime requires.
If the image is not in a resource state match with the above specifications
the runtime may: exhibit undefined behavior.

*Version History*

* Revision 1, 2023-08-24 (Daniel Henell)
** Initial extension description
