`simvx.graphics.materials.shader_compiler`¶

GLSL to SPIR-V: precompiled sets, a per-user cache, and glslc.

func:: compile_shader (a GLSL file) and :func:compile_glsl (GLSL text, which is what a ShaderMaterial or a PostProcessEffect compiles) find the SPIR-V in these places, in order:

For a file, the precompiled set beside it, <source dir>/spirv/. The graphics wheel ships every engine shader and every permutation the engine can request there (simvx.graphics.shaders.variants).
The game’s shader bundle, precompiled_shaders/ beside the running game’s main module (:func:game_shader_bundle). An export writes it, and the examples wheel ships one beside every example with GLSL of its own, so a player needs no compiler.
The per-user shader cache (:func:shader_cache_dir), which holds whatever was compiled on the local machine before.
glslc, which compiles into that cache.

Every lookup is by a key hashed from the source, every file it #include\ s, the defines and the compile options, so an edited source never reads a stale binary: an edit changes the key, and the old file is simply never asked for. The cache key adds the compiler’s version. Nothing is ever written beside the source, so a read-only install works, and a cache write is a temporary file renamed into place, so concurrent processes never see a torn one.

Standard library only at module level: the wheel’s build hook loads this file by path, without importing :mod:simvx.graphics.

Module Contents¶

Functions¶

`resolve_includes`	Recursively resolve `#include "file.glsl"` directives in GLSL source.
`shader_key`	The hash naming src’s SPIR-V: its stage, defines, options and source closure.
`source_key`	func: `shader_key` for GLSL text, as if it were a file called name with no includes.
`spirv_name`	The file name of a compiled permutation: readable, and unique by key.
`shader_cache_dir`	The directory shaders compiled at run time are cached in.
`game_shader_bundle`	`precompiled_shaders/` beside the running game’s main module, when there is one.
`compile_shader`	The SPIR-V for the GLSL file src compiled with defines, as a file path.
`compile_glsl`	The SPIR-V for GLSL text, found or compiled the way :func:`compile_shader` does.
`precompile_shaders`	Compile every `(file name, defines)` in variants into out_dir under its shipped name.
`precompile_sources`	Compile every `(file name, GLSL text)` into out_dir, named as :func:`compile_glsl` looks it up.

Data¶

`__all__`
`log`
`TARGET_ENV`
`PRECOMPILED_DIR_NAME`
`BUNDLE_DIR_NAME`
`CACHE_DIR_ENV`
`GLSLC_INSTALL`

API¶

simvx.graphics.materials.shader_compiler.__all__¶: [‘BUNDLE_DIR_NAME’, ‘CACHE_DIR_ENV’, ‘GLSLC_INSTALL’, ‘PRECOMPILED_DIR_NAME’, ‘TARGET_ENV’, ‘compile…

simvx.graphics.materials.shader_compiler.log¶: ‘getLogger(…)’

simvx.graphics.materials.shader_compiler.TARGET_ENV¶: ‘vulkan1.2’

simvx.graphics.materials.shader_compiler.PRECOMPILED_DIR_NAME¶: ‘spirv’

simvx.graphics.materials.shader_compiler.BUNDLE_DIR_NAME¶: ‘precompiled_shaders’

simvx.graphics.materials.shader_compiler.CACHE_DIR_ENV¶: ‘SIMVX_SHADER_CACHE_DIR’

simvx.graphics.materials.shader_compiler.GLSLC_INSTALL¶: ‘Install glslc, the GLSL compiler from shaderc: on Windows and macOS with the LunarG Vulkan SDK (http…’

simvx.graphics.materials.shader_compiler.resolve_includes(source: str, base_dir: pathlib.Path, _seen: set[str] | None = None) → str¶

Recursively resolve #include "file.glsl" directives in GLSL source.

Args: source: GLSL source text. base_dir: Directory to resolve relative include paths against. _seen: Internal set tracking already-included files to prevent cycles.

Returns: Processed GLSL source with all includes inlined.

Raises: FileNotFoundError: If an included file does not exist. RuntimeError: If a circular include is detected.

simvx.graphics.materials.shader_compiler.shader_key(src: pathlib.Path, defines: tuple[str, ...] = ()) → str¶

The hash naming src’s SPIR-V: its stage, defines, options and source closure.

The file’s stem is left out, so the same source under another name shares its entry.

simvx.graphics.materials.shader_compiler.source_key(source: str, name: str, defines: tuple[str, ...] = ()) → str¶

Func:: shader_key for GLSL text, as if it were a file called name with no includes.

simvx.graphics.materials.shader_compiler.spirv_name(src_name: str, defines: tuple[str, ...], key: str) → str¶

The file name of a compiled permutation: readable, and unique by key.

Valued defines keep their value (NAME=4 becomes NAME_4), so a name says which permutation it holds.

simvx.graphics.materials.shader_compiler.shader_cache_dir() → pathlib.Path¶

The directory shaders compiled at run time are cached in.

$SIMVX_SHADER_CACHE_DIR when set, else [rendering] shader_cache_dir from the project’s simvx.toml, else shaders under the platform’s per-user cache directory ($XDG_CACHE_HOME/simvx/shaders on Linux, ~/Library/Caches/simvx/shaders on macOS, %LOCALAPPDATA%\simvx\shaders on Windows).

simvx.graphics.materials.shader_compiler.game_shader_bundle() → pathlib.Path | None¶

precompiled_shaders/ beside the running game’s main module, when there is one.

The main module is the script python was given, the file an example runner or an export runs as __main__, or a frozen build’s entry script.

simvx.graphics.materials.shader_compiler.compile_shader(src: pathlib.Path, out: pathlib.Path | None = None, *, force: bool = False, defines: tuple[str, ...] = ()) → pathlib.Path¶

The SPIR-V for the GLSL file src compiled with defines, as a file path.

Looks in the precompiled set beside src, the game’s shader bundle and the user shader cache, and compiles with glslc into that cache only when none has it. Never writes beside src.

Args: src: Path to the GLSL source file. out: Compile to exactly this path instead, always with glslc, bypassing every lookup. force: Compile with glslc into the cache even when a lookup would hit. defines: Preprocessor macros (NAME or NAME=VALUE) passed to glslc as -D flags. The engine’s own permutations are listed in simvx.graphics.shaders.variants.

Returns: Path to the compiled SPIR-V file.

Raises: RuntimeError: If compilation fails, with glslc’s diagnostics, or if the shader has to be compiled and glslc is not on PATH, saying how to install it.

simvx.graphics.materials.shader_compiler.compile_glsl(source: str, name: str, *, defines: tuple[str, ...] = (), force: bool = False) → pathlib.Path¶

The SPIR-V for GLSL text, found or compiled the way :func:compile_shader does.

name is the file name the text is compiled as, whose suffix is the stage (shader_material.frag). It is part of the name the SPIR-V is stored under, so the tool that builds a bundle and the renderer that reads it must pass the same one; ShaderMaterial and PostProcessEffect each use a fixed name. The text must have its #include directives already resolved.

simvx.graphics.materials.shader_compiler.precompile_shaders(shader_dir: pathlib.Path, out_dir: pathlib.Path, variants: collections.abc.Iterable[tuple[str, tuple[str, ...]]], *, glslc: str = 'glslc', jobs: int | None = None) → list[pathlib.Path]¶

Compile every (file name, defines) in variants into out_dir under its shipped name.

What the graphics wheel’s build hook and tools/compile_shaders.py run. Compiles in parallel, and raises once with every failure listed rather than stopping at the first, so a build reports all of its broken shaders.

Raises: RuntimeError: If any variant fails to compile or glslc cannot be run.

simvx.graphics.materials.shader_compiler.precompile_sources(sources: collections.abc.Iterable[tuple[str, str]], out_dir: pathlib.Path, *, glslc: str = 'glslc', jobs: int | None = None) → list[pathlib.Path]¶

Compile every (file name, GLSL text) into out_dir, named as :func:compile_glsl looks it up.

What building a game’s shader bundle runs.

Raises: RuntimeError: If any source fails to compile or glslc cannot be run.

simvx.graphics.materials.shader_compiler¶

Module Contents¶

Functions¶

Data¶

API¶

`simvx.graphics.materials.shader_compiler`¶