github/wgpu
1
1
Fork 0
mirror of https://github.com/gfx-rs/wgpu.git synced 2026-04-22 03:02:01 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add WGSL examples to documentation (#2888)

Browse Source 
Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com>
This commit is contained in:
ani
2022-08-02 19:24:10 +00:00
committed by GitHub
parent 8444fbe460
commit 29f5f8f60e
2 changed files with 132 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
CHANGELOG.md
View File

@@ -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

156
wgpu-types/src/lib.rs
View File

@@ -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,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<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.
@@ -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<storage> buffer_array: array<MyBuffer, 10>` (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<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>