diff --git a/design/references/p2-visibility-diagnostics-implemented.png b/design/references/p2-visibility-diagnostics-implemented.png new file mode 100644 index 0000000..6daee0f Binary files /dev/null and b/design/references/p2-visibility-diagnostics-implemented.png differ diff --git a/design/references/p2-visibility-diagnostics-prototype.md b/design/references/p2-visibility-diagnostics-prototype.md new file mode 100644 index 0000000..a78ec60 --- /dev/null +++ b/design/references/p2-visibility-diagnostics-prototype.md @@ -0,0 +1,11 @@ +# P2 visibility diagnostics visual reference + +![Generated visibility diagnostics prototype](p2-visibility-diagnostics-prototype.png) + +Generated with the built-in image generation tool before implementing the developer overlay. This is a visual prototype, not a Faset screenshot or a feature specification. The greybox scene, values, metrics, and viewport controls in the generated image are illustrative. In particular, Faset does not report the prototype's triangle-visibility, HZB texture-size, or history-length numbers. + +The implementation uses the prototype's compact three-mode visibility selector, near-black surfaces, restrained lavender selection, simple dividers, and grouping. It only reports actual `Renderer::FrameStats` fields and retains the existing ImGui diagnostics behavior. The runtime renderer and source code define functionality. + +![Implemented diagnostics in the headless Vulkan test](p2-visibility-diagnostics-implemented.png) + +The second image is the actual 640 × 420 test capture with a deliberately empty scene. It verifies the selected GPU frustum button and the real counters, with the panel scrolling on a small viewport. diff --git a/design/references/p2-visibility-diagnostics-prototype.png b/design/references/p2-visibility-diagnostics-prototype.png new file mode 100644 index 0000000..a0cd7fd Binary files /dev/null and b/design/references/p2-visibility-diagnostics-prototype.png differ diff --git a/docs/manual/editor/diagnostics.md b/docs/manual/editor/diagnostics.md index 59d4c15..8c4f84d 100644 --- a/docs/manual/editor/diagnostics.md +++ b/docs/manual/editor/diagnostics.md @@ -10,7 +10,9 @@ build/linux-debug/faset_editor --project examples/projects/collect-3d --gui On Windows, use `windows-debug` for both presets and `build/windows-debug/faset_editor.exe`. Press **F12** to show or hide the panel. Drag its title bar to move it; **Freeze counters** holds a completed-frame sample for inspection. Closing the panel does not stop rendering. Pointer gestures inside the overlay are kept out of the authoring UI. -The panel reports the previous completed frame: renderer wall time, GPU timestamp time where available, synchronous readback time, draw calls, packed vertices, culled meshes, textures, explicit Vulkan allocation sizes, actual validation availability/errors, and GPU pass-label count. Renderer wall time includes waiting for GPU work; it is not thread CPU usage. Memory excludes driver-internal allocations. The overlay itself adds drawing work, so hide it for a baseline performance measurement. +Use the **Visibility** selector to compare **Direct**, **GPU frustum**, and **GPU occlusion** on the same open scene. This is a live renderer setting for the Editor viewport; it does not change the scene or exported game. The selected mode is independent of **Freeze counters**. The counters describe the previous completed frame, so render one more frame after changing modes before reading them. **Path: active** under GPU visibility confirms that the GPU path actually ran; a selected GPU mode by itself is not evidence that it ran. + +The panel reports the previous completed frame: renderer wall time, GPU timestamp time where available, synchronous readback time, draw calls, packed vertices, culled meshes, textures, explicit Vulkan allocation sizes, actual validation availability/errors, and GPU pass-label count. It also shows whether GPU visibility ran, submitted indirect bins, visible instances, frustum rejects, deferred and post-pass visible instances, HZB history validity, and counts per prepared LOD level. A zero may mean either that there were no candidates or that the selected path did not run; check the active-path indicator. **HZB history: unavailable / invalid** is expected after a camera cut or resize until compatible depth history is available. Renderer wall time includes waiting for GPU work; it is not thread CPU usage. Memory excludes driver-internal allocations. The overlay itself adds drawing work, so hide it for a baseline performance measurement. The Vulkan backend emits `VK_EXT_debug_utils` labels for `ShadowMap`, `ForwardAndUI`, `Readback`, and, when presenting, `Presentation`. A graphics capture tool that supports this extension can identify those command-buffer regions. Labels remain available without the Khronos validation layer when the extension is exposed; unsupported systems continue rendering and report labels unavailable. A submitted-label count confirms calls were emitted, not that an external capture tool was tested. diff --git a/include/faset/editor/debug_overlay.hpp b/include/faset/editor/debug_overlay.hpp index 1df15a6..ddbf589 100644 --- a/include/faset/editor/debug_overlay.hpp +++ b/include/faset/editor/debug_overlay.hpp @@ -15,7 +15,7 @@ class DebugOverlay { void set_visible(bool); // F12 toggles the overlay; events captured by its widgets are removed for this frame. std::vector process_events(std::span); - void append(render::Snapshot&, const render::Renderer&, float delta_seconds); + void append(render::Snapshot&, render::Renderer&, float delta_seconds); private: struct Impl; diff --git a/src/editor/debug_overlay.cpp b/src/editor/debug_overlay.cpp index 4c2fe4a..0e8112d 100644 --- a/src/editor/debug_overlay.cpp +++ b/src/editor/debug_overlay.cpp @@ -168,7 +168,7 @@ std::vector DebugOverlay::process_events(std::spancontext); auto& state = *impl_; auto& io = ImGui::GetIO(); @@ -180,17 +180,36 @@ void DebugOverlay::append(render::Snapshot& output, const render::Renderer& rend auto& style = ImGui::GetStyle(); style = ImGuiStyle{}; ImGui::StyleColorsDark(); + // Developer tooling follows the editor's neutral, low-contrast dark palette. + style.Colors[ImGuiCol_WindowBg] = {0.11f, 0.11f, 0.115f, 0.98f}; + style.Colors[ImGuiCol_TitleBg] = {0.085f, 0.085f, 0.087f, 1.f}; + style.Colors[ImGuiCol_TitleBgActive] = {0.11f, 0.11f, 0.115f, 1.f}; + style.Colors[ImGuiCol_FrameBg] = {0.15f, 0.15f, 0.16f, 1.f}; + style.Colors[ImGuiCol_FrameBgHovered] = {0.19f, 0.19f, 0.20f, 1.f}; + style.Colors[ImGuiCol_Button] = {0.15f, 0.15f, 0.16f, 1.f}; + style.Colors[ImGuiCol_ButtonHovered] = {0.21f, 0.21f, 0.22f, 1.f}; + style.Colors[ImGuiCol_ButtonActive] = {0.24f, 0.23f, 0.28f, 1.f}; + style.Colors[ImGuiCol_Border] = {0.23f, 0.23f, 0.24f, 1.f}; + style.Colors[ImGuiCol_Separator] = style.Colors[ImGuiCol_Border]; + style.Colors[ImGuiCol_Text] = {0.88f, 0.88f, 0.89f, 1.f}; + style.Colors[ImGuiCol_TextDisabled] = {0.60f, 0.60f, 0.62f, 1.f}; + style.Colors[ImGuiCol_CheckMark] = {0.66f, 0.63f, 0.76f, 1.f}; + style.WindowRounding = 5.f; + style.FrameRounding = 4.f; + style.WindowBorderSize = 1.f; style.ScaleAllSizes(scale); style.FontScaleMain = scale; if (state.window_rect[2] == 0) - state.window_rect = {16 * scale, 44 * scale, 390 * scale, 310 * scale}; + state.window_rect = {16 * scale, 44 * scale, 420 * scale, 455 * scale}; state.scale = scale; } // Complete an ImGui frame while hidden too, so queued input cannot accumulate. ImGui::NewFrame(); if (state.visible) { ImGui::SetNextWindowPos({16 * scale, 44 * scale}, ImGuiCond_FirstUseEver); - ImGui::SetNextWindowSize({390 * scale, 310 * scale}, ImGuiCond_FirstUseEver); + ImGui::SetNextWindowSize({420 * scale, + std::min(455 * scale, std::max(220.f, io.DisplaySize.y - 60.f * scale))}, + ImGuiCond_FirstUseEver); if (ImGui::Begin("Faset diagnostics (F12)", &state.visible, ImGuiWindowFlags_NoSavedSettings | ImGuiWindowFlags_NoCollapse)) { const auto position = ImGui::GetWindowPos(), size = ImGui::GetWindowSize(); @@ -198,10 +217,33 @@ void DebugOverlay::append(render::Snapshot& output, const render::Renderer& rend if (!state.freeze) state.displayed = renderer.stats(); const auto& stats = state.displayed; - ImGui::TextUnformatted("Previous completed frame"); - ImGui::TextWrapped("%s", stats.device.c_str()); - ImGui::Checkbox("Freeze counters", &state.freeze); + ImGui::TextUnformatted("Visibility"); + const auto current_mode = renderer.visibility_mode(); + const struct { + const char* label; + render::VisibilityMode value; + } modes[] = {{"Direct", render::VisibilityMode::Direct}, + {"GPU frustum", render::VisibilityMode::GpuFrustum}, + {"GPU occlusion", render::VisibilityMode::GpuOcclusion}}; + const float button_width = + (ImGui::GetContentRegionAvail().x - 2.f * ImGui::GetStyle().ItemSpacing.x) / 3.f; + for (int i = 0; i < 3; ++i) { + if (i) + ImGui::SameLine(); + const bool selected = current_mode == modes[i].value; + if (selected) + ImGui::PushStyleColor(ImGuiCol_Button, ImVec4{.35f, .33f, .43f, 1.f}); + if (ImGui::Button(modes[i].label, {button_width, 0})) + renderer.set_visibility_mode(modes[i].value); + if (selected) + ImGui::PopStyleColor(); + } + ImGui::TextDisabled("Renderer mode; no scene or export changes"); ImGui::Separator(); + ImGui::TextUnformatted("Previous completed frame"); + ImGui::SameLine(); + ImGui::Checkbox("Freeze counters", &state.freeze); + ImGui::TextWrapped("%s", stats.device.c_str()); ImGui::Text("Frame: %llu", static_cast(stats.frame)); ImGui::Text("Render call (wall): %.3f ms", stats.cpu_ms); if (stats.gpu_ms > 0) @@ -212,6 +254,18 @@ void DebugOverlay::append(render::Snapshot& output, const render::Renderer& rend ImGui::Text("Draws: %u Packed vertices: %u", stats.draw_calls, stats.vertices); ImGui::Text("Culled meshes: %u Textures: %u", stats.culled_meshes, stats.texture_count); + ImGui::Separator(); + ImGui::TextUnformatted("GPU visibility"); + ImGui::Text("Path: %s", stats.gpu_visibility_active ? "active" : "inactive"); + ImGui::Text("Indirect bins: %u Visible: %u", stats.gpu_bins, + stats.gpu_visible_instances); + ImGui::Text("Frustum rejected: %u", stats.gpu_frustum_rejected); + ImGui::Text("HZB history: %s", stats.hzb_valid ? "valid" : "unavailable / invalid"); + ImGui::Text("Deferred: %u Post visible: %u", stats.gpu_occlusion_deferred, + stats.gpu_post_visible); + ImGui::Text("Prepared LOD: %u / %u / %u / %u+", stats.lod_counts[0], + stats.lod_counts[1], stats.lod_counts[2], stats.lod_counts[3]); + ImGui::Separator(); ImGui::Text("Vulkan allocations: %.2f MiB", double(stats.gpu_allocated_bytes) / 1048576.0); ImGui::Text("Validation: %s Errors: %u", diff --git a/tests/editor_debug_overlay.cpp b/tests/editor_debug_overlay.cpp index 21c6279..65997e6 100644 --- a/tests/editor_debug_overlay.cpp +++ b/tests/editor_debug_overlay.cpp @@ -25,6 +25,26 @@ int main(int argc, char** argv) { overlay.append(scene, renderer, 1.f / 60.f); require(!scene.ui_triangles.empty() && scene.ui_triangles.front().texture, "ImGui draw data reaches Faset's textured UI triangle API"); + require(renderer.visibility_mode() == render::VisibilityMode::Direct, + "Diagnostic visibility mode starts with the renderer default"); + render::Event mode_click; + mode_click.type = render::Event::Type::MouseDown; + mode_click.button = 1; + mode_click.x = 205; + mode_click.y = 99; + require(overlay.process_events(std::span(&mode_click, 1)).empty(), + "Visibility mode button captures pointer down"); + scene.ui_triangles.clear(); + overlay.append(scene, renderer, 1.f / 60.f); + mode_click.type = render::Event::Type::MouseUp; + require(overlay.process_events(std::span(&mode_click, 1)).empty(), + "Visibility mode button captures pointer up"); + scene.ui_triangles.clear(); + overlay.append(scene, renderer, 1.f / 60.f); + require(renderer.visibility_mode() == render::VisibilityMode::GpuFrustum, + "Clicking GPU frustum switches the live renderer"); + scene.ui_triangles.clear(); + overlay.append(scene, renderer, 1.f / 60.f); renderer.render(scene); auto shown = renderer.pixels(); std::size_t changed{};