mach/gpu
provides a truly cross-platform graphics API for Zig (desktop, mobile, and web) with unified low-level graphics & compute backed by Vulkan, Metal, D3D12, and OpenGL (as a best-effort fallback.)
See the mach/gpu examples showcase for more information.
- Desktop, Steam Deck, (soon) web, and (future) mobile support.
- A modern graphics API similar to Metal, Vulkan, and DirectX 12.
- Cross-platform shading language
- Compute shaders
- Seamless cross-compilation & zero-fuss installation, as with all Mach libraries.
- Advanced GPU features where hardware support is available, such as:
- Depth buffer clip control
- Special depth/stencil format with 32 bit floating point depth and 8 bits integer stencil.
- Timestamp queries
- Pipeline statistics queries
- Texture compression (BC, ETC2, and ASTC)
- Indirect first-instance
- Depth clamping
- Shader 16-bit float support
- Multi planar formats
mach/gpu
is a zero-cost idiomatic Zig interface to the next-generation WebGPU API, which supersedes WebGL and exposes the common denominator between the latest low-level graphics APIs (Vulkan, Metal, D3D12) in the web.
Despite its name, WebGPU was built with native support in mind and has substantial investment from Mozilla, Google, Microsoft, Intel, and Apple.
When targeting WebAssembly, mach/gpu
merely calls into the browser's native WebGPU implementation.
When targeting native platforms, we build Google Chrome's WebGPU implementation, Dawn using Zig as the C/C++ compiler toolchain. We bypass the client-server sandboxing model, and use zig build
(plus a lot of hand-holding) to support zero-fuss cross compilation & installation without any third-party Google tools, libraries, etc. Just zig
and git
needed, nothing else.
There is a detailed write-up of how we've been perfecting WebGPU for Zig.
mach/gpu
can be used in three ways:
This involves creating a window (using GLFW, and other APIs if you want Web, Mobile, or other platform support), using Dawn's API to create a device and bind it to that window, using OS-specific APIs to get the window handle to bind, etc.
examples/main.zig
demonstrates how to do this. There's a fair amount of setup code involved. You might instead want to consider Mach core:
Mach core can be thought of as an alternative to SDL or GLFW:
- Mach handles creating a window, giving you user input, and gives you the WebGPU API for every platform.
- You give Mach an
init
,deinit
andupdate
function for your app which will be called every frame. - As we add support for more platforms (browser, mobile, etc.) in the future, you get them for free because Mach core is truly cross platform.
mach/gpu
is the graphics abstraction used by Mach engine, but we're not there yet. See https://machengine.org for more information.
Join us in the Mach Discord server to discuss the project, ask questions, get help, etc.
Issues are tracked in the main Mach repository.
Contributions are very welcome. Pull requests must be sent to the main repository to avoid some complex merge conflicts we'd get by accepting contributions in both repositories. Once the changes are merged there, they'll get sync'd to this repository automatically.
- Allow comptime-defined interception of WebGPU API requests (comptime interfaces.)
- Expose a standard Dawn
webgpu.h
-compliant C ABI, which routes through Zig comptime interfaces. - Support Dawn and Browser (via WASM/JS) implementations of WebGPU.
- Broad platform support: desktop, mobile, web, consoles.
- First-class Linux support (Wayland, OpenGL and OpenGL ES fallbacks, etc.)
- Support non-Dawn (e.g. Rust WebGPU) implementations if they don't match the same
webgpu.h
as Dawn. - Maintain backwards compatibility with deprecated
webgpu.h
methods.
We make the following quality of life improvements.
See perfecting WebGPU for Zig.
- Optional values default to their zero value (either
null
or a struct constructor.{}
) when specified asoptional
indawn.json
. This means things likelabel
,next_in_chain
, etc. do not need to be specified. - Fields representing a slice with a
_count
field are nullable pointers defaulting to null and 0 by default.
Some WebGPU APIs expose slices as pointers and lengths, we either wrap these to provide a slice or alter the method directly to provide a slice (if little overhead.) The original C-style API can always be accessed via the gpu.Impl
type in any case.
The slice helpers are:
Adapter.enumerateFeaturesOwned
Buffer.getConstMappedRange
Buffer.getMappedRange
CommandEncoder.writeBuffer
ComputePassEncoder.setBindGroup
Device.enumerateFeaturesOwned
Queue.writeTexture
Queue.writeBuffer
RenderPassEncoder.executeBundles
RenderBundleEncoder.setBindGroup
RenderPassEncoder.setBindGroup
And, to initialize data structures with slices in them, the following helpers are provided:
BindGroupLayout.Descriptor.init
BindGroup.Descriptor.init
InstanceDescriptor.init
TogglesDeviceDescriptor.init
Device.Descriptor.init
PipelineLayout.Descriptor.init
QuerySet.Descriptor.init
RenderBundleEncoder.Descriptor.init
Texture.Descriptor.init
ComputePassDescriptor.init
RenderPassDescriptor.init
ProgrammableStageDescriptor.init
VertexBufferLayout.init
VertexState.init
FragmentState.init
CompilationInfo.getMessages
Most WebGPU callbacks provide a way to provide a userdata: *anyopaque
pointer to the callback for context. We alter these APIs to expose a typed context pointer instead (again, the original API is always available via the gpu.Impl
type should you want it):
Instance.requestAdapter
Adapter.requestDevice
Queue.onSubmittedWorkDone
Buffer.mapAsync
ShaderModule.getCompilationInfo
Device.createComputePipelineAsync
Device.createRenderPipelineAsync
Device.popErrorScope
Device.setDeviceLostCallback
Device.setLoggingCallback
Device.setUncapturedErrorCallback
WebGPU exposes struct types which are extendable arbitrarily, often by implementation-specific extensions. For example:
const extension = gpu.Surface.DescriptorFromWindowsHWND{
.chain = gpu.ChainedStruct{.next = null, .s_type = .surface_descriptor_from_windows_hwnd},
.hinstance = foo,
.hwnd = bar,
}
const descriptor = gpu.Surface.Descriptor{
.next_in_chain = @ptrCast(?*const ChainedStruct, &extension),
};
Here gpu.Surface.Descriptor
is a concrete type. The next_in_chain
field is set to an arbitrary pointer which follows the gpu.ChainedStruct
pattern: it must begin with a gpu.ChainedStruct
where the s_type
identifies which fields may follow after, and .next
could theoretically chain more extensions on too.
Complexity aside, next_in_chain
is not type safe! It cannot be, because such an extension could be implementation-specific. To make this safer, we instead change the next_in_chain
field type to be a union, where one option is the type-unsafe generic
pointer, and the other options are known extensions:
pub const NextInChain = extern union {
generic: ?*const ChainedStruct,
from_windows_hwnd: *const DescriptorFromWindowsHWND,
// ...
};
Additionally we initialize .chain
with a default value, making our earlier snippet look like this in most cases:
const descriptor = gpu.Surface.Descriptor{
.next_in_chain = .{.from_windows_hwnd = &.{
.hinstance = foo,
.hwnd = bar,
}},
}
Device.createShaderModuleWGSL
(helper to create WGSL shader modules more nicely)
There may be other opportunities for helpers, to improve the existing APIs, or add utility APIs on top of the existing APIs. If you find one, please open an issue we'd love to consider it.
Dawn's webgpu.h
is the authoritative source for our API. You can find the current version we use here.
The rules for translating webgpu.h
are as follows:
WGPUBuffer
->gpu.Buffer
:- Opaque pointers like these become a
pub const Buffer = opaque {_}
to ensure they are still pointers compatible with the C ABI, while still allowing us to declare methods on them. - As a result, a
null
ableBuffer
is represented simply as?*Buffer
, and any function that would normally takeWGPUBuffer
now takes*Buffer
as a parameter.
- Opaque pointers like these become a
WGPUBufferBindingType
->gpu.Buffer.BindingType
(purely because it's prefix matches an opaque pointer type, it thus goes into theBuffer
opaque type.)- Reserved Zig keywords are translated as follows:
error
->err
type
->typ
opaque
->opaq
- Undefined in Zig commonly means undefined memory. WebGPU however uses undefined as terminology to indicate something was not specified, as the optional none value, which Zig represents as null. Since null is a reserved keyword in Zig, we rename all WebGPU undefined terminology to "unspecified" instead.
- Constant names map using a few simple rules, but it's easiest to describe them with some concrete examples:
RG11B10Ufloat -> rg11_b10_ufloat
Depth24PlusStencil8 -> depth24_plus_stencil8
BC5RGUnorm -> bc5_rg_unorm
BC6HRGBUfloat -> bc6_hrgb_ufloat
ASTC4x4UnormSrgb -> astc4x4_unorm_srgb
maxTextureDimension3D -> max_texture_dimension_3d
- Sometimes an enum will begin with numbers, e.g.
WGPUTextureViewDimension_2DArray
. In this case, we add a prefix so instead of the enum field being2d_array
it isdimension_2d_array
(an enum field name must not start with a number in Zig.) - Dawn extension types
WGPUDawnFoobar
are placed undergpu.dawn.Foobar
- Regarding "undefined" terminology:
- In Zig, undefined usually means undefined memory, undefined behavior, etc.
- In WebGPU, undefined commonly refers to JS-style undefined: an optional value that was not specified
- Zig refers to optional values not specified as null, but null is a reserved keyword and so can't be used.
- We could use "none", but "BindingType none" and "BindingType not specified" clearly have non-equal meanings.
- As a result of all this, we translate "undefined" in WebGPU to "undef" in Zig: it has no overlap with the reserved undefined keyword, and distinguishes its meaning.