22 lines
1.8 KiB
Markdown
22 lines
1.8 KiB
Markdown
# Rendering & coordinate conventions
|
||
|
||
Implementation notes for the `renderer` crate and for code that imports geometry. The project-wide coordinate convention itself (+Y up, right-handed, 1 unit = 1 block) is stated in [`AGENTS.md`](../AGENTS.md#coordinate-system--units); this note collects the gotchas that arise because neighbouring systems use different conventions. These are not convention changes, only mismatches to handle in one agreed place.
|
||
|
||
## Shader compilation
|
||
|
||
GLSL sources under `assets/shaders/` are compiled to SPIR-V by the `renderer` crate's build script and embedded from `OUT_DIR`; no compiled module is committed. Building the crate therefore requires `libshaderc`, either as a distribution package (`libshaderc-dev` on Debian and Ubuntu, `shaderc` on Arch, the Vulkan SDK on Windows) or, failing that, a C++ toolchain with cmake and ninja so `shaderc-sys` can build the library from source.
|
||
|
||
A shader that fails to compile aborts the build, naming the source file and the offending line.
|
||
|
||
## Vulkan clip space
|
||
|
||
Vulkan clip space is **Y-down** by default, and its depth range is `[0, 1]` (not `[-1, 1]` as in OpenGL). The projection matrix must flip Y, or the viewport height is set negative, both are common idioms in `ash` examples. World and view space stay Y-up; only clip space differs.
|
||
|
||
## Blender import
|
||
|
||
Blender is **Z-up, right-handed**. Models exported from Blender need a coordinate swap on import: rotate −90° around X, or swap Y/Z with a sign change. Decide once where that swap happens, at export, at import, or never (by adopting the source convention), and keep it in a single place. Performing it in two places eventually produces a model that is mirrored or upside-down.
|
||
|
||
## glTF import
|
||
|
||
glTF is **Y-up, right-handed**, which matches the engine convention. It is therefore the most friction-free model format when there is a choice.
|