WebGPU

Whether WebGPU can be used here. Natively it is always true, though there may still be no adapter. In the browser it is false when the page has no WebGPU or can't suspend the program while it waits, so a program can fall back instead of failing at its first call.

if !webgpu_available() {
    print("this browser has no WebGPU\n");
    return;
}

A WGPUStringView for a Jai string, to pass where the C API wants text. It borrows the string's bytes.

view := to_string_view("compute");
assert(view.length == 7);

A string for a view the implementation wrote (an adapter name, an error message). It borrows the view's bytes.

view := to_string_view("hello");
assert(to_string(view) == "hello");

Processes events until done is set by a callback created with mode .AllowProcessEvents or .AllowSpontaneous. Natively it polls wgpu-native and sleeps a little once the wait gets long; in the browser each poll lets the page run.

instance := wgpuCreateInstance(null);
done := false;
// ... start something whose callback sets `done` ...
webgpu_wait(instance, *done);

Requests an adapter (a GPU) and waits for it. Returns null, and logs why, when there is none.

instance := wgpuCreateInstance(null);
adapter := webgpu_request_adapter(instance);
if !adapter return;

Requests a device from an adapter and waits for it. Returns null on failure. Uncaptured errors are logged unless the descriptor sets its own callback.

instance := wgpuCreateInstance(null);
adapter := webgpu_request_adapter(instance);
device := webgpu_request_device(instance, adapter);

Maps size bytes of buffer at offset for reading (.Read) or writing (.Write) and waits until they are mapped. wgpuBufferGetConstMappedRange or wgpuBufferGetMappedRange then give the bytes, and wgpuBufferUnmap ends the mapping. Returns false, and logs why, when mapping failed.

instance := wgpuCreateInstance(null);
buffer: WGPUBuffer;
if webgpu_map_buffer(instance, buffer, .Read) {
    bytes := wgpuBufferGetConstMappedRange(buffer, 0, 64);
    // ... read from bytes ...
    wgpuBufferUnmap(buffer);
}

Copies the base level of a 2D texture back to the CPU and returns its bytes, rows packed one after another. The texture needs the .CopySrc usage and can't be multisampled. Free the result with array_free. It submits its own command buffer and waits, so use it for screenshots and tests rather than every frame. Returns an empty array, and logs why, on failure.

instance := wgpuCreateInstance(null);
device: WGPUDevice;
queue: WGPUQueue;
texture: WGPUTexture;
pixels := webgpu_read_texture(instance, device, queue, texture, 256, 256);
defer array_free(pixels);

Pops the device's innermost error scope and waits for it. Returns the type of the first error the scope caught (.NoError for none) and its message, which lives in temporary storage.

instance := wgpuCreateInstance(null);
device: WGPUDevice;
wgpuDevicePushErrorScope(device, .Validation);
// ... calls that might be invalid ...
type, message := webgpu_pop_error_scope(instance, device);
if type != .NoError print("%\n", message);

Makes a surface for a Window_Creation window. It's native only; in the browser, pass the canvas to wgpuInstanceCreateSurface. Returns null, and logs why, when the window is invalid.

#import "Window_Creation";

instance := wgpuCreateInstance(null);
window := create_window(800, 600, "gpu");
surface := webgpu_create_surface(instance, window);

The format to configure surface with: one it supports that is not sRGB, unless srgb is set, so colours mean the same everywhere. Natively a surface usually lists an sRGB format first, where the GPU converts the shader's output on write; a browser canvas has only plain formats. A shader that writes already encoded colours wants srgb = false; one that writes linear colours wants srgb = true and must encode them itself where the surface has no sRGB format (see webgpu_format_is_srgb). Returns .Undefined when the surface lists none.

surface: WGPUSurface;
adapter: WGPUAdapter;
format := webgpu_surface_format(surface, adapter);

Whether the GPU sRGB-encodes writes to format.

assert(webgpu_format_is_srgb(.BGRA8UnormSrgb));
assert(!webgpu_format_is_srgb(.BGRA8Unorm));

Browser only: the size in pixels of the page's canvas. It changes when the page resizes the canvas, so compare it each frame and configure the surface again.

width, height := webgpu_canvas_size();

Native only: the size in pixels of the surface window shows.

#import "Window_Creation";

window: Window_Type;
width, height := webgpu_window_size(window);

Shows the frame drawn into the surface's current texture and waits until the next one is due. Natively that is wgpuSurfacePresent, which blocks for vsync on a FIFO surface. In the browser it waits for the page's next animation frame.

surface: WGPUSurface;
while true {
    // ... draw into the surface's current texture ...
    webgpu_present(surface);
}