zig/mach
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

gpu: update README, add TODO-webgpu.h

Browse source 
Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
This commit is contained in:
Stephen Gutekanst 2022-07-10 18:28:56 -07:00 • committed by Stephen Gutekanst
parent 2174936469
commit 919499327e
2 changed files with 1796 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

89
gpu/README.md
View file

@ -1,4 +1,4 @@
# mach/gpu, truly cross-platform graphics for Zig <a href="https://hexops.com"><img align="right" alt="Hexops logo" src="https://raw.githubusercontent.com/hexops/media/master/readme.svg"></img></a>
# mach/gpu, cross-platform GPU API for Zig <a href="https://hexops.com"><img align="right" alt="Hexops logo" src="https://raw.githubusercontent.com/hexops/media/master/readme.svg"></img></a>
`mach/gpu` provides a truly cross-platform graphics API (desktop, mobile, and web) with unified low-level graphics & compute backed by Vulkan, Metal, D3D12, and OpenGL (as a best-effort fallback.)
@ -6,72 +6,71 @@
## Features
* Desktop, (future) mobile, and (future) web support.
* Desktop, (future) mobile, and web support.
* A modern graphics API similar to Metal, Vulkan, and DirectX 12.
* Cross-platform shading language
* Compute shaders
* Cross-compilation & no fuss installation, using `zig build`, as with all Mach libraries.
* Advanced GPU features where hardware support is available:
* Depth buffer clipping control
* Depth buffer format control
* Texture compression (BC, ETC2, and ASTC)
* Timestamp querying (for GPU profiling)
* Indirect draw support
* (bindless in the future, but not today)
* 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
## Different approach to graphics API abstraction
## A different approach to graphics API abstraction
Most engines today (Unreal, Unity, Godot, etc.) maintain their own GPU abstraction layer over native graphics APIs at great expense, requiring years of development and ongoing maintenance.
Many are attempting graphics abstraction layers on their own including Godot (and their custom shading language), [SDL's recently announced GPU abstraction layer](https://news.ycombinator.com/item?id=29203534), [sokol_gfx](https://github.com/floooh/sokol), and others including Blender3D which target varying native graphics APIs. These are admirable efforts, but come at great development costs.
Many are attempting graphics abstraction layers on their own including Godot (and their custom shading language), [SDL's recently announced GPU abstraction layer](https://news.ycombinator.com/item?id=29203534), [sokol_gfx](https://github.com/floooh/sokol), and others including Blender3D which target varying native graphics APIs on their own. These are admirable efforts, but cost a great deal of effort.
Vulkan aims to be a cross-platform graphics API, but also requires abstraction layers like MoltenVK on Apple hardware and is often in practice too verbose for use by regular folks without at least one higher level abstraction layer (often the engine's rendering layer.) With a simpler API like Metal or D3D, however, one could stay closer to the underlying API without introducing as many abstraction layers on top and perhaps make smarter choices as a result.
Vulkan aims to be a cross-platform graphics API, but also requires abstraction layers like MoltenVK on Apple hardware and is often in practice too verbose for use by mere mortals without at least one higher level abstraction layer (often the engine's rendering layer.) With a more refined API that acts as the union of Vulkan/Metal/D3D APIs, we believe one could stay closer to the underlying API without introducing as many abstractions on top and perhaps make smarter choices as a result.
With Mach, we'd rather focus on building the interesting and innovative bits of an engine rather than burning years on yet-another-graphics-abstraction-layer.
With Mach, we'd rather focus on building the interesting and innovative bits of an engine rather than burning years on yet-another-graphics-abstraction-layer, and so..
## Behind the scenes
## WebGPU / Dawn for Zig
`mach/gpu` is an idiomatic Zig interface to [the next-generation WebGPU API](https://www.w3.org/TR/webgpu/), which supersedes WebGL and exposes the common denominator between the latest low-level graphics APIs (Vulkan, Metal, D3D12) in the web.
`mach/gpu` is a zero-cost idiomatic Zig interface to [the next-generation WebGPU API](https://www.w3.org/TR/webgpu/), 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 also built with native support in mind](http://kvark.github.io/web/gpu/native/2020/05/03/point-of-webgpu-native.html) and has substantial investment from Mozilla, Google, Microsoft, Intel, and, critically, Apple:
![](https://user-images.githubusercontent.com/3173176/137647342-abf2bde6-a8bb-4276-b072-95c279c5d92f.png)
Despite its name, [WebGPU was built with native support in mind](http://kvark.github.io/web/gpu/native/2020/05/03/point-of-webgpu-native.html) 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](https://dawn.googlesource.com/dawn), bypassing 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.
When targeting native platforms, we build Google Chrome's WebGPU implementation, [Dawn](https://dawn.googlesource.com/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.
[Read more about why we believe WebGPU may be the future of graphics here](https://devlog.hexops.com/2021/mach-engine-the-future-of-graphics-with-zig#truly-cross-platform-graphics-api)
## Warning: We're not fully done yet!
## Usage
We have quite a lot, but are also missing a lot. You should be made aware of the pros and cons:
`mach/gpu` can be used in three ways:
* ✅ One example rendering a triangle
* ✅ `gpu.Interface` (akin to `std.mem.Allocator` but for interfacing with GPUs.)
* ✅ 99% of Dawn's `webgpu.h` exposed
* ✅ Ziggified API
* No chained structs (which make the `webgpu.h` API somewhat illegible)
* C enums -> Zig Enums
* C ptr+size -> Zig slices
* untyped pointers -> generic Zig functions
* ✅ Mac/Linux/Windows support + cross compilation
* ❌ Zig API finalization (may change as we learn more)
* ❌ WebGPU API finalization (WebGPU is not 100% finalized yet!)
* ❌ Browser implementation of `gpu.Interface`
* ❌ Nice examples
* ❌ Clear documentation
* ❌ Android support
* ❌ iOS support
* ❌ Dawn-specific API exposures
### "I want to do everything myself"
## Learning resources
See `examples/main.zig` - note that this is complex, involves creating a window yourself, using Dawn's API to create a device and bind it to the window, use OS-specific APIs to get the window handle, etc.
First check out `examples/main.zig` which contains a standalone basic example.
### "I want a Window, input & the WebGPU API - nothing else."
**Mach core** provides this:
* Mach handles creating a window and giving you user input for every OS (desktop, mobile & web.)
* You give Mach an `init`, `deinit` and `update` function for your app which will be called every frame.
* You'll have access to the WebGPU API, and nothing else.
### "I want a full engine"
See https://machengine.org
### Examples & Learning aterial
Check out https://machengine.org/gpu
The following may also prove useful:
* (long) Excellent introductory article: https://surma.dev/things/webgpu/
* Surma's compute article: https://surma.dev/things/webgpu/
* WebGPU Specification: https://gpuweb.github.io/gpuweb/
* WebGPU Explainer: https://gpuweb.github.io/gpuweb/explainer/
@ -89,10 +88,6 @@ Contributions are very welcome. Pull requests must be sent to [the main reposito
## WebGPU version
The interface and all documentation corresponds to the spec found at:
Dawn's `webgpu.h` is the authoritative source for our API. You can find [the current version we use here](https://github.com/hexops/dawn/blob/generated-2022-07-10/out/Debug/gen/webgpu-headers/webgpu.h).
https://github.com/gpuweb/gpuweb/tree/main/spec
Revision: 3382f327520b4bcd5ea617fa7e7fe60e214f0d96
Tracking this enables us to diff the spec and keep our interface up to date.
When updating, every single change is verified against [the WebGPU spec itself](https://github.com/gpuweb/gpuweb/tree/main/spec) to ensure our WebAssembly backend also functions effectively.