1.8 KiB
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; 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.