Crate naga_to_tokenstream

Expand description

§Naga to TokenStream

This library takes a Naga module and produces a proc_macro::TokenStream giving information about the module. It is intended for use in other libraries which process a shader at compile time, for example in a proc macro or build script, to expose a large collection of useful information to the Rust compiler (and hence programmer) about items in the module.

§Generated Items

This module generates the following items:

A Rust constant for each WGSL const with a type representable in Rust.
- If glam is enabled, then Glam types will be used to represent vectors and matrices.
A Rust struct for each WGSL struct with types representable in Rust.
- If encase is enabled, these structs will derive from encase::ShaderType.
A Rust module for each entry point, containing constants giving their name, workgroup size, etc.
A Rust module for each bind group, containing constants giving their name and bindings, and a type redefinition of their generated Rust type if applicable.
- If naga is enabled, these modules will also contain naga::AddressSpace information.

As an example, take the following shader, written in 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() {
    ...
}

Then this crate would generate something like the following:


/// 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 = "...";

Modules§

constants
Methods for converting sets of naga::Constants to token streams.
entry_points
Methods for converting sets of naga::EntryPoints to token streams.
globals
Methods for converting sets of naga::GlobalVariables to token streams.
types
Methods for converting sets of naga::Types to token streams.

Structs§

ModuleToTokensConfig
The configuration required to create a token stream describing a module.

Traits§