Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zig-gamedev/zgpu

Cross-platform graphics lib for Zig built on top of Dawn native WebGPU implementation.
https://github.com/zig-gamedev/zgpu

cross-platform dawn gamedev graphics native webgpu zig

Last synced: 3 months ago
JSON representation

Cross-platform graphics lib for Zig built on top of Dawn native WebGPU implementation.

Awesome Lists containing this project

README 

        
# [zgpu](https://github.com/zig-gamedev/zgpu)



Cross-platform graphics lib for Zig built on top of [Dawn](https://github.com/zig-gamedev/dawn) native WebGPU implementation.



Supports Windows 10+ (DirectX 12), macOS 12+ (Metal) and Linux (Vulkan).



## Features



- Zero-overhead wgpu API bindings ([source code](https://github.com/zig-gamedev/zgpu/blob/main/src/wgpu.zig))

- Uniform buffer pool for fast CPU->GPU transfers

- Resource pools and handle-based GPU resources

- Async shader compilation

- GPU mipmap generator



## Getting started



Example `build.zig`:



```zig

pub fn build(b: *std.Build) void {

    const exe = b.addExecutable(.{ ... });



    @import("zgpu").addLibraryPathsTo(exe);



    const zgpu = b.dependency("zgpu", .{});

    exe.root_module.addImport("zgpu", zgpu.module("root"));

    exe.linkLibrary(zgpu.artifact("zdawn"));

}

```



## Sample applications



- [gui test (wgpu)](https://github.com/zig-gamedev/zig-gamedev/tree/main/samples/gui_test_wgpu)

- [physically based rendering (wgpu)](https://github.com/zig-gamedev/zig-gamedev/tree/main/samples/physically_based_rendering_wgpu)

- [bullet physics test (wgpu)](https://github.com/zig-gamedev/zig-gamedev/tree/main/samples/bullet_physics_test_wgpu)

- [procedural mesh (wgpu)](https://github.com/zig-gamedev/zig-gamedev/tree/main/samples/procedural_mesh_wgpu)

- [textured quad (wgpu)](https://github.com/zig-gamedev/zig-gamedev/tree/main/samples/textured_quad_wgpu)

- [triangle (wgpu)](https://github.com/zig-gamedev/zig-gamedev/tree/main/samples/triangle_wgpu)



## Library overview



Below you can find an overview of main `zgpu` features.



### Compile-time options



You can override default options in your `build.zig`:



```zig

pub fn build(b: *std.Build) void {

    ...



    const zgpu = @import("zgpu").package(b, target, optimize, .{

        .options = .{

            .uniforms_buffer_size = 4 * 1024 * 1024,

            .dawn_skip_validation = false,

            .buffer_pool_size = 256,

            .texture_pool_size = 256,

            .texture_view_pool_size = 256,

            .sampler_pool_size = 16,

            .render_pipeline_pool_size = 128,

            .compute_pipeline_pool_size = 128,

            .bind_group_pool_size = 32,

            .bind_group_layout_pool_size = 32,

            .pipeline_layout_pool_size = 32,

        },

    });



    zgpu.link(exe);



    ...

}

```



### Graphics Context



Create a `GraphicsContext` using a `WindowProvider`. For example, using [zglfw](https://github.com/zig-gamedev/zglfw):



```zig

const gctx = try zgpu.GraphicsContext.create(

    allocator,

    .{

        .window = window,

        .fn_getTime = @ptrCast(&zglfw.getTime),

        .fn_getFramebufferSize = @ptrCast(&zglfw.Window.getFramebufferSize),



        // optional fields

        .fn_getWin32Window = @ptrCast(&zglfw.getWin32Window),

        .fn_getX11Display = @ptrCast(&zglfw.getX11Display),

        .fn_getX11Window = @ptrCast(&zglfw.getX11Window),

        .fn_getWaylandDisplay = @ptrCast(&zglfw.getWaylandDisplay),

        .fn_getWaylandSurface = @ptrCast(&zglfw.getWaylandWindow),

        .fn_getCocoaWindow = @ptrCast(&zglfw.getCocoaWindow),

    },

    .{}, // default context creation options

);

```



### Uniforms



- Implemented as a uniform buffer pool

- Easy to use

- Efficient - only one copy operation per frame



```zig

struct DrawUniforms = extern struct {

    object_to_world: zm.Mat,

};

const mem = gctx.uniformsAllocate(DrawUniforms, 1);

mem.slice[0] = .{ .object_to_world = zm.transpose(zm.translation(...)) };



pass.setBindGroup(0, bind_group, &.{mem.offset});

pass.drawIndexed(...);



// When you are done encoding all commands for a frame:

gctx.submit(...); // Injects *one* copy operation to transfer *all* allocated uniforms

```



### Resource pools



- Every GPU resource is identified by 32-bit integer handle

- All resources are stored in one system

- We keep basic info about each resource (size of the buffer, format of the texture, etc.)

- You can always check if resource is valid (very useful for async operations)

- System keeps basic info about resource dependencies, for example, `TextureViewHandle` knows about its

  parent texture and becomes invalid when parent texture becomes invalid; `BindGroupHandle` knows

  about all resources it binds so it becomes invalid if any of those resources become invalid



```zig

const buffer_handle = gctx.createBuffer(...);



if (gctx.isResourceValid(buffer_handle)) {

    const buffer = gctx.lookupResource(buffer_handle).?;  // Returns `wgpu.Buffer`



    const buffer_info = gctx.lookupResourceInfo(buffer_handle).?; // Returns `zgpu.BufferInfo`

    std.debug.print("Buffer size is: {d}", .{buffer_info.size});

}



// If you want to destroy a resource before shutting down graphics context:

gctx.destroyResource(buffer_handle);



```



### Async shader compilation



- Thanks to resource pools and resources identified by handles we can easily async compile all our shaders



```zig

const DemoState = struct {

    pipeline_handle: zgpu.PipelineLayoutHandle = .{},

    ...

};

const demo = try allocator.create(DemoState);



// Below call schedules pipeline compilation and returns immediately. When compilation is complete

// valid pipeline handle will be stored in `demo.pipeline_handle`.

gctx.createRenderPipelineAsync(allocator, pipeline_layout, pipeline_descriptor, &demo.pipeline_handle);



// Pass using our pipeline will be skipped until compilation is ready

pass: {

    const pipeline = gctx.lookupResource(demo.pipeline_handle) orelse break :pass;

    ...



    pass.setPipeline(pipeline);

    pass.drawIndexed(...);

}

```



### Mipmap generation on the GPU



- wgpu API does not provide mipmap generator

- zgpu provides decent mipmap generator implemented in a compute shader

- It supports 2D textures, array textures and cubemap textures of any format

  (`rgba8_unorm`, `rg16_float`, `rgba32_float`, etc.)

- Currently it requires that: `texture_width == texture_height and isPowerOfTwo(texture_width)`

- It takes ~260 microsec to generate all mips for 1024x1024 `rgba8_unorm` texture on GTX 1660



```zig

// Usage:

gctx.generateMipmaps(arena, command_encoder, texture_handle);

```