readme.md

Naga Organised Integration Library (naga-oil) is a crate for combining and manipulating shaders.

• compose presents a modular shader composition framework
• prune strips shaders down to required parts

and probably less useful externally:

• derive allows importing of items from multiple shaders into a single shader
• redirect modifies a shader by substituting function calls and modifying bindings

Compose

the compose module allows construction of shaders from modules (which are themselves shaders).

it does this by treating shaders as modules, and

• building each module independently to naga IR
• creating "header" files for each supported language, which are used to build dependent modules/shaders
• making final shaders by combining the shader IR with the IR for imported modules

for multiple small shaders with large common imports, this can be faster than parsing the full source for each shader, and it allows for constructing shaders in a cleaner modular manner with better scope control.

imports

shaders can be added to the composer as modules. this makes their types, constants, variables and functions available to modules/shaders that import them. note that importing a module will affect the final shader's global state if the module defines globals variables with bindings.

modules may include a #define_import_path directive that names the module:

#define_import_path my_module

fn my_func() -> f32 {
	return 1.0;
}

alternatively the module name can be specified as an argument to Composer::add_composable_module.

shaders can then import the module with an #import directive (with an optional as name) :

#import my_module;
#import my_other_module as mod2;

fn main() -> f32 {
    let x = my_module::my_func();
    let y = mod2::my_other_func();
    return x*y;
}

or import a comma-separated list of individual items :

#import my_module::{my_func, my_const}

fn main() -> f32 {
    return my_func(my_const);
}

Some rust-style import syntax is supported, and items can be directly imported using the fully qualified item name :

#import my_package::{
    first_module::{item_one as item, item_two}, 
    second_module::submodule,
}

fn main() -> f32 {
    return item + item_two + submodule::subitem + my_package::third_module::item;
}

module::self and module::* are not currently supported.

imports can be nested - modules may import other modules, but not recursively. when a new module is added, all its #imports must already have been added. the same module can be imported multiple times by different modules in the import tree. there is no overlap of namespaces, so the same function names (or type, constant, or variable names) may be used in different modules.

note: the final shader will include the required dependencies (bindings, globals, consts, other functions) of any imported items that are used, but will not include the rest of the imported module.

overriding functions

virtual functions can be declared with the virtual keyword:

    virtual fn point_light(world_position: vec3<f32>) -> vec3<f32> { ... }

virtual functions defined in imported modules can then be overridden using the override keyword:

#import bevy_pbr::lighting as Lighting

override fn Lighting::point_light (world_position: vec3<f32>) -> vec3<f32> {
    let original = Lighting::point_light(world_position);
    let quantized = vec3<u32>(original * 3.0);
    return vec3<f32>(quantized) / 3.0;
}

overrides must either be declared in the top-level shader, or the module containing the override must be imported as an additional_import in a Composer::add_composable_module or Composer::make_naga_module call. using #import to import a module with overrides will not work due to tree-shaking.

override function definitions cause all calls to the original function in the entire shader scope to be replaced by calls to the new function, with the exception of calls within the override function itself.

the function signature of the override must match the base function.

overrides can be specified at any point in the final shader's import tree.

multiple overrides can be applied to the same function. for example, given :

• a module a containing a function f,
• a module b that imports a, and containing an override a::f function,
• a module c that imports a and b, and containing an override a::f function,

then b and c both specify an override for a::f.

the override fn a::f declared in module b may call to a::f within its body.

the override fn a::f declared in module c may call to a::f within its body, but the call will be redirected to b::f.

any other calls to a::f (within modules a or b, or anywhere else) will end up redirected to c::f.

in this way a chain or stack of overrides can be applied.

different overrides of the same function can be specified in different import branches. the final stack will be ordered based on the first occurrence of the override in the import tree (using a depth first search).

note that imports into a module/shader are processed in order, but are processed before the body of the current shader/module regardless of where they occur in that module, so there is no way to import a module containing an override and inject a call into the override stack prior to that imported override. you can instead create two modules each containing an override and import them into a parent module/shader to order them as required.

override functions can currently only be defined in wgsl.

if the override_any crate feature is enabled, then the virtual keyword is not required for the function being overridden.

languages

modules can we written in GLSL or WGSL. shaders with entry points can be imported as modules (provided they have a #define_import_path directive). entry points are available to call from imported modules either via their name (for WGSL) or via module::main (for GLSL).

final shaders can also be written in GLSL or WGSL. for GLSL users must specify whether the shader is a vertex shader or fragment shader via the ShaderType argument (GLSL compute shaders are not supported).

preprocessing

when generating a final shader or adding a composable module, a set of shader_def string/value pairs must be provided. The value can be a bool (ShaderDefValue::Bool), an i32 (ShaderDefValue::Int) or a u32 (ShaderDefValue::UInt).

these allow conditional compilation of parts of modules and the final shader. conditional compilation is performed with #if / #ifdef / #ifndef, #else and #endif preprocessor directives:

fn get_number() -> f32 {
    #ifdef BIG_NUMBER
        return 999.0;
    #else
        return 0.999;
    #endif
}

the #ifdef directive matches when the def name exists in the input binding set (regardless of value). the #ifndef directive is the reverse.

the #if directive requires a def name, an operator, and a value for comparison:

• the def name must be a provided shader_def name.
• the operator must be one of ==, !=, >=, >, <, <=
• the value must be an integer literal if comparing to a ShaderDefValue::Int or ShaderDefValue::Uint, or true or false if comparing to a ShaderDef::Bool.

shader defs can also be used in the shader source with #SHADER_DEF or #{SHADER_DEF}, and will be substituted for their value.

the preprocessor branching directives (ifdef, ifndef and if) can be prefixed with #else to create more complex control flows:

fn get_number() -> f32 {
    #ifdef BIG_NUMBER
        return 999.0;
    #else if USER_NUMBER > 1
        return f32(#USER_NUMBER)
    #else
        return 0.999;
    #endif
}

shader defs can be created or overridden at the start of the top-level shader with the #define directive:

#define USER_NUMBER 42

the created value will default to true if not specified.

error reporting

codespan reporting for errors is available using the error emit_to_string method. this requires validation to be enabled, which is true by default. Composer::non_validating() produces a non-validating composer that is not able to give accurate error reporting.

prune

• strips dead code and bindings from shaders based on specified required output. intended to be used for building reduced depth and/or normal shaders from arbitrary vertex/fragment shaders.

proper docs tbd

redirect

• redirects function calls
• wip: rebinds global bindings
• todo one day: translate between uniform, texture and buffer accesses so shaders written for direct passes can be used in indirect

proper docs tbd

derive

• builds a single self-contained naga module out of parts of one or more existing modules

proper docs tbd