ADD: planet quadtree stabilized

docs/RenderGraph.md

@@ -7,29 +7,52 @@ Lightweight render graph that builds a per‑frame DAG from pass declarations, c
 - Centralize synchronization and image layout transitions across passes.
 - Make passes declarative: author declares reads/writes; the graph inserts barriers and begins/ends rendering.
 - Keep existing pass classes (`IRenderPass`) while migrating execution to the graph.
+- Provide runtime profiling and debugging capabilities for pass execution.
 
 ### High‑Level Flow
 
-- Engine creates the graph each frame and imports swapchain/G‑Buffer images: `src/core/engine.cpp:303`.
+- Engine creates the graph each frame and imports swapchain/G‑Buffer images: `src/core/engine.cpp`.
 - Each pass registers its work by calling `register_graph(graph, ...)` and declaring resources via a builder.
 - The graph appends a present chain (copy HDR `drawImage` → swapchain, then transition to `PRESENT`), optionally inserting ImGui before present.
-- `compile()` topologically sorts passes by data dependencies (read/write) and computes per‑pass barriers.
-- `execute(cmd)` emits barriers, begins dynamic rendering if attachments were declared, calls the pass record lambda, and ends rendering.
+- `compile()` topologically sorts passes by data dependencies (read/write hazards: RAW/WAW/WAR) and computes per‑pass barriers using `VkDependencyInfo` with `Vk*MemoryBarrier2`.
+- `execute(cmd)` creates timestamp query pools, emits barriers, begins dynamic rendering if attachments were declared, calls the pass record lambda, ends rendering, and records GPU/CPU timings.
+- `resolve_timings()` retrieves GPU timestamp results after the fence is signaled, converting them to milliseconds.
 
 ### Core API
 
+**Lifecycle:**
+- `RenderGraph::init(ctx)` — Initialize with engine context. See `src/render/graph/graph.cpp:28`.
+- `RenderGraph::clear()` — Clear all passes and reset resources. See `src/render/graph/graph.cpp:34`.
+- `RenderGraph::shutdown()` — Destroy GPU resources (query pools) before device shutdown. See `src/render/graph/graph.cpp:40`.
+
+**Pass Registration:**
 - `RenderGraph::add_pass(name, RGPassType type, BuildCallback build, RecordCallback record)`
   - Declare image/buffer accesses and attachments inside `build` using `RGPassBuilder`.
   - Do your actual rendering/copies in `record` using resolved Vulkan objects from `RGPassResources`.
-  - See: `src/render/graph/graph.h:36`, `src/render/graph/graph.cpp:51`.
+  - See: `src/render/graph/graph.h:42`, `src/render/graph/graph.cpp:91`.
+- Legacy form: `add_pass(name, type, record)` for passes with no resource declarations. See `src/render/graph/graph.cpp:117`.
 
-- `RenderGraph::compile()` → builds ordering and per‑pass `Vk*MemoryBarrier2` lists. See `src/render/graph/graph.cpp:83`.
+**Resource Creation:**
+- `import_image(desc)` / `import_buffer(desc)` — Import externally owned resources (deduplicated by VkImage/VkBuffer handle).
+- `create_image(desc)` / `create_buffer(desc)` — Create transient resources (destroyed at end of frame via deletion queue).
+- `create_depth_image(name, extent, format=D32_SFLOAT)` — Convenience helper for depth-only images with depth attachment + sampled usage. See `src/render/graph/graph.cpp:67`.
 
-- `RenderGraph::execute(cmd)` → emits barriers and dynamic rendering begin/end. See `src/render/graph/graph.cpp:592`.
+**Compilation and Execution:**
+- `RenderGraph::compile()` — Build topological ordering (Kahn's algorithm) and per‑pass `VkImageMemoryBarrier2` / `VkBufferMemoryBarrier2` lists. Returns false on error. See `src/render/graph/graph.cpp:123`.
+- `RenderGraph::execute(cmd)` — Creates timestamp query pool, emits barriers via `vkCmdPipelineBarrier2`, begins dynamic rendering if attachments exist, invokes record callbacks, ends rendering, and writes GPU timestamps. See `src/render/graph/graph.cpp:874`.
+- `RenderGraph::resolve_timings()` — Fetch GPU timestamp results after fence wait and convert to milliseconds. Must be called before next `execute()`. See `src/render/graph/graph.cpp:1314`.
 
-- Import helpers for engine images: `import_draw_image()`, `import_depth_image()`, `import_gbuffer_*()`, `import_swapchain_image(index)`. See `src/render/graph/graph.cpp:740`.
+**Import Helpers:**
+- `import_draw_image()`, `import_depth_image()`, `import_gbuffer_position()`, `import_gbuffer_normal()`, `import_gbuffer_albedo()`, `import_gbuffer_extra()`, `import_id_buffer()`, `import_swapchain_image(index)` — Convenience wrappers for engine-owned images. See `src/render/graph/graph.cpp:1147–1312`.
 
-- Present chain: `add_present_chain(draw, swapchain, appendExtra)` inserts Copy→Present passes and lets you inject extra passes (e.g., ImGui) in between. See `src/render/graph/graph.cpp:705`.
+**Present Chain:**
+- `add_present_chain(draw, swapchain, appendExtra)` — Inserts `PresentLetterbox` pass (blit draw→swapchain with letterboxing) and `PreparePresent` pass (layout transition to `PRESENT_SRC_KHR`). Optional `appendExtra` callback injects passes (e.g., ImGui) in between. See `src/render/graph/graph.cpp:1043`.
+
+**Debug and Profiling:**
+- `pass_count()`, `pass_name(i)`, `pass_enabled(i)`, `set_pass_enabled(i, enabled)` — Runtime pass enable/disable. See `src/render/graph/graph.h:105–108`.
+- `debug_get_passes(out)` — Retrieve pass metadata including GPU/CPU timings, resource access counts, attachment info. See `src/render/graph/graph.cpp:1163`.
+- `debug_get_images(out)` — Retrieve image metadata (imported/transient, format, extent, usage, lifetime). See `src/render/graph/graph.cpp:1186`.
+- `debug_get_buffers(out)` — Retrieve buffer metadata. See `src/render/graph/graph.cpp:1207`.
 
 ### Declaring a Pass
 
@@ -65,63 +88,155 @@ void MyPass::register_graph(RenderGraph* graph,
 
 ### Builder Reference (`RGPassBuilder`)
 
-- Images
-  - `read(RGImageHandle, RGImageUsage)` → sample/read usage for this pass.
-  - `write(RGImageHandle, RGImageUsage)` → write usage (compute/storage/transfer).
-  - `write_color(RGImageHandle, bool clearOnLoad=false, VkClearValue clear={})` → declares a color attachment.
-  - `write_depth(RGImageHandle, bool clearOnLoad=false, VkClearValue clear={})` → declares a depth attachment.
+Passed to the `BuildCallback` to declare resource accesses and attachments. See `src/render/graph/builder.h:40`.
 
-- Buffers
-  - `read_buffer(RGBufferHandle, RGBufferUsage)` / `write_buffer(RGBufferHandle, RGBufferUsage)`.
-  - Convenience import: `read_buffer(VkBuffer, RGBufferUsage, size, name)` and `write_buffer(VkBuffer, ...)` dedup by raw handle.
+**Image Access:**
+- `read(RGImageHandle, RGImageUsage)` — Declare sampled/read usage (e.g., `SampledFragment`, `TransferSrc`). See `src/render/graph/builder.cpp:20`.
+- `write(RGImageHandle, RGImageUsage)` — Declare write usage (e.g., `ComputeWrite`, `TransferDst`). See `src/render/graph/builder.cpp:25`.
+- `write_color(RGImageHandle, bool clearOnLoad=false, VkClearValue clear={})` — Declare color attachment with optional clear. Sets usage to `ColorAttachment` and `store=true` by default. See `src/render/graph/builder.cpp:30`.
+- `write_depth(RGImageHandle, bool clearOnLoad=false, VkClearValue clear={})` — Declare depth attachment with optional clear. See `src/render/graph/builder.cpp:40`.
 
-See `src/render/graph/builder.h:39` and impl in `src/render/graph/builder.cpp:20`.
+**Buffer Access:**
+- `read_buffer(RGBufferHandle, RGBufferUsage)` — Declare buffer read (e.g., `VertexRead`, `IndexRead`, `UniformRead`, `StorageRead`). See `src/render/graph/builder.cpp:50`.
+- `write_buffer(RGBufferHandle, RGBufferUsage)` — Declare buffer write (e.g., `StorageReadWrite`, `TransferDst`). See `src/render/graph/builder.cpp:55`.
+- Convenience overloads: `read_buffer(VkBuffer, RGBufferUsage, size, name)` and `write_buffer(VkBuffer, ...)` automatically import and deduplicate by raw `VkBuffer` handle. See `src/render/graph/builder.cpp:60,70`.
+
+**Resource Resolution (`RGPassResources`):**
+Used inside the `RecordCallback` to fetch resolved Vulkan objects. See `src/render/graph/builder.h:22`.
+- `image(RGImageHandle)` → `VkImage`
+- `image_view(RGImageHandle)` → `VkImageView`
+- `buffer(RGBufferHandle)` → `VkBuffer`
 
 ### Resource Model (`RGResourceRegistry`)
 
-- Imported vs transient resources are tracked uniformly with lifetime indices (`firstUse/lastUse`).
-- Imports are deduplicated by `VkImage`/`VkBuffer` and keep initial layout/stage/access as the starting state.
-- Transients are created via `ResourceManager` and auto‑destroyed at end of frame using the frame deletion queue.
-- See `src/render/graph/resources.h:11` and `src/render/graph/resources.cpp:1`.
+Manages both imported (externally owned) and transient (graph-owned) resources. See `src/render/graph/resources.h:52`.
+
+**Imported Resources:**
+- Deduplicated by raw Vulkan handle (`VkImage`/`VkBuffer`) using hash maps (`_imageLookup`/`_bufferLookup`). See `src/render/graph/resources.cpp`.
+- Initial layout/stage/access preserved from `RGImportedImageDesc`/`RGImportedBufferDesc`.
+- Ownership remains external; graph does not destroy these resources.
+
+**Transient Resources:**
+- Created via `ResourceManager` (`AllocatedImage`/`AllocatedBuffer`) with VMA allocations. See `src/render/graph/resources.cpp`.
+- Automatically destroyed at end of frame via frame deletion queue.
+- Usage flags must cover all declared usages (validated during `compile()`).
+
+**Lifetime Tracking:**
+- `firstUse` and `lastUse` indices computed during `compile()` (see `src/render/graph/graph.cpp:854–869`).
+- Used for debug visualization and future aliasing/pooling optimizations.
+
+**Records (`RGImageRecord`/`RGBufferRecord`):**
+Unified representation storing `VkImage`/`VkBuffer`, `VkImageView`, format, extent, initial state, and allocation info. See `src/render/graph/resources.h:11,34`.
 
 ### Synchronization and Layouts
 
-- For each pass, `compile()` compares previous state with desired usage and, if needed, adds a pre‑pass barrier:
-  - Images: `VkImageMemoryBarrier2` with stage/access/layout derived from `RGImageUsage`.
-  - Buffers: `VkBufferMemoryBarrier2` with stage/access derived from `RGBufferUsage`.
-- Initial state comes from the imported descriptor; if unknown, buffers default to `TOP_OF_PIPE`.
-- Format/usage checks:
-  - Warns if binding a depth format as color (and vice‑versa).
-  - Warns if a transient resource is used with flags it wasn’t created with.
+**Barrier Generation (see `src/render/graph/graph.cpp:232–851`):**
 
-Image usage → layout/stage examples (subset):
+For each enabled pass, `compile()` tracks per-resource state (`ImageState`/`BufferState`) and inserts barriers when hazards are detected:
 
-- `SampledFragment` → `SHADER_READ_ONLY_OPTIMAL`, `FRAGMENT_SHADER`.
-- `ColorAttachment` → `COLOR_ATTACHMENT_OPTIMAL`, `COLOR_ATTACHMENT_OUTPUT` (read|write).
-- `DepthAttachment` → `DEPTH_ATTACHMENT_OPTIMAL`, `EARLY|LATE_FRAGMENT_TESTS`.
-- `TransferDst` → `TRANSFER_DST_OPTIMAL`, `TRANSFER`.
-- `Present` → `PRESENT_SRC_KHR`, `BOTTOM_OF_PIPE`.
+**Image Barriers (`VkImageMemoryBarrier2`):**
+- Triggered by: layout change, prior write before read/write (RAW/WAW), prior reads before write (WAR).
+- Stage/access/layout derived from `RGImageUsage` via `usage_info_image()` (see `src/render/graph/graph.cpp:313–365`).
+- Aspect determined by usage and format (depth formats get `DEPTH_BIT`, others `COLOR_BIT`).
+- Initial state from `RGImportedImageDesc::currentLayout/currentStage/currentAccess`; if unknown (layout ≠ UNDEFINED but stage=NONE), conservatively assumes `ALL_COMMANDS + MEMORY_READ|WRITE`.
 
-Buffer usage → stage/access examples:
+**Buffer Barriers (`VkBufferMemoryBarrier2`):**
+- Triggered by: prior write before read/write, prior reads before write.
+- Stage/access derived from `RGBufferUsage` via `usage_info_buffer()` (see `src/render/graph/graph.cpp:367–411`).
+- Size: exact size for transients, `VK_WHOLE_SIZE` for imports (to avoid validation errors).
 
-- `IndexRead` → `INDEX_INPUT`, `INDEX_READ`.
-- `VertexRead` → `VERTEX_INPUT`, `VERTEX_ATTRIBUTE_READ`.
-- `UniformRead` → `ALL_GRAPHICS|COMPUTE`, `UNIFORM_READ`.
-- `StorageReadWrite` → `COMPUTE|FRAGMENT`, `SHADER_STORAGE_READ|WRITE`.
+**Usage Priority and Conflict Resolution:**
+When a pass declares multiple conflicting usages for the same resource (e.g., both `SampledFragment` and `ColorAttachment`), the graph selects the highest-priority usage for layout determination (see `image_usage_priority()` at `src/render/graph/graph.cpp:499`). Stages and access masks are unioned. Warns if layout mismatch detected.
+
+**Image Usage → Layout/Stage/Access Mapping:**
+See `usage_info_image()` at `src/render/graph/graph.cpp:313`.
+
+| RGImageUsage | Layout | Stage | Access |
+|---|---|---|---|
+| `SampledFragment` | `SHADER_READ_ONLY_OPTIMAL` | `FRAGMENT_SHADER` | `SHADER_SAMPLED_READ` |
+| `SampledCompute` | `SHADER_READ_ONLY_OPTIMAL` | `COMPUTE_SHADER` | `SHADER_SAMPLED_READ` |
+| `TransferSrc` | `TRANSFER_SRC_OPTIMAL` | `TRANSFER` | `TRANSFER_READ` |
+| `TransferDst` | `TRANSFER_DST_OPTIMAL` | `TRANSFER` | `TRANSFER_WRITE` |
+| `ColorAttachment` | `COLOR_ATTACHMENT_OPTIMAL` | `COLOR_ATTACHMENT_OUTPUT` | `COLOR_ATTACHMENT_READ\|WRITE` |
+| `DepthAttachment` | `DEPTH_ATTACHMENT_OPTIMAL` | `EARLY_FRAGMENT_TESTS\|LATE_FRAGMENT_TESTS` | `DEPTH_STENCIL_ATTACHMENT_READ\|WRITE` |
+| `ComputeWrite` | `GENERAL` | `COMPUTE_SHADER` | `SHADER_STORAGE_READ\|WRITE` |
+| `Present` | `PRESENT_SRC_KHR` | `BOTTOM_OF_PIPE` | `MEMORY_READ` |
+
+**Buffer Usage → Stage/Access Mapping:**
+See `usage_info_buffer()` at `src/render/graph/graph.cpp:367`.
+
+| RGBufferUsage | Stage | Access |
+|---|---|---|
+| `TransferSrc` | `TRANSFER` | `TRANSFER_READ` |
+| `TransferDst` | `TRANSFER` | `TRANSFER_WRITE` |
+| `VertexRead` | `VERTEX_INPUT` | `VERTEX_ATTRIBUTE_READ` |
+| `IndexRead` | `INDEX_INPUT` | `INDEX_READ` |
+| `UniformRead` | `ALL_GRAPHICS\|COMPUTE_SHADER` | `UNIFORM_READ` |
+| `StorageRead` | `COMPUTE_SHADER\|ALL_GRAPHICS` | `SHADER_STORAGE_READ` |
+| `StorageReadWrite` | `COMPUTE_SHADER\|ALL_GRAPHICS` | `SHADER_STORAGE_READ\|WRITE` |
+| `IndirectArgs` | `DRAW_INDIRECT` | `INDIRECT_COMMAND_READ` |
+
+**Validation Warnings:**
+- Depth-format image declared as color attachment (or vice versa). See `src/render/graph/graph.cpp:645–657`.
+- Transient resource used without required usage flags. See `src/render/graph/graph.cpp:659–667` (images), `818–826` (buffers).
+- Multiple conflicting layouts in single pass. See `src/render/graph/graph.cpp:536–543`.
 
 ### Built‑In Pass Wiring (Current)
 
 - Resource uploads (if any) → Background (compute) → Geometry (G‑Buffer) → Lighting (deferred) → SSR → Tonemap+Bloom → FXAA → Transparent → CopyToSwapchain → ImGui → PreparePresent.
 - See registrations in `src/core/engine.cpp`.
 
+### Topological Sorting and Scheduling
+
+**Dependency Graph Construction (see `src/render/graph/graph.cpp:127–231`):**
+- Reads/writes create directed edges: `writer → reader` (RAW), `writer → writer` (WAW), `reader → writer` (WAR).
+- Disabled passes are skipped during edge construction but remain in the pass list.
+- Kahn's algorithm produces a linear execution order respecting all dependencies.
+- If cycle detected (topological sort fails), falls back to insertion order but still computes barriers.
+
+**Execution Order:**
+Passes execute in sorted order (or insertion order if cycle). Only enabled passes run; disabled passes are skipped during `execute()`. See `src/render/graph/graph.cpp:895`.
+
+### Dynamic Rendering Setup
+
+**Render Area Calculation (see `src/render/graph/graph.cpp:936–1000`):**
+- Chooses min extent across all color/depth attachments.
+- Falls back to `EngineContext::drawExtent` if no attachments.
+- Warns if color attachments have mismatched extents.
+
+**Attachment Construction:**
+- Color attachments: `VkRenderingAttachmentInfo` with `clearOnLoad` → `LOAD_OP_CLEAR` / `LOAD_OP_LOAD`, `store` → `STORE_OP_STORE` / `STORE_OP_DONT_CARE`.
+- Depth attachment: similar logic; `clearValue.depthStencil` used if `clearOnLoad=true`.
+- Layout forced to `COLOR_ATTACHMENT_OPTIMAL` or `DEPTH_ATTACHMENT_OPTIMAL`.
+
+See `src/render/graph/graph.cpp:927–1012`.
+
+### Profiling and Timing
+
+**GPU Timing (Timestamps):**
+- Per-frame `VkQueryPool` with 2 queries per pass (begin/end). Created in `execute()`, destroyed in `resolve_timings()` or next `execute()`.
+- `vkCmdWriteTimestamp2()` at `ALL_COMMANDS_BIT` stage before/after pass recording (see `src/render/graph/graph.cpp:919–923`, `1028–1032`).
+- `resolve_timings()` fetches results with `VK_QUERY_RESULT_WAIT_BIT`, converts ticks to milliseconds using `timestampPeriod`. See `src/render/graph/graph.cpp:1314–1355`.
+
+**CPU Timing:**
+- `std::chrono::high_resolution_clock` measures command recording duration (`cpuStart`/`cpuEnd`). See `src/render/graph/graph.cpp:924`, `1026`.
+- Stored in `_lastCpuMillis` vector; accessible via `debug_get_passes()`.
+
+**Debug Structures:**
+- `RGDebugPassInfo`: name, type, enabled, resource counts, attachment info, `gpuMillis`, `cpuMillis`. See `src/render/graph/graph.h:66`.
+- `RGDebugImageInfo`: id, name, imported, format, extent, usage, lifetime. See `src/render/graph/graph.h:83`.
+- `RGDebugBufferInfo`: id, name, imported, size, usage, lifetime. See `src/render/graph/graph.h:94`.
+
 ### Notes & Limits
 
-- No aliasing or transient pooling yet; images created via `create_*` are released end‑of‑frame.
-- Graph scheduling uses a topological order by data dependency; it does not parallelize across queues.
-- Load/store control for attachments is minimal (`clearOnLoad`, `store` on `RGAttachmentInfo`).
-- Render area is the min of all declared attachment extents and `EngineContext::drawExtent`.
+- **No aliasing or transient pooling**: Transient images/buffers created via `create_*` are released end‑of‑frame via frame deletion queue.
+- **Single-queue execution**: Topological order is linear; no multi-queue parallelization.
+- **Minimal load/store control**: Only `clearOnLoad` and `store` flags on `RGAttachmentInfo`; no resolve or stencil control.
+- **No mid-pass barriers**: Conflicting usages within a single pass cannot be synchronized (warns but proceeds with unioned stages/access).
+- **No automatic resource aliasing**: Future work could reuse transient allocations based on lifetime non-overlap.
 
 ### Debugging
 
-- Each pass is wrapped with a debug label (`RG: <name>`).
-- Compile prints warnings for suspicious usages or format mismatches.
+- **Per-pass debug labels**: `vkdebug::cmd_begin_label(cmd, "RG: <name>")` wraps each pass (see `src/render/graph/graph.cpp:903–906`, `1035–1038`).
+- **Compile-time validation warnings**: Printed via `fmt::println` for format mismatches, missing usage flags, layout conflicts.
+- **Runtime introspection**: Use `debug_get_*` APIs to export pass/image/buffer metadata for visualization/debugging tools.

docs/asset_manager.md

@@ -22,15 +22,22 @@ auto chairPath = assets->modelPath("models/chair.glb");
 - Paths
   - `std::string shaderPath(std::string_view)`
   - `std::string assetPath(std::string_view)` / `modelPath(std::string_view)`
+  - `const AssetPaths& paths() const` / `void setPaths(const AssetPaths &p)` — get/set asset paths
 - glTF
   - `std::optional<std::shared_ptr<LoadedGLTF>> loadGLTF(std::string_view nameOrPath)` — cached by canonical absolute path
+  - `std::optional<std::shared_ptr<LoadedGLTF>> loadGLTF(std::string_view nameOrPath, const GLTFLoadCallbacks *cb)` — with custom callbacks
+  - `size_t prefetchGLTFTextures(std::string_view nameOrPath)` — schedule texture loads ahead of time
+  - `GLTFTexturePrefetchResult prefetchGLTFTexturesWithHandles(std::string_view nameOrPath)` — returns handles for tracking
 - Meshes
   - `std::shared_ptr<MeshAsset> createMesh(const MeshCreateInfo &info)`
-  - `std::shared_ptr<MeshAsset> createMesh(const std::string &name, std::span<Vertex> v, std::span<uint32_t> i, std::shared_ptr<GLTFMaterial> material = {})`
+  - `std::shared_ptr<MeshAsset> createMesh(const std::string &name, std::span<Vertex> v, std::span<uint32_t> i, std::shared_ptr<GLTFMaterial> material = {}, bool build_bvh = true)`
   - `std::shared_ptr<MeshAsset> getMesh(const std::string &name) const`
-  - `std::shared_ptr<MeshAsset> getPrimitive(std::string_view name) const` (returns existing default primitives if created)
+  - `std::shared_ptr<MeshAsset> getPrimitive(std::string_view name) const` — returns existing default primitives if created
   - `bool removeMesh(const std::string &name)`
+  - `bool removeMeshDeferred(const std::string &name, DeletionQueue &dq)` — deferred cleanup via deletion queue
   - `void cleanup()` — releases meshes, material buffers, and any images owned by the manager
+- Materials
+  - `std::shared_ptr<GLTFMaterial> createMaterialFromConstants(const std::string &name, const GLTFMetallic_Roughness::MaterialConstants &constants, MaterialPass pass = MaterialPass::MainColor)` — create PBR material from constants using engine default textures
 
 ### Mesh Creation Model
 
@@ -41,15 +48,19 @@ struct AssetManager::MaterialOptions {
   std::string albedoPath;        // resolved through AssetManager
   std::string metalRoughPath;    // resolved through AssetManager
   std::string normalPath;        // resolved through AssetManager (tangent-space normal)
+  std::string occlusionPath;     // resolved through AssetManager (ambient occlusion)
+  std::string emissivePath;      // resolved through AssetManager (emissive/glow)
   bool albedoSRGB      = true;   // VK_FORMAT_R8G8B8A8_SRGB when true
   bool metalRoughSRGB  = false;  // VK_FORMAT_R8G8B8A8_UNORM when false
   bool normalSRGB      = false;  // normal maps should be UNORM
+  bool occlusionSRGB   = false;  // occlusion should be UNORM
+  bool emissiveSRGB    = true;   // emissive is typically sRGB
   GLTFMetallic_Roughness::MaterialConstants constants{}; // extra[0].x as normalScale
   MaterialPass pass    = MaterialPass::MainColor; // or Transparent
 };
 
 struct AssetManager::MeshGeometryDesc {
-  enum class Type { Provided, Cube, Sphere };
+  enum class Type { Provided, Cube, Sphere, Plane, Capsule };
   Type type = Type::Provided;
   std::span<Vertex> vertices{};  // when Provided
   std::span<uint32_t> indices{}; // when Provided
@@ -65,8 +76,9 @@ struct AssetManager::MeshMaterialDesc {
 
 struct AssetManager::MeshCreateInfo {
   std::string name;              // cache key; reused if already created
-  MeshGeometryDesc geometry;     // Provided / Cube / Sphere
+  MeshGeometryDesc geometry;     // Provided / Cube / Sphere / Plane / Capsule
   MeshMaterialDesc material;     // Default or Textured
+  std::optional<BoundsType> boundsType; // optional override for collision/picking bounds
 };
 ```
 
@@ -113,9 +125,23 @@ si.material.kind = AssetManager::MeshMaterialDesc::Kind::Default;
 auto sphere = ctx->getAssets()->createMesh(si);
 ctx->scene->addMeshInstance("sphere.instance", sphere,
     glm::translate(glm::mat4(1.f), glm::vec3(2.f, 0.f, -2.f)));
+
+// Plane primitive
+AssetManager::MeshCreateInfo pi{};
+pi.name = "groundPlane";
+pi.geometry.type = AssetManager::MeshGeometryDesc::Type::Plane;
+pi.material.kind = AssetManager::MeshMaterialDesc::Kind::Default;
+auto plane = ctx->getAssets()->createMesh(pi);
+
+// Capsule primitive
+AssetManager::MeshCreateInfo capi{};
+capi.name = "capsuleA";
+capi.geometry.type = AssetManager::MeshGeometryDesc::Type::Capsule;
+capi.material.kind = AssetManager::MeshMaterialDesc::Kind::Default;
+auto capsule = ctx->getAssets()->createMesh(capi);
 ```
 
-Textured primitive (albedo + metal-rough + normal):
+Textured primitive (albedo + metal-rough + normal + occlusion + emissive):
 
 ```c++
 AssetManager::MeshCreateInfo ti{};
@@ -128,6 +154,8 @@ ti.material.kind = AssetManager::MeshMaterialDesc::Kind::Textured;
 ti.material.options.albedoPath = "textures/ground_albedo.png";     // sRGB
 ti.material.options.metalRoughPath = "textures/ground_mr.png";     // UNORM, G=roughness, B=metallic
 ti.material.options.normalPath     = "textures/ground_n.png";      // UNORM
+ti.material.options.occlusionPath  = "textures/ground_ao.png";     // UNORM (optional)
+ti.material.options.emissivePath   = "textures/ground_emit.png";   // sRGB (optional)
 ti.material.options.constants.extra[0].x = 1.0f;                    // normalScale
 // ti.material.options.pass = MaterialPass::Transparent; // optional
 
@@ -136,7 +164,25 @@ glm::mat4 tx = glm::scale(glm::mat4(1.f), glm::vec3(10.f, 1.f, 10.f));
 ctx->scene->addMeshInstance("ground.textured", texturedPlane, tx);
 ```
 
-Textured cube/sphere via options is analogous — set `geometry.type` to `Cube` or `Sphere` and fill `material.options`.
+Textured cube/sphere/plane/capsule via options is analogous — set `geometry.type` to `Cube`, `Sphere`, `Plane`, or `Capsule` and fill `material.options`.
+
+Using custom material from constants:
+
+```c++
+// Create a material with custom PBR values (using engine default textures)
+GLTFMetallic_Roughness::MaterialConstants constants{};
+constants.colorFactors = glm::vec4(1.0f, 0.0f, 0.0f, 1.0f); // red
+constants.metal_rough_factors = glm::vec4(0.0f, 0.8f, 0.0f, 0.0f); // non-metallic, rough
+
+auto redMaterial = ctx->getAssets()->createMaterialFromConstants(
+    "red_rough_material",
+    constants,
+    MaterialPass::MainColor
+);
+
+// Use with custom mesh
+auto mesh = ctx->getAssets()->createMesh("custom_mesh", vertices, indices, redMaterial);
+```
 
 Runtime glTF spawning:
 
@@ -154,11 +200,74 @@ ctx->scene->addGLTFInstance("chair01", *chair,
 ctx->scene->removeGLTFInstance("chair01");
 ```
 
+### Texture Prefetching
+
+Queue texture loads for a glTF file ahead of time. This parses the glTF, builds TextureCache keys for referenced images (both external URIs and embedded images in buffers), and issues `TextureCache::request()` calls. Actual uploads happen via the normal per-frame pump.
+
+```c++
+// Simple version: returns number of textures scheduled
+size_t count = ctx->getAssets()->prefetchGLTFTextures("models/heavy_asset.glb");
+
+// Advanced version: returns handles for tracking progress
+auto result = ctx->getAssets()->prefetchGLTFTexturesWithHandles("models/heavy_asset.glb");
+fmt::println("Scheduled {} textures", result.scheduled);
+// Use result.handles with TextureCache to monitor loading state
+```
+
+Texture prefetching is particularly useful when combined with `AsyncAssetLoader` for loading large models in the background.
+
+### Async Asset Loading
+
+The `AsyncAssetLoader` class provides asynchronous glTF loading with worker threads for CPU-bound tasks (file I/O, parsing, mesh/BVH building). GPU uploads are still deferred through ResourceManager and the Render Graph.
+
+```c++
+// Access via EngineContext
+auto *loader = ctx->async_loader;
+
+// Queue a model to load in the background
+auto jobID = loader->load_gltf_async(
+    "spaceship_01",                      // scene instance name
+    "models/spaceship.glb",              // model path (resolved via AssetManager)
+    glm::translate(glm::mat4(1.f), glm::vec3(0, 5, -10)), // transform
+    true                                  // preload textures
+);
+
+// Check progress in your update loop
+JobState state;
+float progress;
+std::string error;
+if (loader->get_job_status(jobID, state, progress, &error)) {
+    if (state == JobState::Completed) {
+        fmt::println("Model loaded successfully!");
+    } else if (state == JobState::Failed) {
+        fmt::println("Failed to load: {}", error);
+    }
+}
+
+// Commit completed jobs to the scene (call once per frame)
+loader->pump_main_thread(*ctx->scene);
+
+// Alternative: use WorldVec3 for large-world coordinates
+auto jobID2 = loader->load_gltf_async(
+    "distant_building",
+    "models/building.glb",
+    WorldVec3{1000000.0, 0.0, 500000.0}, // world position
+    glm::quat(1.0f, 0.0f, 0.0f, 0.0f),   // rotation
+    glm::vec3(1.0f),                      // scale
+    false                                  // don't preload textures
+);
+```
+
+The `AsyncAssetLoader` integrates with `TextureCache` to track texture streaming progress. When `preload_textures` is true, the loader will schedule all model textures for loading and track their residency state.
+
 ### Notes
 
-- Default primitives: The engine creates default Cube/Sphere meshes via `AssetManager` and registers them as dynamic scene instances.
+- Default primitives: The engine creates default Cube/Sphere/Plane/Capsule meshes via `AssetManager` and registers them as dynamic scene instances.
 - Reuse by name: `createMesh("name", ...)` returns the cached mesh if it already exists. Use a unique name or call `removeMesh(name)` to replace.
-- sRGB/UNORM: Albedo is sRGB by default, metal-rough is UNORM by default. Adjust via `MaterialOptions`.
+- sRGB/UNORM: Albedo and emissive are sRGB by default, metal-rough/normal/occlusion are UNORM by default. Adjust via `MaterialOptions`.
 - Hot reload: Shaders are resolved via `shaderPath()`; pipeline hot reload is handled by the pipeline manager, not the AssetManager.
 - Normal maps: Supported. If `normalPath` is empty, a flat normal is used.
+- Occlusion & Emissive: Supported via `occlusionPath` and `emissivePath` in `MaterialOptions`.
 - Tangents: Loaded from glTF when present; otherwise generated. Enable MikkTSpace at configure time with `-DENABLE_MIKKTS=ON`.
+- BVH building: Enabled by default for meshes (`build_bvh = true`). Required for picking and ray-tracing.
+- Deferred cleanup: Use `removeMeshDeferred()` when destroying meshes during rendering to avoid destroying resources that are in-flight on the GPU.