Init Repo

2026-06-03 09:00:11 +08:00
commit 9be48d8b9e
155 changed files with 14827 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-08
@@ -0,0 +1,53 @@
+## Context
+
+The application currently uses a fixed-position, fixed-size layout for all ImGui panels. Each window is placed via `SetNextWindowPos`/`SetNextWindowSize` with `ImGuiCond_FirstUseEver`. The `imconfig.h` file has docking-related macros fully commented out, and `ImGuiContext::Initialize()` only sets `ImGuiConfigFlags_NavEnableKeyboard`. A comment in the code explicitly states that docking requires a special build configuration that was intentionally deferred.
+
+ImGui's docking branch (`docking` in the imgui repo) has been stable for years and is widely used. The prebuilt ImGui source in `third_party/Imgui-1.92.7` may or may not include docking support — this must be verified.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Enable ImGui docking at compile time and runtime
+- Create a full-window dockspace spanning the entire application viewport
+- All existing panels (Scene Hierarchy, Layer Panel, Viewport, Property Panel, Stage Info) become dockable
+- Layout persists across sessions via `imgui.ini`
+- Window visibility toggles continue to work via the View menu
+
+**Non-Goals:**
+- Multi-viewport support (floating OS windows) — this requires additional `ImGuiConfigFlags_ViewportsEnable` and is not needed
+- Custom docking layout presets or saved workspace files
+- Theming or styling changes beyond docking enablement
+- Refactoring the panel class hierarchy — panels keep their existing `Render()` signatures
+
+## Decisions
+
+### 1. Use `ImGui::DockSpaceOverViewport` over manual `DockSpace`
+
+**Rationale**: `DockSpaceOverViewport()` automatically creates a dockspace that fills the main viewport and handles resizing. A manual `DockSpace()` requires managing the dockspace ID and the host window's position/size manually. For a single-window application, `DockSpaceOverViewport` is simpler and sufficient.
+
+**Alternative considered**: Manual `ImGui::DockSpace(ImGui::GetID("MainDockSpace"))` inside a full-viewport `ImGui::Begin/End` block. Rejected because it requires more boilerplate with no benefit for our use case.
+
+### 2. Enable docking via CMake compile definition, not imconfig.h
+
+**Rationale**: Adding `target_compile_definitions(... PRIVATE IMGUI_HAS_DOCK)` in `FindImgui.cmake` keeps the configuration centralized and avoids modifying third-party header files. This is the standard approach for conditionally enabling ImGui features.
+
+**Alternative considered**: Modifying `imconfig.h` to uncomment `#define IMGUI_HAS_DOCK`. Rejected because it modifies third-party source and would be lost on imgui updates.
+
+### 3. Remove `SetNextWindowPos`/`SetNextWindowSize` entirely
+
+**Rationale**: When docking is enabled, ImGui manages window positions. Keeping `SetNextWindowPos` calls could interfere with docking behavior. Windows will be created as dockable by default, and the docking system handles placement.
+
+**Alternative considered**: Keeping `SetNextWindowPos` with `ImGuiCond_FirstUseEver` as fallback for undocked state. Rejected because it adds complexity with no user benefit — the docking system's layout persistence already handles first-use defaults.
+
+### 4. Keep `ImGuiWindowFlags_NoCollapse` on main panels
+
+**Rationale**: Core tool panels (Scene Hierarchy, Layer Panel, Viewport, Property Panel) should always be accessible. Allowing collapse could leave users with no visible panel. The View menu already provides show/hide toggles for optional panels.
+
+**Alternative considered**: Allowing collapse on all windows. Rejected because it's easy for users to lose core panels with no obvious way to restore them.
+
+## Risks / Trade-offs
+
+- **Risk**: The prebuilt imgui library in `third_party/Imgui-1.92.7` may not include the docking branch source. → **Mitigation**: Verify the imgui source files contain `DockSpaceOverViewport` and related docking APIs. If not, the docking branch must be fetched.
+- **Risk**: `imgui.ini` may accumulate stale docking layout data across builds/versions. → **Mitigation**: This is standard ImGui behavior; users can reset by deleting `imgui.ini`. Not a new problem.
+- **Risk**: Docking increases per-frame CPU overhead slightly due to dock node management. → **Mitigation**: Negligible for the number of windows in this application (5-6 panels). No measurable performance impact expected.
+- **Risk**: The current legacy WGL/OpenGL setup uses `#version 130` which is compatible with docking. → **Mitigation**: Docking operates at the ImGui level (vertex data generation), not at the rendering backend level. No OpenGL version concerns.
@@ -0,0 +1,31 @@
+## Why
+
+All ImGui windows are fixed-position, fixed-size, and non-dockable, forcing users into a rigid layout that cannot adapt to different screen sizes, workflows, or preferences. Enabling ImGui's built-in docking system allows users to freely arrange, resize, tab, and float panels to suit their workflow — a critical UX feature for any editor application.
+
+## What Changes
+
+- Enable ImGui docking by defining `IMGUI_HAS_DOCK` at compile time via CMake
+- Set `ImGuiConfigFlags_DockingEnable` in the ImGui IO config flags
+- Create a full-window dockspace in the main render loop
+- Replace hardcoded `SetNextWindowPos`/`SetNextWindowSize` calls with dockable window creation
+- Remove manual positioning logic for all panels (Scene Hierarchy, Layer Panel, Viewport, Property Panel, Stage Info)
+- Preserve window visibility toggles (Stage Info, Demo Window) via the View menu
+- Ensure dock layout persists across sessions via `imgui.ini`
+
+## Capabilities
+
+### New Capabilities
+
+- `imgui-docking`: Main application dock space with draggable, resizable, and tabbable panels. Includes compile-time docking enablement, runtime dockspace creation, and panel migration from fixed-position to dock-based layout.
+
+### Modified Capabilities
+
+<!-- No existing specs to modify -->
+
+## Impact
+
+- **CMake**: `FindImgui.cmake` — add `IMGUI_HAS_DOCK` compile definition
+- **imconfig.h**: May need to ensure docking macros are uncommented (or rely on CMake define)
+- **ImGuiContext.cpp**: Add `ImGuiConfigFlags_DockingEnable` to IO config flags in `Initialize()`
+- **Application.cpp**: Add dockspace creation at the start of `RenderUI()`, remove all `SetNextWindowPos`/`SetNextWindowSize` calls from panel rendering
+- **All panel windows**: No API changes — windows remain compatible with docking as-is
@@ -0,0 +1,64 @@
+## ADDED Requirements
+
+### Requirement: Docking is enabled at compile time
+
+The build system SHALL define `IMGUI_HAS_DOCK` prior to compiling any translation unit that includes `imgui.h`.
+
+#### Scenario: ImGui compiled with docking support
+- **WHEN** the project is compiled with CMake
+- **THEN** `IMGUI_HAS_DOCK` is defined for all imgui source files and any file including `imgui.h`
+
+### Requirement: Docking is enabled at runtime
+
+The application SHALL set `ImGuiConfigFlags_DockingEnable` in the ImGui IO configuration during initialization.
+
+#### Scenario: Docking flag set on startup
+- **WHEN** the application starts and `ImGuiContext::Initialize()` is called
+- **THEN** `io.ConfigFlags` includes `ImGuiConfigFlags_DockingEnable`
+
+### Requirement: Main dockspace spans the application window
+
+The application SHALL create a full-viewport dockspace via `ImGui::DockSpaceOverViewport()` at the start of each frame's UI rendering.
+
+#### Scenario: Dockspace created each frame
+- **WHEN** `Application::RenderUI()` executes
+- **THEN** `ImGui::DockSpaceOverViewport()` is called after `NewFrame()` and before any panel `Begin/End` calls
+
+#### Scenario: Dockspace fills the entire viewport
+- **WHEN** the application window is resized
+- **THEN** the dockspace automatically fills the new window dimensions
+
+### Requirement: All panels are dockable
+
+All application panels SHALL be created as dockable ImGui windows that integrate with the dockspace.
+
+#### Scenario: Panel windows use standard Begin/End
+- **WHEN** any panel window is rendered
+- **THEN** its `ImGui::Begin()` call does not include `SetNextWindowPos` or `SetNextWindowSize` calls
+- **AND** the window can be dragged, docked, tabbed, or floated by the user
+
+#### Scenario: Core panels cannot be collapsed
+- **WHEN** the Scene Hierarchy, Layer Panel, Viewport, or Property Panel windows are rendered
+- **THEN** each window is created with `ImGuiWindowFlags_NoCollapse`
+
+### Requirement: Window visibility toggles persist
+
+Existing View menu toggles for Stage Info and Demo Window SHALL continue to control window visibility.
+
+#### Scenario: Toggle Stage Info visibility
+- **WHEN** the user clicks "Stage Info" in the View menu
+- **THEN** the Stage Info window appears or disappears
+- **AND** the toggle state is reflected by the checkmark in the menu item
+
+#### Scenario: Toggle Demo Window visibility
+- **WHEN** the user clicks "ImGui Demo" in the View menu
+- **THEN** the ImGui Demo Window appears or disappears
+- **AND** the toggle state is reflected by the checkmark in the menu item
+
+### Requirement: Dock layout persists across sessions
+
+The docking layout SHALL be saved to and restored from `imgui.ini` automatically by ImGui's built-in persistence.
+
+#### Scenario: Layout restored on restart
+- **WHEN** the user arranges panels into a custom docking layout and restarts the application
+- **THEN** the previous docking layout is restored
@@ -0,0 +1,20 @@
+## 1. Build Configuration
+
+- [x] 1.1 Verify that `third_party/Imgui-1.92.7` source files contain docking APIs (`DockSpaceOverViewport`, `ImGuiConfigFlags_DockingEnable`). If not, fetch the docking branch of imgui.
+- [x] 1.2 Add `IMGUI_HAS_DOCK` compile definition in `cmake/modules/FindImgui.cmake` via `target_compile_definitions` on the imgui library target.
+
+## 2. Runtime Docking Enablement
+
+- [x] 2.1 In `src/ui/ImGuiContext.cpp`, add `ImGuiConfigFlags_DockingEnable` to `io.ConfigFlags` in the `Initialize()` method.
+- [x] 2.2 In `src/ui/Application.cpp`, add `ImGui::DockSpaceOverViewport()` call in `RenderUI()` after `NewFrame()` and before any window/panel `Begin/End` calls.
+
+## 3. Panel Migration to Dockable Layout
+
+- [x] 3.1 Remove all `ImGui::SetNextWindowPos()` and `ImGui::SetNextWindowSize()` calls from every panel window in `Application::RenderUI()` (Scene Hierarchy, Layer Panel, Viewport, Property Panel, Stage Info, Demo Window).
+- [x] 3.2 Add `ImGuiWindowFlags_NoCollapse` to the four core panels: Scene Hierarchy, Layer Panel, Viewport, Property Panel.
+- [x] 3.3 Verify that the View menu visibility toggles (Stage Info, Demo Window) continue to work with dockable windows.
+
+## 4. Build and Verification
+
+- [x] 4.1 Run `cmake --preset default` and `cmake --build` to verify the project compiles without errors.
+- [ ] 4.2 Launch `App.exe` and confirm: dockspace fills the window, panels are draggable/dockable/tabbable, layout persists after restart (check `imgui.ini`), and View menu toggles work correctly.