Add WGSL examples to documentation

[ghost]

Checklist

• Run cargo clippy.
• Run RUSTFLAGS=--cfg=web_sys_unstable_apis cargo clippy --target wasm32-unknown-unknown if applicable.
• Add change to CHANGELOG.md. See simple instructions inside file.
• Add Features example(s).
• Add BufferBindingType example(s).
• Add BindingType example(s).
• Add StorageTextureAccess example(s).
• Add TextureSampleType example(s).
• Add TextureViewDimension example(s).

Connections
Partly addresses #2849.

Description
Adds WGSL examples to wgpu documentation to complement the existing examples written in GLSL.

Testing
Run cargo doc to observe that the documentation is updated, and compile the WGSL examples (e.g. with naga) to confirm they are valid.

[ghost]

Hm. Comparing the WGSL and GLSL specs, it seems that WGSL is far more restrictive than GLSL in terms of access modes. For example, according to this table, I don't think it's possible to define a read-write or write-only uniform, texture, or sampler. However, I see no such restrictions in this rather minimal explanation of access modes offered by the GLSL spec.

If my understanding is correct, then some documentation items may be necessarily devoid of a WGSL example due to the limitations of the language. In particular, I think this is the case with StorageTextureAccess::WriteOnly and StorageTextureAccess::ReadWrite.

[ghost]

I have added explicit readonly annotations to some of the GLSL examples. This is because I do not want to harbor any confusion regarding WGSL vs. GLSL access modes. GLSL is read-write by default in all address spaces and, as explained in a previous comment above, some WGSL address spaces only allow read-only. Thus, for WGSL variables declared in such read-only address spaces, I have added readonly to the GLSL example such that the two examples are semantically identical.
readonly is unnecessary because, while GLSL is technically read-write by default, this is (presumably) automagically coerced to readonly for uniforms.

[cwfitzgerald]

GLSL may allow you to put the keywords there, but uniform buffers, textures, and samplers are always read-only, there is no way to actually write to them. In those examples, I think it's perfectly fine to do normal wgsl declarations.

We offer read-write and read storage texture support as a native extension, so using a wgsl example (using the extension) is totally fine.

[ghost]

GLSL may allow you to put the keywords there, but uniform buffers, textures, and samplers are always read-only, there is no way to actually write to them. In those examples, I think it's perfectly fine to do normal wgsl declarations.

Ah. I will remove the explicit readonly annotations then because it should be read-only for both WGSL and GLSL.

We offer read-write and read storage texture support as a native extension, so using a wgsl example (using the extension) is totally fine.

Hm. naga accepts that? I don't think the WGSL syntax technically permits that, even if it is possible hardware-wise. Should it be noted somewhere that that's not an official WGSL extension (the only one I see is f16 support) but is supported by wgpu/naga?

[ghost]

As an aside: I think some of my confusion arose from storage textures, as defined by the WGSL spec, being write-only, but their handles being read-only. Apparently there is an issue to clarify this already: gpuweb/gpuweb#3047.

[cwfitzgerald]

Should it be noted somewhere that that's not an official WGSL extension (the only one I see is f16 support) but is supported by wgpu/naga?

Wouldn't hurt, though we already do this to an extent by separating "native" and "webgpu" extensions.

[cwfitzgerald]

By and large looks great, thank you! Some nits

[cwfitzgerald]

Thanks!

[ghost]

It seems rustfmt does not like the two trailing spaces after 'ex.'. I'm not sure which lint is causing that, but we could replace the double-space line breaks with backslashes to escape the newline.

[cwfitzgerald]

Yeah that would work - sorry for the delay in responding.