103 lines
6.2 KiB
Markdown
103 lines
6.2 KiB
Markdown
|
# Plan: Brush Editor — Dynamics, Real Preview, Scrollable Panels
|
||
|
|
|
||
|
|
## Goal
|
||
|
|
Extend the existing Krita-style brush editor in `hcie-egui-app/crates/hcie-gui-egui/src/app/brush_editor.rs` so it exposes real brush dynamics, shows an accurate engine-rendered preview, and keeps all dock panels scrollable by mouse wheel / pan without visible scrollbars.
|
||
|
|
|
||
|
|
## Current State
|
||
|
|
- A basic brush editor modal exists with four categories: **Brush Tip**, **Dynamics**, **Color**, **Texture**.
|
||
|
|
- `BrushConfig` (in `hcie-protocol/src/tools.rs`) exposes only `size`, `opacity`, `hardness`, `flow`, `spacing`, `style`, `blend_mode`, `cyclic_color`, `cyclic_speed`, `color_variant`, `variant_amount`, `density`.
|
||
|
|
- Engine `BrushTip` already has `jitter_amount`, `scatter_amount`, `angle`, `roundness`, but the GUI never sets them (canvas code hard-codes `0.0` / `1.0`).
|
||
|
|
- Preview is procedural (`brushes_panel::draw_brush_preview`) and does not reflect actual engine output.
|
||
|
|
- Dock panels vary: some use `ScrollArea`, some do not; scrollbars are visible.
|
||
|
|
|
||
|
|
## Decisions
|
||
|
|
|
||
|
|
### 1. New brush dynamics fields
|
||
|
|
Add to `hcie-protocol/src/tools.rs` `BrushConfig`:
|
||
|
|
```rust
|
||
|
|
pub jitter_amount: f32,
|
||
|
|
pub scatter_amount: f32,
|
||
|
|
pub angle: f32,
|
||
|
|
pub roundness: f32,
|
||
|
|
pub drawing_angle: bool,
|
||
|
|
pub rotation_random: f32,
|
||
|
|
pub time_enabled: bool,
|
||
|
|
pub time_size_start: f32,
|
||
|
|
pub time_size_end: f32,
|
||
|
|
pub time_opacity_start: f32,
|
||
|
|
pub time_opacity_end: f32,
|
||
|
|
pub time_angle_start: f32,
|
||
|
|
pub time_angle_end: f32,
|
||
|
|
```
|
||
|
|
Defaults: `0.0`, `0.0`, `0.0`, `1.0`, `false`, `0.0`, `false`, `1.0/1.0/1.0/1.0/0.0/0.0`.
|
||
|
|
|
||
|
|
### 2. GUI controls
|
||
|
|
- **Brush Tip panel**: keep `Diameter`, `Hardness`, `Spacing`, `Style`, `Blend Mode`; add **Angle**, **Roundness**, **Drawing Angle** checkbox, **Rotation Random**.
|
||
|
|
- **Dynamics panel**: keep `Opacity`, `Flow`, `Pressure Curve` placeholder; add **Jitter**, **Scatter**.
|
||
|
|
- **Color panel**: keep `Color Variant`, `Cyclic Color`; add a **Time** subsection with checkbox and start/end sliders for `size`, `opacity`, `angle`.
|
||
|
|
- Every slider pairs with a right-aligned `DragValue` so mouse users can click/type exact values.
|
||
|
|
- Angles displayed and edited in **degrees**, stored in **radians**.
|
||
|
|
|
||
|
|
### 3. Engine wiring
|
||
|
|
- `hcie-egui-app/crates/hcie-gui-egui/src/canvas/mod.rs`: when building `BrushTip`, copy `jitter_amount`, `scatter_amount`, `angle` (converted to radians), `roundness` from `state.tool_configs.brush`.
|
||
|
|
- `hcie-brush-engine/src/lib.rs`: update `generate_brush_stamp` and dab dispatchers so that:
|
||
|
|
- `drawing_angle == true` overrides `angle` with the stroke segment direction.
|
||
|
|
- `rotation_random` adds a per-dab random offset to the effective angle.
|
||
|
|
- `roundness` scales the stamp along the effective angle (elliptical dab).
|
||
|
|
- `hcie-engine-api/src/stroke_brush.rs`: apply `time_*` interpolation using accumulated stroke distance (`brush_accumulated_dist`) before passing size/opacity/angle to the dab functions. Reset at stroke start (`begin_stroke`).
|
||
|
|
|
||
|
|
### 4. Real preview
|
||
|
|
- Add `Engine::render_brush_preview(&self, width, height, tip, color, stroke_points) -> Vec<u8>` in `hcie-engine-api/src/lib.rs`.
|
||
|
|
- It creates a temporary 1-layer document, draws the supplied stroke points, composites, and returns RGBA pixels.
|
||
|
|
- `brush_editor.rs` calls this on every significant parameter change (when `brush_editor_instant_preview` is true), caches the texture, and draws it in the preview area instead of the procedural function.
|
||
|
|
- Guard with a small debounce to avoid 4K-preview cost.
|
||
|
|
|
||
|
|
### 5. Scrollable panels
|
||
|
|
- Create a helper `scrollable_panel(ui, id, contents)` in a new file `hcie-egui-app/crates/hcie-gui-egui/src/app/scrollable_panel.rs`.
|
||
|
|
- It wraps `egui::ScrollArea::vertical().always_show_scroll(false)` and implements drag-to-pan by tracking pointer delta over the content rect when the left button is held and no widget is being dragged.
|
||
|
|
- Apply the helper to every dock panel body:
|
||
|
|
- `brushes_panel::show_brushes_ui`
|
||
|
|
- `panels.rs` tool-property bodies (Tools, Layers, History, Properties, etc.)
|
||
|
|
- `brush_editor.rs` right-hand settings area
|
||
|
|
- Keep existing `ScrollArea` calls but switch them to the helper so behavior is consistent.
|
||
|
|
|
||
|
|
## Affected Boundaries (Locked Crates)
|
||
|
|
The following crates are normally locked by `hcie-guard`; the implementation agent must run `unlock.sh <crate>`, edit, then `lock.sh <crate>`:
|
||
|
|
- `hcie-protocol/src/tools.rs` — `BrushConfig` fields
|
||
|
|
- `hcie-engine-api/src/lib.rs` — new public preview API
|
||
|
|
- `hcie-engine-api/src/stroke_brush.rs` — time interpolation
|
||
|
|
- `hcie-brush-engine/src/lib.rs` — drawing angle / rotation / roundness behavior
|
||
|
|
|
||
|
|
GUI-only files (open to agent edits):
|
||
|
|
- `hcie-egui-app/crates/hcie-gui-egui/src/app/brush_editor.rs`
|
||
|
|
- `hcie-egui-app/crates/hcie-gui-egui/src/app/brushes_panel.rs`
|
||
|
|
- `hcie-egui-app/crates/hcie-gui-egui/src/app/panels.rs`
|
||
|
|
- `hcie-egui-app/crates/hcie-gui-egui/src/app/mod.rs`
|
||
|
|
- `hcie-egui-app/crates/hcie-gui-egui/src/canvas/mod.rs`
|
||
|
|
|
||
|
|
## Task Order
|
||
|
|
1. Extend `BrushConfig` in `hcie-protocol` and rebuild engine.
|
||
|
|
2. Implement engine preview API.
|
||
|
|
3. Implement `drawing_angle`, `rotation_random`, `roundness` in `hcie-brush-engine`.
|
||
|
|
4. Implement time interpolation in `hcie-engine-api/src/stroke_brush.rs`.
|
||
|
|
5. Wire new fields from GUI config to `BrushTip` in `canvas/mod.rs`.
|
||
|
|
6. Extend `brush_editor.rs` UI (new sliders, real preview, scrollable right panel).
|
||
|
|
7. Implement `scrollable_panel` helper and apply to all dock panels.
|
||
|
|
8. Run `cargo test -p hcie-engine-api --test visual_regression` and `cargo test -p hcie-engine-api --test performance_stroke_4k`.
|
||
|
|
9. Lock affected engine crates.
|
||
|
|
10. Capture screenshots of brush editor and each scrollable panel.
|
||
|
|
|
||
|
|
## Validation
|
||
|
|
- Visual regression tests (`visual_regression`) must still pass.
|
||
|
|
- Performance regression benchmark (`performance_stroke_4k`) must not regress beyond 5%.
|
||
|
|
- Brush editor preview updates within 200 ms of parameter change.
|
||
|
|
- All dock panels scroll by mouse wheel and pan-drag without visible scrollbars.
|
||
|
|
|
||
|
|
## Risks
|
||
|
|
- `hcie-brush-engine` angle/roundness changes can alter default brush appearance if defaults are wrong; test with `visual_regression`.
|
||
|
|
- Real preview allocates a temporary engine/document per frame; debounce/caching is mandatory.
|
||
|
|
- Locked crate modifications require `unlock.sh` / `lock.sh` and possible terminal password prompt.
|
||
|
|
|
||
|
|
## Open Questions
|
||
|
|
- None remaining; user confirmed all decisions.
|