Rendering book

content/learn/book/rendering/_index.md

@@ -0,0 +1,29 @@
++++
+title = "Rendering"
+template = "docs.html"
+insert_anchor_links = "right"
+[extra]
+weight = 16
++++
+
+To display stuff on screen, 3D rendering... (what about 2D?)
+
+list of crates (pbr, core pipeline, mesh, light, anti_aliasing, etc)
+
+Quick start example spawn camera/mesh+material/light/etc:
+```rust
+
+```
+
+The next few pages will cover each of these concepts in greater detail.
+
+wgpu/supported platforms (webgpu, native, mobile, webgl2)
+
+naga/wgsl/wesl
+
+Where to stick?:
+    * Decals (forward, clustered) (stick with meshes?)
+    * OIT
+    * RenderLayers
+    * Particles (not upstreamed in bevy yet)
+    * Useful shader math stuff

content/learn/book/rendering/animation.md

@@ -0,0 +1,11 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+Skinning
+Morph targets
+Animation controller stuff(?) (idk much about animation, and likely deserves it's own book section? Maybe dosen't belong in rendering)

content/learn/book/rendering/anti-aliasing.md

@@ -0,0 +1,11 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+Types of aliasing: Geometric, specular, temporal
+
+MSAA, FXAA, SMAA, TAA, DLSS, CAS sharpening

content/learn/book/rendering/cameras.md

@@ -0,0 +1,11 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+* Split screen / multi-camera
+* Render-to-texture
+* Minimap(?)

content/learn/book/rendering/custom-materials.md

@@ -0,0 +1,12 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+Material API
+Mesh tag
+Different vertex/fragment shader overrides (and how prepass/deferred/shadow mapping/virtual geometry plays with it)
+PBR shader APIs

content/learn/book/rendering/lighting.md

@@ -0,0 +1,119 @@
++++
+title = "Lighting"
+insert_anchor_links = "right"
+[extra]
+weight = 2
+status = 'hidden'
++++
+
+Once you have a camera, meshes, and materials in your scene, the final entity you need to spawn are light sources.
+
+## Theory
+
+Light sources emit rays of light. These rays bounce around the scene, following different paths, and eventually end up hitting the camera and being visible on screen.
+
+You can classify these paths into two types: direct lighting, and indirect lighting.
+
+Direct lighting is a 3-vertex path where a light (x2) emits a ray, it bounces off of one surface (x1), and then hits the camera (x0).
+
+Indirect lighting is an N-vertex path (where N>3) where a light (x4) emits a ray, it bounces off of one surface (x3), which then bounces off of another surface (x2), etc, until it eventually hits the camera (x0).
+
+Indirect lighting is often referred to as global illumination, and is typically much more expensive to compute.
+
+(TODO: Diagram)
+
+Direct lighting controls what regions are dark and in shadow and what regions are brightly illuminated. It's most important for outdoor scenes.
+
+Indirect lighting controls _how dark_ shadowed regions are. Without indirect lighting, shadowed regions will be pitch-black, which is not very physically plausible.
+
+Indirect lighting is most important for indoor scenes, where most of the illumination comes from light coming from a window or lamp and bouncing around the scene.
+
+(TODO: Examples of indoor and outdoor scenes with direct/indirect lighting)
+
+Furthermore, paths can further be classified into diffuse or specular lighting, based on what kinds of materials they hit along the way (link the StandardMaterial page).
+
+Diffuse lighting determines the overall mood of the scene, while specular lighting provides sharper reflections and makes metallic and translucent materials look realistic.
+
+A common beginner mistake is to not setup any indirect lighting sources, and then have metallic and transparent materials that don't look reflective.
+
+(TODO: Examples of diffuse and specular lighting in scenes)
+
+The final thing (TODO: better word) to consider is occlusion. Not all paths are possible. Geometry can get in the way of paths, and block them.
+
+For direct lighting, occlusion is what determines what people typically think of as shadows. If you applied direct light equally to all parts of a scene, without considering occlusion, you wouldn't have any shadows.
+
+For indirect lighting, occlusion is what makes objects appear "grounded" in the scene. If you applied indirect light equally to all aprts of a scene, without considering occlusion, objects would appear to "float". Applying indirect occlusion darkens the corners of a scene, and makes objects appear more "grounded".
+
+(TODO: Screenshot without/without shadow maps, with/without indirect occlusion)
+
+## Workflow
+
+Lighting a scene and making it look "good" can be tricky. Bevy provides a large variety of different lighting systems with different tradeoffs and advantages. There is no one perfect lighting system that looks and performs well in all games. Consider which of the available options best fit your game's style, gameplay, and target audience.
+
+Generally, there are "dynamic" and "baked" lighting methods.
+
+Dynamic methods are more expensive, and have worse quality, but can react in realtime as objects move around and light sources change.
+
+Baked methods are cheap to apply at runtime, and have better quality, but require a time-consuming process to pre-calculate (bake) the scene's lighting ahead of time. This means that if objects move around or the light sources change, the lighting won't adapt, and will look wrong. Additionally, storing the pre-calculated scene lighting takes some disk space.
+
+A puzzle game with mainly static, indoor scenes, targeting laptops with weaker GPUs, might want to rely on mostly baked lighting methods. An FPS with lots of dynamic objects, targeting higher-end systems, might want to rely on more dynamic lighting methods. World size is also a factor. For larger games with many big levels, the lengthy baking process and large amount of disk space consumed can be good reasons to avoid baked lighting.
+
+The Lighting Systems section (TODO: link) will provide an overview of the different lighting systems available.
+
+Either way, you'll probably want to start by referencing some real-world scenes.
+Identify the main source of light in your scene. For outdoor scenes, this will typically be the sun. For indoor scenes, this might be an overhead light fixture (TODO: wordy) or lamp.
+
+Spawn direct light sources like `DirectionalLight`, `PointLight`, or `SpotLight` to represent your main light sources. As always with PBR, use light intensities that match real-world measurements to keep things consistent.
+
+After setting up direct lighting, the next step is to add some indirect lighting. Unlike direct lighting, indirect lighting in Bevy tends to be split into separate systems for diffuse and specular indirect light, as indirect lighting is much more expensive and difficult to calculate.
+
+Additionally, many indirect lighting systems are complementary, and handle e.g. only dynamic or static meshes, or provide additional small-scale detail on top of coarser systems. You'll likely want to use multiple forms of indirect lighting. Either way, stick to trying to match real-world or ground-truth references.
+
+Finally, you'll want to handle occlusion. For direct lighting, choose a low amount (1-4) of the most important lights in the scene, and enable shadow mapping. For indirect lighting, occlusion will either be part of the baking process, approximated with something like screen space ambient occlusion, or ignored altogether (for performance reasons).
+
+You should also make sure that your camera settings (exposure, bloom, tonemapping) fit the scene.
+
+## Lighting Systems
+
+### Direct Lighting
+
+#### DirectionalLight
+* Cascades
+
+#### PointLight
+
+#### SpotLight
+
+#### Shadow mapping
+* PCF and PCSS
+* Shadow map resolution
+* NotShadowCaster/Receiver
+
+### Indirect Lighting
+* Hierachy of light (which sources override and take precedence over others)
+
+#### AmbientLight
+
+#### EnvironmentMapLight
+* Global vs local
+* GeneratedEnvironmentMapLight
+
+#### IrradianceVolume
+
+#### Lightmap
+
+#### Screenspace Methods
+
+#### Faking GI with PointLights
+
+### Volumetrics
+
+#### DistanceFog
+* Non-PBR
+
+#### FogVolume
+
+#### VoumetricFog
+* FogVolume, VolumetricLight
+
+### Solari

content/learn/book/rendering/low-level.md

@@ -0,0 +1,20 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+_Not_ a tutorial for wgpu/graphics programming. Just bevy-specific concepts. Link to learn-wgpu instead.
+
+RenderWorld, ExtractSchedule/world sync, and RenderSystems
+SpecializedPipeline stuff
+Render graph and nodes, add_command_buffer_generation_task()
+RenderAssets
+MeshAllocator
+PipelineCache
+GpuReadback stuff
+Bind group(layout) helpers
+RenderAdapter/RenderDevice/RenderQueue resources
+Render-world camera stuff(?)

content/learn/book/rendering/mesh.md

@@ -0,0 +1,10 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+Vertex attributes
+Virtual geometry

content/learn/book/rendering/performance.md

@@ -0,0 +1,25 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+* Profile first! Really!! (Link to that part of the book)
+  * CPU vs GPU bottlenecks, render world and render commands vs GPU timeline
+* Mesh/material auto-batching and pipeline/draw calls, MeshTag
+* RenderDiagnostics
+* Use a single-digits amount of shadow-casting lights
+* Don't use more than ~10(?) lights affecting the same pixel
+* Deferred vs forward vs forward with prepass
+* Overdraw, culling, and wasted work
+* RenderAssetUsages to save RAM
+* VRAM usage in general (texture size, mesh size, etc)
+* Optimize textures:
+  * Texture size (4k vs 1080p)
+  * Mipmaps (perf, not just quality)
+  * GPU-compressed texture formats (BC or ASTC)
+  * CPU-compressed files (zstd) (different than GPU-compressed _formats_)
+* Give users the option to turn off more expensive features (e.g. lower SSAO quality, or adjust shadow map resolution)
+* LOD/VisibilityRange/VirtualGeometry

content/learn/book/rendering/post-processing.md

@@ -0,0 +1,17 @@
++++
+title = "TODO"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+Bloom
+Tonemapping
+Hdr component
+Auto exposure
+Skybox/Procedural atmosphere(?)
+Motion blur
+Depth of field
+Chromatic aberration
+Color grading

content/learn/book/rendering/standard-material.md

@@ -0,0 +1,55 @@
++++
+title = "Standard Material"
+insert_anchor_links = "right"
+[extra]
+weight = 1
+status = 'hidden'
++++
+
+In Bevy, the main `Material` the engine provides is the `StandardMaterial`.
+
+StandardMaterial, like most of the functionality in `bevy_pbr`, implements an idea called "physically based rendering", or PBR.
+
+PBR is when you use formulas and units derived from real-world physics and math. PBR is a concept more than a strict set of rules, and approximations are often used in the name of performance, but where possible the idea is that you stick to real-world physics.
+
+Before PBR, artists designed lighting, material, and camera properties more ad-hoc. When answering the question "what color should this object be?", artists would just choose a value that they thought looked good. Properties like how shiny or smooth an object are were similarly made up by the artist.
+
+While this process worked fine for smaller scenes, as larger movies and games started being created, assets became harder to reuse. A coin that looked the correct shade of yellow, with a certain shininess in one scene, might look completely wrong when reused in another scene under different lighting conditions.
+
+With PBR, to answer "what color should this object be?", you instead reference values from a database of real-world measurements like [Physically Based](https://physicallybased.info). Assets are more scene-independent, and behave consistently in a variety of different lighting conditions.
+
+Even if you're making a stylized game, PBR is still important for consistency.
+
+## Theory
+
+Bevy's `StandardMaterial`, and PBR materials in general, are based on the concept of a bidirectional reflectance distribution function (BRDF).
+
+In the real world, when light hits a surface, a portion of the energy is absorbed, and a portion is reflected and bounces in a different direction.
+
+Given an incoming ray of light, a BRDF is a formula that describes the possible directions the ray can bounce, and the amount of energy reflected.
+
+A blue surface reflects a lot of blue light, and absorbs a lot of red and green light. A mirror reflects light mostly in one direction, while matte materials reflects light in many directions.
+
+The BRDF determines the appearance of a surface, and is why e.g. plastic looks different than metal.
+
+There are different types of BRDFs. Light might bounce equally in many directions (diffuse), towards one general direction (glossy), or even a perfect reflection in one direction (mirror).
+
+The glossy and mirror cases are typically referred to as specular BRDFs, as opposed to diffuse BRDFs. Diagrams: https://en.wikipedia.org/wiki/Bidirectional_reflectance_distribution_function#Models.
+
+Oftentimes real-world materials are not perfectly diffuse or perfectly specular, but a combination of the two. A common way to classify materials is into "metals" and "non-metals" (dielectrics).
+
+Metals are actual metals like silver, gold, copper, etc, while dielectrics are everything else including plastic, wood, stone, rubber, etc.
+
+Metals have only a specular BRDF, while dielectrics have a combination of diffuse and specular BRDFs.
+
+Bevy's `StandardMaterial` is built to represent arbitrary real-world materials using a combination of diffuse and specular BRDFs mixed together with a set of weights based on the `metallic` property. A subset of more complex materials like wax, cloth, and gemstones that have effects like subsurface scattering, sheen, and refraction, can be modelled with additional properties.
+
+In practice, `StandardMaterial`'s fragment shader sets up some BRDFs based on its properties, loops over the light of lights in the scene, calculates each light's interaction with the BRDF, and accumulates the result to give the final color of the pixel.
+
+Showcase screenshots: https://bevy.org/examples/3d-rendering/pbr and other examples
+
+## Property Reference
+
+Each property has both a value, and an optional texture map.
+
+TODO: Explain and showcase each StandardMaterial property