Included README.md files for published crates

crates/rustc_codegen_spirv-types/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "rustc_codegen_spirv-types"
 description = "SPIR-V backend types shared between rustc_codegen_spirv and spirv-builder"
+documentation = "https://embarkstudios.github.io/rust-gpu/api/rustc_codegen_spirv_types/index.html"
 version.workspace = true
 authors.workspace = true
 edition.workspace = true

crates/rustc_codegen_spirv-types/README.md

@@ -0,0 +1,3 @@
+# `rustc_codegen_spirv-types`
+
+SPIR-V backend types shared between `rustc_codegen_spirv` and `spirv-builder`. Please refer to [`spirv-builder`](https://crates.io/crates/spirv-builder) for more information.

crates/rustc_codegen_spirv/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "rustc_codegen_spirv"
 description = "SPIR-V code generator backend for rustc"
+documentation = "https://embarkstudios.github.io/rust-gpu/api/rustc_codegen_spirv/index.html"
 version.workspace = true
 authors.workspace = true
 edition.workspace = true

crates/rustc_codegen_spirv/README.md

@@ -0,0 +1,7 @@
+# `rustc_codegen_spirv`
+
+Compiler backend for the `SPIR-V` target architecture. This crate is not intended to be used directly. Please refer to [`spirv-builder`](https://crates.io/crates/spirv-builder) for more information.
+
+## Documentation
+
+Because of its nature, this crate can only be built using a very specific nightly version of the Rust toolchain. As such, the `docs.rs` build of the API documentation will likely fail. Please refer to the [documentation in the `rust-gpu` github repo](https://embarkstudios.github.io/rust-gpu/api/rustc_codegen_spirv/index.html) for properly built docs.

crates/spirv-builder/Cargo.toml

@@ -1,6 +1,8 @@
 [package]
 name = "spirv-builder"
 description = "Helper for building shaders with rust-gpu"
+# Documentation currently fails on docs.rs, but it doesn't have to. See https://github.com/EmbarkStudios/rust-gpu/issues/970
+documentation = "https://embarkstudios.github.io/rust-gpu/api/spirv_builder/index.html"
 version.workspace = true
 authors.workspace = true
 edition.workspace = true

crates/spirv-builder/README.md

@@ -0,0 +1,47 @@
+<!-- inline html -->
+<!-- markdownlint-disable-file MD033 -->
+# `spirv-builder`
+
+![Rust version](https://img.shields.io/badge/rust-1.66.0_nightly--2022--10--29-purple.svg)
+
+This crate gives you `SpirvBuilder`, a tool to build shaders using [rust-gpu][rustgpu].
+
+It takes care of pulling in the `SPIR-V` backend for Rust, `rustc_codegen_spirv`, and invoking a nested build using appropriate compiler options, some of which may be set using the `SpirvBuilder` API.
+
+## Example
+
+```rust
+use spirv_builder::{MetadataPrintout, SpirvBuilder};
+
+fn main() {
+    SpirvBuilder::new("my_shaders", "spirv-unknown-vulkan1.1")
+    .print_metadata(MetadataPrintout::Full)
+    .build()
+    .unwrap(); 
+}
+```
+
+This example will build a shader crate called `my_shaders`. You typically insert this code in your crate's `build.rs` that requires the shader binary. The path to the shader module's binary will be set in the `my_shaders.spv` environment variable, which you can include in your project using something along the lines of:
+
+```rust
+const SHADER: &[u8] = include_bytes!(env!("my_shaders.spv"));
+```
+
+## Building with `spirv-builder`
+
+Because of its nature, `rustc_codegen_spirv`, and therefore `spirv-builder` by extension, require the use of a very specific nightly toolchain of Rust.
+
+**The current toolchain is: `nightly-2022-10-29`.**
+
+Toolchains for previous versions of `spirv-builder`:
+
+|Version|Toolchain|
+|-|-|
+|`0.4.0`|`nightly-2022-10-29`|
+|`0.4.0-alpha.16` - `0.4.0-alpha.17`|`nightly-2022-10-01`|
+|`0.4.0-alpha.15`|`nightly-2022-08-29`|
+|`0.4.0-alpha.13` - `0.4.0-alpha.14`|`nightly-2022-04-11`|
+
+The nightly toolchain has to match *exactly*. Starting with `0.4.0-alpha.15`, the commit hash of your local toolchain is checked and you'll get a build error when building `rustc_codegen_spirv` with the wrong toolchain. If you want to experiment with different versions, this check can be omitted by defining the environment variable `RUSTGPU_SKIP_TOOLCHAIN_CHECK`<sup>since `0.4.0-alpha.16`</sup>. Keep in mind that, as `rustc_codegen_spirv` is heavily dependent on `rustc`'s internal API, diverging too much from the required toolchain will quickly result in compile errors.
+
+[rustgpu]: https://github.com/EmbarkStudios/rust-gpu/

crates/spirv-std/README.md

@@ -0,0 +1,52 @@
+# `spirv-std`
+
+Core functions, traits, and more that make up a “standard library” for SPIR-V for use in [rust-gpu](https://github.com/EmbarkStudios/rust-gpu#readme).
+
+This crate gives a `rust-gpu` shader access to the required `#![spirv(..)]` attribute, as well as povide all kinds of APIs that allows a shader to access GPU resources such as textures and buffers. Optionally, through the use of the `"glam"` feature, it includes some boilerplate trait implementations to make `glam` vector types compatible with these APIs.
+
+## 🚨 BREAKING 🚨
+
+As of `0.4.0-alpha.16`, your shaders will require a different preamble. See [this doc][migration] for more information.
+
+## Example
+
+![Sky shader](https://github.com/EmbarkStudios/rust-gpu/raw/main/docs/assets/sky.jpg)
+
+```rust
+use spirv_std::spirv;
+use glam::{Vec3, Vec4, vec2, vec3};
+
+#[spirv(fragment)]
+pub fn main(
+    #[spirv(frag_coord)] in_frag_coord: &Vec4,
+    #[spirv(push_constant)] constants: &ShaderConstants,
+    output: &mut Vec4,
+) {
+    let frag_coord = vec2(in_frag_coord.x, in_frag_coord.y);
+    let mut uv = (frag_coord - 0.5 * vec2(constants.width as f32, constants.height as f32))
+        / constants.height as f32;
+    uv.y = -uv.y;
+
+    let eye_pos = vec3(0.0, 0.0997, 0.2);
+    let sun_pos = vec3(0.0, 75.0, -1000.0);
+    let dir = get_ray_dir(uv, eye_pos, sun_pos);
+
+    // evaluate Preetham sky model
+    let color = sky(dir, sun_pos);
+
+    *output = tonemap(color).extend(1.0)
+}
+```
+
+See [source][source] for full details.
+
+## Getting started
+
+Check out [The `rust-gpu` Dev Guide][gpu-guide] for information on how to get started with using it in your projects.
+
+Experiment with rust-gpu shaders in-browser at [SHADERed][shadered].
+
+[migration]: https://github.com/EmbarkStudios/rust-gpu/blob/main/docs/src/migration-to-register-tool.md
+[source]: https://github.com/EmbarkStudios/rust-gpu/blob/main/examples/shaders/sky-shader/src/lib.rs
+[gpu-guide]: https://embarkstudios.github.io/rust-gpu/book/
+[shadered]: https://shadered.org/shaders?language=rust&sort=hot

crates/spirv-std/macros/README.md

@@ -0,0 +1,3 @@
+# `spirv-std-macros`
+
+This crate implements macros required for `spirv-std`. Most importantly, it implements the `#![spirv(..)]` attribute macro required for use in shader code. Please refer to [`spirv-std`](https://crates.io/crates/spirv-std) for more information.

crates/spirv-std/shared/README.md

@@ -0,0 +1,3 @@
+# `spirv-std-types`
+
+Small shared crate, to share definitions between [`spirv-std`](https://crates.io/crates/spirv-std) and [`spirv-std-macros`](https://crates.io/crates/spirv-std-macros). Please refer to [`spirv-std`](https://crates.io/crates/spirv-std) for more information.