naga_rust_embed/
lib.rs

1//! Translates WGSL shader code to Rust embedded in your crate via macros.
2//!
3//! This does not necessarily mean you can run your compute or render pipelines in Rust
4//! on your CPU unchanged; this is *not* a full “software renderer”. Rather, the primary goal
5//! of the library is to allow you to share simple functions between CPU and GPU code, so
6//! that the two parts of your code can agree on definitions.
7//!
8//! If you need additional control over the translation or to use a different source language,
9//! use the [`naga_rust_back`] library directly instead.
10//!
11//! # Example
12//!
13// TODO: Make this example more obviously an example of WGSL and not Rust.
14//! ```
15//! naga_rust_embed::wgsl!(r"
16//!     fn add_one(x: i32) -> i32 {
17//!         return x + 1;
18//!     }
19//! ");
20//!
21//! assert_eq!(add_one(10), 11);
22//! ```
23//!
24//! This library is in an early stage of development and many features do not work yet.
25//! Expect compilation failures and to have to tweak your code to fit.
26//! Broadly, simple mathematical functions will work, and bindings, textures, atomics,
27//! derivatives, and workgroup operations will not.
28//!
29//! [`naga_rust_back`]: https://docs.rs/naga-rust-back
30#![no_std]
31
32/// Takes the pathname of a WGSL source file, as a string literal, and embeds its Rust translation.
33///
34/// The pathname must be relative to [`CARGO_MANIFEST_DIR`].
35/// (If and when Rust proc-macros gain the ability to access files relative to the current
36/// source file, a new `include_wgsl!` macro will be provided and this `include_wgsl_mr!` will be
37/// deprecated.)
38///
39/// This macro should be used in a position where items are allowed
40/// (e.g. inside a crate, module, function body, or block).
41///
42/// ```
43/// # use naga_rust_embed::include_wgsl_mr;
44/// include_wgsl_mr!("src/example.wgsl");
45/// ```
46///
47/// If any configuration is needed, write it attribute-style before the source code literal:
48///
49/// ```
50/// # use naga_rust_embed::include_wgsl_mr;
51/// include_wgsl_mr!(
52///     global_struct = Globals,
53///     "src/example.wgsl",
54/// );
55/// ```
56///
57#[doc = include_str!("configuration_syntax.md")]
58///
59/// [`CARGO_MANIFEST_DIR`]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates
60pub use naga_rust_macros::include_wgsl_mr;
61
62/// Converts the provided WGSL string literal to Rust.
63///
64/// The macro should be given a single string literal containing the source code,
65/// and used in a position where items are allowed
66/// (e.g. inside a crate, module, function body, or block).
67///
68/// ```
69/// # use naga_rust_embed::wgsl;
70/// wgsl!("fn wgsl_hello_world() {}");
71///
72/// fn main() {
73///     wgsl_hello_world();
74/// }
75/// ```
76///
77/// If any configuration is needed, write it attribute-style before the source code literal:
78///
79/// ```
80/// # use naga_rust_embed::wgsl;
81/// wgsl!(
82///     global_struct = Globals,
83///     "var<private> foo: i32 = 10;",
84/// );
85///
86/// assert_eq!(Globals::default().foo, 10);
87/// ```
88///
89#[doc = include_str!("configuration_syntax.md")]
90pub use naga_rust_macros::wgsl;
91
92/// Support library for the generated Rust code.
93/// Do not use this directly; its contents are not guaranteed to be stable.
94pub use naga_rust_rt as rt;
naga_rust_embed/lib.rs

naga_rust_embed/
lib.rs
