diff --git a/CHANGELOG.md b/CHANGELOG.md index 92bf8c2c9c..b5888e5a2a 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs index 53f3c2499b..5072a2445d 100644 --- a/wgpu-types/src/lib.rs +++ b/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, 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, 10>` (WGSL)\ + /// `uniform image2D textures[10]` (GLSL) /// /// This capability allows them to exist and to be indexed by dynamically uniform /// values. @@ -345,7 +349,9 @@ 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 buffer_array: array` (WGSL)\ + /// `uniform myBuffer { ... } buffer_array[10]` (GLSL) /// /// This capability allows them to exist and to be indexed by dynamically uniform /// values. @@ -353,7 +359,9 @@ bitflags::bitflags! { /// 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 buffer_array: array` (WGSL)\ + /// `buffer myBuffer { ... } buffer_array[10]` (GLSL) /// /// Supported platforms: /// - DX12 @@ -376,7 +384,7 @@ 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: /// @@ -384,13 +392,13 @@ bitflags::bitflags! { /// /// 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,7 +409,7 @@ 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: /// @@ -409,13 +417,13 @@ bitflags::bitflags! { /// /// 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,7 +2203,7 @@ 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), @@ -2203,7 +2211,7 @@ impl TextureFormat { 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, + /// another_uniform: vec2, + /// } + /// @group(0) @binding(0) + /// var 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 my_element: array>; + /// ``` + /// /// 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 my_element: array>; + /// ``` /// /// 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; + /// ``` + /// /// 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; + /// ``` + /// /// 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; + /// ``` + /// /// 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; + /// ``` /// /// 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; + /// ``` /// /// 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; + /// ``` /// /// 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; + /// ``` + /// /// 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; + /// ``` + /// /// 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: