1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203Naga 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:
```wgsl
#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) :
```wgsl
#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 :
```wgsl
#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 :
```wgsl
#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.
## overriding functions
virtual functions can be declared with the `virtual` keyword:
```glsl
virtual fn point_light(world_position: vec3<f32>) -> vec3<f32> { ... }
```
virtual functions defined in imported modules can then be overridden using the `override` keyword:
```wgsl
#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:
```wgsl
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:
```wgsl
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:
```wgsl
#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