The root dir of our repository has grown quite a lot the past few months.
I'd like to make it more clear where the bulk of the engine lives (`src/`) and
also make it more clear which Mach libraries are consumable as standalone projects.
As for the name of this directory, `libs` was my first choice but there's a bit of
a convention of that being external libraries in Zig projects _today_, while these
are libraries maintained as part of Mach in this repository - not external ones.
We will name this directory `libs`, and if we have a need for external libraries
we will use `external` or `deps` for that directory name. I considered other names
such as `components`, `systems`, `modules` (which are bad as they overlap with
major ECS / engine concepts), and it seems likely the official Zig package manager
will break the convention of using a `libs` dir anyway.
Performed via:
```sh
mkdir libs/
git mv freetype libs/
git mv basisu libs/
git mv gamemode libs/
git mv glfw libs/
git mv gpu libs/
git mv gpu-dawn libs/
git mv sysaudio libs/
git mv sysjs libs/
git mv ecs libs/
```
git-subtree-dir: glfw
git-subtree-mainline: 0d5b853443
git-subtree-split: 572d1144f11b353abdb64fff828b25a4f0fbb7ca
Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
git mv ecs libs/
Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
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>
