webgpu-headers

Callback-based APIs in webgpu-native behave similarly to Promise-returning APIs in JavaScript. Instead of separate resolve/reject callbacks, a single callback is used which receives a status code.

• Success: A valid result is returned with an empty message string (represented as {NULL, 0}).
• Failure: An invalid result is returned with a non-empty message string.

The C API and its documentation are driven by two machine-readable files: webgpu.yml and webgpu.json (which contain the same data in different formats).

These files serve as the single source of truth for:

1. Generating the official webgpu.h header.
2. Generating the official documentation.
3. Providing data for third-party tools and language bindings (e.g., creating wrappers for other programming languages).

If you are building language bindings and require additional high-level or semantic information to be available in these files, you can contribute to the project to include that data in webgpu.yml.

Releasing the last external reference to a WGPUDevice triggers automatic destruction if the device is not already lost or destroyed.

Effects of releasing the last ref:

1. It sets a flag on the DeviceLost future to pass a null WGPUDevice to the callback.
2. It calls wgpuDeviceDestroy(), which triggers the DeviceLost event.
3. It decrements the refcount to 0.

Destruction side-effects: Even if you release the last ref instead of calling wgpuDeviceDestroy() explicitly, the following will occur:

• All buffers on the device are destroyed (unmapped and pending map requests aborted).
• The device is lost, triggering the DeviceLost event.

Note on Callbacks: Because the last ref is gone, any DeviceLost callback triggered this way will receive a null pointer for the device.

Following the JavaScript API specification, the double type (equivalent to JS Number) is used as a supertype for various numeric subtypes. The actual numeric type used is determined by the context of the operation.

Key usage patterns include:

• WGPUColor: Acts as a supertype for f32, u32, or i32. For example, in WGPURenderPassColorAttachment::clearValue, the specific type depends on the texture format. In wgpuRenderPassEncoderSetBlendConstant, the type is f32.
• WGPUConstantEntry::value: Acts as a supertype for all overrideable WGSL types (such as bool, f32, u32, i32, f16, etc.). The specific type depends on the WGSL type of the constant being overridden.

An Output String is always explicitly sized and is never null.

Key characteristics:

• There is no guaranteed null terminator inside the string (there may or may not be one after the end).
• If the string is empty, the data pointer may or may not be null.

Formatting with printf: Because these strings are explicitly sized and may lack a null terminator, you must use the %.*s format specifier. This requires providing a 'precision' argument (.*) to specify the maximum number of bytes to read from the pointer.

// Example of formatting an explicitly-sized output string with printf
// Assuming 'ptr' is the data pointer and 'size' is the length
printf("%.*s\n", size, ptr);

When using buffer mapping methods like wgpuBufferGetMappedRange, wgpuBufferGetConstMappedRange, wgpuBufferReadMappedRange, or wgpuBufferWriteMappedRange, calls will fail (returning NULL or WGPUStatus_Error) if they violate WebGPU specification rules for getMappedRange().

Common failure reasons include:

• The buffer is not currently mapped.
• The requested offset or size violates alignment constraints.
• The requested range overlaps with another active range (except for overlaps between const ranges in C on non-Wasm targets).
• wgpuBufferGetMappedRange or wgpuBufferWriteMappedRange is called on a buffer that was not mapped with WGPUMapMode_Write.

Synchronous errors occur immediately during an API call. These include:

• OutStructChainError cases.
• Certain content-timeline errors (check specific documentation for how they are exposed).

When a synchronous error occurs, the API will generally return a failure status (such as WGPUStatus_Error) or NULL, and the implementation may produce an implementation-defined logging message.

Device errors in webgpu-native follow the WebGPU JavaScript specification. They include device-timeline errors, numerically invalid enum values, enum values requiring unenabled features (content-timeline errors), and NonFiniteFloatValueError.

You can capture these errors using:

1. wgpuDevicePopErrorScope() to retrieve errors from the current error scope stack.
2. The uncapturedErrorCallbackInfo field in WGPUDeviceDescriptor to handle errors that were not caught by a scope.

When working with nullable or optional floating-point types (float or double), the value NaN is used to represent a null value.

Important Implementation Note: To check if a value represents a null, you must use isnan(value) != 0. Do not use an equality check with a NaN constant (e.g., if (value == NaN)), because NaN == NaN is always false in floating-point logic.