diff options
Diffstat (limited to 'EFFECT_DEPTH_ANALYSIS.md')
| -rw-r--r-- | EFFECT_DEPTH_ANALYSIS.md | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/EFFECT_DEPTH_ANALYSIS.md b/EFFECT_DEPTH_ANALYSIS.md new file mode 100644 index 0000000..7a33baf --- /dev/null +++ b/EFFECT_DEPTH_ANALYSIS.md @@ -0,0 +1,115 @@ +# Effect Depth Analysis Results + +## Overview +The `seq_compiler` tool now includes a `--analyze` flag to identify performance bottlenecks by analyzing how many effects are stacked (running simultaneously) at each moment in the demo. + +## Usage + +```bash +# Analyze effect stacking depth +./build/seq_compiler assets/demo.seq --analyze + +# Generate analysis with visual Gantt chart +./build/seq_compiler assets/demo.seq --analyze --gantt-html=timeline_analysis.html +``` + +## Current Demo Analysis (demo.seq) + +### Summary +- **Timeline duration**: 36s (65 beats @ 120 BPM) +- **Total effects**: 57 +- **Max concurrent effects**: 11 at t=8.8s ⚠️ +- **Bottleneck periods**: 28 time periods with >5 effects + +### Effect Depth Distribution + +| Depth | Time % | Severity | +|-------|--------|----------| +| 1-2 | 28.3% | Light | +| 3-4 | 26.1% | Moderate | +| 5-6 | 15.9% | Heavy | +| 7-11 | 29.6% | Critical ⚠️ | + +**Key Finding**: Nearly 30% of the demo has 7+ effects running simultaneously, which may cause frame rate drops on lower-end hardware. + +### Identified Bottlenecks + +**Most Critical Sections** (10+ concurrent effects): + +1. **t=4.3s** (10 effects): FlashCubeEffect, FadeEffect, ParticleSprayEffect, ParticlesEffect, GaussianBlurEffect, HeptagonEffect, ThemeModulationEffect, ChromaAberrationEffect, SolarizeEffect, FlashEffect +2. **t=8.6s** (10 effects): FlashCubeEffect, ThemeModulationEffect, ParticleSprayEffect, ParticlesEffect, Hybrid3DEffect, GaussianBlurEffect, ChromaAberrationEffect, HeptagonEffect, FlashEffect (×2) +3. **t=8.8s** (11 effects) - **Peak bottleneck** + +**Heavy Sections** (7-9 concurrent effects): +- t=4.9s: 9 effects +- t=6.7s: 9 effects +- t=7.3s: 7 effects +- t=7.9s: 8 effects +- t=9.1s: 9 effects +- ... and 18 more peaks + +### Recommendations + +**Immediate Actions**: +1. **Reduce overlap at t=8.8s**: The 11-effect peak is excessive. Consider: + - Staggering effect start/end times by 0.1-0.2s + - Removing redundant effects (e.g., duplicate FlashEffect instances) + - Combining similar effects (e.g., multiple GaussianBlur passes) + +2. **Optimize sequence at 8b-12b** (4-6 seconds): + - This section has sustained high effect counts (6-10 effects) + - Consider moving some post-processing effects to later sequences + - Test frame rate on target hardware during this section + +3. **Profile specific effects**: + - GaussianBlurEffect appears frequently (28 instances) + - Hybrid3DEffect runs for long durations (20s total) + - ChromaAberrationEffect appears in most bottleneck periods + +**Optimization Strategies**: +- Use priority layering to ensure critical effects render at higher priority +- Consider effect LOD (Level of Detail) system for lower-end hardware +- Combine multiple post-process passes into single shaders where possible +- Profile GPU time per effect to identify true bottlenecks (not just count) + +### Effect Frequency Analysis + +**Most Used Effects** (estimated from analysis output): +1. GaussianBlurEffect: ~10 instances +2. HeptagonEffect: ~9 instances +3. ThemeModulationEffect: ~7 instances +4. ChromaAberrationEffect: ~6 instances +5. FlashCubeEffect: ~6 instances +6. ParticleSprayEffect: ~5 instances +7. ParticlesEffect: ~5 instances +8. SolarizeEffect: ~4 instances +9. Hybrid3DEffect: ~3 instances +10. FadeEffect: ~2 instances + +**Insight**: GaussianBlur and Heptagon effects are the most heavily used - optimizing these will have the biggest impact on overall performance. + +## Technical Details + +### Analysis Method +- Samples timeline at 10 Hz (every 0.1s) +- Counts overlapping effect time ranges at each sample +- Generates histogram of effect depth distribution +- Identifies peaks (>5 effects) with at least 0.5s separation + +### Limitations +- Does not measure actual GPU/CPU time per effect (only counts) +- Assumes all effects have equal performance cost (not true in practice) +- Does not account for effect complexity (e.g., particle count, shader passes) + +### Future Improvements +- Add GPU profiling integration (Tracy, RenderDoc) +- Weight effects by estimated performance cost +- Suggest specific optimizations per bottleneck +- Generate timeline heatmap visualization +- Compare multiple .seq files (before/after optimization) + +--- + +**Generated**: February 8, 2026 +**Analysis Tool**: seq_compiler v1.1 (--analyze flag) +**Target**: assets/demo.seq |