From 56e10d99831e247af8a1e0370129212382dd7170 Mon Sep 17 00:00:00 2001 From: hydrogendeuteride Date: Mon, 29 Dec 2025 17:33:11 +0900 Subject: [PATCH] ADD: planet quadtree stabilized --- docs/RenderGraph.md | 205 +++++++++++++++++++++------ docs/asset_manager.md | 125 ++++++++++++++-- src/scene/planet/planet_quadtree.cpp | 74 ++++++++-- 3 files changed, 341 insertions(+), 63 deletions(-) diff --git a/docs/RenderGraph.md b/docs/RenderGraph.md index c6768e3..55578af 100644 --- a/docs/RenderGraph.md +++ b/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: `). -- Compile prints warnings for suspicious usages or format mismatches. +- **Per-pass debug labels**: `vkdebug::cmd_begin_label(cmd, "RG: ")` 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. diff --git a/docs/asset_manager.md b/docs/asset_manager.md index b55662e..9c516fe 100644 --- a/docs/asset_manager.md +++ b/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> loadGLTF(std::string_view nameOrPath)` — cached by canonical absolute path + - `std::optional> 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 createMesh(const MeshCreateInfo &info)` - - `std::shared_ptr createMesh(const std::string &name, std::span v, std::span i, std::shared_ptr material = {})` + - `std::shared_ptr createMesh(const std::string &name, std::span v, std::span i, std::shared_ptr material = {}, bool build_bvh = true)` - `std::shared_ptr getMesh(const std::string &name) const` - - `std::shared_ptr getPrimitive(std::string_view name) const` (returns existing default primitives if created) + - `std::shared_ptr 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 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 vertices{}; // when Provided std::span 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; // 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. diff --git a/src/scene/planet/planet_quadtree.cpp b/src/scene/planet/planet_quadtree.cpp index 10c6c49..c8f0f71 100644 --- a/src/scene/planet/planet_quadtree.cpp +++ b/src/scene/planet/planet_quadtree.cpp @@ -16,11 +16,54 @@ namespace planet PatchKey key{}; }; + void compute_patch_visibility_terms(const PatchKey &key, + const glm::dvec3 &patch_center_dir, + double radius_m, + double &out_cos_patch_radius, + double &out_sin_patch_radius, + double &out_bound_radius_m) + { + glm::dvec3 c = patch_center_dir; + const double c_len2 = glm::dot(c, c); + if (!(c_len2 > 0.0)) + { + c = glm::dvec3(0.0, 0.0, 1.0); + } + else + { + c *= (1.0 / std::sqrt(c_len2)); + } + + double u0 = 0.0, u1 = 0.0, v0 = 0.0, v1 = 0.0; + cubesphere_tile_uv_bounds(key.level, key.x, key.y, u0, u1, v0, v1); + + // Conservative angular radius: max angle from patch center direction to any corner direction. + double min_dot = 1.0; + min_dot = std::min(min_dot, glm::dot(c, cubesphere_unit_direction(key.face, u0, v0))); + min_dot = std::min(min_dot, glm::dot(c, cubesphere_unit_direction(key.face, u1, v0))); + min_dot = std::min(min_dot, glm::dot(c, cubesphere_unit_direction(key.face, u0, v1))); + min_dot = std::min(min_dot, glm::dot(c, cubesphere_unit_direction(key.face, u1, v1))); + + const double cos_a = glm::clamp(min_dot, -1.0, 1.0); + const double sin_a = std::sqrt(glm::max(0.0, 1.0 - cos_a * cos_a)); + + // Vertex positions are built as (unit_dir - patch_center_dir) * radius (chord length). + const double chord_r = radius_m * std::sqrt(glm::max(0.0, 2.0 - 2.0 * cos_a)); + + // Skirts extend inward; add a small safety margin so CPU culling stays conservative. + const double skirt_depth = cubesphere_skirt_depth_m(radius_m, key.level); + + out_cos_patch_radius = cos_a; + out_sin_patch_radius = sin_a; + out_bound_radius_m = glm::max(1.0, chord_r + skirt_depth); + } + bool is_patch_visible_horizon(const WorldVec3 &body_center_world, double radius_m, const WorldVec3 &camera_world, const glm::dvec3 &patch_center_dir, - double patch_edge_m) + double cos_patch_radius, + double sin_patch_radius) { const glm::dvec3 w = camera_world - body_center_world; const double d = glm::length(w); @@ -36,15 +79,13 @@ namespace planet const double cos_h = glm::clamp(radius_m / d, 0.0, 1.0); const double sin_h = std::sqrt(glm::max(0.0, 1.0 - cos_h * cos_h)); - // Expand horizon by patch angular radius to avoid culling near silhouettes. - const double half_diag_m = patch_edge_m * 0.7071067811865476; // sqrt(2)/2 - const double ang = glm::clamp(half_diag_m / radius_m, 0.0, glm::pi()); - const double cos_a = std::cos(ang); - const double sin_a = std::sin(ang); - // Visible if theta <= theta_h + ang: // cos(theta) >= cos(theta_h + ang) - const double cos_limit = cos_h * cos_a - sin_h * sin_a; + const double cos_limit = cos_h * cos_patch_radius - sin_h * sin_patch_radius; + if (!std::isfinite(cos_theta) || !std::isfinite(cos_limit)) + { + return true; // fail-safe: avoid catastrophic full culls + } return cos_theta >= cos_limit; } @@ -161,9 +202,22 @@ namespace planet const double patch_edge_m = cubesphere_patch_edge_m(radius_m, k.level); const glm::dvec3 patch_dir = cubesphere_patch_center_direction(k.face, k.level, k.x, k.y); + double cos_patch_radius = 1.0; + double sin_patch_radius = 0.0; + double patch_bound_r_m = 1.0; + if (_settings.horizon_cull || _settings.frustum_cull) + { + compute_patch_visibility_terms(k, patch_dir, radius_m, cos_patch_radius, sin_patch_radius, patch_bound_r_m); + } + if (_settings.horizon_cull) { - if (!is_patch_visible_horizon(body_center_world, radius_m, camera_world, patch_dir, patch_edge_m)) + if (!is_patch_visible_horizon(body_center_world, + radius_m, + camera_world, + patch_dir, + cos_patch_radius, + sin_patch_radius)) { _stats.nodes_culled++; continue; @@ -176,7 +230,7 @@ namespace planet if (_settings.frustum_cull) { const glm::vec3 patch_center_local = world_to_local(patch_center_world, origin_world); - const float bound_r = static_cast(patch_edge_m * 0.7071067811865476); + const float bound_r = static_cast(patch_bound_r_m); if (!is_patch_visible_frustum(patch_center_local, bound_r, scene_data.viewproj)) { _stats.nodes_culled++;