#wgsl

macro wgsl_ln

Experimental crate for writing wgsl in rust!

3 unstable releases

0.2.1 Jul 13, 2024
0.2.0 Jul 11, 2024
0.1.0 Jul 10, 2024

#376 in Procedural macros

44 downloads per month

MIT/Apache

23KB
319 lines

wgsl_ln

Crates.io Docs

Experimental crate for writing wgsl in rust!

The wgsl! macro

The wgsl! macro converts normal rust tokens into a wgsl &'static str, similar to stringify!. This also validates the wgsl string using naga. Errors will be reported with the correct span.

pub static MANHATTAN_DISTANCE: &str = wgsl!(
    fn manhattan_distance(a: vec2<f32>, b: vec2<f32>) -> f32 {
        return abs(a.x - b.x) + abs(a.y - b.y);
    }
);

Most errors can be caught at compile time.

pub static MANHATTAN_DISTANCE: &str = wgsl!(
    fn manhattan_distance(a: vec2<f32>, b: vec2<f32>) -> f32 {
        // not allowed in wgsl
        abs(a.x - b.x) + abs(a.y - b.y)
    }
);

The #[wgsl_export(name)] macro

Export a wgsl item (function, struct, etc) via wgsl_export. Must have the same name as the exported item.

#[wgsl_export(manhattan_distance)]
pub static MANHATTAN_DISTANCE: &str = wgsl!(
    fn manhattan_distance(a: vec2<f32>, b: vec2<f32>) -> f32 {
        return abs(a.x - b.x) + abs(a.y - b.y);
    }
);

Using an exported item

pub static MANHATTAN_DISTANCE_TIMES_FIVE: &str = wgsl!(
    fn manhattan_distance_times_five(a: vec2<f32>, b: vec2<f32>) -> f32 {
        return #manhattan_distance(a, b) * 5.0;
    }
);

#manhattan_distance copies the manhattan_distance function into the module, making it usable. You can specify multiple instances of #manhattan_distance or omit the # in later usages.

Ok what's actually going on?

wgsl_export creates a macro_rules! macro that pastes itself into the wgsl! macro. The macro is #[doc(hidden)] and available in the crate root, i.e. crate::__wgsl_paste_manhattan_distance!.

You don't need to import anything to use items defined in your crate, for other crates, you might want to blanket import the crate root.

mod my_shaders {
    pub use external_shader_defs::*;

    pub static MAGIC: &str = wgsl!(
        fn magic() -> f32 {
            return #magic_number();
        }
    )
}
pub use my_shaders::MAGIC;

naga_oil support

Enable the naga_oil feature to enable limited naga_oil support:

  • Treat #preprocessor_macro_name as tokens instead of imports.
    • #define_import_path
    • #import
    • #if
    • #ifdef
    • #ifndef
    • #else
    • #endif

These values can no longer be imported.

  • Checks will be disabled when naga_oil preprocessor macros are detected.

License

License under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contribution

Contributions are welcome!

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~6–14MB
~171K SLoC