Naga Organised Integration Library (naga-oil
) is a crate for combining and manipulating shaders.
compose
presents a modular shader composition frameworkprune
strips shaders down to required parts
and probably less useful externally:
derive
allows importing of items from multiple shaders into a single shaderredirect
modifies a shader by substituting function calls and modifying bindings
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.
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 #import
s 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.
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 functionf
, - a module
b
that importsa
, and containing anoverride a::f
function, - a module
c
that importsa
andb
, and containing anoverride 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.
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).
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
orShaderDefValue::Uint
, ortrue
orfalse
if comparing to aShaderDef::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.
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.
- 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
- 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
- builds a single self-contained naga module out of parts of one or more existing modules
proper docs tbd