263 lines
8.2 KiB
Markdown
263 lines
8.2 KiB
Markdown
# Minimal Zig WebGPU Compute & Render Library
|
|
|
|
This is a minimal, self-contained Zig library designed to simplify running compute
|
|
shaders and rendering pipelines using WebGPU. It abstracts away much of the boilerplate
|
|
required for GPU device initialization, memory management, bind groups, and pipeline
|
|
execution.
|
|
|
|
## Core Modules
|
|
|
|
The library exports the following primary components:
|
|
|
|
* **`GpuDevice`**: Initializes the WebGPU instance, adapter, device, and queue.
|
|
It is configured to prioritize high performance and automatically requests the `ShaderF16`
|
|
feature if the adapter supports it. It provides the base `GpuAllocator` for raw
|
|
VRAM allocations.
|
|
* **`GpuArenaAllocator`**: A memory management layer that wraps a base allocator
|
|
to track and automatically destroy all allocated WebGPU buffers, textures, views,
|
|
and pipelines when deinitialized.
|
|
* **`GpuBuffer`**: Wraps native WebGPU buffers. It provides a `.load()` method
|
|
for CPU-to-GPU data transfers and a `.read()` method that utilizes a staging
|
|
buffer to map GPU data back to the CPU.
|
|
* **`GpuCompute`**: Compiles WGSL source code into a compute pipeline and dispatches
|
|
compute workgroups.
|
|
* **`GpuRender` / `GpuTexture` / `GpuTextureView`**: Components used to initialize
|
|
render pipelines, set up render attachments (textures), and bind render targets
|
|
for offscreen drawing.
|
|
|
|
---
|
|
|
|
## Example 1: Compute Pipeline
|
|
|
|
Below is a complete example demonstrating how to initialize the GPU via the device
|
|
allocator, manage VRAM using a GPU Arena, run a compute shader, and read the results
|
|
back to the CPU:
|
|
|
|
```zig
|
|
const std = @import("std");
|
|
const gpu = @import("gpu");
|
|
const GpuDevice = gpu.GpuDevice;
|
|
const GpuArenaAllocator = gpu.GpuArenaAllocator;
|
|
const GpuBuffer = gpu.GpuBuffer;
|
|
const GpuCompute = gpu.GpuCompute;
|
|
|
|
pub fn main(init: std.process.Init) !void {
|
|
const allocator = init.gpa;
|
|
|
|
// 1. Open GPU Device
|
|
const device = try GpuDevice.init(.{});
|
|
defer device.deinit();
|
|
|
|
// 2. Create a GPU Arena to manage VRAM
|
|
var grena = GpuArenaAllocator.init(allocator, device.gpuAllocator());
|
|
defer grena.deinit();
|
|
const gloc = grena.gpuAllocator();
|
|
|
|
// 3. Load the WGSL compute pipeline
|
|
const add_cp = try GpuCompute.init(
|
|
gloc,
|
|
@embedFile("shaders/add.wgsl"),
|
|
.{
|
|
.label = "add",
|
|
.bindings = &.{
|
|
.{ .element_size = @sizeOf(f16) },
|
|
.{ .element_size = @sizeOf(f16) },
|
|
.{ .element_size = @sizeOf(f16) },
|
|
},
|
|
},
|
|
);
|
|
|
|
// 4. Setup CPU data
|
|
const len: usize = 16;
|
|
const data_a = try allocator.alloc(f16, len);
|
|
defer allocator.free(data_a);
|
|
const data_b = try allocator.alloc(f16, len);
|
|
defer allocator.free(data_b);
|
|
|
|
for (0..len) |i| {
|
|
data_a[i] = @floatFromInt(i);
|
|
data_b[i] = @floatFromInt(len - 1 - i);
|
|
}
|
|
|
|
// 5. Initialize raw GPU Buffers
|
|
const byte_size = len * @sizeOf(f16);
|
|
const buf_a = try GpuBuffer.init(gloc, .{ .label = "a", .size = byte_size, .usage = .initMany(&.{ .Storage, .CopyDst, .CopySrc }) });
|
|
const buf_b = try GpuBuffer.init(gloc, .{ .label = "b", .size = byte_size, .usage = .initMany(&.{ .Storage, .CopyDst, .CopySrc }) });
|
|
const buf_out = try GpuBuffer.init(gloc, .{ .label = "out", .size = byte_size, .usage = .initMany(&.{ .Storage, .CopyDst, .CopySrc }) });
|
|
|
|
// Note: Buffers are safely tied to the GpuArenaAllocator which will automatically
|
|
// release them at the end. You can also manually call buf_x.deinit() if desired.
|
|
// This will also release pipelines, textures, ect. Everything using a GpuAllocator to init.
|
|
|
|
// 6. Transfer data from CPU slices to GPU Buffers
|
|
try buf_a.load(f16, data_a);
|
|
try buf_b.load(f16, data_b);
|
|
|
|
// 7. Dispatch the Compute
|
|
try add_cp.run(gloc, .{ buf_a, buf_b, buf_out });
|
|
|
|
// 8. Map and copy the resulting buffer back to the CPU
|
|
const out = try buf_out.read(allocator, f16);
|
|
defer allocator.free(out);
|
|
|
|
std.debug.print("Result: {any}\n", .{out});
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Example 2: Rendering Pipeline (Offscreen to PPM Image)
|
|
|
|
This example demonstrates how to initialize a rendering pipeline, allocate an
|
|
output texture target, draw primitives via WebGPU,
|
|
and pull the frame pixels back to the CPU to write a standard image file:
|
|
|
|
```zig
|
|
const std = @import("std");
|
|
const gpu = @import("gpu");
|
|
const GpuDevice = gpu.GpuDevice;
|
|
const GpuArenaAllocator = gpu.GpuArenaAllocator;
|
|
const GpuBuffer = gpu.GpuBuffer;
|
|
const GpuRender = gpu.GpuRender;
|
|
const GpuTexture = gpu.GpuTexture;
|
|
const GpuTextureView = gpu.GpuTextureView;
|
|
|
|
const width: u32 = 512;
|
|
const height: u32 = 512;
|
|
|
|
pub fn main(init: std.process.Init) !void {
|
|
const allocator = init.gpa;
|
|
|
|
// 1. Open GPU Device
|
|
const device = try GpuDevice.init(.{});
|
|
defer device.deinit();
|
|
|
|
// 2. Init VRAM Arena
|
|
var grena = GpuArenaAllocator.init(allocator, device.gpuAllocator());
|
|
defer grena.deinit();
|
|
const gloc = grena.gpuAllocator();
|
|
|
|
// 3. Load Render Pipeline
|
|
const circle_rp = try GpuRender.init(
|
|
gloc,
|
|
@embedFile("shaders/circle.wgsl"),
|
|
.{ .bindings = &.{}, .texture_format = .RGBA8Unorm, .topology = .TriangleStrip },
|
|
);
|
|
defer circle_rp.deinit();
|
|
|
|
// 4. Create VRAM texture to render into
|
|
const texture = try GpuTexture.init(gloc, .{
|
|
.format = .RGBA8Unorm,
|
|
.size = .{ .width = width, .height = height, .depthOrArrayLayers = 1 },
|
|
.usage = .initMany(&.{ .RenderAttachment, .CopySrc }),
|
|
});
|
|
defer texture.deinit();
|
|
|
|
// 5. Create a view from texture
|
|
const view = try GpuTextureView.init(gloc, texture, .{});
|
|
defer view.deinit();
|
|
|
|
// 6. Run the rendering pipeline
|
|
try circle_rp.draw(gloc, view, 4, .{});
|
|
|
|
// 7. Load Texture into GpuBuffer
|
|
const cpu_staging_cpu = try texture.buffCopy(gloc);
|
|
defer cpu_staging_cpu.deinit();
|
|
|
|
// 8. Read GpuBuffer to CPU
|
|
// This need to be free manually because CPU memory
|
|
const pixels = try cpu_staging_cpu.read(allocator, u8);
|
|
defer allocator.free(pixels);
|
|
|
|
// 9. Write a simple ppm image
|
|
try savePpm(init.io, "circle.ppm", width, height, pixels);
|
|
}
|
|
|
|
fn savePpm(io: std.Io, filename: []const u8, w: u32, h: u32, rgba_pixels: []const u8) !void {
|
|
const file = try std.Io.Dir.cwd().createFile(io, filename, .{});
|
|
defer file.close(io);
|
|
|
|
var buf: [255]u8 = undefined;
|
|
var writer = file.writer(io, &buf);
|
|
|
|
// PPM Header: P6 format means raw RGB bytes
|
|
try writer.interface.print("P6\n{d} {d}\n255\n", .{ w, h });
|
|
|
|
// Strip Alpha channel when writing out to standard RGB PPM format
|
|
var i: usize = 0;
|
|
while (i < rgba_pixels.len) : (i += 4) {
|
|
try writer.interface.writeAll(rgba_pixels[i .. i + 3]);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Running Examples Locally
|
|
|
|
If you have cloned the repository, you can run the included examples directly
|
|
using the Zig build system:
|
|
|
|
```bash
|
|
# Run the rendering example (generates circle.ppm)
|
|
zig build circle
|
|
|
|
# Run the compute example
|
|
zig build compute
|
|
|
|
# Run the compute benchmark
|
|
zig build bench_cp
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
* **`wgpu.h`**: The library relies on WebGPU C API headers to bind to the native
|
|
system graphics.
|
|
|
|
## System Requirements
|
|
|
|
Because this library binds to native system graphics APIs via `wgpu-native`,
|
|
you must ensure the appropriate development headers and libraries are available
|
|
on your system before compiling.
|
|
|
|
It work both for x86_64 and aarch64 on all platforms.
|
|
|
|
### Linux (Vulkan)
|
|
|
|
* **Ubuntu / Debian:** `sudo apt update && sudo apt install libvulkan-dev mesa-vulkan-drivers`
|
|
* **Fedora / RHEL:** `sudo dnf install vulkan-devel mesa-vulkan-drivers`
|
|
* **Arch Linux:** `sudo pacman -S vulkan-headers vulkan-icd-loader`
|
|
|
|
### macOS (Metal)
|
|
|
|
No extra installation required. Automatically links against `Metal`, `QuartzCore`,
|
|
`Foundation`, and `CoreGraphics`.
|
|
|
|
### Windows (DirectX 12)
|
|
|
|
No extra installation required. Automatically links against `d3d12`, `dxgi`, and
|
|
`user32`. Ensure you have MSVC build tools installed.
|
|
|
|
---
|
|
|
|
## Adding to your project
|
|
|
|
Add it to your `build.zig.zon`:
|
|
|
|
```bash
|
|
zig fetch --save git+https://git.bouvais.lu/adrien/zig-wgpu#ref=0.3.0
|
|
```
|
|
|
|
Then, expose it in your `build.zig`:
|
|
|
|
```zig
|
|
const zig_wgpu = b.dependency("zig-wgpu", .{
|
|
.target = target,
|
|
.optimize = optimize,
|
|
});
|
|
|
|
exe.root_module.addImport("gpu", zig_wgpu.module("zig-wgpu"));
|
|
```
|