Specify copyTextureToTexture format compatibility (#2329)

kainino0x · web-flow · commit 84dd9a0f154c · 2021-11-23T10:36:57.000-05:00
* Specify copyTextureToTexture format compatibility Specify that copyTextureToTexture is only valid between equal formats, or if the formats diffen only in whether they have `-srgb`. Clean up a few bits of text regarding depth/stencil formats. Add the optional-feature depth/stencil formats to the format table. Fixes #2322 Fixes #1464 * subsection titles, typo
diff --git a/spec/index.bs b/spec/index.bs
@@ -2819,6 +2819,12 @@ enum GPUTextureFormat {
     "depth24plus-stencil8",
     "depth32float",
 
+    // "depth24unorm-stencil8" feature
+    "depth24unorm-stencil8",
+
+    // "depth32float-stencil8" feature
+    "depth32float-stencil8",
+
     // BC compressed formats usable if "texture-compression-bc" is both
     // supported by the device/user agent and enabled in requestDevice.
     "bc1-rgba-unorm",
@@ -2879,29 +2885,24 @@ enum GPUTextureFormat {
     "astc-12x10-unorm-srgb",
     "astc-12x12-unorm",
     "astc-12x12-unorm-srgb",
-
-    // "depth24unorm-stencil8" feature
-    "depth24unorm-stencil8",
-
-    // "depth32float-stencil8" feature
-    "depth32float-stencil8",
 };
 </script>
 
 The depth aspect of the {{GPUTextureFormat/"depth24plus"}}) and {{GPUTextureFormat/"depth24plus-stencil8"}})
-formats may be implemented as either a 24-bit unsigned normalized value ("depth24unorm")
-or a 32-bit IEEE 754 floating point value ("depth32float").
+formats may be implemented as either a 24-bit unsigned normalized value (like "depth24unorm" in {{GPUTextureFormat/"depth24unorm-stencil8"}})
+or a 32-bit IEEE 754 floating point value (like {{GPUTextureFormat/"depth32float"}}).
 
-Issue: add something on GPUAdapter(?) that gives an estimate of the bytes per texel of "stencil8"
+Issue: add something on GPUAdapter(?) that gives an estimate of the bytes per texel of
+{{GPUTextureFormat/"stencil8"}}, {{GPUTextureFormat/"depth24plus-stencil8"}}, and {{GPUTextureFormat/"depth32float-stencil8"}}.
 
 The {{GPUTextureFormat/stencil8}} format may be implemented as
 either a real "stencil8", or "depth24stencil8", where the depth aspect is
 hidden and inaccessible.
 
 Note:
-While the precision of depth32float is strictly higher than the precision of
-depth24unorm for all values in the representable range (0.0 to 1.0),
-note that the set of representable values is not exactly the same:
+While the precision of depth32float channels is strictly higher than the precision of
+depth24unorm channels for all values in the representable range (0.0 to 1.0),
+note that the set of representable values is not an exact superset:
 for depth24unorm, 1 ULP has a constant value of 1 / (2<sup>24</sup> &minus; 1);
 for depth32float, 1 ULP has a variable value no greater than 1 / (2<sup>24</sup>).
 
@@ -6220,8 +6221,8 @@ Issue: convert "Valid Texture Copy Range" into an algorithm with parameters, sim
                     - [$validating GPUImageCopyTexture$](|destination|, |copySize|) returns `true`.
                     - |dstTextureDesc|.{{GPUTextureDescriptor/usage}} contains {{GPUTextureUsage/COPY_DST}}.
                     - |srcTextureDesc|.{{GPUTextureDescriptor/sampleCount}} is equal to |dstTextureDesc|.{{GPUTextureDescriptor/sampleCount}}.
-                    - If |srcTextureDesc|.{{GPUTextureDescriptor/format}} is not equal to |dstTextureDesc|.{{GPUTextureDescriptor/format}}:
-                        - the [=copies of depth and stencil textures|copy configuration is allowed=]
+                    - |srcTextureDesc|.{{GPUTextureDescriptor/format}} and |dstTextureDesc|.{{GPUTextureDescriptor/format}}
+                        must be [=copy-compatible=].
                     - If |srcTextureDesc|.{{GPUTextureDescriptor/format}} is a depth-stencil format:
                         - |source|.{{GPUImageCopyTexture/aspect}} and |destination|.{{GPUImageCopyTexture/aspect}}
                             must both refer to all aspects of |srcTextureDesc|.{{GPUTextureDescriptor/format}}
@@ -9969,7 +9970,6 @@ None of the depth formats can be filtered.
             <th>Bytes per texel
             <th>Aspect
             <th>{{GPUTextureSampleType}}
-            <th>Returned in shaders as...
             <th>Copy aspect from Buffer
             <th>Copy aspect into Buffer
     </thead>
@@ -9978,65 +9978,91 @@ None of the depth formats can be filtered.
         <td>1 &minus; 4
         <td>stencil
         <td>{{GPUTextureSampleType/"uint"}}
-        <td>`vec4<u32>(S, X, X, X)`
         <td colspan=2>&checkmark;
     <tr>
         <td>{{GPUTextureFormat/depth16unorm}}
         <td>2
         <td>depth
         <td>{{GPUTextureSampleType/"depth"}}
-        <td>`f32(D)`
         <td colspan=2>&checkmark;
     <tr>
         <td>{{GPUTextureFormat/depth24plus}}
         <td>4
         <td>depth
         <td>{{GPUTextureSampleType/"depth"}}
-        <td>`f32(D)`
         <td colspan=2>&cross;
     <tr>
         <td rowspan=2 style='white-space:nowrap'>{{GPUTextureFormat/depth24plus-stencil8}}
         <td rowspan=2>4 &minus; 8
         <td>depth
         <td>{{GPUTextureSampleType/"depth"}}
-        <td>`f32(D)`
         <td colspan=2>&cross;
     <tr>
         <td>stencil
         <td>{{GPUTextureSampleType/"uint"}}
-        <td>`vec4<u32>(S, X, X, X)`
         <td colspan=2>&checkmark;
     <tr>
         <td>{{GPUTextureFormat/depth32float}}
         <td>4
         <td>depth
         <td>{{GPUTextureSampleType/"depth"}}
-        <td>`f32(D)`
         <td colspan=1>&cross;
         <td colspan=1>&checkmark;
+    <tr>
+        <td rowspan=2 style='white-space:nowrap'>{{GPUTextureFormat/depth24unorm-stencil8}}
+        <td rowspan=2>4
+        <td>depth
+        <td>{{GPUTextureSampleType/"depth"}}
+        <td colspan=2>&cross;
+    <tr>
+        <td>stencil
+        <td>{{GPUTextureSampleType/"uint"}}
+        <td colspan=2>&checkmark;
+    <tr>
+        <td rowspan=2 style='white-space:nowrap'>{{GPUTextureFormat/depth32float-stencil8}}
+        <td rowspan=2>5 &minus; 8
+        <td>depth
+        <td>{{GPUTextureSampleType/"depth"}}
+        <td colspan=1>&cross;
+        <td colspan=1>&checkmark;
+    <tr>
+        <td>stencil
+        <td>{{GPUTextureSampleType/"uint"}}
+        <td colspan=2>&checkmark;
 </table>
 
-Stencil formats must sample as `vec4<u32>(S, X, X, X)`, where S is the stencil value and each X is an implementation-defined unspecified value.
+#### Reading and Sampling Depth/Stencil Textures #### {#reading-depth-stencil}
+
+When reading or sampling a depth channel via a `texture_depth_*`-typed binding, the value is
+returned as an `f32` value.
+
+Issue(gpuweb/gpuweb#2094): Depending on the resolution of this issue, allow reading/sampling via
+`texture_2d` etc. in the table above and specify the behavior. (`vec4<f32>(D, X, X, X)`?)
+Update the note below which would become slightly outdated.
+
+Reading or sampling a stencil channel must be done via a normal texture binding
+(`texture_2d`, `texture_2d_array`, `texture_cube`, or `texture_cube_array`).
+When doing so, the value is returned as `vec4<u32>(S, X, X, X)`, where S is the stencil value and each X is an implementation-defined unspecified value.
 Authors must not rely on these `.y`, `.z`, and `.w` components, as their behavior is non-portable.
 
 Note:
 Short of adding a new more constrained stencil sampler type (like depth), it's infeasible for implementations to efficiently paper over the driver differences for stencil reads.
 As this was not a portability pain point for WebGL, it's not expected to be problematic in WebGPU.
 In practice, expect either `vec4<u32>(S, S, S, S)` or `vec4<u32>(S, 0, 0, 1)`, depending on hardware.
 
-<dfn dfn>Copies of depth and stencil textures</dfn> can only happen within the following sets of formats:
-  - {{GPUTextureFormat/stencil8}}, {{GPUTextureFormat/depth24plus-stencil8}} (stencil component), {{GPUTextureFormat/r8uint}}
-  - {{GPUTextureFormat/depth16unorm}}, {{GPUTextureFormat/r16uint}}
-  - {{GPUTextureFormat/depth24plus}}, {{GPUTextureFormat/depth24plus-stencil8}} (depth aspect)
+#### Copying Depth/Stencil Textures #### {#copying-depth-stencil}
 
-Additionally, {{GPUTextureFormat/depth32float}} textures can be copied into {{GPUTextureFormat/depth32float}} and {{GPUTextureFormat/r32float}} textures.
+<div algorithm>
+    Two {{GPUTextureFormat}}s |format1| and |format2| are <dfn dfn>copy-compatible</dfn> if:
+
+    - |format1| equals |format2|, or
+    - |format1| and |format2| differ only in whether they are `srgb` formats (have the `-srgb` suffix).
+</div>
 
 Note:
 {{GPUTextureFormat/depth32float}} texel values have a limited range. As a result, copies into
 {{GPUTextureFormat/depth32float}} textures are only valid from other {{GPUTextureFormat/depth32float}} textures.
 
-Issue: clarify if `depth24plus-stencil8` is copyable into `depth24plus` in all target backend APIs.
-
 ### Packed formats ### {#packed-formats}
 
 All packed texture formats support {{GPUTextureUsage/COPY_SRC}}, {{GPUTextureUsage/COPY_DST}}, and {{GPUTextureUsage/TEXTURE_BINDING}} usages. All of these formats have {{GPUTextureSampleType/"float"}} type and can be filtered on sampling.
