Add "texture-component-swizzle" feature (#193)

This PR adds the "texture-component-swizzle" feature added to the spec
in gpuweb/gpuweb#5361

Author: beaufortfrancois

README.md

@@ -83,8 +83,8 @@ Please contribute a PR to add instructions for other setups or improve existing
 - Make sure the submodule is checked out: `git submodule update --init`
 - Pull `gpuweb` changes: `pushd gpuweb && git checkout main && git pull && popd`
 - Install dependencies: `npm ci`
-- Generate `generated/index-fixed.d.ts`: `npm run generate`
-- Open a diff between `generated/index-fixed.d.ts` and `dist/index.d.ts`.
+- Generate `generated/index.d.ts`: `npm run generate`
+- Open a diff between `generated/index.d.ts` and `dist/index.d.ts`.
     The generated file is tracked by Git so you can see what has changed.
     Update the latter according to changes from the former.
     Note the `generated/` and `dist/` files are not the same.

dist/index.d.ts

@@ -318,7 +318,8 @@ type GPUFeatureName =
     | "subgroups"
     | "texture-formats-tier1"
     | "texture-formats-tier2"
-    | "primitive-index";
+    | "primitive-index"
+    | "texture-component-swizzle";
 type GPUFilterMode =
 
     | "nearest"
@@ -1808,6 +1809,21 @@ interface GPUTextureViewDescriptor
    * to the texture view.
    */
   arrayLayerCount?: GPUIntegerCoordinate;
+  /**
+   * A string of length four, with each character mapping to the texture view's red/green/blue/alpha
+   * channels, respectively.
+   * When accessed by a shader, the red/green/blue/alpha channels are replaced by the value
+   * corresponding to the component specified in `swizzle[0]`, `swizzle[1]`, `swizzle[2]`, and
+   * `swizzle[3]`, respectively:
+   * - `"r"`: Take its value from the red channel of the texture.
+   * - `"g"`: Take its value from the green channel of the texture.
+   * - `"b"`: Take its value from the blue channel of the texture.
+   * - `"a"`: Take its value from the alpha channel of the texture.
+   * - `"0"`: Force its value to 0.
+   * - `"1"`: Force its value to 1.
+   * Requires the {@link GPUFeatureName} `"texture-component-swizzle"` feature to be enabled.
+   */
+  swizzle?: string;
 }
 
 interface GPUUncapturedErrorEventInit

generated/index.d.ts

@@ -318,7 +318,8 @@ type GPUFeatureName =
     | "subgroups"
     | "texture-formats-tier1"
     | "texture-formats-tier2"
-    | "primitive-index";
+    | "primitive-index"
+    | "texture-component-swizzle";
 type GPUFilterMode =
 
     | "nearest"
@@ -755,7 +756,18 @@ interface GPUCanvasConfiguration {
   /**
    * The tone mapping determines how the content of textures returned by
    * {@link GPUCanvasContext#getCurrentTexture} are to be displayed.
-   * Note: If an implementation doesn't support HDR WebGPU canvases, it should also not expose this member, to allow for feature detection. See {@link GPUCanvasContext#getConfiguration}.
+   * <div class=note heading>
+   * This is a required feature, but user agents might not yet implement it,
+   * effectively supporting only the default {@link GPUCanvasToneMapping}.
+   * In such implementations, this member **should not** exist in its implementation of
+   * {@link GPUCanvasConfiguration}, to make feature detection possible using
+   * {@link GPUCanvasContext#getConfiguration}.
+   * This is especially important in implementations which otherwise have HDR capabilities
+   * (where a <l>'@media/dynamic-range'</l> of <l>''@media/dynamic-range/high''</l> would be
+   * exposed).
+   * If an implementation exposes this member and a `high` dynamic range, it **should** render the
+   * canvas as an HDR element, not clamp values to the SDR range of the HDR display.
+   * </div>
    */
   toneMapping?: GPUCanvasToneMapping;
   /**
@@ -854,7 +866,7 @@ interface GPUCopyExternalImageDestInfo
    * Otherwise, the results are clamped to the target texture format's range.
    * Note:
    * If {@link GPUCopyExternalImageDestInfo#colorSpace} matches the source image,
-   * conversion may not be necessary. See {@link https://www.w3.org/TR/webgpu/#color-space-conversion-elision}.
+   * conversion might not be necessary. See {@link https://www.w3.org/TR/webgpu/#color-space-conversion-elision}.
    */
   colorSpace?: PredefinedColorSpace;
   /**
@@ -865,7 +877,7 @@ interface GPUCopyExternalImageDestInfo
    * corresponding alpha values.
    * Note:
    * If {@link GPUCopyExternalImageDestInfo#premultipliedAlpha} matches the source image,
-   * conversion may not be necessary. See {@link https://www.w3.org/TR/webgpu/#color-space-conversion-elision}.
+   * conversion might not be necessary. See {@link https://www.w3.org/TR/webgpu/#color-space-conversion-elision}.
    */
   premultipliedAlpha?: boolean;
 }
@@ -1769,6 +1781,21 @@ interface GPUTextureViewDescriptor
    * to the texture view.
    */
   arrayLayerCount?: GPUIntegerCoordinate;
+  /**
+   * A string of length four, with each character mapping to the texture view's red/green/blue/alpha
+   * channels, respectively.
+   * When accessed by a shader, the red/green/blue/alpha channels are replaced by the value
+   * corresponding to the component specified in `swizzle[0]`, `swizzle[1]`, `swizzle[2]`, and
+   * `swizzle[3]`, respectively:
+   * - `"r"`: Take its value from the red channel of the texture.
+   * - `"g"`: Take its value from the green channel of the texture.
+   * - `"b"`: Take its value from the blue channel of the texture.
+   * - `"a"`: Take its value from the alpha channel of the texture.
+   * - `"0"`: Force its value to 0.
+   * - `"1"`: Force its value to 1.
+   * Requires the {@link GPUFeatureName} `"texture-component-swizzle"` feature to be enabled.
+   */
+  swizzle?: string;
 }
 
 interface GPUUncapturedErrorEventInit
@@ -2115,6 +2142,7 @@ interface GPUCanvasContext {
   /**
    * Configures the context for this canvas.
    * This clears the drawing buffer to transparent black (in [$Replace the drawing buffer$]).
+   * See {@link GPUCanvasContext#getConfiguration} for information on feature detection.
    * @param configuration - Desired configuration for the context.
    */
   configure(
@@ -2125,7 +2153,11 @@ interface GPUCanvasContext {
    */
   unconfigure(): undefined;
   /**
-   * Returns the context configuration.
+   * Returns the context configuration, or `null` if the context is not configured.
+   * Note:
+   * This method exists primarily for feature detection of members (and sub-members) of
+   * {@link GPUCanvasConfiguration}; see those members for details.
+   * For supported members, it returns the originally-supplied values.
    */
   getConfiguration(): GPUCanvasConfiguration | null;
   /**
@@ -2849,8 +2881,8 @@ interface GPUShaderModule
   readonly __brand: "GPUShaderModule";
   /**
    * Returns any messages generated during the {@link GPUShaderModule}'s compilation.
-   * The locations, order, and contents of messages are implementation-defined
-   * In particular, messages may not be ordered by {@link GPUCompilationMessage#lineNum}.
+   * The locations, order, and contents of messages are implementation-defined.
+   * In particular, messages aren't necessarily ordered by {@link GPUCompilationMessage#lineNum}.
    */
   getCompilationInfo(): Promise<GPUCompilationInfo>;
 }