Naga to TokenStream

此库接受一个 Naga 模块并生成一个 proc_macro::TokenStream，提供有关模块的信息。它旨在用于其他库中，这些库在编译时处理着色器，例如在 proc macro 或构建脚本中，以向 Rust 编译器（以及程序员）提供有关模块中项的大量有用信息。

生成的项

此模块生成以下项

• 对于每个可由 Rust 表示的 WGSL const，生成一个 Rust 常量。
  • 如果启用了 glam，则使用 Glam 类型来表示向量和矩阵。
• 对于每个可由 Rust 表示的 WGSL struct，生成一个 Rust struct。
  • 如果启用了 encase，则这些结构体会从 encase::ShaderType 继承。
• 为每个入口点生成一个 Rust 模块，其中包含提供其名称、工作组大小等的常量。
• 为每个绑定点生成一个 Rust 模块，其中包含提供其名称和绑定的常量，如果适用，还包含其生成的 Rust 类型的类型重新定义。
  • 如果启用了 naga，则这些模块还将包含 naga::AddressSpace 信息。

以下是一个示例，该着色器是用 wgsl 编写的

const ELEMENTS_LENGTH: u32 = 128u;

struct Foo {
    a: i32,
    b: vec4<u32>,
    c: vec4<u32>,
}
struct Bar {
    size: u32,
    elements: array<vec2<bool>, ELEMENTS_LENGTH>,
    foos: array<Foo>
}

@group(0) @binding(0) var<storage> bar: Bar;

@compute
@workgroup_size(256,1,1)
fn main() {
    ...
}

然后，此 crate 会生成类似以下内容

/// Equivalent Rust definitions of the constants defined in this module
pub mod constants {
    pub mod ELEMENTS_LENGTH {
        pub const NAME: &'static str = "ELEMENTS_LENGTH";
        pub const VALUE: u32 = 128;
    }
}
/// Equivalent Rust definitions of the types defined in this module
pub mod types {
    // `encase::ShaderType` is only derived if the `encase` feature is enabled.
    #[derive(Debug, PartialEq, Clone, encase::ShaderType)] 
    pub struct Foo {
        a: i32,
        // `glam` objects are only generated if the `glam` feature is enabled.
        b: glam::u32::UVec4, 
        c: glam::u32::UVec4,
    }
    #[derive(Debug, PartialEq, Clone, encase::ShaderType)]
    pub struct Bar {
        size: u32,
        elements: [glam::bool::BVec2; 128],
        #[size(runtime)] // Only added if the `encase` feature is enabled.
        foos: Vec<Foo>,
    }
}
pub mod globals {
    /// Information about the `bar` global variable within the shader module.
    pub mod bar {
        pub const NAME: &'static str = "bar";
        pub type Ty = types::Bar;
        pub const SPACE: naga::AddressSpace = naga::AddressSpace::Storage {
            access: naga::StorageAccess::LOAD,
        }
        pub mod binding {
            pub const GROUP: u32 = 0u32;
            pub const BINDING: u32 = 0u32;
        }
    }
}
/// Information about the entry points within the module.
pub mod entry_points {
    pub mod main {
        pub const NAME: &'static str = "main";

        /// The sourcecode for the shader, as a constant string, excluding any other entry points. 
        /// This is useful when the `minify` feature is enabled for this crate, as it allows more aggressive 
        /// minification to be performed with the knowledge of the specific entry point that will be used.
        pub const EXCLUSIVE_SOURCE: &'static str = "...";
    }
}
/// The sourcecode for the shader, as a constant string.
pub const SOURCE: &'static str = "...";