zig/mach
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

gpu: fix confusing terminology conflict between WebGPU vs. Zig "undefined"

Browse source 
Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
This commit is contained in:
Stephen Gutekanst 2022-07-30 04:39:36 -07:00 • committed by Stephen Gutekanst
parent fa96792168
commit 75a09c7828
5 changed files with 49 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

7
gpu/README.md
View file

@ -114,6 +114,7 @@ The rules for translating `webgpu.h` are as follows:
* `null` -> `nul`
* `error` -> `err`
* `type` -> `typ`
* Undefined in Zig commonly means _undefined memory_. WebGPU however uses _undefined_ as terminology to indicate something was not _specified_, as the optional _none value_, which Zig represents as _null_. Since _null_ is a reserved keyword in Zig, we rename all WebGPU _undefined_ terminology to "_unspecified_" instead.
* Constant names map using a few simple rules, but it's easiest to describe them with some concrete examples:
* `RG11B10Ufloat -> rg11_b10_ufloat`
* `Depth24PlusStencil8 -> depth24_plus_stencil8`
@ -123,6 +124,12 @@ The rules for translating `webgpu.h` are as follows:
* `maxTextureDimension3D -> max_texture_dimension_3d`
* Sometimes an enum will begin with numbers, e.g. `WGPUTextureViewDimension_2DArray`. In this case, we add a prefix so instead of the enum field being `2d_array` it is `dimension_2d_array` (an enum field name must not start with a number in Zig.)
* Dawn extension types `WGPUDawnFoobar` are placed under `gpu.dawn.Foobar`
* Regarding _"undefined"_ terminology:
* In Zig, _undefined_ usually means _undefined memory_, _undefined behavior_, etc.
* In WebGPU, _undefined_ commonly refers to JS-style undefined: _an optional value that was not specified_
* Zig refers to optional values not specified as _null_, but _null_ is a reserved keyword and so can't be used.
* We could use "_none_", but "BindingType none" and "BindingType not specified" clearly have non-equal meanings.
* As a result of all this, we translate _"undefined"_ in WebGPU to "undef" in Zig: it has no overlap with the reserved _undefined_ keyword, and distinguishes its meaning.
### Quality of life improvements