Merge pull request #339 from BVE-Reborn/doc-4

BVE-Reborn · Jan 26, 2022 · f2b7df4 · f2b7df4
2 parents 876956a + e8486bb
commit f2b7df4
Show file tree

Hide file tree

Showing 66 changed files with 582 additions and 433 deletions.
diff --git a/.rustfmt.toml b/.rustfmt.toml
@@ -1,6 +1,5 @@
 max_width = 120
 use_field_init_shorthand = true
 use_try_shorthand = true
-wrap_comments = true
 imports_granularity = "Crate"
 edition = "2021"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -45,6 +45,9 @@ Per Keep a Changelog there are 6 main categories of changes:
     - Split the PbrRoutine into two parts `add_prepass_to_graph` and `add_forward_to_graph`.
     - Split out the skybox renderer into `SkyboxRoutine`.
     - Split out tonemapping into the `TonemappingRoutine`.
+- rend3: Renamed the old `RendererMode` to `RendererProfile` and adjusted verbiage to refer to them as profiles.
+  - "CpuPowered" => "CpuDriven".
+  - "GpuPowered" => "GpuDriven".
 - rend3: All meshes now require validation.
   - `MeshBuilder::build()` now returns a `Result<Mesh, MeshValidationError>`. This validation can be unsafely omitted.
   - The implementation functions `Mesh::calculate_normals_for_buffers` and `Mesh::calculate_tangents_for_buffers` are now unsafe.

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,14 +1,14 @@
 [workspace]
 resolver = "2"
 members = [
-    "examples/textured-quad",
     "examples/cube",
     "examples/cube-no-framework",
     "examples/egui",
     "examples/imgui",
-    "examples/gltf",
     "examples/scene-viewer",
     "examples/skinning",
+    "examples/static-gltf",
+    "examples/textured-quad",
     "rend3",
     "rend3-egui",
     "rend3-framework",

diff --git a/README.md b/README.md
@@ -4,34 +4,110 @@
 [![Crates.io](https://img.shields.io/crates/v/rend3)](https://crates.io/crates/rend3)
 [![Documentation](https://docs.rs/rend3/badge.svg)](https://docs.rs/rend3)
 ![License](https://img.shields.io/crates/l/rend3)
-[![Matrix](https://img.shields.io/static/v1?label=rend3%20matrix&message=%23rend3&color=blueviolet&logo=matrix)](https://matrix.to/#/#rend3:matrix.org)
+[![Matrix](https://img.shields.io/static/v1?label=rend3%20dev&message=%23rend3&color=blueviolet&logo=matrix)](https://matrix.to/#/#rend3:matrix.org)
+[![Matrix](https://img.shields.io/static/v1?label=rend3%20users&message=%23rend3-users&color=blueviolet&logo=matrix)](https://matrix.to/#/#rend3-users:matrix.org)
 [![Discord](https://img.shields.io/discord/451037457475960852?color=7289DA&label=discord)](https://discord.gg/mjxXTVzaDg)
 
 
 Easy to use, customizable, efficient 3D renderer library built on wgpu.
 
-Library is under active development. While internals will likely change
-quite a bit, the external api will only experience minor changes as features
-are added.
+Library is under active development. While internals are might change in the
+future, the external api remains stable, with only minor changes occuring as
+features are added.
 
-To use rend3 add the following to your Cargo.toml:
+## Examples
+
+Take a look at the [examples] for getting started with the api. The examples
+will show how the core library and helper crates can be used.
+
+[examples]: https://github.com/BVE-Reborn/rend3/tree/trunk/examples
 
-```
-rend3 = "0.2.0"
-```
+#### Screenshots
 
-## Screenshots
+These screenshots are from the scene-viewer example.
 
 ![scifi-base](https://raw.githubusercontent.com/BVE-Reborn/rend3/trunk/examples/scene-viewer/scifi-base.jpg)
 ![example](https://raw.githubusercontent.com/BVE-Reborn/rend3/trunk/examples/scene-viewer/screenshot.jpg)
 ![bistro](https://raw.githubusercontent.com/BVE-Reborn/rend3/trunk/examples/scene-viewer/bistro.jpg)
 ![emerald-square](https://raw.githubusercontent.com/BVE-Reborn/rend3/trunk/examples/scene-viewer/emerald-square.jpg)
 
-## Examples
+## Crates
 
-Take a look at the [examples] getting started with the api.
+The `rend3` ecosystem is composed of a couple core crates which provide most
+of the functionality and exensibility to the library, extension crates, and
+integration crates
 
-[examples]: https://github.com/BVE-Reborn/rend3/tree/trunk/examples
+#### Core
+
+- `rend3`: The core crate. Performs all handling of world data, provides the
+  Renderer and RenderGraph and defines vocabulary types.
+- `rend3-routine`: Implementation of various "Render Routines" on top of the
+  RenderGraph. Also provides for re-usable graphics work. Provides PBR
+  rendering, Skyboxes, Shadow Rendering, and Tonemapping.
+
+#### Extensions
+
+There are extension crates that are not required, but provide pre-made bits
+of useful code that I would recommend using.
+
+- `rend3-framework`: Vastly simplifies correct handling of the window and
+  surface across platforms.
+- `rend3-gltf`: Modular gltf file and scene loader.
+
+#### Integration
+
+Integration with other external libraries are also offered. Due to external
+dependencies, the versions of these may increase at a much higher rate than
+the rest of the ecosystem.
+
+- `rend3-egui`: Integration with the [egui](https://github.com/emilk/egui)
+  immediate mode gui.
+- `rend3-imgui`: Integration with the [imgui](https://github.com/ocornut/imgui)
+  immediate mode gui.
+
+## Features and Platform Support
+
+rend3 supports two different rendering profiles one for speed and one for
+compatibility.
+
+#### Profile Features
+
+The modern profile not only offloads a lot more work to the gpu, it can do more
+aggressive performance optimizations including only drawing exactly the triangles that are needed
+
+| Profile   | Texture Access | Object Culling | Triangle Culling | Draw Calls          |
+|:----------|----------------|----------------|------------------|---------------------|
+| GpuDriven | Bindless       | On GPU         | On GPU           | Merged Indirect     |
+| CpuDriven | Bound          | On CPU         | ❌                | Instanced Direct    |
+
+#### Profile Support
+
+The following table shows support of various profiles on various apis/platforms. This will
+hopefully help you judge what your target demographic supports.
+
+| OS                   | API    | GPU                                        | GpuDriven | CpuDriven |
+|----------------------|--------|--------------------------------------------|:---------:|:---------:|
+| Windows 7+           | Vulkan | AMD / NVIDIA                               | ✅    | —       |
+|                      | Vulkan | Intel 6XXX+                                | ❌      | ✅     |
+|                      | Dx11   | Intel 2XXX+                                | ❌      | 🚧     |
+| Windows 10+          | Dx12   | Intel 6XXX+ / AMD GCN 2+ / NVIDIA 6XX+     | 🚧    | ✅     |
+| MacOS 10.13+ iOS 11+ | Metal  | Intel / Apple A13+ / M1+                   | ✅    | —       |
+|                      |        | Apple A9+                                  | ❌      | ✅     |
+| Linux                | Vulkan | Intel 6XXX+ / AMD GCN 2+  / NVIDIA 6XX+    | ✅    | —       |
+|                      |        | Intel 4XXX+                                | ❌      | ✅     |
+| Android              | Vulkan | All                                        | ❌      | ✅     |
+
+Footnotes:
+- ✅ Supported
+- 🚧 In Progress
+- ❌ Unsupported
+- — Modern Profile Used
+- Intel 6XXX = Skylake
+- Intel 4XXX = Haswell
+- Intel 2XXX = Sandy Bridge
+- AMD GCN 2 = Rx 200+, RX 5000+
+- Apple A9 = iPhone 6S, iPad 5th Gen
+- Apple A13 = iPhone 11, iPad 9th Gen
 
 ## Purpose
 
@@ -47,19 +123,6 @@ an advanced game or simulation nor care how you structure     your program.
 I do have plans for a `rend3-util` (or similar) crate that is a very basic
 framework for the second use case listed above.
 
-## Helper Crates
-
-This is the primary crate which holds the main [`Renderer`] struct. We have
-some other crates:
-- `rend3-gltf`: contains code to load from a .gltf or .glb file.
-- `rend3-routine`: contains render routines for drawing PBR-style objects.
-
-## GPU Culling
-
-On Vulkan and DX12 "gpu mode" is enabled by default, which uses modern
-bindless resources and gpu-based culling. This reduces CPU load and allows
-significantly more powerful culling.
-
 ## Future Plans
 
 I have grand plans for this library. An overview can be found in the issue
@@ -72,10 +135,11 @@ tracker under the [enhancement] label.
 We have a matrix chatroom that you can come and join if you want to chat
 about using rend3 or developing it:
 
-[![Matrix](https://img.shields.io/static/v1?label=rend3%20matrix&message=%23rend3&color=blueviolet&logo=matrix)](https://matrix.to/#/#rend3:matrix.org)
+[![Matrix](https://img.shields.io/static/v1?label=rend3%20dev&message=%23rend3&color=blueviolet&logo=matrix)](https://matrix.to/#/#rend3:matrix.org)
+[![Matrix](https://img.shields.io/static/v1?label=rend3%20users&message=%23rend3-users&color=blueviolet&logo=matrix)](https://matrix.to/#/#rend3-users:matrix.org)
 
 If discord is more your style, our meta project has a channel which mirrors
-the matrix:
+the matrix rooms:
 
 [![Discord](https://img.shields.io/discord/451037457475960852?color=7289DA&label=discord)](https://discord.gg/mjxXTVzaDg)
 

diff --git a/build.bash b/build.bash
@@ -12,18 +12,18 @@ case $1 in
         glslc rend3-routine/shaders/src/cull.comp   -DPREFIX_CULL                        -O -g -o rend3-routine/shaders/spirv/cull-prefix-cull.comp.spv
         glslc rend3-routine/shaders/src/cull.comp   -DPREFIX_SUM                         -O -g -o rend3-routine/shaders/spirv/cull-prefix-sum.comp.spv
         glslc rend3-routine/shaders/src/cull.comp   -DPREFIX_OUTPUT                      -O -g -o rend3-routine/shaders/spirv/cull-prefix-output.comp.spv
-        glslc rend3-routine/shaders/src/depth.vert  -DCPU_MODE                           -O -g -o rend3-routine/shaders/spirv/depth.vert.cpu.spv
-        glslc rend3-routine/shaders/src/depth.frag  -DCPU_MODE                           -O -g -o rend3-routine/shaders/spirv/depth-opaque.frag.cpu.spv
-        glslc rend3-routine/shaders/src/depth.frag  -DCPU_MODE -DALPHA_CUTOUT            -O -g -o rend3-routine/shaders/spirv/depth-cutout.frag.cpu.spv
-        glslc rend3-routine/shaders/src/depth.vert  -DGPU_MODE                           -O -g -o rend3-routine/shaders/spirv/depth.vert.gpu.spv
-        glslc rend3-routine/shaders/src/depth.frag  -DGPU_MODE                           -O -g -o rend3-routine/shaders/spirv/depth-opaque.frag.gpu.spv
-        glslc rend3-routine/shaders/src/depth.frag  -DGPU_MODE -DALPHA_CUTOUT            -O -g -o rend3-routine/shaders/spirv/depth-cutout.frag.gpu.spv
-        glslc rend3-routine/shaders/src/opaque.vert -DCPU_MODE                           -O -g -o rend3-routine/shaders/spirv/opaque.vert.cpu.spv
-        glslc rend3-routine/shaders/src/opaque.vert -DCPU_MODE -DBAKING                  -O -g -o rend3-routine/shaders/spirv/opaque-baking.vert.cpu.spv
-        glslc rend3-routine/shaders/src/opaque.frag -DCPU_MODE                           -O -g -o rend3-routine/shaders/spirv/opaque.frag.cpu.spv
-        glslc rend3-routine/shaders/src/opaque.vert -DGPU_MODE                           -O -g -o rend3-routine/shaders/spirv/opaque.vert.gpu.spv
-        glslc rend3-routine/shaders/src/opaque.vert -DGPU_MODE -DBAKING                  -O -g -o rend3-routine/shaders/spirv/opaque-baking.vert.gpu.spv
-        glslc rend3-routine/shaders/src/opaque.frag -DGPU_MODE                           -O -g -o rend3-routine/shaders/spirv/opaque.frag.gpu.spv
+        glslc rend3-routine/shaders/src/depth.vert  -DCPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/depth.vert.cpu.spv
+        glslc rend3-routine/shaders/src/depth.frag  -DCPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/depth-opaque.frag.cpu.spv
+        glslc rend3-routine/shaders/src/depth.frag  -DCPU_DRIVEN -DALPHA_CUTOUT          -O -g -o rend3-routine/shaders/spirv/depth-cutout.frag.cpu.spv
+        glslc rend3-routine/shaders/src/depth.vert  -DGPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/depth.vert.gpu.spv
+        glslc rend3-routine/shaders/src/depth.frag  -DGPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/depth-opaque.frag.gpu.spv
+        glslc rend3-routine/shaders/src/depth.frag  -DGPU_DRIVEN -DALPHA_CUTOUT          -O -g -o rend3-routine/shaders/spirv/depth-cutout.frag.gpu.spv
+        glslc rend3-routine/shaders/src/opaque.vert -DCPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/opaque.vert.cpu.spv
+        glslc rend3-routine/shaders/src/opaque.vert -DCPU_DRIVEN -DBAKING                -O -g -o rend3-routine/shaders/spirv/opaque-baking.vert.cpu.spv
+        glslc rend3-routine/shaders/src/opaque.frag -DCPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/opaque.frag.cpu.spv
+        glslc rend3-routine/shaders/src/opaque.vert -DGPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/opaque.vert.gpu.spv
+        glslc rend3-routine/shaders/src/opaque.vert -DGPU_DRIVEN -DBAKING                -O -g -o rend3-routine/shaders/spirv/opaque-baking.vert.gpu.spv
+        glslc rend3-routine/shaders/src/opaque.frag -DGPU_DRIVEN                         -O -g -o rend3-routine/shaders/spirv/opaque.frag.gpu.spv
         glslc rend3-routine/shaders/src/skybox.vert                                      -O -g -o rend3-routine/shaders/spirv/skybox.vert.spv
         glslc rend3-routine/shaders/src/skybox.frag                                      -O -g -o rend3-routine/shaders/spirv/skybox.frag.spv
 

diff --git a/examples/README.md b/examples/README.md
@@ -2,10 +2,16 @@
 
 The examples are separate crates, so to run an example run `cargo run --bin <name>`.
 
+If you want to demo running rend3, [`scene-viewer`](scene-viewer) is what you should use. It is a full fledged gltf viewer.
+
+If you want to look at how the basics of the code works, look at either the [`cube`](cube) or [`cube-no-framework`](cube-no-framework) example.
+
 | Name                | Description | Image |
 |:-------------------:|:------------|-------|
-| cube (no-framework) | Basic example, best way to get started with the api. Second example cube-no-framework which shows how the parts put together without using the framework. | ![](cube/screenshot.png) |
-| gltf                | Similar to cube, but geometry is pulled from a gltf file | ![](gltf/screenshot.jpg) |
-| scene-viewer        | Advanced example used to test rend3. | ![](scene-viewer/scifi-base.jpg) ![](scene-viewer/screenshot.jpg) ![](scene-viewer/bistro.jpg) ![](scene-viewer/emerald-square.jpg) |
-| textured-quad       | Basic 2d rendering with an orthographic camera | ![](textured-quad/screenshot.png) |
+| scene-viewer        | Advanced gltf model and scene viewer. Used to test all of rend3's complex features. | ![](scene-viewer/scifi-base.jpg) ![](scene-viewer/screenshot.jpg) ![](scene-viewer/bistro.jpg) ![](scene-viewer/emerald-square.jpg) |
+| cube                | Basic example. Shows how to get started with the api, both with and without the use of rend3-framework. | ![](cube/screenshot.png) |
+| egui                | Shows integration with egui and rend3-egui | ![](egui/screenshot.png) |
+| imgui               | Shows integration with imgui and rend3-imgui | ![](imgui/screenshot.png) |
 | skinning            | Basic bone deformation of a loaded gltf model | ![](skinning/screenshot.png) |
+| static-gltf         | Similar to cube, but geometry is pulled from a simple gltf file | ![](static-gltf/screenshot.png) |
+| textured-quad       | Basic 2D rendering with an orthographic camera | ![](textured-quad/screenshot.png) |
diff --git a/examples/cube-no-framework/src/main.rs b/examples/cube-no-framework/src/main.rs
@@ -68,7 +68,7 @@ fn main() {
     let window_size = window.inner_size();
 
     // Create the Instance, Adapter, and Device. We can specify preferred backend,
-    // device name, or rendering mode. In this case we let rend3 choose for us.
+    // device name, or rendering profile. In this case we let rend3 choose for us.
     let iad = pollster::block_on(rend3::create_iad(None, None, None, None)).unwrap();
 
     // The one line of unsafe needed. We just need to guarentee that the window

diff --git a/examples/cube/screenshot.png b/examples/cube/screenshot.png
diff --git a/examples/egui/screenshot.png b/examples/egui/screenshot.png
diff --git a/examples/egui/src/main.rs b/examples/egui/src/main.rs
@@ -55,6 +55,7 @@ impl rend3_framework::App for EguiExample {
         // Add PBR material with all defaults except a single color.
         let material = rend3_routine::pbr::PbrMaterial {
             albedo: rend3_routine::pbr::AlbedoComponent::Value(glam::Vec4::new(0.0, 0.5, 0.5, 1.0)),
+            transparency: rend3_routine::pbr::Transparency::Blend,
             ..rend3_routine::pbr::PbrMaterial::default()
         };
         let material_handle = renderer.add_material(material);
@@ -151,6 +152,7 @@ impl rend3_framework::App for EguiExample {
                             &data.material_handle.clone(),
                             rend3_routine::pbr::PbrMaterial {
                                 albedo: rend3_routine::pbr::AlbedoComponent::Value(glam::Vec4::from(data.color)),
+                                transparency: rend3_routine::pbr::Transparency::Blend,
                                 ..rend3_routine::pbr::PbrMaterial::default()
                             },
                         );

diff --git a/examples/gltf/screenshot.jpg b/examples/gltf/screenshot.jpg
diff --git a/examples/imgui/screenshot.png b/examples/imgui/screenshot.png
diff --git a/examples/scene-viewer/src/lib.rs b/examples/scene-viewer/src/lib.rs
@@ -7,7 +7,7 @@ use rend3::{
         TextureFormat,
     },
     util::typedefs::FastHashMap,
-    Renderer, RendererMode,
+    Renderer, RendererProfile,
 };
 use rend3_framework::{lock, AssetPath, Mutex};
 use rend3_routine::{base::BaseRenderGraph, pbr::NormalTextureYDirection, skybox::SkyboxRoutine};
@@ -135,10 +135,10 @@ fn extract_backend(value: &str) -> Result<Backend, &'static str> {
     })
 }
 
-fn extract_mode(value: &str) -> Result<rend3::RendererMode, &'static str> {
+fn extract_mode(value: &str) -> Result<rend3::RendererProfile, &'static str> {
     Ok(match value.to_lowercase().as_str() {
-        "legacy" | "c" | "cpu" => rend3::RendererMode::CpuPowered,
-        "modern" | "g" | "gpu" => rend3::RendererMode::GpuPowered,
+        "legacy" | "c" | "cpu" => rend3::RendererProfile::CpuDriven,
+        "modern" | "g" | "gpu" => rend3::RendererProfile::GpuDriven,
         _ => return Err("unknown rendermode"),
     })
 }
@@ -218,7 +218,7 @@ Meta:
 Rendering:
   -b --backend                 Choose backend to run on ('vk', 'dx12', 'dx11', 'metal', 'gl').
   -d --device                  Choose device to run on (case insensitive device substring).
-  -m --mode                    Choose rendering mode to run on ('cpu', 'gpu').
+  -p --profile                 Choose rendering profile to use ('cpu', 'gpu').
   --msaa <level>               Level of antialiasing (either 1 or 4). Default 1.
 
 Windowing:
@@ -243,7 +243,7 @@ struct SceneViewer {
     absolute_mouse: bool,
     desired_backend: Option<Backend>,
     desired_device_name: Option<String>,
-    desired_mode: Option<RendererMode>,
+    desired_profile: Option<RendererProfile>,
     file_to_load: Option<String>,
     walk_speed: f32,
     run_speed: f32,
@@ -279,7 +279,7 @@ impl SceneViewer {
         let desired_backend = option_arg(args.opt_value_from_fn(["-b", "--backend"], extract_backend));
         let desired_device_name: Option<String> =
             option_arg(args.opt_value_from_str(["-d", "--device"])).map(|s: String| s.to_lowercase());
-        let desired_mode = option_arg(args.opt_value_from_fn(["-m", "--mode"], extract_mode));
+        let desired_mode = option_arg(args.opt_value_from_fn(["-p", "--profile"], extract_mode));
         let samples = option_arg(args.opt_value_from_fn("--msaa", extract_msaa)).unwrap_or(SampleCount::One);
 
         // Windowing
@@ -340,7 +340,7 @@ impl SceneViewer {
             absolute_mouse,
             desired_backend,
             desired_device_name,
-            desired_mode,
+            desired_profile: desired_mode,
             file_to_load,
             walk_speed,
             run_speed,
@@ -377,7 +377,7 @@ impl rend3_framework::App for SceneViewer {
             Ok(rend3::create_iad(
                 self.desired_backend,
                 self.desired_device_name.clone(),
-                self.desired_mode,
+                self.desired_profile,
                 None,
             )
             .await?)

diff --git a/examples/skinning/README.md b/examples/skinning/README.md
@@ -1,5 +1,5 @@
 # skinning
 
-This example showcases how to import a mesh with an armature and positions its bones.
+This example showcases how to import a mesh with an armature and position its bones.
 
 ![](screenshot.png)
diff --git a/examples/skinning/screenshot.png b/examples/skinning/screenshot.png
diff --git a/examples/gltf/Cargo.toml → examples/static-gltf/Cargo.toml b/examples/gltf/Cargo.toml → examples/static-gltf/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "rend3-gltf-example"
+name = "rend3-static-gltf-example"
 license = "MIT OR Apache-2.0 OR Zlib"
 version = "0.2.0"
 authors = ["The rend3 Developers"]
@@ -8,7 +8,7 @@ publish = false
 rust-version = "1.57"
 
 [[bin]]
-name = "gltf"
+name = "static-gltf"
 path = "src/main.rs"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html