diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-05 00:15:00 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-05 00:15:00 +0100 |
| commit | 873fa985bb4b3ec3841fa77adc16a99184cb9507 (patch) | |
| tree | de047f4045c81314327c20d85c00e552640874d2 /doc/SEQUENCE.md | |
| parent | 458b00d254f5e3b1fece6e57462769ce43c96a72 (diff) | |
feat: Replace explicit priorities with stack-based priority modifiers
Simplifies effect priority management by using relative modifiers instead
of explicit numbers, making timeline reordering much more practical.
## New Priority System
Effects now use priority modifiers after EFFECT keyword:
- `+` increment priority by 1 (or start at 0 if first)
- `=` keep same priority as previous effect
- `-` decrement priority (or start at -1 if first, for background)
Old syntax:
```
EFFECT FlashEffect 0.0 0.5 0
EFFECT FadeEffect 0.1 0.3 1
EFFECT BgCube 0.2 3 -1
```
New syntax:
```
EFFECT - BgCube 0.2 3 # Priority -1 (background)
EFFECT + FlashEffect 0.0 0.5 # Priority 0
EFFECT + FadeEffect 0.1 0.3 # Priority 1
```
## Benefits
✓ Reordering effects no longer requires renumbering all priorities
✓ Priority relationships are explicit and relative
✓ File order matches render order (easier to understand)
✓ Same-priority effects clearly marked with `=`
✓ Background layers (-1) clearly marked with `-`
✓ Reduces errors when reorganizing timelines
## Implementation
- Updated seq_compiler to parse +/=/- modifiers
- Tracks current priority per sequence
- First effect sets base priority (0 or -1)
- Subsequent effects modify relative to previous
- Generated C++ code unchanged (still uses integer priorities)
## Changes to demo.seq
- All effects updated to use new syntax
- Effects reordered by priority within sequences
- Priority gaps removed (were likely unintentional)
- Comments updated to reflect new system
## Documentation
- Updated SEQUENCE.md with new syntax
- Added examples showing +, =, - usage
- Explained priority calculation rules
This makes timeline authoring significantly more maintainable, especially
when experimenting with different effect orderings during development.
Diffstat (limited to 'doc/SEQUENCE.md')
| -rw-r--r-- | doc/SEQUENCE.md | 53 |
1 files changed, 36 insertions, 17 deletions
diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md index 05cdc93..614339e 100644 --- a/doc/SEQUENCE.md +++ b/doc/SEQUENCE.md @@ -79,17 +79,26 @@ SEQUENCE <global_start> <priority> [optional_end] ### EFFECT Declaration ``` -EFFECT <EffectClassName> <local_start> <local_end> <priority> [constructor_args...] +EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...] ``` **Parameters:** +- Priority modifier (one of): + - `+`: Increment priority (or start at 0 if first effect) + - `=`: Keep same priority as previous effect + - `-`: Decrement priority (or start at -1 if first effect, for background layers) - `EffectClassName`: C++ class name (must be declared in `demo_effects.h`) - `local_start`: Start time relative to sequence start (beats or seconds) - `local_end`: End time relative to sequence start (beats or seconds) -- `priority`: Render order within sequence (lower = drawn first/background) - - Negative priorities draw behind everything - `constructor_args`: Optional additional parameters (rarely used) +**Priority System:** +- Effects are assigned priorities based on their order in the file +- First effect: `+` starts at 0, `-` starts at -1, `=` starts at 0 +- Subsequent effects: `+` increments, `=` keeps same, `-` decrements +- Priorities determine render order (lower = drawn first/background) +- Effects should be listed in desired priority order within each sequence + --- ## Time Notation @@ -223,36 +232,46 @@ White flash on strong beat hits. ### Basic Sequence ``` SEQUENCE 0 0 - EFFECT FlashEffect 0.0 0.5 1 # Starts immediately, runs 0.5s, priority 1 - EFFECT HeptagonEffect 0.2 10 0 # Starts at 0.2s, runs until 10s, priority 0 + EFFECT + FlashEffect 0.0 0.5 # Priority 0 (first with +) + EFFECT + HeptagonEffect 0.2 10 # Priority 1 (increment) +``` + +### Same Priority (Layered Effects) +``` +SEQUENCE 0 0 + EFFECT + Flash 0.0 0.5 # Priority 0 + EFFECT = Fade 0.1 0.3 # Priority 0 (same as Flash) + EFFECT + Other 0.2 3 # Priority 1 (increment) +``` + +### Background Elements +``` +SEQUENCE 0 0 + EFFECT - FlashCube 0 10 # Priority -1 (background) + EFFECT = BgEffect 0 5 # Priority -1 (same layer) + EFFECT + MainEffect 0 10 # Priority 0 (foreground) ``` ### Sequence with Explicit End Time ``` SEQUENCE 8b 0 [5.0] - EFFECT ParticlesEffect 0 120 1 # Would run 120s, but sequence ends at 5s + EFFECT + Particles 0 120 # Would run 120s, but sequence ends at 5s ``` ### Post-Processing Chain ``` SEQUENCE 0 10 - EFFECT GaussianBlurEffect 0 60 1 # Applied first - EFFECT ChromaAberrationEffect 0 60 2 # Applied second - EFFECT SolarizeEffect 0 60 3 # Applied last -``` - -### Background Element -``` -SEQUENCE 0 0 - EFFECT FlashCubeEffect 0 10 -1 # priority -1 = background layer + EFFECT + GaussianBlur 0 60 # Priority 0 (applied first) + EFFECT + ChromaAberration 0 60 # Priority 1 (applied second) + EFFECT + Solarize 0 60 # Priority 2 (applied last) ``` ### Music-Synchronized Effects ``` # BPM 120 SEQUENCE 0b 0 # Start at beat 0 (0.0s) - EFFECT FlashEffect 0b 1b 1 # Flash from beat 0 to beat 1 (0-0.5s) - EFFECT HeptagonEffect 4b 8b 0 # Main effect from beat 4 to 8 (2-4s) + EFFECT + Flash 0b 1b # Flash from beat 0 to beat 1 (0-0.5s) + EFFECT + Heptagon 4b 8b # Main effect from beat 4 to 8 (2-4s) ``` --- |
