diff --git a/docs/pane-grid-migration.md b/docs/pane-grid-migration.md new file mode 100644 index 00000000..358dd31a --- /dev/null +++ b/docs/pane-grid-migration.md @@ -0,0 +1,145 @@ +# Migrating model tiles to `iced::pane_grid` + +Status: **planned, not started.** This is a design note for a future migration of +OpenCADStudio's custom model-space tiling (`model_tiles`) onto iced's +`pane_grid` widget. It records the motivation, blockers, decisions and a phased +plan so the work can start cold later. + +## Goal + +Replace the bespoke rect-based tiling with `pane_grid` to get drag-resize, +drag-to-swap, and maximize/restore "for free", and to delete the custom +hit-testing / edge-drag / split math. + +Non-goal: **floating viewports.** `pane_grid` is a tiling widget — panes never +overlap or float. If floating palettes/viewports are ever wanted, that is a +separate effort (multi-window via the iced `daemon` API, or a custom z-ordered +overlay stack). Do not pick `pane_grid` expecting floating. + +## Current architecture (what we'd replace) + +Tiles are normalized rectangles in a flat `Vec`, each carrying its own view +state. Rendering is a **single wgpu shader with one scissor pass per tile**; +overlays are a single canvas spanning the whole viewport, positioned at the +active tile. + +Core types / functions (`src/scene/mod.rs`): +- `struct ModelTile { rect, camera, render_mode, grid_on, snap_on }` — per-pane state. +- `model_tiles: RefCell>`, `active_model_tile: Cell`. +- `struct TileEdge { orient, ... }`, `enum TileEdgeOrient` — draggable dividers. +- `split_active_model_tile(horizontal)` — binary split of the active tile. +- `set_model_tile_layout(rects)` — VPORTS presets / reset. +- `set_active_model_tile_at(nx, ny)` — hover/click activation by point. +- `hit_model_tile_edge(...)`, `move_model_tile_edge(...)`, `model_tile_edges()`, + `collapse_small_model_tiles(...)` — divider drag + cleanup. +- `active_model_tile_bounds(vw, vh)` — active tile's canvas rect (drives grid / + crosshair / UCS / viewcube placement). +- `model_tile_grid_views(vw, vh)` — per-tile grid params (added for #121). +- `viewports_to_render(...)` — the per-tile scissor passes for the single shader. + +DWG round-trip (`src/scene/mod.rs`): +- `save_model_tiles_to_vports()` / `restore_model_tiles_from_vports()` — + `ModelTile ↔ *Active VPort` entries (rect via `tile_rect_to_vport` / + `vport_to_tile_rect`, camera via `vport_from_camera` / `camera_from_vport`, + plus `render_mode`, `grid_on`, `snap_on`). + +App glue: +- `src/app/update.rs`: `Message::SplitModelViewport`, hover activation in + `ViewportMove` (~2481), click activation in the left-press path (~3104), + edge-drag (~2308), `sync_vport_display` / `adopt_view_display` (grid/snap + follow the active viewport). +- `src/app/view.rs`: builds the overlay (`tile_edges`, grid, viewcube, + control chip) at `active_model_tile_bounds`; the top-left `viewport_controls` + chip emits `SplitModelViewport`. + +## Why this is not a drop-in + +### 1. Rendering architecture (the hard part) +Today: **one shader, N scissor passes** — shared pipeline/buffers, cheap. +`pane_grid` wants each pane's content to be a normal `Element`, so each pane +would hold its **own `shader` widget** → N independent shader instances. That +changes how cameras, pipelines and GPU buffers are shared, and splits the +single full-canvas overlay into one overlay per pane. + +Two viable shapes: +- **(A) Per-pane shader + per-pane overlay.** Cleanest conceptually (a pane is a + self-contained viewport: shader + its own grid/snap/crosshair/viewcube). Big + refactor; need to confirm N wgpu shader widgets share resources acceptably and + perform. +- **(B) Hybrid — `pane_grid` for layout only, keep the single-shader-scissor.** + Tempting, but `pane_grid` does not hand you the computed pane bounds for an + external renderer; you'd track split ratios/orientation yourself and recompute + rects — i.e. re-implement most of what `model_tiles` already does. Low payoff. + +Decision lean: **(A)**, gated on a spike (below). If the spike shows shader +sharing/perf is bad, abandon or stay hybrid-custom. + +### 2. VPORT round-trip fidelity +The DWG VPORT table stores **arbitrary** per-viewport rects (lower_left / +upper_right). `pane_grid` is a **binary split tree**; its layout is ratios + +orientation, not free rects. Standard VPORTS configs (2H, 3-left, 4-equal) are +tree-expressible, but arbitrary rects saved by other CAD apps may **not** map to +a clean tree → lossy load/save. + +Mitigations: +- Keep `ModelTile`-equivalent rects as the **source of truth for I/O**; convert + tree ↔ rects at the boundary. On load, best-effort fit saved rects to a tree; + if they don't fit, fall back to the current flat-rect path for that file. +- Store the pane_grid `Configuration` (split ratios/orientation) and reconstruct + on load; write each leaf's computed rect to its VPort entry on save. + +### 3. Overlays +Grid, snap markers, crosshair, UCS icon, viewcube, dynamic-input boxes, and the +control chip are currently one canvas at the active tile. Under (A) each becomes +per-pane. Per-#121 the grid is already per-tile (`model_tile_grid_views`), which +is a good precedent — the rest follow the same shape. + +## What `pane_grid` gives us +- Drag-resize dividers, drag-to-swap panes, maximize/restore — deletes + `TileEdge`, `hit_model_tile_edge`, `move_model_tile_edge`, edge-drag handling, + `collapse_small_model_tiles`, `set_active_model_tile_at` hit-testing. +- Natural per-pane mouse events (no manual point→tile mapping). +- `pane_grid::State` carries per-pane state (camera / render_mode / + grid_on / snap_on) directly. +- Focus model replaces `active_model_tile` (adapt hover-vs-click activation; + OCS currently activates on hover — decide whether to keep that or move to + click-to-focus, which is the `pane_grid` default). + +## Phased plan + +**Phase 0 — Spike (throwaway).** One `pane_grid` with a `shader` widget per +pane rendering the OCS scene with the pane's camera. Answer: does the scene draw +correctly per pane? Do N wgpu shader widgets share resources / perform with 4 +panes? This decides go/no-go for shape (A). + +**Phase 1 — Layout + rendering.** Introduce `pane_grid::State` +alongside the existing `model_tiles` behind a flag. Move rendering to per-pane +shader + per-pane overlay. Keep the control chip per pane (top-left). Wire split +to `pane_grid` split, resize/swap/maximize to its built-ins. Remove `TileEdge` +and friends once parity is reached. + +**Phase 2 — Activation + grid/snap.** Map focus → active pane. Reroute +`sync_vport_display` / `adopt_view_display` to the focused pane's state. Decide +hover-activation policy. + +**Phase 3 — DWG I/O.** Tree ↔ rect conversion in `save_model_tiles_to_vports` / +`restore_model_tiles_from_vports`. Best-effort fit on load; lossless for +tree-expressible configs; document the lossy edge case. + +**Phase 4 — Cleanup.** Delete the old flat-rect path and the feature flag once +the new path is at parity and round-trips real multi-viewport DWGs. + +## Open questions +- Can iced `shader` widgets share a wgpu pipeline/buffers across panes, or does + each allocate its own? (Phase 0 answers this — the whole migration hinges on + it.) +- Keep hover-to-activate, or switch to click-to-focus (`pane_grid` default)? +- Acceptable to be lossy for non-tree VPORT rect configs from foreign CAD apps, + or keep a flat-rect fallback path indefinitely? + +## Recommendation +Worth a Phase-0 spike. If shader-per-pane is clean and fast, the UX win +(resize/swap/maximize) and the code deleted are real. If not, keep the current +rect model — it already maps directly to VPORTs and renders efficiently — and do +not adopt `pane_grid`. Either way, `pane_grid` does **not** unlock floating +viewports.