53 lines
4.4 KiB
Markdown
53 lines
4.4 KiB
Markdown
## 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. |