2.5 KiB
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. 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.