rend3/lib.rs
1//! Easy to use, customizable, efficient 3D renderer library built on wgpu.
2//!
3//! Library is under active development. While internals are might change in the
4//! future, the external api remains stable, with only minor changes occuring as
5//! features are added.
6//!
7//! # Examples
8//!
9//! Take a look at the [examples] for getting started with the api. The examples
10//! will show how the core library and helper crates can be used.
11//!
12//! [examples]: https://github.com/BVE-Reborn/rend3/tree/trunk/examples
13//!
14//! ### Screenshots
15//!
16//! These screenshots are from the scene-viewer example.
17//!
18//! 
19//! 
20//! 
21//! 
22//!
23//! # Crates
24//!
25//! The `rend3` ecosystem is composed of a couple core crates which provide most
26//! of the functionality and exensibility to the library, extension crates, and
27//! integration crates
28//!
29//! ### Core
30//!
31//! - `rend3`: The core crate. Performs all handling of world data, provides the
32//! Renderer and RenderGraph and defines vocabulary types.
33//! - `rend3-routine`: Implementation of various "Render Routines" on top of the
34//! RenderGraph. Also provides for re-usable graphics work. Provides PBR
35//! rendering, Skyboxes, Shadow Rendering, and Tonemapping.
36//!
37//! ### Extensions
38//!
39//! There are extension crates that are not required, but provide pre-made bits
40//! of useful code that I would recommend using.
41//!
42//! - `rend3-framework`: Vastly simplifies correct handling of the window and
43//! surface across platforms.
44//! - `rend3-gltf`: Modular gltf file and scene loader.
45//!
46//! ### Integration
47//!
48//! Integration with other external libraries are also offered. Due to external
49//! dependencies, the versions of these may increase at a much higher rate than
50//! the rest of the ecosystem.
51//!
52//! - `rend3-egui`: Integration with the [egui](https://github.com/emilk/egui)
53//! immediate mode gui.
54//! - `rend3-imgui`: Integration with the [imgui](https://github.com/ocornut/imgui)
55//! immediate mode gui.
56//!
57//! # Features and Platform Support
58//!
59//! rend3 supports two different rendering profiles one for speed and one for
60//! compatibility.
61//!
62//! ### Profile Features
63//!
64//! The modern profile not only offloads a lot more work to the gpu, it can do more
65//! aggressive performance optimizations including only drawing exactly the triangles that are needed
66//!
67//! | Profile | Texture Access | Object Culling | Triangle Culling | Draw Calls |
68//! |:----------|----------------|----------------|------------------|---------------------|
69//! | GpuDriven | Bindless | On GPU | On GPU | Merged Indirect |
70//! | CpuDriven | Bound | On CPU | ❌ | Instanced Direct |
71//!
72//! ### Profile Support
73//!
74//! The following table shows support of various profiles on various apis/platforms. This will
75//! hopefully help you judge what your target demographic supports.
76//!
77//! | OS | API | GPU | GpuDriven | CpuDriven |
78//! |----------------------|--------|--------------------------------------------|:---------:|:---------:|
79//! | Windows 7+ | Vulkan | AMD / NVIDIA | ✅ | — |
80//! | | Vulkan | Intel 6XXX+ | ❌ | ✅ |
81//! | | Dx11 | Intel 2XXX+ | ❌ | 🚧 |
82//! | Windows 10+ | Dx12 | Intel 6XXX+ / AMD GCN 2+ / NVIDIA 6XX+ | 🚧 | ✅ |
83//! | MacOS 10.13+ iOS 11+ | Metal | Intel / Apple A13+ / M1+ | ✅ | — |
84//! | | | Apple A9+ | ❌ | ✅ |
85//! | Linux | Vulkan | Intel 6XXX+ / AMD GCN 2+ / NVIDIA 6XX+ | ✅ | — |
86//! | | | Intel 4XXX+ | ❌ | ✅ |
87//! | Android | Vulkan | All | ❌ | ✅ |
88//!
89//! Footnotes:
90//! - ✅ Supported
91//! - 🚧 In Progress
92//! - ❌ Unsupported
93//! - — Modern Profile Used
94//! - Intel 6XXX = Skylake
95//! - Intel 4XXX = Haswell
96//! - Intel 2XXX = Sandy Bridge
97//! - AMD GCN 2 = Rx 200+, RX 5000+
98//! - Apple A9 = iPhone 6S, iPad 5th Gen
99//! - Apple A13 = iPhone 11, iPad 9th Gen
100//!
101//! # Purpose
102//!
103//! `rend3` tries to fulfill the following usecases:
104//! 1. Games and visualizations that need a customizable, and efficient renderer.
105//! 2. Projects that just want to put objects on screen, but want lighting and effects.
106//! 3. A small cog in a big machine: a renderer that doesn't interfere with the rest of the program.
107//!
108//! `rend3` is not:
109//! 1. A framework or engine. It does not include all the parts needed to make an
110//! advanced game or simulation nor care how you structure your program.
111//! If you want a very basic framework to deal with windowing and event loop management,
112//! `rend3-framework` can help you. This will always be optional and is just there to help
113//! with the limited set of cases it canhelp
114//!
115//! # Future Plans
116//!
117//! I have grand plans for this library. An overview can be found in the issue
118//! tracker under the [enhancement] label.
119//!
120//! [enhancement]: https://github.com/BVE-Reborn/rend3/labels/enhancement
121//!
122//! # Matrix Chatroom
123//!
124//! We have a matrix chatroom that you can come and join if you want to chat
125//! about using rend3 or developing it:
126//!
127//! [](https://matrix.to/#/#rend3:matrix.org)
128//! [](https://matrix.to/#/#rend3-users:matrix.org)
129//!
130//! If discord is more your style, our meta project has a channel which mirrors
131//! the matrix rooms:
132//!
133//! [](https://discord.gg/mjxXTVzaDg)
134//!
135//! # Helping Out
136//!
137//! We welcome all contributions and ideas. If you want to participate or have
138//! ideas for this library, we'd love to hear them!
139
140mod renderer;
141/// Managers for various type of resources.
142pub mod managers {
143 mod camera;
144 mod directional;
145 mod material;
146 mod mesh;
147 mod object;
148 mod skeleton;
149 mod texture;
150
151 pub use camera::*;
152 pub use directional::*;
153 pub use material::*;
154 pub use mesh::*;
155 pub use object::*;
156 pub use skeleton::*;
157 pub use texture::*;
158}
159
160/// Reexport of [`rend3_types`] with some added wgpu re-exports.
161pub mod types {
162 pub use rend3_types::*;
163 #[doc(inline)]
164 pub use wgpu::{Surface, SurfaceError};
165}
166/// Utilities and isolated bits of functionality that need a home.
167pub mod util {
168 pub mod bind_merge;
169 pub mod buffer;
170 pub mod buffer_copier;
171 pub mod frustum;
172 pub mod math;
173 pub mod mipmap;
174 pub mod output;
175 /// Core datastructures that associate handles with data in a gpu-friendly
176 /// format.
177 pub mod registry {
178 mod archetypical;
179 mod basic;
180 mod erased;
181
182 pub use archetypical::*;
183 pub use basic::*;
184 pub use erased::*;
185 }
186 pub mod typedefs;
187}
188
189pub mod graph;
190mod instruction;
191mod profile;
192mod setup;
193mod surface;
194
195pub use profile::*;
196pub use renderer::{error::*, Renderer, RendererDataCore};
197pub use setup::*;
198pub use surface::*;
199
200/// Format of all shadow maps.
201pub const INTERNAL_SHADOW_DEPTH_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Depth32Float;
202// TODO: This needs to be dynamic
203/// Resolution of all shadow maps.
204pub const SHADOW_DIMENSIONS: u32 = 2048;