Indicate when compositing is using depth values

toji · toji · commit 2be9085ccfc6 · 2019-04-01T11:36:39.000-07:00
This addresses a concern brought up by @kearwood during the discussion of #523. He pointed out that it would be useful for some apps to know if the compositor actually was using the depth values in the case where `ignoreDepthValues` was not set to `true` at layer creation time, because that would allow some applications to skip an unnecessary explicit depth write step that they otherwise would be happy to do if they knew it would contribute to the final frame. Following the pattern set by other WebGL-style attributes like `antialias`, this PR indicates that the layer attribute should communicate whether or not depth values are actually being ignored by the compositor, rather than simply echo the boolean passed in at layer creation time.
diff --git a/explainer.md b/explainer.md
@@ -530,7 +530,7 @@ Some applications may violate that assumption, such as when using certain deferr
 let webglLayer = new XRWebGLLayer(xrSession, gl, { ignoreDepthValues: true });
 ```
 
-If `ignoreDepthValues` is not set to `true` the The UA is allowed (but not required) to use depth buffer as it sees fit. As a result, barring compositor access to the depth buffer in this way may lead to certain platform or UA features being unavailable or less robust.
+If `ignoreDepthValues` is not set to `true` the The UA is allowed (but not required) to use depth buffer as it sees fit. As a result, barring compositor access to the depth buffer in this way may lead to certain platform or UA features being unavailable or less robust. To detect if the depth buffer is being used by the compositor, check the `ignoreDepthValues` attribute of the `XRWebGLLayer` after the layer is created. A value of `true` indicates that the depth buffer will not be utilized by the compositor even if `ignoreDepthValues` was set to `false` during layer creation.
 
 ### Handling non-opaque displays
 
diff --git a/index.bs b/index.bs
@@ -1168,7 +1168,8 @@ The <dfn constructor for="XRWebGLLayer">XRWebGLLayer(|session|, |context|, |laye
   1. Initialize |layer|'s {{XRWebGLLayer/depth}} to |layerInit|'s {{XRWebGLLayerInit/depth}} value.
   1. Initialize |layer|'s {{XRWebGLLayer/stencil}} to |layerInit|'s {{XRWebGLLayerInit/stencil}} value.
   1. Initialize |layer|'s {{XRWebGLLayer/alpha}} to |layerInit|'s {{XRWebGLLayerInit/alpha}} value.
-  1. Initialize |layer|'s {{XRWebGLLayer/ignoreDepthValues}} to |layerInit|'s {{XRWebGLLayerInit/ignoreDepthValues}} value.
+  1. If |layerInit|'s {{XRWebGLLayerInit/ignoreDepthValues}} value is <code>false</code> and the [=XR Compositor=] will make use of depth values, Initialize |layer|'s {{XRWebGLLayer/ignoreDepthValues}} to <code>false</code>.
+  1. Else Initialize |layer|'s {{XRWebGLLayer/ignoreDepthValues}} to <code>true</code>
   1. Initialize |layer|'s {{XRWebGLLayer/framebuffer}} to a new [=opaque framebuffer=] created with |context|.
   1. Initialize the |layer|'s [=swap chain=].
   1. If |layer|'s [=swap chain=] was unable to be created for any reason, throw an {{OperationError}} and abort these steps.
@@ -1194,7 +1195,7 @@ The <dfn attribute for="XRWebGLLayer">stencil</dfn> attribute is <code>true</cod
 
 The <dfn attribute for="XRWebGLLayer">alpha</dfn> attribute is <code>true</code> if the {{framebuffer}} has an alpha buffer attachment and <code>false</code> if no alpha buffer is attached.
 
-The <dfn attribute for="XRWebGLLayer">ignoreDepthValues</dfn> attribute, if <code>true</code>, indicates the [=XR Compositor=] MUST NOT make use of values in the depth buffer attachment when rendering. When the attribute is <code>false</code> it indicates that the content of the depth buffer attachment is expected to be representative of the scene rendered into the layer and MAY be used by the [=XR Compositor=].
+The <dfn attribute for="XRWebGLLayer">ignoreDepthValues</dfn> attribute, if <code>true</code>, indicates the [=XR Compositor=] MUST NOT make use of values in the depth buffer attachment when rendering. When the attribute is <code>false</code> it indicates that the content of the depth buffer attachment will be used by the [=XR Compositor=] and is expected to be representative of the scene rendered into the layer.
 
 Depth values stored in the buffer are expected to be between <code>0.0</code> and <code>1.0</code>, with <code>0.0</code> representing the distance of {{XRRenderState/depthNear}} and <code>1.0</code> representing the distance of {{XRRenderState/depthFar}}, with intermediate values interpolated linearly. This is the default behavior of WebGL. (See documentation for the <a href="https://www.khronos.org/registry/OpenGL-Refpages/es2.0/xhtml/glDepthRangef.xml">depthRange function</a> for additional details.))
 
