XCEngine/docs/plan/NewEditor_D3D12_UI_RootArchitectureRefactorPlan_2026-04-21.md

# NewEditor D3D12 UI Root Architecture Refactor Plan

Date: `2026-04-21`

Supersedes:
- `docs/used/NewEditor_D3D12_UI_Pass_RefactorPlan_Archived_2026-04-21.md`

## Goal

Keep `new_editor` on the native `D3D12` main-window path and refactor the UI stack from the root so the renderer can actually reach native-backend performance ceilings.

This plan is not a patch plan. It is a structural replacement plan.

## Hard Constraints

- Do not roll the main editor window back to `D2D` or `D3D11On12`.
- Do not keep long-term fallback-heavy mixed rendering for the main window.
- Do not treat scene rendering optimization as part of this task.
- Do not optimize around symptoms while preserving the current multi-rebuild architecture.
- Do not touch unrelated dirty worktree changes outside the scoped editor/UI files.

## Confirmed Root Problems

### 1. The editor frame graph rebuilds shell/workspace layout too many times per frame

Confirmed call-chain facts:

- `new_editor/app/Platform/Win32/EditorWindow.cpp`
- `new_editor/app/Platform/Win32/EditorWindowFrameOrchestrator.cpp`
- `new_editor/app/Composition/EditorShellRuntime.cpp`
- `new_editor/src/Shell/UIEditorShellInteraction.cpp`
- `new_editor/src/Workspace/UIEditorWorkspaceInteraction.cpp`
- `new_editor/src/Workspace/UIEditorWorkspaceCompose.cpp`
- `new_editor/src/Docking/UIEditorDockHostInteraction.cpp`
- `new_editor/src/Docking/UIEditorDockHost.cpp`

Current behavior:

- the shell request is rebuilt multiple times inside one frame
- the workspace compose path is rebuilt again for input ownership preview and again for final compose
- dock host interaction rebuilds dock layout twice inside one rebuild
- the renderer then consumes a fresh immediate `UIDrawData` again instead of a retained render product

Result:

- CPU cost scales with repeated full-tree work before rendering even begins
- a fast renderer still receives expensive, redundant input

### 2. The current native D3D12 UI renderer is not GPU-native in architecture

Confirmed files:

- `new_editor/app/Rendering/D3D12/D3D12UiRenderer.cpp`
- `new_editor/app/Rendering/D3D12/D3D12UiTextureHost.cpp`
- `new_editor/app/Rendering/Native/NativeRenderer.cpp`

Current behavior:

- rounded rects, circles, outlines and fills are tessellated on the CPU every frame
- text is cached as `string -> texture`, not `glyph -> atlas`
- rasterized text misses go through `DirectWrite + WIC + upload`
- the renderer rebuilds vertices, indices and batches from high-level draw commands every frame

Result:

- `D3D12` is only the final API, not the actual rendering architecture
- the current implementation replaces a mature high-level renderer with a naive CPU front-end

### 3. The main editor output is still immediate-command oriented instead of retained and dirty-driven

Confirmed files:

- `new_editor/app/Composition/EditorShellRuntime.cpp`
- `new_editor/app/Features/Project/ProjectPanel.cpp`
- `new_editor/app/Features/Hierarchy/HierarchyPanel.cpp`
- `new_editor/app/Features/Inspector/InspectorPanel.cpp`
- `new_editor/src/Shell/UIEditorShellCompose.cpp`

Current behavior:

- panels already keep interaction and layout state
- but final rendering still emits immediate `UIDrawList` commands every frame
- there is no long-lived UI render scene, panel packet cache, or subtree dirty invalidation on the final render path

Result:

- stable UI still pays repeated build and translation costs

## End State

The final main-window rendering chain must be:

```text
single authoritative shell/workspace frame
-> retained UI scene / panel render packets
-> native D3D12 primitive pass + native D3D12 text pass
-> same command list
-> same direct queue
-> explicit backbuffer state transitions
-> present
```

The final main-window chain must not contain:

- `D3D11On12`
- `D2D` draw submission
- per-frame CPU polygon generation for common UI primitives
- per-string text textures as the primary text path
- repeated full compose/layout rebuilds inside one frame

## Non-Goals

- scene renderer optimization
- viewport render graph redesign
- Vulkan/OpenGL editor-host parity during this task
- cosmetic UI redesign

## Refactor Principles

- Freeze the already validated present/swapchain/backbuffer path first.
- Refactor top-down ownership and bottom-up rendering architecture together.
- Make one frame produce one authoritative layout/compose snapshot.
- Move from immediate draw commands to retained render packets.
- Move from CPU geometry generation to GPU-friendly primitive evaluation.
- Move from string texture caching to glyph atlas rendering.
- Remove dead compatibility paths after replacement is validated.

## Workstream A: Freeze The Validated D3D12 Present Path

Purpose:

- protect the working `D3D12` present path from further accidental churn while higher layers are rebuilt

Scope:

- `new_editor/app/Rendering/D3D12/D3D12WindowRenderLoop.*`
- `new_editor/app/Rendering/D3D12/D3D12WindowRenderer.*`
- `new_editor/app/Rendering/D3D12/D3D12WindowSwapChainPresenter.*`
- `new_editor/app/Rendering/D3D12/D3D12HostDevice.*`

Required outcome:

- preserve current explicit `Present -> RenderTarget -> Present` flow
- preserve current `Immediate + maxFrameLatency=1` policy unless later measurement proves a different policy is better
- do not mix this workstream with UI-pass redesign logic

## Workstream B: Collapse Shell And Workspace To One Authoritative Frame Build

Purpose:

- remove repeated layout/compose/rebuild work inside a single frame

Primary files:

- `new_editor/app/Platform/Win32/EditorWindowFrameOrchestrator.cpp`
- `new_editor/app/Composition/EditorShellRuntime.cpp`
- `new_editor/src/Shell/UIEditorShellInteraction.cpp`
- `new_editor/src/Shell/UIEditorShellCompose.cpp`
- `new_editor/src/Workspace/UIEditorWorkspaceInteraction.cpp`
- `new_editor/src/Workspace/UIEditorWorkspaceCompose.cpp`
- `new_editor/src/Docking/UIEditorDockHostInteraction.cpp`
- `new_editor/src/Docking/UIEditorDockHost.cpp`
- `new_editor/src/Panels/UIEditorPanelContentHost.cpp`

Required structural changes:

- introduce one authoritative frame object for shell/workspace layout, hit-test inputs, mounted panel bounds and viewport slots
- stop rebuilding shell request multiple times unless a real state mutation invalidates the frame
- remove preview compose + final compose duplication where the same layout data is recomputed from scratch
- remove the double `BuildUIEditorDockHostLayout()` pattern inside dock-host interaction rebuilds
- make input ownership resolution consume the authoritative layout snapshot instead of forcing an extra full compose
- ensure panel mount bounds, viewport slot bounds and dock hit-test data all come from the same frame snapshot

Deliverables:

- one frame build entrypoint
- one dock-host layout build per frame in the steady state
- explicit invalidation points when menu state, dock mutation, panel visibility or viewport mounts actually change

Acceptance criteria:

- no steady-state frame should perform repeated full shell/workspace compose passes without a state mutation that requires recomputation

## Workstream C: Introduce A Retained UI Scene Instead Of Per-Frame Immediate UIDrawData

Purpose:

- stop rebuilding the final render payload from scratch for stable UI

Primary files:

- `new_editor/app/Composition/EditorShellRuntime.cpp`
- `new_editor/app/Features/Project/ProjectPanel.*`
- `new_editor/app/Features/Hierarchy/HierarchyPanel.*`
- `new_editor/app/Features/Inspector/InspectorPanel.*`
- `new_editor/app/Features/Console/ConsolePanel.*`
- `new_editor/app/Features/ColorPicker/ColorPickerPanel.*`
- `new_editor/app/Features/Scene/SceneViewportFeature.*`
- `new_editor/app/Platform/Win32/EditorWindow.cpp`

Required structural changes:

- define a retained `UiScene` or equivalent render-product layer for the main editor window
- each major shell region and hosted panel produces a stable render packet instead of immediate draw commands
- packets carry primitive instances, image instances, text runs, clip rectangles and z/order information
- packets are rebuilt only when their owning state is dirty
- stable frame append becomes packet aggregation, not command regeneration

Recommended ownership model:

- shell chrome packet
- menu bar packet
- toolbar packet
- status bar packet
- dock host packet
- per-panel packet
- overlay packet

Acceptance criteria:

- a steady-state empty panel must not rebuild full command streams each frame
- unchanged panels must be reusable across frames

## Workstream D: Replace The Current D3D12UiRenderer With A Real Native Primitive Pass

Purpose:

- stop treating `D3D12` as a thin API wrapper around CPU-generated meshes

Primary files:

- `new_editor/app/Rendering/D3D12/D3D12UiRenderer.*`
- potentially new files under `new_editor/app/Rendering/D3D12/`

Current path to retire:

- CPU polygon generation for rounded rects and circles
- CPU-generated outline rings for common primitives
- direct translation of every immediate command to transient vertices and indices

Target design:

- fixed quad or minimal base geometry
- instance buffers for:
  - solid rect
  - rounded rect
  - border rect
  - line
  - circle
  - image quad
- shader-side shape evaluation for fill, border and clipping
- batch grouping by pipeline, texture set, clip state and blend behavior

Required renderer modules:

- `D3D12UiPrimitivePass`
- `D3D12UiFrameResources`
- `D3D12UiClipState` or equivalent scissor/clip stream
- `D3D12UiImagePass` or merged image primitive path

Acceptance criteria:

- no CPU tessellation for common editor primitives in the steady state
- vertex/index growth no longer scales with roundness or circle segment counts

## Workstream E: Replace String Texture Text Rendering With Glyph Atlas Text Rendering

Purpose:

- remove the largest text-side architectural bottleneck

Primary files:

- `new_editor/app/Rendering/D3D12/D3D12UiRenderer.*`
- `new_editor/app/Rendering/D3D12/D3D12UiTextureHost.*`
- `new_editor/app/Rendering/Native/NativeRenderer.*`
- new text-system files under `new_editor/app/Rendering/D3D12/` or a dedicated text namespace

Current path to retire:

- `text + font size + dpi -> whole string texture`
- `RasterizeTextMask()`
- transient WIC bitmap creation for display text misses

Target design:

- `DirectWrite` remains for shaping, metrics and glyph raster generation
- per-glyph atlas pages on the GPU
- glyph run cache keyed by text content, font, size, DPI and shaping result
- render text as glyph instances or glyph quads, not per-string textures
- share text metrics cache with render cache so measure and render do not do separate work

Required renderer modules:

- `D3D12UiTextSystem`
- `D3D12UiGlyphAtlas`
- `D3D12UiGlyphRunCache`
- `D3D12UiTextPass`

Acceptance criteria:

- no main-window display text path uses per-string textures as the primary render mechanism
- repeated labels reuse shaped runs and glyph atlas entries

## Workstream F: Establish Dirty/Invalidation-Driven Packet Rebuild Rules

Purpose:

- make retained rendering actually effective

Primary files:

- shell/workspace interaction and compose files
- panel state files
- new retained-scene cache files

Required invalidation classes:

- layout dirty
- visual dirty
- text content dirty
- texture binding dirty
- clip hierarchy dirty
- panel visibility/mount dirty
- DPI dirty

Rules:

- layout dirty rebuilds bounds and dependent packets
- visual dirty only rebuilds affected render packet contents
- text dirty only rebuilds affected text runs
- viewport texture changes do not invalidate unrelated shell packets
- panel-local changes do not invalidate the full editor scene

Acceptance criteria:

- dirty propagation is explicit and local
- unchanged subtrees survive frame-to-frame without packet regeneration

## Workstream G: Remove Obsolete Main-Window Compatibility Paths

Purpose:

- finish the refactor cleanly instead of leaving dead bridges in the hot path

Primary files:

- `new_editor/app/Rendering/Native/NativeRenderer.*`
- `new_editor/app/Rendering/D3D12/D3D12WindowInteropContext.*`
- `new_editor/app/Rendering/Native/AutoScreenshot.*`
- any remaining main-window D3D11On12 bridge code

Required cleanup:

- remove old main-window `D3D11On12/D2D` composition entrypoints
- keep screenshot/offscreen interop only if it still serves a non-main-window path
- remove unused string-texture caches once glyph atlas path is validated
- remove dead UI texture semantics only needed by the old D2D bridge

Acceptance criteria:

- no main-window render code path references D3D11On12 wrapped resources
- screenshot/offscreen helpers are clearly isolated from the main editor hot path

## Workstream H: Instrumentation And Verification

Purpose:

- prevent another round of “wrong bottleneck, wrong fix”

Required measurements before and during each phase:

- shell/workspace frame build count per presented frame
- dock-host layout rebuild count per presented frame
- panel packet rebuild count per frame
- primitive instance counts by type
- text run cache hit/miss counts
- glyph atlas upload count and uploaded pixel count
- batch count
- total draw call count
- CPU time for:
  - shell/workspace frame build
  - retained scene rebuild
  - primitive pass build
  - text shaping/raster/atlas upload
  - final render submission

Instrumentation targets:

- `EditorWindowRuntimeController`
- `EditorWindowFrameOrchestrator`
- shell/workspace interaction and compose files
- `D3D12UiRenderer`
- future primitive/text pass modules

Acceptance criteria:

- each major architectural replacement can be validated against measured cost shifts

## Recommended Execution Order

1. Freeze present path and add instrumentation.
2. Collapse shell/workspace to one authoritative frame build.
3. Introduce retained UI scene and per-panel render packets.
4. Replace primitive rendering with GPU-native instance-based primitive pass.
5. Replace text rendering with glyph atlas rendering.
6. Add explicit dirty propagation and cache invalidation rules.
7. Remove obsolete main-window D2D/D3D11On12 paths.
8. Tighten screenshot/offscreen ownership boundaries.
9. Final performance verification and cleanup pass.

## Commit Strategy

Recommended submission boundaries:

1. docs and instrumentation only
2. shell/workspace authoritative frame collapse
3. retained UI scene and panel packet introduction
4. primitive pass replacement
5. text system replacement
6. cleanup and dead-path removal
7. final verification and documentation

## Risks To Manage Explicitly

- input hit-testing drift if layout ownership changes without updating all consumers
- stale packet reuse if dirty propagation is incomplete
- glyph atlas eviction bugs causing missing text
- clip/scissor mismatches after primitive-pass conversion
- hidden dependencies on old `UIDrawData` immediate ordering
- viewport texture lifetime issues when packet caching crosses frame boundaries

## Final Acceptance Standard

This refactor is only considered complete when all of the following are true:

- the main editor window stays on the native `D3D12` path only
- one steady-state frame does not repeatedly rebuild shell/workspace layout
- unchanged panels reuse retained render products
- common UI primitives are not CPU-tessellated per frame
- main-window display text is rendered from a glyph atlas path
- old D3D11On12/D2D main-window composition code is removed or fully isolated from the hot path
- performance analysis shows the dominant steady-state cost moved away from repeated CPU rebuild work and naive UI translation