hcie-rust-v3.05/criterion.md

# Canvas Performance Regression Protection — Walkthrough

HCIE v4 engine API'si üzerindeki 4K tuval optimizasyonlarının yanlışlıkla bozulmasını (regresyon) engellemek için `criterion` kütüphanesi entegre edildi ve dört kritik mekanizma için kalıcı benchmark testleri yazıldı.

## Neler Yapıldı?

1. **`hcie-engine-api/Cargo.toml` Güncellemesi**
   - `criterion` kütüphanesi dev-dependency olarak eklendi.
   - Her benchmark için özel `[[bench]]` kayıtları tanımlandı.

2. **`active_stroke_mask` Pooling Koruması** 
   - [benches/stroke_mask_pooling.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/stroke_mask_pooling.rs)
   - Brush engine'in kullandığı ~8 MB mask buffer'ın `end_stroke()` sırasında serbest bırakılıp bırakılmadığını kontrol eder.
   - İlk tahsis (cold) ile sonraki ardışık strokların (warm) sürelerini karşılaştırır.

3. **`composite_scratch` Pooling Koruması**
   - [benches/composite_scratch_pooling.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/composite_scratch_pooling.rs)
   - ~33 MB composite render buffer'ın `render_composite_region()` içinde yeniden kullanıldığını doğrular.

4. **`below_cache` Ardışık Stroke Reuse Koruması**
   - [benches/below_cache_reuse.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/below_cache_reuse.rs)
   - Aynı katmanda birden çok stroke atıldığında alttaki katmanların yeniden derlenmek yerine (cache rebuild) mevcut cache'in kullanıldığını test eder.
   - 4K çözünürlükte, 10 katmanlı senaryoda cache build (ilk vuruş) ve cache reuse (ikinci vuruş) maliyetlerini ayırır.

5. **`effects_dirty` Conditional Skip Koruması**
   - [benches/effects_skip.rs](file:///mnt/extra/00_PROJECTS/hcie-rust-v3.05/hcie-engine-api/benches/effects_skip.rs)
   - Efekt/stili olmayan katmanlarda pahalı effects pipeline (ve 33 MB buffer kopyası) adımının bypass edildiğinden emin olur.

## Doğrulama Sonuçları

- Yeni criterion testlerinin API erişimleri (özellikle `update_layer_style` fonksiyon imzası) ve bağımlılıkları derlenip onaylandı.
- Eski golden testler olan `visual_regression.rs` çalıştırılarak yeni performans testlerinin deterministik render sonuçlarını (pixel-perfect) bozmadığı **doğrulandı** (8/8 başarılı).
- Eski performans testi `performance_stroke_4k.rs` de sorunsuz çalıştırıldı.

> [!TIP]
> **Tüm Benchmark'ları Çalıştırmak İçin:**
> Terminal üzerinden engine dizinine giderek şu komutu kullanabilirsiniz:
> ```bash
> cargo bench -p hcie-engine-api
> ```
> _Not: Bu testler 4K ve çok katmanlı benchmarklar içerdiğinden belleği yoğun kullanır. Sonuçlar `./criterion/report/index.html` olarak dökülecektir. CRITERION_HOME, `.cargo/config.toml` içinde `relative = true` olarak ayarlanmıştır; tüm `cargo bench` çağrıları workspace root'taki `criterion/` dizinine yazar._