fabrilis/docs/UI.md
loki5512344 1042269d7e
Finish M4: cart, log facade, idle diagnostics and terrain LOD
Add the core::log facade with five levels and a sink; migrate the app dev log and enable trace in --dev. Replace the dropped cubes with a four-wheel cart on revolute joints driven by velocity motors, add WASD controls, a golden trajectory and a slope test. Instrument idle frame spikes and throttle the window title. Add chunked terrain LOD with skirts (2368 vs 8192 triangles) while physics keeps the full mesh. Pin Rust 1.100.0; edition stays 2024.
2026-11-17 14:32:52 +01:00

106 lines
6.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# UI
UI Fabrilis — это редактор и отладочный оверлей внутри приложения, а не отдельный
UI-фреймворк и не библиотека для чужих программ. Окно обычное прямоугольное,
управление окном и вводом — на `winit` (D24), рисование — на нашем `wgpu`-рендере,
готовые UI-библиотеки не берём (D20).
## Модель
- **Immediate-mode на старте.** UI каждый кадр строит список команд рисования
(прямоугольник, скруглённый прямоугольник, линия, текст, картинка, клип), рендер
батчит их. Состояние виджетов живёт в приложении, а не в дереве UI.
- **Retained-дерево только по доказанной нужде.** Если профилирование покажет, что
пересборка команд дорога, вводим стабильные `NodeId`, dirty-флаги и кеш ресурсов.
Reconciliation и анимационный граф заранее не пишем.
- **Event-driven redraw.** Нет изменений — нет кадра. Каждый кадр имеет причину
(`Input`, `Animation`, `Resize`, `SimulationTick`, `Debug`), счётчик причин виден
в оверлее; в простое — 0 кадров/с.
- **Кеш ресурсов.** Пайплайны кешируются по `shader + layout + format + blend`;
текст — через общий glyph atlas, а не текстуру на надпись. Offscreen-проходы
только там, где эффект этого требует.
- **Capability-модель.** Вместо `bool` — `Available | Unavailable { reason } |
Conditional { reason }`: «нет прозрачности», «fractional scale не поддержан»,
«эффект недоступен на этом backend'е». Не выполнять молча.
## Что есть в M4 и M10
| Этап | UI |
|---|---|
| M4 | оверлей отладки: FPS/RTF, число тел, причины кадров, время подсистем; прямоугольники, текст, линии, клип |
| M10 | панели и сплиттеры, дерево конструкции, таблица свойств, графики, 3D-вид, диалоги, текстовые поля |
Виджеты вводятся по одному и только под конкретную задачу редактора. Зоопарк
«на будущее» запрещён (KISS).
## Управление (M4)
В окне одна сцена: тележка на террейне. Ввод задаёт только цель моторов на
границе кадра и не меняет шаг симуляции.
| Ввод | Действие |
|---|---|
| `W` / `S` | газ вперёд / назад (тележка) |
| `A` / `D` | поворот влево / вправо (тележка) |
| Стрелки | камера: вперёд/назад, влево/вправо |
| `Q` / `E` | камера вниз / вверх |
| `Shift` | ускорить камеру |
| ЛКМ + мышь | обзор камерой |
| `Escape` | выход |
Когда клавиши отпущены, цель моторов — ноль: тележка тормозит, а не катится
по инерции.
## Текст
- Сейчас: `fontdue` только растеризует глифы, раскладку строк и переносы делаем сами.
Для латиницы и кириллицы этого достаточно.
- Текстовые поля требуют shaping и IME. Решение отложено до M10: кандидаты —
`cosmic-text` или `Parley` (+ `glyphon` для wgpu). Берём только когда появляется
настоящее поле ввода, с записью в DECISIONS.md.
- Курсор, выделение, копирование и IME не эмулируем частично: либо полноценно, либо
поле ввода не выпускаем.
## Что взято из ShapeUI blueprint
Локальная копия: `ref/shapeui-blueprint_v0.2_revised_ru.md` (в git не входит).
Из него берём идеи, не архитектуру:
- event-driven redraw и счётчик причины кадра;
- render command list и батчинг вместо draw call на виджет;
- общий glyph atlas;
- раздельные dirty-флаги (стиль, layout, текст, геометрия);
- capability-модель вместо обещаний `bool`;
- оверлей диагностики: PSS/RSS, draw calls, offscreen passes, кеши, причина кадра;
- дисциплину «сначала панели/текст/ввод, потом виджеты».
## Что из ShapeUI не берём
- Окна произвольной формы, click-through, `wl_region`, `set_input_region`: у нас
обычное окно, этим занимается `winit`.
- Свой Wayland-backend и raw `wl_surface`: дублирует `winit`.
- CPU-рендерер, Vello, несколько backend'ов, morphing, shader marketplace.
- Собственный scene graph с реконсиляцией до доказанной необходимости.
- Доступность (AccessKit) с первого дня; вернёмся к ней перед публичным релизом.
## Диагностика
Оверлей показывает то, что можно проверить:
```
PSS / RSS 38.4 / 51.1 MiB (estimated)
draw calls 6
offscreen 1
pipelines 5
glyph atlas 2.1 MiB
frames last 10s 0
last frame Idle
```
Числа не выдаются за «всю VRAM процесса»; приблизительные помечаются `estimated`.
## Открыто
- Shaping и IME для текстовых полей: `cosmic-text` или `Parley`, решаем на M10.
- Нужен ли retained-слой: решаем по профилировке M10, не заранее.
- Графики: своя простая отрисовка линий и областей; библиотеку не берём.