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//! This library is in an early stage of development and many features do not work yet.
12//! Expect compilation failures, incorrect behaviors, and to have to tweak your code to fit,
13//! if you wish to use it. Broadly:
14//!
15//! * Simple mathematical functions will work.
16//! * Code involving pointers is likely to fail to compile.
17//! * Textures are supported but texture filtering is not.
18//! * Atomics, derivatives, and workgroup operations are not supported.
19//! * Pipelines involving multiple shaders (e.g. passing data from vertex to fragment)
20//!   are not automatically executed but you can build that yourself.
21//!
22//! # Example
23//!
24// TODO: Make this example more obviously an example of WGSL and not Rust.
25//! ```
26//! naga_rust_embed::wgsl!(r"
27//!     fn add_one(x: i32) -> i32 {
28//!         return x + 1;
29//!     }
30//! ");
31//!
32//! assert_eq!(add_one(10), 11);
33//! ```
34//!
35//! [`naga_rust_back`]: https://docs.rs/naga-rust-back
36#![no_std]
37
38/// Takes the pathname of a WGSL source file, as a string literal, and embeds its Rust translation.
39///
40/// The pathname must be relative to [`CARGO_MANIFEST_DIR`].
41/// (If and when Rust proc-macros gain the ability to access files relative to the current
42/// source file, a new `include_wgsl!` macro will be provided and this `include_wgsl_mr!` will be
43/// deprecated.)
44///
45/// This macro should be used in a position where items are allowed
46/// (e.g. inside a crate, module, function body, or block).
47///
48/// ```
49/// # use naga_rust_embed::include_wgsl_mr;
50/// include_wgsl_mr!("src/example.wgsl");
51/// ```
52///
53/// If any configuration is needed, write it attribute-style before the source code literal:
54///
55/// ```
56/// # use naga_rust_embed::include_wgsl_mr;
57/// include_wgsl_mr!(
58///     global_struct = Globals,
59///     "src/example.wgsl",
60/// );
61/// ```
62///
63#[doc = include_str!("configuration_syntax.md")]
64///
65/// [`CARGO_MANIFEST_DIR`]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates
66pub use naga_rust_macros::include_wgsl_mr;
67
68/// Converts the provided WGSL string literal to Rust.
69///
70/// The macro should be given a single string literal containing the source code,
71/// and used in a position where items are allowed
72/// (e.g. inside a crate, module, function body, or block).
73///
74/// ```
75/// # use naga_rust_embed::wgsl;
76/// wgsl!("fn wgsl_hello_world() {}");
77///
78/// fn main() {
79///     wgsl_hello_world();
80/// }
81/// ```
82///
83/// If any configuration is needed, write it attribute-style before the source code literal:
84///
85/// ```
86/// # use naga_rust_embed::wgsl;
87/// wgsl!(
88///     global_struct = Globals,
89///     "var<private> foo: i32 = 10;",
90/// );
91///
92/// assert_eq!(Globals::new().foo, naga_rust_embed::rt::Scalar(10));
93/// ```
94///
95#[doc = include_str!("configuration_syntax.md")]
96pub use naga_rust_macros::wgsl;
97
98/// Support library for the generated Rust code.
99/// Do not use this directly; its contents are not guaranteed to be stable.
100pub use naga_rust_rt as rt;
naga_rust_embed/lib.rs

naga_rust_embed/
lib.rs
