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

Signed-off-by: Stephen Gutekanst <stephen@hexops.com>

gpu/README.md

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

gpu/src/main.zig

@@ -1,10 +1,10 @@
 const std = @import("std");
 
-pub const array_layer_count_undefined = 0xffffffff;
-pub const copy_stride_undefined = 0xffffffff;
-pub const limit_u32_undefined = 0xffffffff;
-pub const limit_u64_undefined = 0xffffffffffffffff;
-pub const mip_level_count_undefined = 0xffffffff;
+pub const array_layer_count_undef = 0xffffffff;
+pub const copy_stride_undef = 0xffffffff;
+pub const limit_u32_undef = 0xffffffff;
+pub const limit_u64_undef = 0xffffffffffffffff;
+pub const mip_level_count_undef = 0xffffffff;
 pub const whole_map_size = std.math.maxInt(usize);
 pub const whole_size = 0xffffffffffffffff;
 

gpu/src/texture.zig

@@ -3,7 +3,7 @@ const ChainedStruct = @import("types.zig").ChainedStruct;
 const TextureView = @import("texture_view.zig").TextureView;
 const Extent3D = @import("types.zig").Extent3D;
 const Impl = @import("interface.zig").Impl;
-const copy_stride_undefined = @import("main.zig").copy_stride_undefined;
+const copy_stride_undef = @import("main.zig").copy_stride_undef;
 
 pub const Texture = opaque {
     pub const Aspect = enum(u32) {
@@ -169,8 +169,8 @@ pub const Texture = opaque {
     pub const DataLayout = extern struct {
         next_in_chain: ?*const ChainedStruct = null,
         offset: u64 = 0,
-        bytes_per_row: u32 = copy_stride_undefined,
-        rows_per_image: u32 = copy_stride_undefined,
+        bytes_per_row: u32 = copy_stride_undef,
+        rows_per_image: u32 = copy_stride_undef,
     };
 
     pub const Descriptor = extern struct {

gpu/src/texture_view.zig

@@ -1,8 +1,8 @@
 const ChainedStruct = @import("types.zig").ChainedStruct;
 const Texture = @import("texture.zig").Texture;
 const Impl = @import("interface.zig").Impl;
-const mip_level_count_undefined = @import("main.zig").mip_level_count_undefined;
-const array_layer_count_undefined = @import("main.zig").array_layer_count_undefined;
+const mip_level_count_undef = @import("main.zig").mip_level_count_undef;
+const array_layer_count_undef = @import("main.zig").array_layer_count_undef;
 
 pub const TextureView = opaque {
     pub const Dimension = enum(u32) {
@@ -21,9 +21,9 @@ pub const TextureView = opaque {
         format: Texture.Format = .undef,
         dimension: Dimension = .dimension_undef,
         base_mip_level: u32 = 0,
-        mip_level_count: u32 = mip_level_count_undefined,
+        mip_level_count: u32 = mip_level_count_undef,
         base_array_layer: u32 = 0,
-        array_layer_count: u32 = array_layer_count_undefined,
+        array_layer_count: u32 = array_layer_count_undef,
         aspect: Texture.Aspect = .all,
     };
 

gpu/src/types.zig

@@ -4,8 +4,8 @@ const Texture = @import("texture.zig").Texture;
 const TextureView = @import("texture_view.zig").TextureView;
 const Buffer = @import("buffer.zig").Buffer;
 const ShaderModule = @import("shader_module.zig").ShaderModule;
-const limit_u32_undefined = @import("main.zig").limit_u32_undefined;
-const limit_u64_undefined = @import("main.zig").limit_u64_undefined;
+const limit_u32_undef = @import("main.zig").limit_u32_undef;
+const limit_u64_undef = @import("main.zig").limit_u64_undef;
 
 pub const AlphaMode = enum(u32) {
     premultiplied = 0x00000000,
@@ -400,34 +400,34 @@ pub const Extent3D = extern struct {
 };
 
 pub const Limits = extern struct {
-    max_texture_dimension_1d: u32 = limit_u32_undefined,
-    max_texture_dimension_2d: u32 = limit_u32_undefined,
-    max_texture_dimension_3d: u32 = limit_u32_undefined,
-    max_texture_array_layers: u32 = limit_u32_undefined,
-    max_bind_groups: u32 = limit_u32_undefined,
-    max_dynamic_uniform_buffers_per_pipeline_layout: u32 = limit_u32_undefined,
-    max_dynamic_storage_buffers_per_pipeline_layout: u32 = limit_u32_undefined,
-    max_sampled_textures_per_shader_stage: u32 = limit_u32_undefined,
-    max_samplers_per_shader_stage: u32 = limit_u32_undefined,
-    max_storage_buffers_per_shader_stage: u32 = limit_u32_undefined,
-    max_storage_textures_per_shader_stage: u32 = limit_u32_undefined,
-    max_uniform_buffers_per_shader_stage: u32 = limit_u32_undefined,
-    max_uniform_buffer_binding_size: u64 = limit_u64_undefined,
-    max_storage_buffer_binding_size: u64 = limit_u64_undefined,
-    min_uniform_buffer_offset_alignment: u32 = limit_u32_undefined,
-    min_storage_buffer_offset_alignment: u32 = limit_u32_undefined,
-    max_vertex_buffers: u32 = limit_u32_undefined,
-    max_vertex_attributes: u32 = limit_u32_undefined,
-    max_vertex_buffer_array_stride: u32 = limit_u32_undefined,
-    max_inter_stage_shader_components: u32 = limit_u32_undefined,
-    max_inter_stage_shader_variables: u32 = limit_u32_undefined,
-    max_color_attachments: u32 = limit_u32_undefined,
-    max_compute_workgroup_storage_size: u32 = limit_u32_undefined,
-    max_compute_invocations_per_workgroup: u32 = limit_u32_undefined,
-    max_compute_workgroup_size_x: u32 = limit_u32_undefined,
-    max_compute_workgroup_size_y: u32 = limit_u32_undefined,
-    max_compute_workgroup_size_z: u32 = limit_u32_undefined,
-    max_compute_workgroups_per_dimension: u32 = limit_u32_undefined,
+    max_texture_dimension_1d: u32 = limit_u32_undef,
+    max_texture_dimension_2d: u32 = limit_u32_undef,
+    max_texture_dimension_3d: u32 = limit_u32_undef,
+    max_texture_array_layers: u32 = limit_u32_undef,
+    max_bind_groups: u32 = limit_u32_undef,
+    max_dynamic_uniform_buffers_per_pipeline_layout: u32 = limit_u32_undef,
+    max_dynamic_storage_buffers_per_pipeline_layout: u32 = limit_u32_undef,
+    max_sampled_textures_per_shader_stage: u32 = limit_u32_undef,
+    max_samplers_per_shader_stage: u32 = limit_u32_undef,
+    max_storage_buffers_per_shader_stage: u32 = limit_u32_undef,
+    max_storage_textures_per_shader_stage: u32 = limit_u32_undef,
+    max_uniform_buffers_per_shader_stage: u32 = limit_u32_undef,
+    max_uniform_buffer_binding_size: u64 = limit_u64_undef,
+    max_storage_buffer_binding_size: u64 = limit_u64_undef,
+    min_uniform_buffer_offset_alignment: u32 = limit_u32_undef,
+    min_storage_buffer_offset_alignment: u32 = limit_u32_undef,
+    max_vertex_buffers: u32 = limit_u32_undef,
+    max_vertex_attributes: u32 = limit_u32_undef,
+    max_vertex_buffer_array_stride: u32 = limit_u32_undef,
+    max_inter_stage_shader_components: u32 = limit_u32_undef,
+    max_inter_stage_shader_variables: u32 = limit_u32_undef,
+    max_color_attachments: u32 = limit_u32_undef,
+    max_compute_workgroup_storage_size: u32 = limit_u32_undef,
+    max_compute_invocations_per_workgroup: u32 = limit_u32_undef,
+    max_compute_workgroup_size_x: u32 = limit_u32_undef,
+    max_compute_workgroup_size_y: u32 = limit_u32_undef,
+    max_compute_workgroup_size_z: u32 = limit_u32_undef,
+    max_compute_workgroups_per_dimension: u32 = limit_u32_undef,
 };
 
 pub const Origin3D = extern struct {