@@ -31,40 +31,46 @@ There are two main ways to setup your shader project locally.
3131 flags in your cargo configuration to enable you to run ` cargo build ` in your
3232 shader crate.
3333
34-
3534### Using ` spirv-builder `
3635If you're writing a bigger application and you want to integrate SPIR-V shader
3736crates to display, it's recommended to use ` spirv-builder ` in a build script.
3837
39381 . Copy the [ ` rust-toolchain ` ] file to your project. (You must use the same
40- version of Rust as ` rust-gpu ` .)
39+ version of Rust as ` rust-gpu ` . Utimately, the build will fail with a nice
40+ error message when you don't use the exact same version)
41412 . Reference ` spirv-builder ` in your Cargo.toml:
4242 ``` toml
4343 [build-dependencies ]
44- spirv-builder = { git = " https://github.com/EmbarkStudios/rust-gpu " }
44+ spirv-builder = " 0.4 "
4545 ```
46- (we currently do not publish spirv-builder on crates.io)
46+ All dependent crates are published on [ crates.io](https://crates.io).
47473. Create a `build.rs` in your project root.
4848
4949# ### `build.rs`
50- Paste the following into the `main` for your build script.
50+ Paste the following into ` build.rs`
5151
5252```rust,no_run
53- SpirvBuilder::new(path_to_shader, target)
54- .print_metadata(MetadataPrintout::Full)
55- .build()?;
53+ use spirv_builder::{MetadataPrintout, SpirvBuilder};
54+
55+ fn main() {
56+ SpirvBuilder::new(shader_crate, target)
57+ .print_metadata(MetadataPrintout::Full)
58+ .build()
59+ .unwrap();
60+ }
5661```
5762
58- The values available for the ` target ` parameter are available
63+ Substituting ` shader_crate ` with a relative path to your shader crate. The values available for the ` target ` parameter are available
5964[ here] ( ./platform-support.md ) . For example, if building for vulkan 1.1, use
6065` "spirv-unknown-vulkan1.1" ` .
6166
6267The ` SpirvBuilder ` struct has numerous configuration options available, see
63- rustdoc for documentation.
68+ [ documentation] ( https://embarkstudios.github.io/rust-gpu/api/spirv_builder/struct.SpirvBuilder.html ) .
6469
6570#### ` main.rs `
71+ The following will directly include the shader module binary into your application.
6672``` rust,no_run
67- const SHADER: &[u8] = include_bytes!(env!("<shader_name >.spv"));
73+ const SHADER: &[u8] = include_bytes!(env!("<shader_crate >.spv"));
6874```
6975
7076> ** Note** If your shader name contains hyphens, the name of environment variable will be the name with hyphens changed to underscores.
@@ -100,7 +106,7 @@ necessary flags. Before you can do that however you need to do a couple of steps
100106first to build the compiler backend.
101107
1021081 . Clone the ` rust-gpu ` repository
103- 3 . ` cargo build --release ` in ` rust-gpu ` .
109+ 2 . ` cargo build --release ` in ` rust-gpu ` .
104110
105111Now you should have a ` librustc_codegen_spirv ` dynamic library available in
106112` target/release ` . You'll need to keep this somewhere stable that you can
@@ -134,3 +140,26 @@ Now you should have `<project_name>.spv` SPIR-V file in `target/debug` that you
134140can give to a renderer.
135141
136142[ `rust-toolchain` ] : https://github.com/EmbarkStudios/rust-gpu/blob/main/rust-toolchain
143+
144+ ## Writing your first shader
145+
146+ Configure your shader crate as a ` "dylib" ` type crate, and add ` spirv-std ` to its dependencies. The following example also enables the ` glam ` vector library.
147+
148+ ``` toml
149+ [dependencies ]
150+ spirv-std = { version = " 0.4" features = [" glam"
151+ ```
152+
153+ Make sure your shader code uses the ` no_std ` attribute and makes the ` spirv ` attribute visibile in the global scope. Then, you're ready to write your first shader. Here's a very simple fragment shader called ` main_fs ` as an example that outputs the color red:
154+
155+ ``` rust,norun
156+ #![no_std]
157+
158+ use spirv_std::spirv;
159+ use spirv_std::glam::{vec4, Vec4};
160+
161+ #[spirv(fragment)]
162+ pub fn main_fs(output: &mut Vec4) {
163+ *output = vec4(1.0, 0.0, 0.0, 1.0);
164+ }
165+ ```
0 commit comments