包含 WGSL-oil

提供宏，用于在编译时包含 wgsl 文件，使用 naga-oil 预处理器。

动机

在运行时运行 naga-oil 预处理器会增加应用程序的启动时间，并且只在运行时报告着色器错误。在编译时运行它可以在用户运行应用程序之前花费预处理器成本，并允许 Rust 编译器在编译时报告着色器错误。

此包还使用 naga-to-tokenstream 来公开着色器中类型、常量和全局变量的大量信息。这使得可以进行代码去重，其中着色器模块中的常量可以用作 Rust 常量，并且在着色器中定义的结构可以用作 Rust 结构。

功能

• 着色器错误在编译时报告

• naga-oil 预处理器添加到 wgsl 中的语法，如 include 和方法重写。

• 类型、常量和全局变量公开给 Rust，允许代码在不重复代码的情况下引用着色器中的事物。

• 支持 glam 和 encase，带有相应的功能标志。

• 支持使用 wgsl-minifier 包的 minify 功能标志进行 wgsl 最小化，进一步减少启动时间。

入门指南

包含着色器模块的语法类似于 Rust 的 include_str 或 include_bytes 宏，其中给出相对于宏调用的 Rust 文件的包含文件夹的路径。然而，include_wgsl_oil 宏会生成大量的对象，因此它被作为您希望它用着色器信息填充的模块的属性调用。

#[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); 

导入

着色器导入既相对于导入文件处理，也相对于包源文件夹的根处理，只要文件之间的导入没有循环依赖，着色器就可以导入任何其他着色器。

例如，如果您的包目录结构如下所示

my-crate/
├─ src/
│  ├─ submodule/
│  │  ├─ subsubmodule/
│  │  │  ├─ extra_special_shader.wgsl
│  │  ├─ special_shader.wgsl
│  │  ├─ mod.rs
│  ├─ general_shader.wgsl
│  ├─ main.rs
├─ Cargo.toml

然后 special_shader.wgsl 可以通过以下任一行的方式包含 general_shader.wgsl

#import general_shader.wgsl as GeneralShader
#import ../general_shader.wgsl as GeneralShader

GeneralShader::foo();

并且 extra_special_shader.wgsl 可以通过以下任一行的方式包含 special_shader.wgsl

#import ../special_shader.wgsl as SpecialShader
#import submodule/special_shader.wgsl as SpecialShader

SpecialShader::foo();

导出类型

在您的着色器中定义的结构可以被导出为等效的Rust结构。为此，结构体中的每个字段都必须可表示，例如，通过启用glam功能来表示向量和矩阵，然后您的结构定义必须前置一个 @export 标签，如下所示

@export struct MyStruct {
    foo: u32,
    bar: i32
}

然后，在您的Rust文件中，您可以执行以下操作

#[include_wgsl_oil::include_wgsl_oil("path/to/shader.wgsl")]
mod my_shader { }

let my_instance = my_shader::types::MyStruct {
    foo: 12,
    bar: -7
};

此crate上的 encase 功能使每个导出的结构都继承自 encase::ShaderType。请注意，这可能会使导出的结构无效，因为某些类型（如 bool）无法用 encase 进行编码，但是假设您想要导出的唯一结构是程序在主机和GPU之间共享的结构，因此应该是可编码的。

定义

以下定义被添加到从Rust传递信息到您的着色器

• __DEBUG 被定义为 true 当且仅当您的项目是以调试模式构建时。

因此，在由这个crate包含的着色器中，您可以执行以下操作

#if __DEBUG
    do_something_debug();
#endif

生成的项目

要获取包含此宏的模块时生成的项目的完整列表，请参阅 naga-to-tokenstream 文档。