diff --git a/gpu/README.md b/gpu/README.md index 06d0dc01..aff2d969 100644 --- a/gpu/README.md +++ b/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 diff --git a/gpu/src/main.zig b/gpu/src/main.zig index f22665af..decbd247 100644 --- a/gpu/src/main.zig +++ b/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; diff --git a/gpu/src/texture.zig b/gpu/src/texture.zig index d28214d9..b9b74118 100644 --- a/gpu/src/texture.zig +++ b/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 { diff --git a/gpu/src/texture_view.zig b/gpu/src/texture_view.zig index fa380cb7..0f448c04 100644 --- a/gpu/src/texture_view.zig +++ b/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, }; diff --git a/gpu/src/types.zig b/gpu/src/types.zig index 6c5b177b..43a8d974 100644 --- a/gpu/src/types.zig +++ b/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 {