Add advanced topics documentation: Ray Query, Planar Reflections, Robustness2, Mipmaps and LOD, glTF Animation, and Push Constants.

Author: gpx1000

en/Building_a_Simple_Engine/Advanced_Topics/01_introduction.adoc

@@ -0,0 +1,27 @@
+::pp: {plus}{plus}
+
+= Advanced Topics (Simple Engine)
+
+Welcome — this section collects short, conversational guides that explain what each feature is, why we use it, and how it’s implemented in the Simple Engine.
+
+Start anywhere that matches your interest:
+
+* xref:Planar_Reflections.adoc[Planar Reflections]
+* xref:Ray_Query_Rendering.adoc[Ray Query Rendering]
+* xref:Ray_Query_Reflections_and_Transparency.adoc[Ray Query Reflections and Transparency]
+* xref:Rendering_Pipeline_Overview.adoc[Rendering Pipeline Overview]
+* xref:Forward_ForwardPlus_Deferred.adoc[Forward, Forward+, Deferred]
+* xref:ForwardPlus_Rendering.adoc[Forward+ Rendering]
+* xref:Culling.adoc[Frustum Culling and Distance LOD]
+* xref:Mipmaps_and_LOD.adoc[Mipmaps and LOD]
+* xref:GLTF_Animation.adoc[glTF Animation & Transform Composition]
+* xref:Push_Constants_Per_Object.adoc[Push Constants (per‑object material)]
+* xref:Descriptor_Indexing_UpdateAfterBind.adoc[Descriptor Indexing & Stable Updates]
+* xref:Separate_Image_Sampler_Descriptors.adoc[Separate Image/Sampler]
+* xref:Synchronization_and_Streaming.adoc[Synchronization & Streaming]
+* xref:Synchronization_2_Frame_Pacing.adoc[Synchronization 2 & Frame Pacing]
+* xref:Robustness2.adoc[VK_EXT_robustness2]
+* xref:Dynamic_Rendering_Local_Read.adoc[Dynamic Rendering Local Read]
+* xref:Shader_Tile_Image.adoc[Shader Tile Image]
+
+link:../index.html[Back to Building a Simple Engine]

en/Building_a_Simple_Engine/Advanced_Topics/Culling.adoc

@@ -0,0 +1,46 @@
+= Frustum Culling and Distance‑based LOD
+
+Culling is the simplest way to keep your GPU focused on what the camera can see. In this engine we keep it intentionally pragmatic: CPU frustum tests plus a tiny “distance/size LOD” that skips objects that would contribute only a handful of pixels.
+
+* CPU frustum culling against per‑mesh AABBs
+* A tiny distance/size LOD that skips very small objects (projected size threshold)
+
+== What we do
+
+1. Extract the camera frustum planes from `proj * view` once per frame.
+2. For each mesh instance, transform its local AABB to world space and test against the planes.
+3. If enabled, estimate projected pixel size and skip objects below a threshold (separate thresholds for opaque vs transparent).
+
+== Where to look in the code
+
+* Plane extraction and AABB tests:
+** `renderer_rendering.cpp` (helpers near the top of the file)
+* Per-frame culling application:
+** `renderer_rendering.cpp` (the render list building and per-pass filtering)
+* UI controls:
+** ImGui panel in `renderer_rendering.cpp` — “Frustum culling”, “Distance LOD”, and per-pass thresholds
+
+== Why it’s set up this way
+
+* AABBs are cheap to transform and test; doing this on the CPU avoids sending obviously invisible draws.
+* A projected‑size cutoff is a practical alternative to a full LOD system for large scenes.
+
+== Tuning tips
+
+* Start conservative (smaller thresholds), then increase until you can’t notice pop‑in while moving.
+* Transparent objects typically need a slightly higher threshold due to blending artifacts at tiny sizes.
+
+== Future work ideas
+
+If you want to push this further:
+
+* Add per-material or per-layer culling rules (e.g., keep signage readable longer).
+* Add hierarchical culling (BVH of AABBs) for very large scenes.
+* Add GPU occlusion culling (HZB) once the pipeline grows beyond “readable sample” scale.
+* Replace the projected-size heuristic with real mesh LODs (or meshlets).
+
+== What to read next
+
+* `Rendering_Pipeline_Overview.adoc`
+* `ForwardPlus_Rendering.adoc`
+* `Ray_Query_Rendering.adoc`

en/Building_a_Simple_Engine/Advanced_Topics/Descriptor_Indexing_UpdateAfterBind.adoc

@@ -0,0 +1,73 @@
+= Descriptor Indexing and Stable Descriptor Updates
+
+Vulkan descriptors are powerful, but they’re also one of the easiest places to accidentally violate “frame in flight” lifetime rules.
+
+In this engine we use one simple rule:
+
+*Only update descriptors at a known safe point.*
+
+That rule keeps streaming stable, keeps validation clean, and (most importantly) keeps the code readable.
+
+== The safe point
+
+Each frame‑in‑flight has a fence. At the start of a new frame, we wait for that fence. Once it signals, the GPU is done with any work that referenced this frame’s descriptor sets. That’s the safe moment to update this frame’s sets.
+
+Why it matters: updating a set that’s still in use leads to invalid writes or so‑called “update‑after‑bind” violations unless you deliberately opt into those behaviors and structure your pipeline around them. The safe point pattern stays portable and clear.
+
+== What we update
+
+* Material textures that finished streaming.
+* The reflection texture binding (binding 10) for planar reflections.
+* Per‑frame buffers for Forward+ (tile headers/indices, lights SSBO) when resized.
+
+In Ray Query mode we also refresh the large texture table (the fixed-size sampler array) so that newly streamed textures become visible without rebuilding the pipeline.
+
+We refresh only the current frame’s sets at the safe point and leave other frames to update at their own turn. This prevents cross‑frame “flip‑flop” where a texture looks different on alternating frames.
+
+== Descriptor Indexing: when to use it
+
+Descriptor Indexing opens features such as variable‑sized arrays and update‑after‑bind. It’s powerful, but it shifts complexity to your synchronization and lifetime rules. In this sample we emphasize clarity:
+
+* We keep descriptor layouts simple and stable.
+* We update at the safe point rather than while a command buffer might still be pending.
+
+When we do use descriptor indexing features, it’s for one specific reason: large, non-uniformly indexed descriptor arrays (e.g., Ray Query’s texture table). In that case, correctness depends on:
+
+* enabling the descriptor indexing feature bits required by the GPU
+* marking bindings with the correct binding flags (when supported)
+* never caching stale Vulkan image/sampler handles across async streaming
+
+If your project needs truly dynamic descriptor arrays or frequent mid‑frame updates, Descriptor Indexing can be the right tool—just document the new invariants carefully.
+
+== Practical tips
+
+* Centralize descriptor updates; don’t scatter writes across the frame.
+* Use default textures for placeholders, then swap once—don’t bounce between real and default.
+* Prefer combined image samplers for samples aimed at teaching; split image/sampler only when you need the flexibility.
+
+== Where to look in the code
+
+* Frame safe point + per-frame descriptor refresh:
+** `renderer_rendering.cpp`
+* Descriptor set layouts (including update-after-bind flags when enabled):
+** `renderer_pipelines.cpp`
+* Device feature enable for descriptor indexing:
+** `renderer_core.cpp`
+* Streaming-safe Ray Query texture table rebuild:
+** `renderer_ray_query.cpp`
+
+== Future work ideas
+
+If you want to explore more advanced descriptor patterns:
+
+* Move to variable descriptor counts for texture tables (when device support is good enough for your targets).
+* Use separate image/sampler descriptors to share samplers across many textures.
+* Add a “descriptor stress test” mode (development-only) that rapidly streams textures to validate lifetime rules.
+
+== What to read next
+
+* `Synchronization_and_Streaming.adoc`
+* `Separate_Image_Sampler_Descriptors.adoc`
+* `Ray_Query_Rendering.adoc`
+
+This conservative approach avoids common pitfalls while keeping the code approachable.

en/Building_a_Simple_Engine/Advanced_Topics/Dynamic_Rendering_Local_Read.adoc

@@ -0,0 +1,39 @@
+= VK_KHR_dynamic_rendering_local_read — keeping color data in tile memory
+
+Dynamic Rendering lets you render without full render passes/subpasses. The `VK_KHR_dynamic_rendering_local_read` feature is a small but handy addition: it allows same‑pass reads from attachments via tile/local memory paths on hardware that supports it.
+
+== Why it matters
+
+Some post‑lighting effects and resolve‑like steps read the color you just wrote. With this feature, drivers can service those reads from fast on‑chip memory instead of round‑tripping to VRAM.
+
+== How we approach it
+
+* We enable the feature if present and keep codepaths compatible when it isn’t.
+* We still end a rendering instance before doing layout transitions. The feature does not allow arbitrary barrier misuse — regular Synchronization 2 rules apply.
+
+== Practical guidance
+
+* Treat this as an optimization, not a new API surface.
+* Keep stage/access masks precise. In this sample we keep transitions outside active rendering for clarity.
+
+== Where to look in the code
+
+* Feature detection and enablement:
+** `renderer_core.cpp` (device feature enable path)
+* Dynamic rendering setup + barriers:
+** `renderer_rendering.cpp`
+** `renderer_pipelines.cpp`
+
+== Future work ideas
+
+If you want to demonstrate local-read more directly:
+
+* Add a small “same-pass” effect that reads the current color attachment (e.g., a simple local contrast or edge highlight).
+* Add a debug HUD that prints whether the feature is enabled on the current device.
+* Compare performance with and without local-read on tile-based GPUs (mobile) using a fixed camera path.
+
+== What to read next
+
+* `Rendering_Pipeline_Overview.adoc`
+* `Synchronization_and_Streaming.adoc`
+* `Synchronization_2_Frame_Pacing.adoc`

en/Building_a_Simple_Engine/Advanced_Topics/ForwardPlus_Rendering.adoc

@@ -0,0 +1,37 @@
+= Forward+ Rendering in this Sample
+
+Forward+ keeps the forward shading model you already know, but limits the per‑pixel light loop to only the lights that might affect that pixel. It does this by dividing the screen into tiles (and optionally Z‑slices) and building per‑tile light lists with a compute pass.
+
+== What we do
+
+* Depth pre‑pass (optional): populates depth so the compute stage can cull by Z more effectively.
+* Compute pass: assigns lights to tiles (and slices) and writes compact lists to SSBOs.
+* Main PBR pass: for each pixel, fetch the tile header and iterate only those lights.
+
+== Where to look in code
+
+* Buffers, per-frame state, and descriptor bindings:
+** `renderer_compute.cpp` and `renderer_resources.cpp` (look for the `ForwardPlusPerFrame` data)
+* Compute dispatch and per-frame parameters:
+** `renderer_rendering.cpp`
+* Shader-side light list consumption:
+** `shaders/pbr.slang` (Forward+ light loop)
+
+== Tips
+
+* Tune tile size; 16×16 is a reasonable default for 1080p.
+* If you pre‑pass depth, use `depthWriteEnable=false` and `depthCompare=Equal` in the subsequent opaque color pass.
+
+== Future work ideas
+
+If you want to take this beyond a compact sample:
+
+* Upgrade from 2D tiles to clustered Forward+ (depth slicing and/or logarithmic Z).
+* Add a small light “budget” UI and debug visualizations (tile heatmap) behind a development build flag.
+* Add shadowing (start with a single directional light shadow map) and extend the tile data to include shadowed light indices.
+
+== What to read next
+
+* `Forward_ForwardPlus_Deferred.adoc`
+* `Rendering_Pipeline_Overview.adoc`
+* `Synchronization_2_Frame_Pacing.adoc`

en/Building_a_Simple_Engine/Advanced_Topics/Forward_ForwardPlus_Deferred.adoc

@@ -0,0 +1,102 @@
+= Forward, Forward+, and Deferred — choosing the right path
+
+Vulkan lets you build many kinds of pipelines. In practice, most real‑time engines gravitate toward one of three shading architectures: Forward, Forward+, or Deferred.
+
+This page explains what each one is, why this sample chooses Forward+, and where the relevant pieces live in the code.
+
+== Forward rendering
+
+Forward draws each object with its lighting in a single pass. It’s the most direct model: bind a material, bind lights (uniforms or textures/SSBOs), draw. It’s easy to reason about and integrates well with transparency and MSAA.
+
+Pros:
+
+* Simple and predictable.
+* Good with transparent objects and MSAA.
+* Great for small light counts or baked lighting.
+
+Cons:
+
+* Per‑pixel light loops can get expensive as the number of lights grows.
+* You evaluate lights even when most don’t affect the pixel.
+
+== Forward+ (what we use for dynamic lights)
+
+Forward+ partitions the screen into tiles and assigns lights to those tiles with a compute pass. The main pass then shades with only the lights relevant to the pixel’s tile. In this sample we use a lightweight Forward+ that focuses on emissive/simplified lights to keep the code approachable.
+
+Pros:
+
+* Scales to many local lights; you only evaluate lights that might affect the pixel.
+* Keeps forward’s strengths (transparency/MSAA friendliness).
+
+Cons:
+
+* Requires a pre‑pass or depth info and a compute dispatch to build the tile lists.
+* More moving parts than plain forward.
+
+== Deferred shading (when to consider it)
+
+Deferred writes material properties (G‑Buffer) in the first pass, then lights that buffer in a second pass. That turns lighting cost into “cost per lighted pixel” and tends to excel with many lights, but it makes transparency and MSAA trickier.
+
+Pros:
+
+* Many dynamic lights at high performance.
+* Clear separation of material/write and light/evaluate.
+
+Cons:
+
+* Transparent objects must be handled separately (often with a forward pass).
+* MSAA is more complex; memory bandwidth can be high.
+
+== What the sample uses (and why)
+
+We use Forward+ for small, dynamic lights and a forward material path for everything else. That keeps the code compact while still letting you place many little lights around the scene. Transparency (glass) is shaded in a second forward pass so order and blending are correct.
+
+If your project needs hundreds of shadowed lights and complex post‑lighting, explore a deferred path or a hybrid: deferred for opaque, forward for transparent.
+
+== Implementation highlights in this codebase
+
+* A small compute pass builds per‑tile light lists.
+* Per‑frame SSBOs hold tile headers/light indices; the main PBR pass reads those to loop only relevant lights.
+* Descriptor updates happen at the frame’s safe point so we don’t touch in‑use sets.
+
+== Where to look in the code
+
+* Forward/Forward+ render loop integration:
+** `renderer_rendering.cpp`
+* Pipeline + descriptor layout setup:
+** `renderer_pipelines.cpp`
+* Main PBR shader (reads per-tile light lists when Forward+ is enabled):
+** `shaders/pbr.slang`
+
+NOTE: The tile/cluster build shader is wired in `renderer_pipelines.cpp`. Start there and follow which compute pipeline is created for the Forward+ light assignment pass.
+
+== Choosing for your project
+
+Use Forward if:
+
+* Light count is low, transparency/MSAA are priorities, and you want the simplest pipeline.
+
+Use Forward+ if:
+
+* You want many local lights but still want forward’s strengths.
+
+Use Deferred if:
+
+* You need to scale to many dynamic lights with complex lighting, and you’re ready to solve transparency/MSAA separately.
+
+There’s no one answer; pick the simplest that meets your needs. You can always grow the pipeline later.
+
+== Future work ideas
+
+If you want to expand the lighting system beyond “readable sample”:
+
+* Add clustered Forward+ (3D clusters using depth slices) instead of 2D tiles.
+* Add shadows (start with a single directional shadow map, then add point/spot shadows).
+* Add a small deferred path for opaque only (keep transparent as forward).
+* Add ray query helpers for selective effects (reflection rays, shadow rays, or AO probes) without building a full RT pipeline.
+
+== What to read next
+
+* `Rendering_Pipeline_Overview.adoc`
+* `ForwardPlus_Rendering.adoc`
+* `Synchronization_2_Frame_Pacing.adoc`