Add WGSL examples to documentation (#2888)

Co-authored-by: Connor Fitzgerald <[email protected]>

CHANGELOG.md

@@ -66,13 +66,16 @@ the same every time it is rendered, we now warn if it is missing.
 ### Changes
 
 #### General
+- Added downlevel restriction error message for `InvalidFormatUsages` error by @Seamooo in [#2886](https://github.com/gfx-rs/wgpu/pull/2886)
 - Add warning when using CompareFunction::*Equal with vertex shader that is missing @invariant tag by @cwfitzgerald in [#2887](https://github.com/gfx-rs/wgpu/pull/2887)
 
 #### Metal
 - Extract the generic code into `get_metal_layer` by @jinleili in [#2826](https://github.com/gfx-rs/wgpu/pull/2826)
 
+### Documentation
+
 #### General
-- Added downlevel restriction error message for `InvalidFormatUsages` error by @Seamooo in [#2886](https://github.com/gfx-rs/wgpu/pull/2886)
+- Add WGSL examples to complement existing examples written in GLSL by @norepimorphism in [#2888](https://github.com/gfx-rs/wgpu/pull/2888)
 
 ### Performance
 

wgpu-types/src/lib.rs

@@ -326,12 +326,16 @@ bitflags::bitflags! {
         const MAPPABLE_PRIMARY_BUFFERS = 1 << 16;
         /// Allows the user to create uniform arrays of textures in shaders:
         ///
-        /// eg. `uniform texture2D textures[10]`.
+        /// ex.
+        /// `var textures: binding_array<texture_2d<f32>, 10>` (WGSL)\
+        /// `uniform texture2D textures[10]` (GLSL)
         ///
         /// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
         /// may also create uniform arrays of storage textures.
         ///
-        /// eg. `uniform image2D textures[10]`.
+        /// ex.
+        /// `var textures: array<texture_storage_2d<f32, write>, 10>` (WGSL)\
+        /// `uniform image2D textures[10]` (GLSL)
         ///
         /// This capability allows them to exist and to be indexed by dynamically uniform
         /// values.
@@ -345,15 +349,19 @@ bitflags::bitflags! {
         const TEXTURE_BINDING_ARRAY = 1 << 17;
         /// Allows the user to create arrays of buffers in shaders:
         ///
-        /// eg. `uniform myBuffer { .... } buffer_array[10]`.
+        /// ex.
+        /// `var<uniform> buffer_array: array<MyBuffer, 10>` (WGSL)\
+        /// `uniform myBuffer { ... } buffer_array[10]` (GLSL)
         ///
         /// This capability allows them to exist and to be indexed by dynamically uniform
         /// values.
         ///
         /// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
         /// may also create arrays of storage buffers.
         ///
-        /// eg. `buffer myBuffer { ... } buffer_array[10]`
+        /// ex.
+        /// `var<storage> buffer_array: array<MyBuffer, 10>` (WGSL)\
+        /// `buffer myBuffer { ... } buffer_array[10]` (GLSL)
         ///
         /// Supported platforms:
         /// - DX12
@@ -376,21 +384,21 @@ bitflags::bitflags! {
         const STORAGE_RESOURCE_BINDING_ARRAY = 1 << 19;
         /// Allows shaders to index sampled texture and storage buffer resource arrays with dynamically non-uniform values:
         ///
-        /// eg. `texture_array[vertex_data]`
+        /// ex. `texture_array[vertex_data]`
         ///
         /// In order to use this capability, the corresponding GLSL extension must be enabled like so:
         ///
         /// `#extension GL_EXT_nonuniform_qualifier : require`
         ///
         /// and then used either as `nonuniformEXT` qualifier in variable declaration:
         ///
-        /// eg. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
+        /// ex. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
         ///
         /// or as `nonuniformEXT` constructor:
         ///
-        /// eg. `texture_array[nonuniformEXT(vertex_data)]`
+        /// ex. `texture_array[nonuniformEXT(vertex_data)]`
         ///
-        /// HLSL does not need any extension.
+        /// WGSL and HLSL do not need any extension.
         ///
         /// Supported platforms:
         /// - DX12
@@ -401,21 +409,21 @@ bitflags::bitflags! {
         const SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING = 1 << 20;
         /// Allows shaders to index uniform buffer and storage texture resource arrays with dynamically non-uniform values:
         ///
-        /// eg. `texture_array[vertex_data]`
+        /// ex. `texture_array[vertex_data]`
         ///
         /// In order to use this capability, the corresponding GLSL extension must be enabled like so:
         ///
         /// `#extension GL_EXT_nonuniform_qualifier : require`
         ///
         /// and then used either as `nonuniformEXT` qualifier in variable declaration:
         ///
-        /// eg. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
+        /// ex. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
         ///
         /// or as `nonuniformEXT` constructor:
         ///
-        /// eg. `texture_array[nonuniformEXT(vertex_data)]`
+        /// ex. `texture_array[nonuniformEXT(vertex_data)]`
         ///
-        /// HLSL does not need any extension.
+        /// WGSL and HLSL do not need any extension.
         ///
         /// Supported platforms:
         /// - DX12
@@ -1206,22 +1214,22 @@ bitflags_serde_shim::impl_serde_for_bitflags!(ShaderStages);
 #[cfg_attr(feature = "trace", derive(Serialize))]
 #[cfg_attr(feature = "replay", derive(Deserialize))]
 pub enum TextureViewDimension {
-    /// A one dimensional texture. `texture1D` in glsl shaders.
+    /// A one dimensional texture. `texture_1d` in WGSL and `texture1D` in GLSL.
     #[cfg_attr(feature = "serde", serde(rename = "1d"))]
     D1,
-    /// A two dimensional texture. `texture2D` in glsl shaders.
+    /// A two dimensional texture. `texture_2d` in WGSL and `texture2D` in GLSL.
     #[cfg_attr(feature = "serde", serde(rename = "2d"))]
     D2,
-    /// A two dimensional array texture. `texture2DArray` in glsl shaders.
+    /// A two dimensional array texture. `texture_2d_array` in WGSL and `texture2DArray` in GLSL.
     #[cfg_attr(feature = "serde", serde(rename = "2d-array"))]
     D2Array,
-    /// A cubemap texture. `textureCube` in glsl shaders.
+    /// A cubemap texture. `texture_cube` in WGSL and `textureCube` in GLSL.
     #[cfg_attr(feature = "serde", serde(rename = "cube"))]
     Cube,
-    /// A cubemap array texture. `textureCubeArray` in glsl shaders.
+    /// A cubemap array texture. `texture_cube_array` in WGSL and `textureCubeArray` in GLSL.
     #[cfg_attr(feature = "serde", serde(rename = "cube-array"))]
     CubeArray,
-    /// A three dimensional texture. `texture3D` in glsl shaders.
+    /// A three dimensional texture. `texture_3d` in WGSL and `texture3D` in GLSL.
     #[cfg_attr(feature = "serde", serde(rename = "3d"))]
     D3,
 }
@@ -2195,15 +2203,15 @@ impl TextureFormat {
             Self::Rgb10a2Unorm =>        (   native,   float,    linear, msaa_resolve, (1, 1),  4, attachment, 4),
             Self::Rg11b10Float =>        (   native,   float,    linear,         msaa, (1, 1),  4,      basic, 3),
 
-            // Packed 32 bit textures  
+            // Packed 32 bit textures
             Self::Rg32Uint =>            (   native,    uint,    linear,         noaa, (1, 1),  8,  all_flags, 2),
             Self::Rg32Sint =>            (   native,    sint,    linear,         noaa, (1, 1),  8,  all_flags, 2),
             Self::Rg32Float =>           (   native, nearest,    linear,         noaa, (1, 1),  8,  all_flags, 2),
             Self::Rgba16Uint =>          (   native,    uint,    linear,         msaa, (1, 1),  8,  all_flags, 4),
             Self::Rgba16Sint =>          (   native,    sint,    linear,         msaa, (1, 1),  8,  all_flags, 4),
             Self::Rgba16Float =>         (   native,   float,    linear, msaa_resolve, (1, 1),  8,  all_flags, 4),
 
-            // Packed 32 bit textures  
+            // Packed 32 bit textures
             Self::Rgba32Uint =>          (   native,    uint,    linear,         noaa, (1, 1), 16,  all_flags, 4),
             Self::Rgba32Sint =>          (   native,    sint,    linear,         noaa, (1, 1), 16,  all_flags, 4),
             Self::Rgba32Float =>         (   native, nearest,    linear,         noaa, (1, 1), 16,  all_flags, 4),
@@ -2215,7 +2223,7 @@ impl TextureFormat {
             Self::Depth24PlusStencil8 => (   native,   depth,    linear,         msaa, (1, 1),  4, attachment, 2),
             Self::Depth24UnormStencil8 => (  d24_s8,   depth,    linear,         msaa, (1, 1),  4, attachment, 2),
 
-            // Packed uncompressed  
+            // Packed uncompressed
             Self::Rgb9e5Ufloat =>        (   native,   float,    linear,         noaa, (1, 1),  4,      basic, 3),
 
             // Optional normalized 16-bit-per-channel formats
@@ -3710,6 +3718,16 @@ pub struct ImageDataLayout {
 pub enum BufferBindingType {
     /// A buffer for uniform values.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// struct Globals {
+    ///     a_uniform: vec2<f32>,
+    ///     another_uniform: vec2<f32>,
+    /// }
+    /// @group(0) @binding(0)
+    /// var<uniform> globals: Globals;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(std140, binding = 0)
@@ -3721,6 +3739,12 @@ pub enum BufferBindingType {
     Uniform,
     /// A storage buffer.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var<storage, read_write> my_element: array<vec4<f32>>;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout (set=0, binding=0) buffer myStorageBuffer {
@@ -3729,7 +3753,15 @@ pub enum BufferBindingType {
     /// ```
     Storage {
         /// If `true`, the buffer can only be read in the shader,
-        /// and it must be annotated with `readonly`.
+        /// and it:
+        /// - may or may not be annotated with `read` (WGSL).
+        /// - must be annotated with `readonly` (GLSL).
+        ///
+        /// Example WGSL syntax:
+        /// ```rust,ignore
+        /// @group(0) @binding(0)
+        /// var<storage, read> my_element: array<vec4<f32>>;
+        /// ```
         ///
         /// Example GLSL syntax:
         /// ```cpp,ignore
@@ -3757,6 +3789,12 @@ impl Default for BufferBindingType {
 pub enum TextureSampleType {
     /// Sampling returns floats.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var t: texure_2d<f32>;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(binding = 0)
@@ -3769,6 +3807,12 @@ pub enum TextureSampleType {
     },
     /// Sampling does the depth reference comparison.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var t: texture_depth_2d;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(binding = 0)
@@ -3777,6 +3821,12 @@ pub enum TextureSampleType {
     Depth,
     /// Sampling returns signed integers.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var t: texture_2d<i32>;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(binding = 0)
@@ -3785,6 +3835,12 @@ pub enum TextureSampleType {
     Sint,
     /// Sampling returns unsigned integers.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var t: texture_2d<u32>;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(binding = 0)
@@ -3810,23 +3866,49 @@ impl Default for TextureSampleType {
 #[cfg_attr(feature = "replay", derive(Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
 pub enum StorageTextureAccess {
-    /// The texture can only be written in the shader and it must be annotated with `writeonly`.
+    /// The texture can only be written in the shader and it:
+    /// - may or may not be annotated with `write` (WGSL).
+    /// - must be annotated with `writeonly` (GLSL).
+    ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var my_storage_image: texture_storage_2d<f32, write>;
+    /// ```
     ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(set=0, binding=0, r32f) writeonly uniform image2D myStorageImage;
     /// ```
     WriteOnly,
-    /// The texture can only be read in the shader and it must be annotated with `readonly`.
-    /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access mode,
+    /// The texture can only be read in the shader and it must be annotated with `read` (WGSL) or
+    /// `readonly` (GLSL).
+    ///
+    /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access
+    /// mode. This is a native-only extension.
+    ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var my_storage_image: texture_storage_2d<f32, read>;
+    /// ```
     ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(set=0, binding=0, r32f) readonly uniform image2D myStorageImage;
     /// ```
     ReadOnly,
-    /// The texture can be both read and written in the shader.
-    /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access mode.
+    /// The texture can be both read and written in the shader and must be annotated with
+    /// `read_write` in WGSL.
+    ///
+    /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access
+    /// mode.  This is a nonstandard, native-only extension.
+    ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var my_storage_image: texture_storage_2d<f32, read_write>;
+    /// ```
     ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
@@ -3891,6 +3973,12 @@ pub enum BindingType {
     },
     /// A sampler that can be used to sample a texture.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var s: sampler;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(binding = 0)
@@ -3902,6 +3990,12 @@ pub enum BindingType {
     Sampler(SamplerBindingType),
     /// A texture binding.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var t: texture_2d<f32>;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
     /// layout(binding = 0)
@@ -3922,9 +4016,15 @@ pub enum BindingType {
     },
     /// A storage texture.
     ///
+    /// Example WGSL syntax:
+    /// ```rust,ignore
+    /// @group(0) @binding(0)
+    /// var my_storage_image: texture_storage_2d<f32, write>;
+    /// ```
+    ///
     /// Example GLSL syntax:
     /// ```cpp,ignore
-    /// layout(set=0, binding=0, r32f) uniform image2D myStorageImage;
+    /// layout(set=0, binding=0, r32f) writeonly uniform image2D myStorageImage;
     /// ```
     /// Note that the texture format must be specified in the shader as well.
     /// A list of valid formats can be found in the specification here: <https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.60.html#layout-qualifiers>