// Copyright (c) 2017-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

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

*Last Modified Date*::
    2019-01-24
*IP Status*::
    No known IP claims.
*Contributors*::
    Paul Pedriana, Oculus +
    Bryce Hutchings, Microsoft +
    Andreas Loeve Selvik, Arm +
    Martin Renschler, Qualcomm

*Overview*

This extension defines an extra layer type which allows applications to
submit depth images along with color images in projection layers, i.e.
slink:XrCompositionLayerProjection.

The XR runtime may: use this information to perform more accurate
reprojections taking depth into account.
Use of this extension does not affect the order of layer composition as
described in <<rendering-compositing>>.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_COMPOSITION_LAYER_DEPTH_INFO_KHR

*New Enums*

*New Structures*

[open,refpage='XrCompositionLayerDepthInfoKHR',desc='Depth map layer info',type='structs',xrefs='XrCompositionLayerProjectionView XrCompositionLayerProjection XrCompositionLayerBaseHeader XrFrameEndInfo xrEndFrame']
--
When submitting depth images along with projection layers, add the
slink:XrCompositionLayerDepthInfoKHR to the pname:next chain for all
slink:XrCompositionLayerProjectionView structures in the given layer.

The slink:XrCompositionLayerDepthInfoKHR structure is defined as:

include::{generated}/api/structs/XrCompositionLayerDepthInfoKHR.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:subImage identifies the depth image slink:XrSwapchainSubImage to be
  associated with the color swapchain.
  The swapchain must: have been created with a
  slink:XrSwapchainCreateInfo::pname:faceCount of 1.
* pname:minDepth and pname:maxDepth are the window space depths that
  correspond to the near and far frustum planes, respectively.
  pname:minDepth must be less than pname:maxDepth.
  pname:minDepth and pname:maxDepth must be in the range [0, 1].
* pname:nearZ and pname:farZ are the positive distances in meters to the
  near and far frustum planes, respectively.
  pname:nearZ and pname:farZ must: not be equal.
  pname:nearZ and pname:farZ must: be in the range (0, +infinity].
****

[NOTE]
.Note
====
The window space depth values pname:minDepth and pname:maxDepth are akin to
the parameters of fname:glDepthRange that specify the mapping from
normalized device coordinates into window space.
====

[NOTE]
.Note
====
A reversed mapping of depth, such that points closer to the view have a
window space depth that is greater than points further away can be achieved
by making nearZ > farZ.
====

slink:XrCompositionLayerDepthInfoKHR contains the information needed to
associate depth with the color information in a projection layer.
When submitting depth images along with projection layers, add the
slink:XrCompositionLayerDepthInfoKHR to the pname:next chain for all
slink:XrCompositionLayerProjectionView structures in the given layer.

The homogeneous transform from view space z to window space depth is given
by the following matrix, where a = minDepth, b = maxDepth, n = nearZ, and f
= farZ.

image::images/windowFromView.png[align="center", title="Homogeneous transform from view space to window space depth"]

Homogeneous values are constructed from real values by appending a w
component with value 1.0.

General homogeneous values are projected back to real space by dividing by
the w component.

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

*New Functions*

*Issues*

. Should the range of pname:minDepth and pname:maxDepth be constrained to [0,1]?
+
*RESOLVED*: Yes.
+
There is no compelling mathematical reason for this constraint, however, it
does not impose any hardship currently, and the constraint could be relaxed
in a future version of the extension if needed.

. Should we require pname:minDepth be less than pname:maxDepth?
+
*RESOLVED*: Yes.
+
There is no compelling mathematical reason for this constraint, however, it
does not impose any hardship currently, and the constraint could be relaxed
in a future version of the extension if needed.
Reverse z mappings can be achieved by making pname:nearZ > pname:farZ.

. Does this extension support view space depth images?
+
*RESOLVED*: No. +
The formulation of the transform between view and window depths implies
projected depth.
A different extension would be needed to support a different interpretation
of depth.

. Is there any constraint on the resolution of the depth subimage?
+
*RESOLVED*: No.
+
The resolution of the depth image need not match that of the corresponding
color image.

*Version History*

* Revision 1, 2017-08-18 (Paul Pedriana)
** Initial proposal.
* Revision 2, 2017-10-30 (Kaye Mason)
** Migration from Images to Swapchains.
* Revision 3, 2018-07-20 (Bryce Hutchings)
** Support for swapchain texture arrays
* Revision 4, 2018-12-17 (Andreas Loeve Selvik)
** depthImageRect in pixels instead of UVs
* Revision 5, 2019-01-24 (Martin Renschler)
** changed depthSwapchain/depthImageRect/depthImageArrayIndex +
to slink:XrSwapchainSubImage
** reformat and spec language changes
** removed vendor specific terminology
* Revision 6, 2022-02-16 (Cass Everitt)
** Provide homogeneous transform as function of provided parameters
