28 lines
2.5 KiB
Markdown
28 lines
2.5 KiB
Markdown
# Rendering and coordinate conventions
|
||
|
||
This document covers implementation notes for the `renderer` crate and any code that imports geometry. The project-wide coordinate convention (+Y up, right-handed, 1 unit = 1 block) is strictly defined in [`DEVELOPMENT.md`](../DEVELOPMENT.md#coordinate-system--units). This note just collects the common gotchas that pop up because neighboring systems and tools use different conventions. To be clear, these are not convention changes for our engine, just necessary translations we have to handle in one agreed-upon place.
|
||
|
||
## Shader compilation
|
||
|
||
We compile GLSL sources located under `assets/shaders/` to SPIR-V using the `renderer` crate's build script. The compiled output is embedded directly from the `OUT_DIR`; we intentionally do not commit any compiled modules to the repository.
|
||
|
||
Because of this, building the crate requires `libshaderc`. You can get this as a distribution package (`libshaderc-dev` on Debian and Ubuntu, `shaderc` on Arch, or via the Vulkan SDK on Windows). If you don't have it installed, the build script will fall back to using a C++ toolchain with cmake and ninja so `shaderc-sys` can build the library from source.
|
||
|
||
If a shader fails to compile, the build aborts immediately, and the error will explicitly name the source file and the offending line.
|
||
|
||
## Vulkan clip space
|
||
|
||
Vulkan clip space is **Y-down** by default, and its depth range is strictly `[0, 1]`. This is completely different from OpenGL, which uses `[-1, 1]`.
|
||
|
||
Because our world space and view space stay Y-up, you have to flip Y when moving into clip space. You can do this by having the projection matrix flip Y, or by setting the viewport height to a negative value. Both are common idioms in `ash` examples.
|
||
|
||
## Blender import
|
||
|
||
Blender natively uses a **Z-up, right-handed** coordinate system.
|
||
|
||
When you export models from Blender, they require a coordinate swap on import: you have to either rotate them −90° around the X-axis, or swap the Y and Z axes while applying a sign change. The hard rule here is to decide *exactly once* where that swap happens (at export, at import, or never, by simply adopting the source convention) and keep it in a single place. If you accidentally perform the swap in two places, you will eventually end up with a model that is mirrored or rendered completely upside-down.
|
||
|
||
## glTF import
|
||
|
||
The glTF format is natively **Y-up, right-handed**, which perfectly matches our engine's convention. Because of this, it is easily the most friction-free model format to use whenever you have a choice.
|