Provides a macro for including a wgsl file, using the naga-oil
preprocessor at compile time.
Running the naga-oil
preprocessor at runtime increases startup time for apps, and also leads to shader errors only being reported at runtime. Running it at compile time allows the preprocessor cost to be spent before the user runs the app, and allows the Rust compiler to report shader errors at compile time.
This crate also uses naga-to-tokenstream
to expose a bunch of information about the types, constants and globals within a shader to Rust. This allows for de-duplication of code, where a constant from a shader module can be used as a Rust constant, and structs defined in shaders to be used as Rust structs.
-
Shader errors are reported at compile time
-
Bonus syntax added to wgsl by the
naga-oil
preprocessor likeinclude
s and method overriding. -
Types, constants and globals are exposed to Rust, allowing code to refer to things in the shader without duplicating code.
-
Support for
glam
andencase
with the corresponding feature flags. -
Support for wgsl minification using the
wgsl-minifier
crate with theminify
feature flag, further reducing startup time.
Including a shader module follows similar syntax to the Rust include_str
or include_bytes
macros, where a path is given relative to the containing folder of the Rust file that the macro is invoked from. However the include_wgsl_oil
macro generates a large number of objects, so it is instead invoked as an attribute to a module that you would like it to populate with shader information:
#[include_wgsl_oil::include_wgsl_oil("path/to/shader.wgsl")]
mod my_shader {}
// The preprocessed sourcecode constant string can be found in the `SOURCE` constant at the root of the module:
println!("shader source: {}", my_shader::SOURCE);
Shader imports are processed both relative to the importing file, and relative to the root of the crate source folder, and shaders may import any other shaders so long as there is no circular dependency on imports between files.
For example, if your crate directory structure looks like the following:
my-crate/
├─ src/
│ ├─ submodule/
│ │ ├─ subsubmodule/
│ │ │ ├─ extra_special_shader.wgsl
│ │ ├─ special_shader.wgsl
│ │ ├─ mod.rs
│ ├─ general_shader.wgsl
│ ├─ main.rs
├─ Cargo.toml
Then special_shader.wgsl
is able to include general_shader.wgsl
with either of the following lines:
#import general_shader.wgsl as GeneralShader
#import ../general_shader.wgsl as GeneralShader
GeneralShader::foo();
And extra_special_shader.wgsl
is able to include special_shader.wgsl
with either of the following lines:
#import ../special_shader.wgsl as SpecialShader
#import submodule/special_shader.wgsl as SpecialShader
SpecialShader::foo();
Structs defined in your shader can be exported as an equivalent Rust struct. To do this, each of the fields of the struct must be representable, for example by enabling the glam
feature to represent vectors and matrices, and then your struct definition must be prepended with an @export
tag, as follows:
@export struct MyStruct {
foo: u32,
bar: i32
}
Then, in your Rust file, you can do the following:
#[include_wgsl_oil::include_wgsl_oil("path/to/shader.wgsl")]
mod my_shader { }
let my_instance = my_shader::types::MyStruct {
foo: 12,
bar: -7
};
The encase
feature on this crate makes every exported struct derive encase::ShaderType
. Note that this may invalidate exported structs, as some types (such as bool
s) cannot be encoded with encase
, however it is assumed that the only structs that you would want to export are structs that your program shares between host and GPU, and so should be encodable.
The following definitions are added to pass information from Rust to your shaders:
__DEBUG
is defined astrue
iff your project is being built in debug mode.
So in your shaders included by this crate, you can do something like the following:
#if __DEBUG
do_something_debug();
#endif
For a full list of the items generated when including a module with this macro, see the naga-to-tokenstream
documentation.