Skip to content

Commit 29f5f8f

Browse files
anicwfitzgerald
andauthored
Add WGSL examples to documentation (#2888)
Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com>
1 parent 8444fbe commit 29f5f8f

File tree

2 files changed

+132
-29
lines changed

2 files changed

+132
-29
lines changed

CHANGELOG.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,13 +66,16 @@ the same every time it is rendered, we now warn if it is missing.
6666
### Changes
6767

6868
#### General
69+
- Added downlevel restriction error message for `InvalidFormatUsages` error by @Seamooo in [#2886](https://github.com/gfx-rs/wgpu/pull/2886)
6970
- 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)
7071

7172
#### Metal
7273
- Extract the generic code into `get_metal_layer` by @jinleili in [#2826](https://github.com/gfx-rs/wgpu/pull/2826)
7374

75+
### Documentation
76+
7477
#### General
75-
- Added downlevel restriction error message for `InvalidFormatUsages` error by @Seamooo in [#2886](https://github.com/gfx-rs/wgpu/pull/2886)
78+
- Add WGSL examples to complement existing examples written in GLSL by @norepimorphism in [#2888](https://github.com/gfx-rs/wgpu/pull/2888)
7679

7780
### Performance
7881

wgpu-types/src/lib.rs

Lines changed: 128 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -326,12 +326,16 @@ bitflags::bitflags! {
326326
const MAPPABLE_PRIMARY_BUFFERS = 1 << 16;
327327
/// Allows the user to create uniform arrays of textures in shaders:
328328
///
329-
/// eg. `uniform texture2D textures[10]`.
329+
/// ex.
330+
/// `var textures: binding_array<texture_2d<f32>, 10>` (WGSL)\
331+
/// `uniform texture2D textures[10]` (GLSL)
330332
///
331333
/// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
332334
/// may also create uniform arrays of storage textures.
333335
///
334-
/// eg. `uniform image2D textures[10]`.
336+
/// ex.
337+
/// `var textures: array<texture_storage_2d<f32, write>, 10>` (WGSL)\
338+
/// `uniform image2D textures[10]` (GLSL)
335339
///
336340
/// This capability allows them to exist and to be indexed by dynamically uniform
337341
/// values.
@@ -345,15 +349,19 @@ bitflags::bitflags! {
345349
const TEXTURE_BINDING_ARRAY = 1 << 17;
346350
/// Allows the user to create arrays of buffers in shaders:
347351
///
348-
/// eg. `uniform myBuffer { .... } buffer_array[10]`.
352+
/// ex.
353+
/// `var<uniform> buffer_array: array<MyBuffer, 10>` (WGSL)\
354+
/// `uniform myBuffer { ... } buffer_array[10]` (GLSL)
349355
///
350356
/// This capability allows them to exist and to be indexed by dynamically uniform
351357
/// values.
352358
///
353359
/// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
354360
/// may also create arrays of storage buffers.
355361
///
356-
/// eg. `buffer myBuffer { ... } buffer_array[10]`
362+
/// ex.
363+
/// `var<storage> buffer_array: array<MyBuffer, 10>` (WGSL)\
364+
/// `buffer myBuffer { ... } buffer_array[10]` (GLSL)
357365
///
358366
/// Supported platforms:
359367
/// - DX12
@@ -376,21 +384,21 @@ bitflags::bitflags! {
376384
const STORAGE_RESOURCE_BINDING_ARRAY = 1 << 19;
377385
/// Allows shaders to index sampled texture and storage buffer resource arrays with dynamically non-uniform values:
378386
///
379-
/// eg. `texture_array[vertex_data]`
387+
/// ex. `texture_array[vertex_data]`
380388
///
381389
/// In order to use this capability, the corresponding GLSL extension must be enabled like so:
382390
///
383391
/// `#extension GL_EXT_nonuniform_qualifier : require`
384392
///
385393
/// and then used either as `nonuniformEXT` qualifier in variable declaration:
386394
///
387-
/// eg. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
395+
/// ex. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
388396
///
389397
/// or as `nonuniformEXT` constructor:
390398
///
391-
/// eg. `texture_array[nonuniformEXT(vertex_data)]`
399+
/// ex. `texture_array[nonuniformEXT(vertex_data)]`
392400
///
393-
/// HLSL does not need any extension.
401+
/// WGSL and HLSL do not need any extension.
394402
///
395403
/// Supported platforms:
396404
/// - DX12
@@ -401,21 +409,21 @@ bitflags::bitflags! {
401409
const SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING = 1 << 20;
402410
/// Allows shaders to index uniform buffer and storage texture resource arrays with dynamically non-uniform values:
403411
///
404-
/// eg. `texture_array[vertex_data]`
412+
/// ex. `texture_array[vertex_data]`
405413
///
406414
/// In order to use this capability, the corresponding GLSL extension must be enabled like so:
407415
///
408416
/// `#extension GL_EXT_nonuniform_qualifier : require`
409417
///
410418
/// and then used either as `nonuniformEXT` qualifier in variable declaration:
411419
///
412-
/// eg. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
420+
/// ex. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
413421
///
414422
/// or as `nonuniformEXT` constructor:
415423
///
416-
/// eg. `texture_array[nonuniformEXT(vertex_data)]`
424+
/// ex. `texture_array[nonuniformEXT(vertex_data)]`
417425
///
418-
/// HLSL does not need any extension.
426+
/// WGSL and HLSL do not need any extension.
419427
///
420428
/// Supported platforms:
421429
/// - DX12
@@ -1206,22 +1214,22 @@ bitflags_serde_shim::impl_serde_for_bitflags!(ShaderStages);
12061214
#[cfg_attr(feature = "trace", derive(Serialize))]
12071215
#[cfg_attr(feature = "replay", derive(Deserialize))]
12081216
pub enum TextureViewDimension {
1209-
/// A one dimensional texture. `texture1D` in glsl shaders.
1217+
/// A one dimensional texture. `texture_1d` in WGSL and `texture1D` in GLSL.
12101218
#[cfg_attr(feature = "serde", serde(rename = "1d"))]
12111219
D1,
1212-
/// A two dimensional texture. `texture2D` in glsl shaders.
1220+
/// A two dimensional texture. `texture_2d` in WGSL and `texture2D` in GLSL.
12131221
#[cfg_attr(feature = "serde", serde(rename = "2d"))]
12141222
D2,
1215-
/// A two dimensional array texture. `texture2DArray` in glsl shaders.
1223+
/// A two dimensional array texture. `texture_2d_array` in WGSL and `texture2DArray` in GLSL.
12161224
#[cfg_attr(feature = "serde", serde(rename = "2d-array"))]
12171225
D2Array,
1218-
/// A cubemap texture. `textureCube` in glsl shaders.
1226+
/// A cubemap texture. `texture_cube` in WGSL and `textureCube` in GLSL.
12191227
#[cfg_attr(feature = "serde", serde(rename = "cube"))]
12201228
Cube,
1221-
/// A cubemap array texture. `textureCubeArray` in glsl shaders.
1229+
/// A cubemap array texture. `texture_cube_array` in WGSL and `textureCubeArray` in GLSL.
12221230
#[cfg_attr(feature = "serde", serde(rename = "cube-array"))]
12231231
CubeArray,
1224-
/// A three dimensional texture. `texture3D` in glsl shaders.
1232+
/// A three dimensional texture. `texture_3d` in WGSL and `texture3D` in GLSL.
12251233
#[cfg_attr(feature = "serde", serde(rename = "3d"))]
12261234
D3,
12271235
}
@@ -2195,15 +2203,15 @@ impl TextureFormat {
21952203
Self::Rgb10a2Unorm => ( native, float, linear, msaa_resolve, (1, 1), 4, attachment, 4),
21962204
Self::Rg11b10Float => ( native, float, linear, msaa, (1, 1), 4, basic, 3),
21972205

2198-
// Packed 32 bit textures
2206+
// Packed 32 bit textures
21992207
Self::Rg32Uint => ( native, uint, linear, noaa, (1, 1), 8, all_flags, 2),
22002208
Self::Rg32Sint => ( native, sint, linear, noaa, (1, 1), 8, all_flags, 2),
22012209
Self::Rg32Float => ( native, nearest, linear, noaa, (1, 1), 8, all_flags, 2),
22022210
Self::Rgba16Uint => ( native, uint, linear, msaa, (1, 1), 8, all_flags, 4),
22032211
Self::Rgba16Sint => ( native, sint, linear, msaa, (1, 1), 8, all_flags, 4),
22042212
Self::Rgba16Float => ( native, float, linear, msaa_resolve, (1, 1), 8, all_flags, 4),
22052213

2206-
// Packed 32 bit textures
2214+
// Packed 32 bit textures
22072215
Self::Rgba32Uint => ( native, uint, linear, noaa, (1, 1), 16, all_flags, 4),
22082216
Self::Rgba32Sint => ( native, sint, linear, noaa, (1, 1), 16, all_flags, 4),
22092217
Self::Rgba32Float => ( native, nearest, linear, noaa, (1, 1), 16, all_flags, 4),
@@ -2215,7 +2223,7 @@ impl TextureFormat {
22152223
Self::Depth24PlusStencil8 => ( native, depth, linear, msaa, (1, 1), 4, attachment, 2),
22162224
Self::Depth24UnormStencil8 => ( d24_s8, depth, linear, msaa, (1, 1), 4, attachment, 2),
22172225

2218-
// Packed uncompressed
2226+
// Packed uncompressed
22192227
Self::Rgb9e5Ufloat => ( native, float, linear, noaa, (1, 1), 4, basic, 3),
22202228

22212229
// Optional normalized 16-bit-per-channel formats
@@ -3710,6 +3718,16 @@ pub struct ImageDataLayout {
37103718
pub enum BufferBindingType {
37113719
/// A buffer for uniform values.
37123720
///
3721+
/// Example WGSL syntax:
3722+
/// ```rust,ignore
3723+
/// struct Globals {
3724+
/// a_uniform: vec2<f32>,
3725+
/// another_uniform: vec2<f32>,
3726+
/// }
3727+
/// @group(0) @binding(0)
3728+
/// var<uniform> globals: Globals;
3729+
/// ```
3730+
///
37133731
/// Example GLSL syntax:
37143732
/// ```cpp,ignore
37153733
/// layout(std140, binding = 0)
@@ -3721,6 +3739,12 @@ pub enum BufferBindingType {
37213739
Uniform,
37223740
/// A storage buffer.
37233741
///
3742+
/// Example WGSL syntax:
3743+
/// ```rust,ignore
3744+
/// @group(0) @binding(0)
3745+
/// var<storage, read_write> my_element: array<vec4<f32>>;
3746+
/// ```
3747+
///
37243748
/// Example GLSL syntax:
37253749
/// ```cpp,ignore
37263750
/// layout (set=0, binding=0) buffer myStorageBuffer {
@@ -3729,7 +3753,15 @@ pub enum BufferBindingType {
37293753
/// ```
37303754
Storage {
37313755
/// If `true`, the buffer can only be read in the shader,
3732-
/// and it must be annotated with `readonly`.
3756+
/// and it:
3757+
/// - may or may not be annotated with `read` (WGSL).
3758+
/// - must be annotated with `readonly` (GLSL).
3759+
///
3760+
/// Example WGSL syntax:
3761+
/// ```rust,ignore
3762+
/// @group(0) @binding(0)
3763+
/// var<storage, read> my_element: array<vec4<f32>>;
3764+
/// ```
37333765
///
37343766
/// Example GLSL syntax:
37353767
/// ```cpp,ignore
@@ -3757,6 +3789,12 @@ impl Default for BufferBindingType {
37573789
pub enum TextureSampleType {
37583790
/// Sampling returns floats.
37593791
///
3792+
/// Example WGSL syntax:
3793+
/// ```rust,ignore
3794+
/// @group(0) @binding(0)
3795+
/// var t: texure_2d<f32>;
3796+
/// ```
3797+
///
37603798
/// Example GLSL syntax:
37613799
/// ```cpp,ignore
37623800
/// layout(binding = 0)
@@ -3769,6 +3807,12 @@ pub enum TextureSampleType {
37693807
},
37703808
/// Sampling does the depth reference comparison.
37713809
///
3810+
/// Example WGSL syntax:
3811+
/// ```rust,ignore
3812+
/// @group(0) @binding(0)
3813+
/// var t: texture_depth_2d;
3814+
/// ```
3815+
///
37723816
/// Example GLSL syntax:
37733817
/// ```cpp,ignore
37743818
/// layout(binding = 0)
@@ -3777,6 +3821,12 @@ pub enum TextureSampleType {
37773821
Depth,
37783822
/// Sampling returns signed integers.
37793823
///
3824+
/// Example WGSL syntax:
3825+
/// ```rust,ignore
3826+
/// @group(0) @binding(0)
3827+
/// var t: texture_2d<i32>;
3828+
/// ```
3829+
///
37803830
/// Example GLSL syntax:
37813831
/// ```cpp,ignore
37823832
/// layout(binding = 0)
@@ -3785,6 +3835,12 @@ pub enum TextureSampleType {
37853835
Sint,
37863836
/// Sampling returns unsigned integers.
37873837
///
3838+
/// Example WGSL syntax:
3839+
/// ```rust,ignore
3840+
/// @group(0) @binding(0)
3841+
/// var t: texture_2d<u32>;
3842+
/// ```
3843+
///
37883844
/// Example GLSL syntax:
37893845
/// ```cpp,ignore
37903846
/// layout(binding = 0)
@@ -3810,23 +3866,49 @@ impl Default for TextureSampleType {
38103866
#[cfg_attr(feature = "replay", derive(Deserialize))]
38113867
#[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
38123868
pub enum StorageTextureAccess {
3813-
/// The texture can only be written in the shader and it must be annotated with `writeonly`.
3869+
/// The texture can only be written in the shader and it:
3870+
/// - may or may not be annotated with `write` (WGSL).
3871+
/// - must be annotated with `writeonly` (GLSL).
3872+
///
3873+
/// Example WGSL syntax:
3874+
/// ```rust,ignore
3875+
/// @group(0) @binding(0)
3876+
/// var my_storage_image: texture_storage_2d<f32, write>;
3877+
/// ```
38143878
///
38153879
/// Example GLSL syntax:
38163880
/// ```cpp,ignore
38173881
/// layout(set=0, binding=0, r32f) writeonly uniform image2D myStorageImage;
38183882
/// ```
38193883
WriteOnly,
3820-
/// The texture can only be read in the shader and it must be annotated with `readonly`.
3821-
/// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access mode,
3884+
/// The texture can only be read in the shader and it must be annotated with `read` (WGSL) or
3885+
/// `readonly` (GLSL).
3886+
///
3887+
/// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access
3888+
/// mode. This is a native-only extension.
3889+
///
3890+
/// Example WGSL syntax:
3891+
/// ```rust,ignore
3892+
/// @group(0) @binding(0)
3893+
/// var my_storage_image: texture_storage_2d<f32, read>;
3894+
/// ```
38223895
///
38233896
/// Example GLSL syntax:
38243897
/// ```cpp,ignore
38253898
/// layout(set=0, binding=0, r32f) readonly uniform image2D myStorageImage;
38263899
/// ```
38273900
ReadOnly,
3828-
/// The texture can be both read and written in the shader.
3829-
/// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access mode.
3901+
/// The texture can be both read and written in the shader and must be annotated with
3902+
/// `read_write` in WGSL.
3903+
///
3904+
/// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] must be enabled to use this access
3905+
/// mode. This is a nonstandard, native-only extension.
3906+
///
3907+
/// Example WGSL syntax:
3908+
/// ```rust,ignore
3909+
/// @group(0) @binding(0)
3910+
/// var my_storage_image: texture_storage_2d<f32, read_write>;
3911+
/// ```
38303912
///
38313913
/// Example GLSL syntax:
38323914
/// ```cpp,ignore
@@ -3891,6 +3973,12 @@ pub enum BindingType {
38913973
},
38923974
/// A sampler that can be used to sample a texture.
38933975
///
3976+
/// Example WGSL syntax:
3977+
/// ```rust,ignore
3978+
/// @group(0) @binding(0)
3979+
/// var s: sampler;
3980+
/// ```
3981+
///
38943982
/// Example GLSL syntax:
38953983
/// ```cpp,ignore
38963984
/// layout(binding = 0)
@@ -3902,6 +3990,12 @@ pub enum BindingType {
39023990
Sampler(SamplerBindingType),
39033991
/// A texture binding.
39043992
///
3993+
/// Example WGSL syntax:
3994+
/// ```rust,ignore
3995+
/// @group(0) @binding(0)
3996+
/// var t: texture_2d<f32>;
3997+
/// ```
3998+
///
39053999
/// Example GLSL syntax:
39064000
/// ```cpp,ignore
39074001
/// layout(binding = 0)
@@ -3922,9 +4016,15 @@ pub enum BindingType {
39224016
},
39234017
/// A storage texture.
39244018
///
4019+
/// Example WGSL syntax:
4020+
/// ```rust,ignore
4021+
/// @group(0) @binding(0)
4022+
/// var my_storage_image: texture_storage_2d<f32, write>;
4023+
/// ```
4024+
///
39254025
/// Example GLSL syntax:
39264026
/// ```cpp,ignore
3927-
/// layout(set=0, binding=0, r32f) uniform image2D myStorageImage;
4027+
/// layout(set=0, binding=0, r32f) writeonly uniform image2D myStorageImage;
39284028
/// ```
39294029
/// Note that the texture format must be specified in the shader as well.
39304030
/// 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>

0 commit comments

Comments
 (0)