Refactor Documentation into a docs folder (#7202)

docs/api-specs/ray_tracing.md

@@ -0,0 +1,202 @@
+# Ray Tracing Extensions
+
+🧪Experimental🧪
+
+`wgpu` supports an experimental version of ray tracing which is subject to change. The extensions allow for acceleration structures to be created and built (with
+`Features::EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE` enabled) and interacted with in shaders. Currently `naga` only supports ray queries
+(accessible with `Features::EXPERIMENTAL_RAY_QUERY` enabled in wgpu).
+
+**Note**: The features documented here may have major bugs in them and are expected to be subject
+to breaking changes, suggestions for the API exposed by this should be posted on [the ray-tracing issue](https://github.com/gfx-rs/wgpu/issues/1040).
+Large changes may mean that this documentation may be out of date.
+
+***This is not*** an introduction to raytracing, and assumes basic prior knowledge, to look at the fundamentals look at
+an [introduction](https://developer.nvidia.com/blog/introduction-nvidia-rtx-directx-ray-tracing/).
+
+## `wgpu`'s raytracing API:
+
+The documentation and specific details of the functions and structures provided
+can be found with their definitions.
+
+A [`Blas`] can be created with [`Device::create_blas`].
+A [`Tlas`] can be created with [`Device::create_tlas`].
+
+Unless one is planning on using the unsafe building API (not recommended for beginners) a [`Tlas`] should be put inside
+a [`TlasPackage`]. After that a reference to the [`Tlas`] can be retrieved by calling [`TlasPackage::tlas`].
+This reference can be placed in a bind group to be used in a shader. A reference to a [`Blas`] can
+be used to create [`TlasInstance`] alongside a transformation matrix, a custom index
+(this can be any data that should be given to the shader on a hit) which only the first 24
+bits may be set, and a mask to filter hits in the shader.
+
+A [`Blas`] must be built in either the same build as any [`Tlas`] it is used to build or an earlier build call.
+Before a [`Tlas`] is used in a shader it must
+- have been built
+- have all [`Blas`]es that it was last built with to have last been built in either the same build as
+  this [`Tlas`] or an earlier build call.
+
+[`Device::create_blas`]: https://wgpu.rs/doc/wgpu/struct.Device.html#method.create_blas
+[`Device::create_tlas`]: https://wgpu.rs/doc/wgpu/struct.Device.html#method.create_tlas
+[`Tlas`]: https://wgpu.rs/doc/wgpu/struct.Tlas.html
+[`Blas`]: https://wgpu.rs/doc/wgpu/struct.Blas.html
+[`TlasInstance`]: https://wgpu.rs/doc/wgpu/struct.TlasInstance.html
+[`TlasPackage`]: https://wgpu.rs/doc/wgpu/struct.TlasPackage.html
+[`TlasPackage::tlas`]: https://wgpu.rs/doc/wgpu/struct.TlasPackage.html#method.tlas
+
+## `naga`'s raytracing API:
+
+`naga` supports ray queries (also known as inline raytracing) only. Ray tracing pipelines are currently unsupported.
+Naming is mostly taken from vulkan.
+
+```wgsl
+// - Initializes the `ray_query` to check where (if anywhere) the ray defined by `ray_desc` hits in `acceleration_structure
+rayQueryInitialize(rq: ptr<function, ray_query>, acceleration_structure: acceleration_structure, ray_desc: RayDesc)
+
+// - Traces the ray in the initialized ray_query (partially) through the scene.
+// - Returns true if a triangle that was hit by the ray was in a `Blas` that is not marked as opaque.
+// - Returns false if all triangles that were hit by the ray were in `Blas`es that were marked as opaque.
+// - The hit is considered `Candidate` if this function returns true, and the hit is considered `Committed` if
+//   this function returns false.
+// - A `Candidate` intersection interrupts the ray traversal.
+// - A `Candidate` intersection may happen anywhere along the ray, it should not be relied on to give the closest hit. A
+//   `Candidate` intersection is to allow the user themselves to decide if that intersection is valid*. If one wants to get
+//   the closest hit a `Committed` intersection should be used.
+// - Calling this function multiple times will cause the ray traversal to continue if it was interrupted by a `Candidate`
+//   intersection.
+rayQueryProceed(rq: ptr<function, ray_query>) -> bool
+
+// - Generates a hit from procedural geometry at a particular distance.
+rayQueryGenerateIntersection(hit_t: f32)
+
+// - Commits a hit from triangular non-opaque geometry.
+rayQueryConfirmIntersection()
+
+// - Aborts the query.
+rayQueryTerminate()
+
+// - Returns intersection details about a hit considered `Committed`.
+rayQueryGetCommittedIntersection(rq: ptr<function, ray_query>) -> RayIntersection
+
+// - Returns intersection details about a hit considered `Candidate`.
+rayQueryGetCandidateIntersection(rq: ptr<function, ray_query>) -> RayIntersection
+```
+
+> [!CAUTION]
+>
+> ### ⚠️Undefined behavior ⚠️:
+> - Calling `rayQueryGetCommittedIntersection` or `rayQueryGetCandidateIntersection` when `rayQueryProceed` has not been
+> called on this ray query since it was initialized (or if the ray query has not been previously initialized).
+> - Calling `rayQueryGetCommittedIntersection` when `rayQueryProceed`'s latest return on this ray query is considered
+>   `Candidate`.
+> - Calling `rayQueryGetCandidateIntersection` when `rayQueryProceed`'s latest return on this ray query is considered
+>   `Committed`.
+> - Calling `rayQueryProceed` when `rayQueryInitialize` has not previously been called on this ray query
+> - Calling `rayQueryGenerateIntersection` on a query with last intersection kind not being
+>   `RAY_QUERY_INTERSECTION_AABB`,
+> - Calling `rayQueryGenerateIntersection` with `hit_t` outside of `RayDesc::t_min .. RayDesc::t_max` range.
+>   or when `rayQueryProceed`'s latest return on this ray query is not considered `Candidate`.
+> - Calling `rayQueryConfirmIntersection` on a query with last intersection kind not being
+>   `RAY_QUERY_INTERSECTION_TRIANGLE`,
+>   or when `rayQueryProceed`'s latest return on this ray query is not considered `Candidate`.
+>
+> *this is only known undefined behaviour, and will be worked around in the future.
+
+```wgsl
+struct RayDesc {
+    // Contains flags to use for this ray (e.g. consider all `Blas`es opaque)
+    flags: u32,
+    // If the bitwise and of this and any `TlasInstance`'s `mask` is not zero then the object inside
+    // the `Blas` contained within that `TlasInstance` may be hit.
+    cull_mask: u32,
+    // Only points on the ray whose t is greater than this may be hit.
+    t_min: f32,
+    // Only points on the ray whose t is less than this may be hit.
+    t_max: f32,
+    // The origin of the ray.
+    origin: vec3<f32>,
+    // The direction of the ray, t is calculated as the length down the ray divided by the length of `dir`.
+    dir: vec3<f32>,
+}
+
+struct RayIntersection {
+    // the kind of the hit, no other member of this structure is useful if this is equal
+    // to constant `RAY_QUERY_INTERSECTION_NONE`.
+    kind: u32,
+    // Distance from starting point, measured in units of `RayDesc::dir`.
+    t: f32,
+    // Corresponds to `instance.custom_data` where `instance` is the `TlasInstance`
+    // that the intersected object was contained in.
+    instance_custom_data: u32,
+    // The index into the `TlasPackage` to get the `TlasInstance` that the hit object is in
+    instance_index: u32,
+    // The offset into the shader binding table. Currently, this value is always 0.
+    sbt_record_offset: u32,
+    // The index into the `Blas`'s build descriptor (e.g. if `BlasBuildEntry::geometry` is
+    // `BlasGeometries::TriangleGeometries` then it is the index into that contained vector).
+    geometry_index: u32,
+    // The object hit's index into the provided buffer (e.g. if the object is a triangle
+    // then this is the triangle index)
+    primitive_index: u32,
+    // Two of the barycentric coordinates, the third can be calculated (only useful if this is a triangle).
+    barycentrics: vec2<f32>,
+    // Whether the hit face is the front (only useful if this is a triangle).
+    front_face: bool,
+    // Matrix for converting from object-space to world-space.
+    //
+    // This matrix needs to be on the left side of the multiplication. Using it the other way round will not work.
+    // Use it this way: `let transformed_vector = intersecion.object_to_world * vec4<f32>(x, y, z, transform_multiplier);
+    object_to_world: mat4x3<f32>,
+    // Matrix for converting from world-space to object-space
+    //
+    // This matrix needs to be on the left side of the multiplication. Using it the other way round will not work.
+    // Use it this way: `let transformed_vector = intersecion.world_to_object * vec4<f32>(x, y, z, transform_multiplier);
+    world_to_object: mat4x3<f32>,
+}
+
+/// -- Flags for `RayDesc::flags` --
+
+// All `Blas`es are marked as opaque.
+const FORCE_OPAQUE = 0x1;
+
+// All `Blas`es are marked as non-opaque.
+const FORCE_NO_OPAQUE = 0x2;
+
+// Instead of searching for the closest hit return the first hit.
+const TERMINATE_ON_FIRST_HIT = 0x4;
+
+// Unused: implemented for raytracing pipelines.
+const SKIP_CLOSEST_HIT_SHADER = 0x8;
+
+// If `RayIntersection::front_face` is false do not return a hit.
+const CULL_BACK_FACING = 0x10;
+
+// If `RayIntersection::front_face` is true do not return a hit.
+const CULL_FRONT_FACING = 0x20;
+
+// If the `Blas` a intersection is checking is marked as opaque do not return a hit.
+const CULL_OPAQUE = 0x40;
+
+// If the `Blas` a intersection is checking is not marked as opaque do not return a hit.
+const CULL_NO_OPAQUE = 0x80;
+
+// If the `Blas` a intersection is checking contains triangles do not return a hit.
+const SKIP_TRIANGLES = 0x100;
+
+// If the `Blas` a intersection is checking contains AABBs do not return a hit.
+const SKIP_AABBS = 0x200;
+
+/// -- Constants for `RayIntersection::kind` --
+
+// The ray hit nothing.
+const RAY_QUERY_INTERSECTION_NONE = 0;
+
+// The ray hit a triangle.
+const RAY_QUERY_INTERSECTION_TRIANGLE = 1;
+
+// The ray hit a custom object, this will only happen in a committed intersection
+// if a ray which intersected a bounding box for a custom object which was then committed.
+const RAY_QUERY_INTERSECTION_GENERATED = 2;
+
+// The ray hit a AABB, this will only happen in a candidate intersection
+// if the ray intersects the bounding box for a custom object.
+const RAY_QUERY_INTERSECTION_AABB = 3;
+```

docs/big-picture.xml

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2023-12-04T19:38:59.956Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:120.0) Gecko/20100101 Firefox/120.0" etag="ZvsPE6AT2WA2xAhdKlfq" version="22.1.5" type="device"><diagram id="FLHi6BIjYAkfD6NTjxEH" name="Page-1">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</diagram></mxfile>

docs/release-checklist.md

@@ -0,0 +1,77 @@
+This is an overview of how to run wgpu releases.
+
+## Structure
+
+We do a major breaking release every 12 weeks. This happens no matter the status of various in-flight projects.
+
+We do a patch releases as needed in the weeks between major releases. Once a new major release is cut, we stop doing patch releases for the previous major release unless there is a critical bug or a compilation issue.
+
+## People
+
+Anyone can perform most of these steps, except actually publishing the crates.
+
+Currently only @kvark and @cwfitzgerald can publish all crates. @grovesNL can also publish `wgpu` crates. @jimblandy can publish `naga` crates.
+
+## Major Release Process
+
+Approx 1 Week Before:
+- Determine if `glow` (@groves), `metal-rs` (@kvark and @cwfitzgerald) or any other dependant crates will need a release. If so, coordinate with their maintainers.
+- Go through the changelog:
+  - Re-categorize miscategorized items.
+  - Edit major changes so a user can easily understand what they need to do.
+  - Add missing major changes that users need to know about.
+  - Copy-edit the changelog for clarity.
+
+Day of Release:
+- Update all crates to be the new version. We bump all versions even if there were no changes.
+  - `naga`
+  - `naga-cli`
+  - `wgpu-types`
+  - `wgpu-hal`
+  - `wgpu-core`
+  - `Cargo.toml` (this covers the rest of the crates).
+- Ensure `glow` and `metal` are updated to the latest version if needed.
+- Add a new header for the changelog with the release version and date.
+- Create a PR with all of the version changes and changelog updates.
+- Once the PR is CI clean, (force) merge it.
+- Checkout `trunk` with the merged PR.
+- Publish! These commands can be pasted directly into your terminal in a single command, and they will publish everything.
+  ```bash
+    cargo publish -p naga
+    cargo publish -p naga-cli
+    cargo publish -p wgpu-types
+    cargo publish -p wgpu-hal --all-features
+    cargo publish -p wgpu-core --all-features
+    cargo publish -p wgpu
+    cargo publish -p wgpu-info
+  ```
+- Create a new release on the `wgpu` repo with the changelog and a tag called `vX.Y.Z`.
+- Create a branch with the with the new version `vX.Y` and push it to the repo.
+- Publish the link to the github release in the following places.
+  - [r/rust](https://www.reddit.com/r/rust/).
+    - Add an AMA comment.
+  - Crosspost to [r/rust_gamedev](https://www.reddit.com/r/rust_gamedev/).
+    - Add an AMA comment.
+  - Include the r/rust post shortlink in the following posts as well:
+  - [wgpu matrix](https://matrix.to/#/#wgpu:matrix.org)
+  - [Rust Gamedev Discord](https://discord.gg/yNtPTb2) in the #crates channel
+  - [Bevy Discord](https://discord.com/invite/bevy) in the #rendering-dev channel
+  - [Graphics Programming Discord](https://discord.gg/6mgNGk7) in the #webgpu channel
+  - [Rust Community Discord](https://discord.gg/rust-lang-community) in the #games-and-graphics channel
+- Complete the release's milestone on GitHub.
+- Create a new milestone for the next release, in 12 weeks time.
+
+## Patch Release Process
+- Enumerate all PRs that haven't been backported yet. These use the `needs-backport` label. [GH Link](https://github.com/gfx-rs/wgpu/issues?q=label%3A%22PR%3A+needs+back-porting)
+- On _your own branch_ based on the latest release branch. Cherry-pick the PRs that need to be backported. When modifying the commits, use --append to retain their original authorship.
+- Remove the `needs-backport` label from the PRs.
+- Fix the changelogs items and add a new header for the patch release with the release version and date.
+- Once all the PRs are cherry-picked, look at the diff between HEAD and the previous patch release. See what crates changed.
+- Bump all the versions of the crates that changed.
+- Create a PR with all of the version changes and changelog updates into the release branch.
+- Once the PR is CI clean, (force) rebase merge it.
+- Checkout the release branch with the merged PR.
+- Publish all relevant crates (see list above).
+- Create a new release on the `wgpu` repo with the changelog and a tag called `vX.Y.Z` on the release branch.
+- Backport the changelog and version bumps to the `trunk` branch.
+  - Ensure that any items in the newly-released changelog don't appear in the "unreleased" section of the trunk changelog.

docs/review-checklist.md

@@ -0,0 +1,68 @@
+# Review Checklist
+
+This is a collection of notes on things to watch out for when
+reviewing pull requests submitted to wgpu and Naga.
+
+Ideally, we want to keep items off this list entirely:
+
+- Using Rust effectively can turn some mistakes into compile-time
+  errors. For example, in Naga, using exhaustive matching ensures that
+  changes to the IR will cause compile-time errors in any code that
+  hasn't been updated.
+
+- Refactoring can gather together all the code responsible for
+  enforcing some invariant in one place, making it clear whether a
+  change preserves it or not. For example, Naga localizes all handle
+  validation to `naga::valid::Validator::validate_module_handles`,
+  allowing the rest of the validator to assume that all handles are
+  valid.
+
+- Offering custom abstractions can help contributors avoid
+  implementing a weaker abstraction by themselves. For example,
+  because `HandleSet` and `HandleVec` are used throughout Naga,
+  contributors are less likely to write code that uses a `BitSet` or
+  `Vec` on handle indices, which would invite bugs by erasing the
+  handle types.
+
+This checklist gathers up the concerns that we haven't found a
+satisfying way to address in a more robust way.
+
+## Naga
+
+### General
+
+- [ ] If your change iterates over a collection, did you ensure the
+      order of iteration was deterministic? Using `HashMap` and
+      `HashSet` is fine, as long as you don't iterate over it.
+
+### WGSL Extensions
+
+- [ ] If you added a new feature to WGSL that is not covered by the
+      WebGPU specification:
+  - [ ] Did you add a `Capability` flag for it?
+  - [ ] Did you document the feature fully in that flag's doc comment?
+  - [ ] Did you ensure the validator rejects programs that use the
+        feature unless its capability is enabled?
+
+### IR changes
+
+If your change adds or removes `Handle`s from the IR:
+- [ ] Did you update handle validation in `valid::handles`?
+- [ ] Did you update the compactor in `compact`?
+- [ ] Did you update `back::pipeline_constants::adjust_expr`?
+
+If your change adds a new operation:
+- [ ] Did you update the typifier in `proc::typifier`?
+- [ ] Did you update the validator in `valid::expression`?
+- [ ] If the operation can be used in constant expressions, did you
+      update the constant evaluator in `proc::constant_evaluator`?
+
+### Backend changes
+
+- [ ] If your change introduces any new identifiers to generated code,
+      how did you ensure they won't conflict with the users'
+      identifiers? (This is usually not relevant to the SPIR-V
+      backend.)
+  - [ ] Did you use the `Namer` to generate a fresh identifier?
+  - [ ] Did you register the identifier as a reserved word with the the `Namer`?
+  - [ ] Did you use a reserved prefix registered with the `Namer`?