5741082848
WebGPU objects, like say `WGPUTexture`, could be represented in one of two ways:
1. As an `enum(usize)` as we were doing previously
2. As an `*opaque` pointer
In `webgpu.h` natively, `void*` opaque pointers are used. However, WebGPU objects are not
actually pointers: they are just IDs. A concrete example of this is how it is almost always
valid to for example pass a `WGPUTexture` that has been freed into the API. Doing so does
not result in undefined behavior, instead the implementation considers the texture to be an
ID and since it can't find such an ID it knows that texture has been free'd and to generate
an error instead of undefined behavior. In this regard, we can say that `enum(usize)` is the
more faithful representation.
`enum(usize)` is not without issues, though: it cannot effectively represent nullability in
Zig, which is used in the `webgpu.h` C ABI to represent _optionality_. `?enum(usize)` is not
a valid exported C type, the Zig compiler rejects it. And so in practice to maintain C ABI
compatability with descriptor struct types (which we do not want to copy or bitcast), we must
represent nullability with a `null` value:
```zig
pub const Texture = enum(usize) {
_,
pub const null: Texture = @intToEnum(Texture, 0);
pub const Descriptor = extern struct {
next_in_chain: *const ChainedStruct,
};
pub fn init() Texture {
return Texture.null;
}
};
```
The downside to this is that `init` cannot return a clear optional `?Texture`, and instead
must return a `Texture` which may be `== .null`. This downside seems significant enough to
warrant _not_ going with `enum(usize)` and instead going with `*opaque`:
```zig
pub const Texture = *opaque {
pub fn init() ?Texture { return null }
};
pub const TextureDescriptor = extern struct {
next_in_chain: *const ChainedStruct,
};
```
The downside to `*opaque` is that the namespace cannot have types nested below it.
`gpu.Texture.Descriptor` becomes `gpu.TextureDescriptor`.
Not ideal, but a tradeoff we'll accept to be able to represent optionality with the actual
Zig type system.
Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
|
||
|---|---|---|
| .github | ||
| dev | ||
| doc | ||
| ecs | ||
| examples | ||
| freetype | ||
| gamemode | ||
| glfw | ||
| gpu | ||
| gpu-dawn | ||
| libmach | ||
| shaderexp | ||
| src | ||
| sysaudio | ||
| sysjs | ||
| tools | ||
| www | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| build.zig | ||
| LICENSE | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
Mach: game engine & graphics toolkit for the future
Written in Zig, Mach is for creating games, graphical applications, and desktop/mobile apps:
- Data-driven, tooling oriented
- Composable
- Competitive with Unity and Unreal in spirit (a fully fledged editor in the future, etc.)
Cross-platform graphics in ~60 seconds
git clone https://github.com/hexops/mach
cd mach/
zig build run-example-boids
Cross-platform graphics, a unified shader language & compute shaders.
(Requires zig 0.10.x | known issues)
Libraries
Mach has many libraries you can use for game development in Zig - you don't have to use the entire engine. All our libraries aim to have the same zero-fuss installation, cross compilation, and platform support:
- mach-glfw: Ziggified GLFW bindings with 100% API coverage
- mach-freetype: Ziggified Freetype 2 & HarfBuzz bindings
- mach-gpu-dawn: Google's Dawn WebGPU implementation, cross-compiled with Zig into a single static library
- mach-system-sdk: More libraries for cross-compilation with Zig
Join the community
- #hexops:matrix.org Matrix chat and Discord server, come discuss the future of game engines & graphics in Zig!
- machengine.org
- Follow @machengine on Twitter for updates.
Contributors are very welcome! There are lots of places you can help out with little knowledge, so feel free to join the Matrix chat and say hi!
Sponsor development
No, it’s not Tom from myspace - it’s me, @slimsag! It’s taken almost a year to get here - staring at broken CI pipelines, C++ compiler errors, buying hardware to test every OS+arch possible, and more.
There are few things in life that I am more serious about than this work. I dedicate ~48 hours/week to my dayjob, and ~50h/week to Zig building Mach and running zigmonthly.org. After three years of aggressively pushing for progress in this exact way, I have no plans to slow down anytime soon.
Supported platforms
Mach is still early stages, so far we have support for building from the following OS to the following targets:
| Building for | From macOS x86_64 | From macOS M1/aarch64 | From Linux x86_64 | From Windows x86_64 |
|---|---|---|---|---|
| macOS x86_64 | ✅ | ✅ | ✅ | ✅ |
| macOS M1/aarch64 | ✅ | ✅ | ✅ | ✅ |
| Linux x86_64 | ✅ | ✅ | ✅ | ✅ |
| Windows x86_64 | ✅ | ✅ | ✅ | ✅ |
| iOS | 🏃 | 🏃 | 🏃 | 🏃 |
| Android | 🏃 | 🏃 | 🏃 | 🏃 |
| Web (Wasm) | 🏃 | 🏃 | 🏃 | 🏃 |
- ✅ Tested and verified via CI.
- ✔️ Should work, not tested via CI yet.
- 🏃 Planned or in progress.
- ⚠️ Implemented, but has known issues (e.g. bugs in Zig.)
Supported Zig version
Mach targets Zig nightly, binary releases are available at https://ziglang.org/download
Currently tested with: 0.10.0-dev.3027+0e26c6149
Contributing
Mach is maintained as a monorepo. When changes are merged to this repository, we use some git-fu to pick out the commits to subdirectories and push them to sub-repositories automagically. Changes to the glfw/ directory in this repository get pushed to the separate mach-glfw repository after being merged here, for example.
Please prefix commits / pull requests with the project name (glfw: fix an issue, gpu: fix an issue, examples: fix an issue, etc.) and if possible only one project per commit. If you don't know how to do this, no worries, we can help - just send your PR anyway!