Docs: non-finite float value errors

doc/articles/Errors.md

@@ -16,6 +16,7 @@ These errors include:
 - Enum values which are numerically invalid (this is not possible in JavaScript).
 - Enum values which are require features not enabled on the device (a [content-timeline](https://www.w3.org/TR/webgpu/#content-timeline) error in JavaScript), for example compressed texture formats.
 - Other content-timeline errors where specified.
+- @ref NonFiniteFloatValueError (except when they interrupt Wasm execution)
 
 ### Error Scopes {#ErrorScopes}
 

doc/articles/FloatingPointNumbers.md

@@ -0,0 +1,31 @@
+# Floating-Point Numbers {#FloatingPointNumbers}
+
+## Double-as-Supertype {#DoubleAsSupertype}
+
+Like in the JS API, `double` (aka JavaScript's native `Number` type) is used in several places as a supertype of various numeric values.
+Such a value will be numerically downcast to the appropriate subtype depending how it is used,
+as specified in the JS API spec.
+
+- In @ref WGPUColor, as a supertype of `f32`/`u32`/`i32`
+    - In @ref WGPURenderPassColorAttachment::clearValue, the type depends on the texture format.
+    - In @ref wgpuRenderPassEncoderSetBlendConstant, the type is `f32`.
+- In @ref WGPUConstantEntry::value, as a supertype of all of the overrideable WGSL types
+  (`bool`/`f32`/`u32`/`i32`/`f16` and possibly more).
+    - The type depends on the WGSL type of the constant being overridden.
+
+## Nullable Floating-Point Type {#NullableFloatingPointType}
+
+Floating-point-typed (`float`/`double`) values which are nullable or optional use `NaN` to
+represent the null value. A value `value` represents the null value iff `isnan(value) != 0`.
+(Do not use an equality check with a `NaN` constant, because `NaN == NaN` is false.)
+
+Infinities are invalid. See @ref NonFiniteFloatValueError.
+
+## Non-Finite Float Value Errors {#NonFiniteFloatValueError}
+
+The JavaScript API does not allow non-finite floating-point values (it throws a `TypeError`).
+
+In `webgpu.h`, a value is finite iff `isfinite(value) != 0`.
+Using a non-finite value (aside from `NaN` for a @ref NullableFloatingPointType)
+results in a validation @ref DeviceError, except on Wasm-on-JS targets where a `TypeError`
+thrown by JS **may** be passed unhandled, interrupting Wasm execution.

doc/articles/SentinelValues.md

@@ -43,3 +43,4 @@ WebIDL's more flexible typing:
     - \ref WGPUStorageTextureBindingLayout::access = \ref WGPUStorageTextureAccess_BindingNotUsed
     - \ref WGPURenderPassColorAttachment::view = `NULL`
     - \ref WGPUColorTargetState::format = \ref WGPUTextureFormat_Undefined
+- \ref NullableFloatingPointType

doc/articles/index.md

@@ -2,8 +2,9 @@
 
 - \subpage Asynchronous-Operations
 - \subpage Errors
+- \subpage FloatingPointNumbers
 - \subpage Ownership
-- \subpage Surfaces
 - \subpage SentinelValues
 - \subpage Strings
 - \subpage StructChaining
+- \subpage Surfaces

gen/gen.go

@@ -270,9 +270,9 @@ func (g *Generator) CType(typ string, pointerType PointerType, suffix string) st
 		return appendModifiers("int16_t", pointerType)
 	case "int32":
 		return appendModifiers("int32_t", pointerType)
-	case "float32":
+	case "float32", "nullable_float32":
 		return appendModifiers("float", pointerType)
-	case "float64":
+	case "float64", "float64_supertype":
 		return appendModifiers("double", pointerType)
 	case "c_void":
 		return appendModifiers("void", pointerType)
@@ -571,7 +571,7 @@ func (g *Generator) DefaultValue(member ParameterType, isDocString bool) string
 		} else {
 			return literal(*member.Default)
 		}
-	case member.Type == "float32":
+	case member.Type == "float32" || member.Type == "nullable_float32":
 		if member.Default == nil {
 			return literal("0.f")
 		} else if strings.HasPrefix(*member.Default, "constant.") {
@@ -581,7 +581,7 @@ func (g *Generator) DefaultValue(member ParameterType, isDocString bool) string
 		} else {
 			return literal(*member.Default + ".f")
 		}
-	case member.Type == "float64":
+	case member.Type == "float64" || member.Type == "float64_supertype":
 		if member.Default == nil {
 			return literal("0.")
 		} else if strings.HasPrefix(*member.Default, "constant.") {

schema.json

@@ -45,7 +45,9 @@
                 "int16",
                 "int32",
                 "float32",
+                "nullable_float32",
                 "float64",
+                "float64_supertype",
                 "array<bool>",
                 "array<string>",
                 "array<uint16>",

webgpu.h

@@ -1788,6 +1788,10 @@ typedef struct WGPUBufferDescriptor {
 })
 
 /**
+ * An RGBA color. Represents a `f32`, `i32`, or `u32` color using @ref DoubleAsSupertype.
+ *
+ * If any channel is non-finite, produces a @ref NonFiniteFloatValueError.
+ *
  * Default values can be set using @ref WGPU_COLOR_INIT as initializer.
  */
 typedef struct WGPUColor {
@@ -1931,6 +1935,10 @@ typedef struct WGPUConstantEntry {
      */
     WGPUStringView key;
     /**
+     * Represents a WGSL numeric or boolean value using @ref DoubleAsSupertype.
+     *
+     * If non-finite, produces a @ref NonFiniteFloatValueError.
+     *
      * The `INIT` macro sets this to `0.`.
      */
     double value;
@@ -2500,11 +2508,12 @@ typedef struct WGPURenderPassDepthStencilAttachment {
      */
     WGPUStoreOp depthStoreOp;
     /**
-     * If NaN, indicates an `undefined` value (as defined by the JS spec).
+     * This is a @ref NullableFloatingPointType.
+     *
+     * If `NaN`, indicates an `undefined` value (as defined by the JS spec).
      * Use @ref WGPU_DEPTH_CLEAR_VALUE_UNDEFINED to indicate this semantically.
      *
-     * NaN is determined by `isnan(depthClearValue) != 0`.
-     * (Do not use an equality check, because `NaN == NaN` is false.)
+     * If infinite, produces a @ref NonFiniteFloatValueError.
      *
      * The `INIT` macro sets this to @ref WGPU_DEPTH_CLEAR_VALUE_UNDEFINED.
      */
@@ -2700,10 +2709,18 @@ typedef struct WGPUSamplerDescriptor {
      */
     WGPUMipmapFilterMode mipmapFilter;
     /**
+     * TODO
+     *
+     * If non-finite, produces a @ref NonFiniteFloatValueError.
+     *
      * The `INIT` macro sets this to `0.f`.
      */
     float lodMinClamp;
     /**
+     * TODO
+     *
+     * If non-finite, produces a @ref NonFiniteFloatValueError.
+     *
      * The `INIT` macro sets this to `32.f`.
      */
     float lodMaxClamp;
@@ -3731,10 +3748,18 @@ typedef struct WGPUDepthStencilState {
      */
     int32_t depthBias;
     /**
+     * TODO
+     *
+     * If non-finite, produces a @ref NonFiniteFloatValueError.
+     *
      * The `INIT` macro sets this to `0.f`.
      */
     float depthBiasSlopeScale;
     /**
+     * TODO
+     *
+     * If non-finite, produces a @ref NonFiniteFloatValueError.
+     *
      * The `INIT` macro sets this to `0.f`.
      */
     float depthBiasClamp;
@@ -5893,13 +5918,22 @@ WGPU_EXPORT void wgpuRenderPassEncoderInsertDebugMarker(WGPURenderPassEncoder re
 WGPU_EXPORT void wgpuRenderPassEncoderPopDebugGroup(WGPURenderPassEncoder renderPassEncoder) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderPushDebugGroup(WGPURenderPassEncoder renderPassEncoder, WGPUStringView groupLabel) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderSetBindGroup(WGPURenderPassEncoder renderPassEncoder, uint32_t groupIndex, WGPU_NULLABLE WGPUBindGroup group, size_t dynamicOffsetCount, uint32_t const * dynamicOffsets) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * @param color
+ * The RGBA blend constant. Represents an `f32` color using @ref DoubleAsSupertype.
+ */
 WGPU_EXPORT void wgpuRenderPassEncoderSetBlendConstant(WGPURenderPassEncoder renderPassEncoder, WGPUColor const * color) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderSetIndexBuffer(WGPURenderPassEncoder renderPassEncoder, WGPUBuffer buffer, WGPUIndexFormat format, uint64_t offset, uint64_t size) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderSetLabel(WGPURenderPassEncoder renderPassEncoder, WGPUStringView label) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderSetPipeline(WGPURenderPassEncoder renderPassEncoder, WGPURenderPipeline pipeline) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderSetScissorRect(WGPURenderPassEncoder renderPassEncoder, uint32_t x, uint32_t y, uint32_t width, uint32_t height) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderSetStencilReference(WGPURenderPassEncoder renderPassEncoder, uint32_t reference) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderSetVertexBuffer(WGPURenderPassEncoder renderPassEncoder, uint32_t slot, WGPU_NULLABLE WGPUBuffer buffer, uint64_t offset, uint64_t size) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * TODO
+ *
+ * If any argument is non-finite, produces a @ref NonFiniteFloatValueError.
+ */
 WGPU_EXPORT void wgpuRenderPassEncoderSetViewport(WGPURenderPassEncoder renderPassEncoder, float x, float y, float width, float height, float minDepth, float maxDepth) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderAddRef(WGPURenderPassEncoder renderPassEncoder) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuRenderPassEncoderRelease(WGPURenderPassEncoder renderPassEncoder) WGPU_FUNCTION_ATTRIBUTE;

webgpu.yml

@@ -1752,25 +1752,23 @@ structs:
         default: false
   - name: color
     doc: |
-      TODO
+      An RGBA color. Represents a `f32`, `i32`, or `u32` color using @ref DoubleAsSupertype.
+
+      If any channel is non-finite, produces a @ref NonFiniteFloatValueError.
     type: standalone
     members:
       - name: r
-        doc: |
-          TODO
-        type: float64
+        doc: ""
+        type: float64_supertype
       - name: g
-        doc: |
-          TODO
-        type: float64
+        doc: ""
+        type: float64_supertype
       - name: b
-        doc: |
-          TODO
-        type: float64
+        doc: ""
+        type: float64_supertype
       - name: a
-        doc: |
-          TODO
-        type: float64
+        doc: ""
+        type: float64_supertype
   - name: color_target_state
     doc: |
       TODO
@@ -1913,8 +1911,10 @@ structs:
         type: string_with_default_empty
       - name: value
         doc: |
-          TODO
-        type: float64
+          Represents a WGSL numeric or boolean value using @ref DoubleAsSupertype.
+
+          If non-finite, produces a @ref NonFiniteFloatValueError.
+        type: float64_supertype
   - name: depth_stencil_state
     doc: |
       TODO
@@ -1959,11 +1959,15 @@ structs:
       - name: depth_bias_slope_scale
         doc: |
           TODO
+
+          If non-finite, produces a @ref NonFiniteFloatValueError.
         type: float32
         default: 0.0
       - name: depth_bias_clamp
         doc: |
           TODO
+
+          If non-finite, produces a @ref NonFiniteFloatValueError.
         type: float32
         default: 0.0
   - name: device_descriptor
@@ -2465,12 +2469,13 @@ structs:
         default: undefined
       - name: depth_clear_value
         doc: |
-          If NaN, indicates an `undefined` value (as defined by the JS spec).
+          This is a @ref NullableFloatingPointType.
+
+          If `NaN`, indicates an `undefined` value (as defined by the JS spec).
           Use @ref WGPU_DEPTH_CLEAR_VALUE_UNDEFINED to indicate this semantically.
 
-          NaN is determined by `isnan(depthClearValue) != 0`.
-          (Do not use an equality check, because `NaN == NaN` is false.)
-        type: float32
+          If infinite, produces a @ref NonFiniteFloatValueError.
+        type: nullable_float32
         default: constant.depth_clear_value_undefined
       - name: depth_read_only
         doc: |
@@ -2674,11 +2679,15 @@ structs:
       - name: lod_min_clamp
         doc: |
           TODO
+
+          If non-finite, produces a @ref NonFiniteFloatValueError.
         type: float32
         default: 0.0
       - name: lod_max_clamp
         doc: |
           TODO
+
+          If non-finite, produces a @ref NonFiniteFloatValueError.
         type: float32
         default: 32.0
       - name: compare
@@ -4751,12 +4760,14 @@ objects:
         args:
           - name: color
             doc: |
-              TODO
+              The RGBA blend constant. Represents an `f32` color using @ref DoubleAsSupertype.
             type: struct.color
             pointer: immutable
       - name: set_viewport
         doc: |
           TODO
+
+          If any argument is non-finite, produces a @ref NonFiniteFloatValueError.
         args:
           - name: x
             doc: |