hcie-rust-v3.05/.kilo/plans/4k-multilayer-psd-performance-regression.md

4K Çok Katmanlı PSD Çizim Performans Regresyonu — Plan

Hedef

4K çözünürlükte, çok katmanlı PSD üzerine fırça/pen çizimi yapılırken yaşanan yavaşlamanın kök nedenini bulmak, daha önce çalışan ama sonradan bozulan/basıitleştirilen optimizasyonları git geçmişinden geri getirmek ve bu tür regresyonların tekrar etmesini önlemek.

Mevcut Durum Özeti

• Kilitli engine crate'leri kullanıcı tarafından geçici olarak açıldı.
• Şu anki main (HEAD dfef0de) içinde var olan optimizasyonlar:
  • hcie-engine-api/src/lib.rs: active_stroke_mask, composite_scratch, below_cache pooling/partial update (sonradan eklenmiş).
  • hcie-egui-app/crates/hcie-gui-egui/src/canvas/render.rs: dirty-region texture upload.
• Ancak git geçmişi incelendiğinde daha önce var olan ama şu an eksik/zayıflamış özellikler var:
  • hcie-composite/src/tiled.rs: a257e66 mesajı "tile render iptal" — tile rendering daha önce devre dışı bırakılmış/geri alınmış.
  • hcie-tile/src/lib.rs: tek commit (6f3fe5d) ile hiç güncellenmemiş; tile motoru eskimiş olabilir.
  • hcie-engine-api/src/lib.rs: sadece 2 commit; daha önce başka bir yerde/dalda (örn. hcie-core-app veya v3) daha gelişmiş partial composite kodu olabilir.

Kritik Hipotezler

1. Daha Önce Tile Rendering Vardı, Şimdi İptal Edilmiş/Daralmış

• Commit a257e66 ("layer visibility çözüldü . renk sorunları var, blend fx sorunlu eksik, tile render iptal") tiled composite üzerinde clipping mask desteği eklerken tile rendering’i kısmen iptal etmiş veya gerilemiş olabilir.
• Şu anki hcie-composite/src/tiled.rs hâlâ par_chunks_exact_mut ile her satır için thread başlatıyor; küçük dirty region’larda bu ağır.
• Eylem: a257e66 öncesi ve sonrası tiled.rs’i karşılaştır; eksik tile fast-path’leri bul.

2. hcie-tile/src/lib.rs Eski ve Yetersiz

• TiledLayer::update_tiles_in_region() muhtemelen tüm tile’ları değil, sadece dirty bölgeye denk gelen tile’ları güncellemesi lazım ama implementation detaylarına bakılmalı.
• Sparse tile’ların hafıza kullanımı ve erişim deseni optimize edilebilir.
• Eylem: Tile update fonksiyonunu incele; gereksiz kopya ve sıfırlama varsa kaldır.

3. Engine API effects_dirty Gereksiz Set

• stroke_to() ve draw_pen_segment() her çizimde layer.effects_dirty.store(true) yapıyor.
• Effects olmayan layerlarda bu, sonraki composite’te effects pass’i tetikliyor; 4K’da 33MB clone + apply_layer_effects maliyeti.
• Eylem: Sadece effects/styles varsa flag set et.

4. Tile Cache Over-Clear

• set_layer_opacity, set_layer_visible, set_layer_blend_mode, set_layer_parent gibi değişiklikler tile_layers.clear() yapıyor.
• Opacity/blend/visibility sadece composite sırasında uygulanıyor; tile pikselleri değişmiyor. Tile cache’i silmek gereksiz.
• Eylem: Bu fonksiyonlarda tile_layers.clear() yerine sadece dirty flag/composite_dirty set et.

5. render_composite_region Full-Canvas Fallback

• has_dirty && dirty.is_none() durumunda tüm canvas dirty işaretleniyor.
• stroke_to içinde expand_dirty çağrılmadığı veya yanlış çağrıldığı için partial region kayboluyor olabilir.
• Eylem: stroke_to içinde dirty bounds genişletmeyi doğrula; fallback neden oluşuyor bul.

6. below_cache Her begin_stroke’ta Yeniden Hesaplanıyor

• Aktif layer en üstteyse her stroke başlangıcında N-1 katman full composited.
• Alt katmanlar değişmediyse below_cache reuse edilebilir.
• Eylem: Alt katmanlarda değişiklik olmadıkça below_cache’i yeniden hesaplama.

7. GUI Tarafında Thumbnail + Selection + Pointer Downsampling

• canvas/render.rs her karede dirty layer thumbnail’larını yeniliyor.
• draw_selection_overlay her karede tüm canvası (4K ≈ 8M piksel) tarıyor.
• Tablet/winit yüksek frekanslı event’ler smoothing yapılmadan engine’e gönderiliyor.
• Eylem: Thumbnail cache, selection edge cache, pointer distance threshold ekle.

Yapılacaklar

A. Git Geçmişi Arkeolojisi

1. a257e66 öncesi hcie-composite/src/tiled.rs halini çıkar (git show a257e66^:hcie-composite/src/tiled.rs).
2. 6f3fe5d sonrası hcie-tile/src/lib.rs değişiklikleri ara; varsa branch/stash geçmişinde daha gelişmiş versiyon olup olmadığını kontrol et.
3. hcie-core-app geçmişinde (silinmiş dizin) tile rendering / GPU acceleration / partial update kodu araştır.
4. hcie-engine-api-orig crate’ini incele; orijinal engine API’de daha iyi partial composite var mı?
5. Eski iyi hal ile şu anki hal arasındaki farkları listele.

B. Kök Neden Tespiti

1. hcie-engine-api/src/lib.rs içine detaylı TRACE logları ekle:
   • render_composite_region giriş/çıkış süresi, dirty rect boyutu, cache hit/miss.
   • begin_stroke below_cache build süresi.
   • sync_dirty_tiles süresi ve kaç layer/tile güncellediği.
   • effects pass tetiklenip tetiklenmediği, neden tetiklendiği.
2. hcie-composite/src/tiled.rs içine TRACE ekle:
   • tile path vs dense path seçimi, region boyutu, thread path seçimi.
3. Kullanıcıdan RUST_LOG=trace ile 10 saniyelik çizim oturumu logu al.
4. Log analizi ile en ağır maliyetli bölgeyi tespit et.

C. Eski İyi Optimizasyonları Geri Getir

1. hcie-composite/src/tiled.rs içindeki tile fast-path’i güçlendir:
   • Küçük region’larda sequential path seç.
   • Clipping mask lookup’u layer başına bir kez ön hesapla.
   • Effects olan layerlar için effects_cache reuse et.
2. hcie-tile/src/lib.rs tile update’ini optimize et:
   • Sadece dirty bölgeye denk gelen tile’ları güncelle.
   • Gereksiz dense→tile kopya ve sıfırlama varsa kaldır.
3. hcie-engine-api/src/lib.rs içinde:
   • effects_dirty yalnızca effects/styles varsa set et.
   • set_layer_opacity/visible/blend_mode/parent içinde tile_layers.clear() kaldır.
   • below_cache alt katman değişmedikçe reuse et.
   • render_composite_region full-canvas fallback nedenlerini ortadan kaldır.
4. hcie-brush-engine / hcie-draw içinde geçici allocation varsa azalt.

D. GUI Optimizasyonları

1. Layer thumbnail cache: AppDocument içinde dirty flag tut, sadece değişiklikte yenile.
2. Selection overlay edge cache: mask değiştiğinde marching-ants edge listesi hesapla.
3. Pointer downsampling: iki stroke_to arası minimum mesafe koşulu.

E. Regresyon Önlemleri

1. Performans regresyon testi ekle:
   • hcie-engine-api/tests/performance_stroke_4k.rs: 3840×2160, 10 katman, 100 stroke segment, stroke_to + render_composite_region süre ölçüm.
   • CI threshold olmadan, manuel karşılaştırma için log çıktısı.
2. Pre-commit/post-commit hook’lara opsiyonel benchmark adımı ekle:
   • logs/functional_regression_check.sh --benchmark modu.
3. AGENTS.md / plan dosyasına kritik performans kodlarının (tile rendering, partial composite, dirty rect, effects cache, below_cache) korunması gerektiği notu ekle; gelecekteki değişikliklerde bu alanlara dokunulmadan önce review/benchmark zorunluluğu.

F. Doğrulama

1. cargo test -p hcie-engine-api --test visual_regression — golden hash’ler değişmemeli.
2. logs/functional_regression_check.sh --fast.
3. Yeni benchmark’ı önce eski haliyle (HEAD öncesi stash veya geçici branch), sonra değişikliklerle çalıştır; kazanımı ölç.

Uygulama Sırası

1. Git arkeolojisi: eski iyi kodu bul ve karşılaştır.
2. Kök neden tanısı: TRACE logları ve log analizi.
3. En büyük kazanımı hedefle: tile cache over-clear + effects_dirty fix.
4. Tile composite engine güçlendir: sequential small-region path + effects cache reuse.
5. Engine below_cache reuse.
6. GUI thumbnail/selection/pointer optimizasyonları.
7. Benchmark + regresyon önlemleri.
8. Kilitleri geri kilitle (./lock.sh all).

Kısıtlar

• hcie-engine-api public API’sini değiştirmeden optimize et; GUI kodu derlenmeye devam etmeli.
• Mevcut işlevselliği bozmadan optimize et; golden hash’ler değişmemeli.
• Her seansta en fazla 5 dosya değişikliği; fazla ise görev bölünecek.
• Değişiklikler bitince ./lock.sh all ile kilitleri geri kilitle.

Başarı Kriteri

• 4K çok katmanlı PSD üzerinde fırça/pen çizimi sırasında hissedilir lag azalır.
• cargo test -p hcie-engine-api --test visual_regression geçmeye devam eder.
• logs/functional_regression_check.sh --fast geçmeye devam eder.
• Performans benchmark’ında ortalama frame/segment süresi önceki haline göre düşer.
• Eski çalışan optimizasyonlar geri getirilmiş ve korunmak üzere belgelenmiştir.