56 lines
6.0 KiB
Markdown
56 lines
6.0 KiB
Markdown
|
# Refactor: Split hcie-fx/src/shadow.rs into Domain Modules
|
||
|
|
|
||
|
|
## Goal
|
||
|
|
Split the monolithic `shadow.rs` (1482 lines containing 10+ effect generators + helpers) into focused modules: `emboss.rs`, `outer_glow.rs`, etc. Keep `shadow.rs` containing only `apply_layer_effects`, `generate_shadow`, `generate_inner_shadow`, and shared helpers (`box_blur`, `box_blur_f32`, `smoothstep`, composites).
|
||
|
|
|
||
|
|
## Handover from Planning Session
|
||
|
|
|
||
|
|
### Discoveries
|
||
|
|
|
||
|
|
- **`generate_bevel_emboss` is called directly (not via a re-export)** from `apply_layer_effects` at line 58 of `shadow.rs` — it's a plain function call `generate_bevel_emboss(...)`, not `self::generate_bevel_emboss(...)`. After moving it to `emboss.rs`, need to add `use crate::emboss::generate_bevel_emboss;` at top of `shadow.rs`.
|
||
|
|
- **No other crate or file calls individual effect generators directly** — only `tune_mae_emboss.rs` and `tune_mae_outer_glow.rs` call `generate_bevel_tuned` / `generate_glow_tuned` via `hcie_fx::shadow::...`. All other consumers (test_psd_composite.rs, debug_glow.rs, gui.rs, etc.) only call `apply_layer_effects` (the top-level pub function).
|
||
|
|
- **`generate_bevel_emboss` has a duplicate `generate_bevel_tuned`** already in shadow.rs (lines 883-1076) with identical math but extra param args. Both must move to `emboss.rs`.
|
||
|
|
- **`generate_glow_tuned` does NOT exist in shadow.rs yet** — the tune file references it but it was removed during the backup restore. Need to ADD it to `outer_glow.rs` as part of Phase 2.
|
||
|
|
- **`edt_*` functions are private and called only from `generate_bevel_emboss`/`generate_bevel_tuned`** — safe to move entirely into `emboss.rs`.
|
||
|
|
- **`smoothstep` is defined but never used** in shadow.rs (only referenced in comment). Keep it in shadow.rs for now.
|
||
|
|
- **`box_blur` (u8 version) is defined but only shadow.rs internal functions call it** — all effect generators use `box_blur_f32` (f32 version). `box_blur` can stay in shadow.rs as `pub(crate)`.
|
||
|
|
- **`sample_gradient` is a private helper only used by `generate_gradient_overlay`** — will move with overlays in Phase 3.
|
||
|
|
|
||
|
|
### Relevant Files
|
||
|
|
|
||
|
|
- `/mnt/extra/00_PROJECTS/hcie-rust-v4/hcie-fx/src/shadow.rs` — 1482 lines, the monolithic source to split. `apply_layer_effects` (pub), 10 effect generators (fn), plus EDT, blur, composite helpers.
|
||
|
|
- `/mnt/extra/00_PROJECTS/hcie-rust-v4/hcie-fx/src/lib.rs` — declares `pub mod shadow;`. Needs `pub mod emboss;`, `pub mod outer_glow;` etc.
|
||
|
|
- `/mnt/extra/00_PROJECTS/hcie-rust-v4/hcie-io/examples/tune_mae_emboss.rs` — calls `hcie_fx::shadow::generate_bevel_tuned` at line 202. Needs update to `hcie_fx::emboss::generate_bevel_tuned`.
|
||
|
|
- `/mnt/extra/00_PROJECTS/hcie-rust-v4/hcie-io/examples/tune_mae_outer_glow.rs` — calls `hcie_fx::shadow::generate_glow_tuned` at line 81. Needs update to `hcie_fx::outer_glow::generate_glow_tuned`.
|
||
|
|
- `/mnt/extra/00_PROJECTS/hcie-rust-v4/hcie-io/examples/test_sultan.rs` — uses `hcie_fx::shadow::apply_layer_effects` indirectly via hcie_composite. No change needed.
|
||
|
|
- `/mnt/extra/00_PROJECTS/hcie-rust-v4/hcie-io/src/test_psd_composite.rs` — uses `hcie_fx::apply_layer_effects` (re-exported from lib.rs). No change needed.
|
||
|
|
- `/mnt/extra/00_PROJECTS/hcie-rust-v4/hcie-io/examples/gui.rs` — uses `hcie_fx::protocol_to_hcie_fx_effect`, `hcie_fx::LayerEffect` enum, etc. No change needed as long as lib.rs re-exports are intact.
|
||
|
|
|
||
|
|
### Implementation Notes
|
||
|
|
|
||
|
|
- **Do Phase 1 first (emboss.rs), then verify cargo check passes, then tune.** After Phase 1, the `tune_mae_emboss` example uses the new module path, but `tune_mae_outer_glow` will still reference `hcie_fx::shadow::generate_glow_tuned` which won't exist yet — that's fine, only build the specific example.
|
||
|
|
- **Use `cargo check --package hcie-fx` first** to verify the library compiles, then `cargo check --example tune_mae_emboss --release` for the example.
|
||
|
|
- **`generate_bevel_tuned` is labeled `pub`** in shadow.rs — it needs to stay pub in emboss.rs for the tune example to call it.
|
||
|
|
- **The BEGIN_TUNING_ZONE/END_TUNING_ZONE comments** in shadow.rs (lines 828 and 878) should move WITH `generate_bevel_emboss` into emboss.rs so the tune script can still find them by string matching. Same for BEGIN_GLOW_TUNING_ZONE/END_GLOW_TUNING_ZONE in `generate_glow`.
|
||
|
|
- **After Phase 2**, the backup `shadow.rs.bak` should be updated (or deleted) since it no longer matches the refactored structure.
|
||
|
|
- **Running `test_sultan` after all phases** requires all crate examples to compile — don't leave broken references in example files. Either fix both tune examples after each phase, or only run the specific working example.
|
||
|
|
|
||
|
|
## Todo List
|
||
|
|
|
||
|
|
- [~] Fix tune_eval vs production mismatch — the tune scripts (`tune_mae_emboss`, `tune_mae_outer_glow`) and the production functions (`generate_bevel_emboss`, `generate_glow`) have diverged. The tune versions have additional parameters and different tuning zone structures. Need to reconcile: either fold tune params into production, or make production call the tuned version with default params.
|
||
|
|
- [ ] **Phase 1**: Extract emboss.rs from shadow.rs
|
||
|
|
- [ ] Copy `generate_bevel_emboss` (lines ~796-882), `generate_bevel_tuned` (lines 883-1076), and `edt_*` helpers to new `emboss.rs`
|
||
|
|
- [ ] Add `pub mod emboss;` to `lib.rs`
|
||
|
|
- [ ] Add `use crate::emboss::generate_bevel_emboss;` to `shadow.rs`
|
||
|
|
- [ ] Remove the moved functions from `shadow.rs`
|
||
|
|
- [ ] Update `tune_mae_emboss.rs` to use `hcie_fx::emboss::generate_bevel_tuned`
|
||
|
|
- [ ] Verify with `cargo check --package hcie-fx` and `cargo check --example tune_mae_emboss --release`
|
||
|
|
- [ ] **Phase 2**: Extract outer_glow.rs from shadow.rs
|
||
|
|
- [ ] Add `generate_glow_tuned` (production version + tuned version) to `outer_glow.rs`
|
||
|
|
- [ ] Add `pub mod outer_glow;` to `lib.rs`
|
||
|
|
- [ ] Add `use crate::outer_glow::*;` to `shadow.rs`
|
||
|
|
- [ ] Remove `generate_glow` from `shadow.rs`
|
||
|
|
- [ ] Update `tune_mae_outer_glow.rs` to use `hcie_fx::outer_glow::generate_glow_tuned`
|
||
|
|
- [ ] Verify with `cargo check`
|
||
|
|
- [ ] **Phase 3**: Extract overlay modules (gradient_overlay, pattern_overlay, stroke, color_overlay)
|
||
|
|
- [ ] **Final**: Clean up, delete `shadow.rs.bak`, run `test_sultan`
|