adrien/zig-wgpu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Formated README

Browse Source
This commit is contained in:
adrien 2026-05-27 13:20:13 +02:00
parent ff1226f268
commit e3e39af1a4
1 changed files with 34 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
README.md
View File

@ -1,22 +1,37 @@
# Minimal Zig WebGPU Compute & Render Library # 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. 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 ## Core Modules
The library exports the following primary components: 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. * **`GpuDevice`**: Initializes the WebGPU instance, adapter, device, and queue.
* **`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. It is configured to prioritize high performance and automatically requests the `ShaderF16`
* **`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. feature if the adapter supports it. It provides the base `GpuAllocator` for raw
* **`GpuCompute`**: Compiles WGSL source code into a compute pipeline and dispatches compute workgroups. VRAM allocations.
* **`GpuRender` / `GpuTexture` / `GpuTextureView`**: Components used to initialize render pipelines, set up render attachments (textures), and bind render targets for offscreen drawing. * **`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 ## 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: 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 ```zig
const std = @import("std"); const std = @import("std");
@ -93,7 +108,8 @@ pub fn main(init: std.process.Init) !void {
## Example 2: Rendering Pipeline (Offscreen to PPM Image) ## 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, 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: and pull the frame pixels back to the CPU to write a standard image file:
```zig ```zig
@ -179,7 +195,8 @@ fn savePpm(io: std.Io, filename: []const u8, w: u32, h: u32, rgba_pixels: []cons
## Running Examples Locally ## Running Examples Locally
If you have cloned the repository, you can run the included examples directly using the Zig build system: If you have cloned the repository, you can run the included examples directly
using the Zig build system:
```bash ```bash
# Run the rendering example (generates circle.ppm) # Run the rendering example (generates circle.ppm)
@ -196,12 +213,14 @@ zig build bench_cp
## Dependencies ## Dependencies
* **`wgpu.h`**: The library relies on WebGPU C API headers to bind to the native system graphics. * **`wgpu.h`**: The library relies on WebGPU C API headers to bind to the native
system graphics.
## System Requirements ## System Requirements
Because this library binds to native system graphics APIs via `wgpu-native`, 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. 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. It work both for x86_64 and aarch64 on all platforms.
@ -213,11 +232,13 @@ It work both for x86_64 and aarch64 on all platforms.
### macOS (Metal) ### macOS (Metal)
No extra installation required. Automatically links against `Metal`, `QuartzCore`, `Foundation`, and `CoreGraphics`. No extra installation required. Automatically links against `Metal`, `QuartzCore`,
`Foundation`, and `CoreGraphics`.
### Windows (DirectX 12) ### Windows (DirectX 12)
No extra installation required. Automatically links against `d3d12`, `dxgi`, and `user32`. Ensure you have MSVC build tools installed. No extra installation required. Automatically links against `d3d12`, `dxgi`, and
`user32`. Ensure you have MSVC build tools installed.
--- ---