refactor(docs): standardize warning messages and update documentation formatting
- Replaced "⚠️ ISSUE" with "Warning: ISSUE" for consistency across dependency architecture documentation.
- Removed checkmarks from completed items in various documents to maintain uniformity in status representation.
- Enhanced clarity by ensuring all sections follow a consistent formatting style.
Benefits:
- Improves readability and consistency in documentation, making it easier for contributors to understand the project's status and issues.
- Aligns with the overall documentation style, fostering a more professional appearance across all documents.
This commit is contained in:
scawful
@@ -1,39 +1,31 @@
|
||||
# Graphics Renderer Migration - Complete Documentation
|
||||
|
||||
**Date**: October 7, 2025
|
||||
**Status**: ✅ Complete
|
||||
**Status**: Complete
|
||||
**Migration**: SDL2 Singleton → IRenderer Interface with SDL2/SDL3 Support
|
||||
|
||||
---
|
||||
|
||||
## 📋 Executive Summary
|
||||
## Executive Summary
|
||||
|
||||
This document details the complete migration of YAZE's rendering architecture from a tightly-coupled SDL2 singleton pattern to a flexible, abstracted renderer interface. This migration enables future SDL3 support, improves testability, and implements a high-performance deferred texture system.
|
||||
This document records the migration from the legacy SDL2 `core::Renderer` singleton to a dependency-injected renderer interface. The new design enables SDL3 backends, keeps SDL2 compatibility, and moves texture work onto a deferred queue.
|
||||
|
||||
### Key Achievements
|
||||
- ✅ **100% Removal** of `core::Renderer` singleton
|
||||
- ✅ **Zero Breaking Changes** to existing editor functionality
|
||||
- ✅ **Performance Gains** through batched texture operations
|
||||
- ✅ **SDL3 Ready** via abstract `IRenderer` interface
|
||||
- ✅ **Backwards Compatible** Canvas API for legacy code
|
||||
- ✅ **Memory Optimized** with texture/surface pooling
|
||||
Key outcomes:
|
||||
- `core::Renderer` singleton removed; editors now depend on `gfx::IRenderer`.
|
||||
- Deferred queue batches up to eight texture operations per frame (`gfx::Arena::ProcessTextureQueue`).
|
||||
- Canvas APIs remain source-compatible for existing editors.
|
||||
- Texture and surface pooling reduces redundant allocations during editor startup.
|
||||
|
||||
Migration goals and current state:
|
||||
- Decouple from SDL2: complete. Rendering code paths call `gfx::IRenderer`.
|
||||
- SDL3 readiness: backends implement `IRenderer`; an SDL3 backend can now be added without touching editor code.
|
||||
- Performance: local benchmarks during October 2025 testing showed faster editor startup due to batched texture creation.
|
||||
- Compatibility: existing editors build and run without behavioural regressions on SDL2.
|
||||
- Code cleanup: renderer TODOs resolved and tests updated to use the injected interface.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Migration Goals & Results
|
||||
|
||||
| Goal | Status | Details |
|
||||
|------|--------|---------|
|
||||
| Decouple from SDL2 | ✅ Complete | All rendering goes through `IRenderer` |
|
||||
| Enable SDL3 migration | ✅ Ready | New backend = implement `IRenderer` |
|
||||
| Improve performance | ✅ 40% faster | Batched texture ops, deferred queue |
|
||||
| Maintain compatibility | ✅ Zero breaks | Legacy constructors preserved |
|
||||
| Reduce memory usage | ✅ 25% reduction | Surface/texture pooling in Arena |
|
||||
| Fix all TODOs | ✅ Complete | All rendering TODOs resolved |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
## Architecture Overview
|
||||
|
||||
### Before: Singleton Pattern
|
||||
```cpp
|
||||
@@ -75,11 +67,11 @@ void Controller::DoRender() {
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Swap SDL2/SDL3 by changing backend
|
||||
- ✅ Batched texture ops (8 per frame)
|
||||
- ✅ Non-blocking asset loading
|
||||
- ✅ Testable with mock renderer
|
||||
- ✅ Better CPU/GPU utilization
|
||||
- Swap SDL2/SDL3 by changing backend
|
||||
- Batched texture ops (8 per frame)
|
||||
- Non-blocking asset loading
|
||||
- Testable with mock renderer
|
||||
- Better CPU/GPU utilization
|
||||
|
||||
---
|
||||
|
||||
@@ -405,7 +397,7 @@ SDL_Surface* Arena::AllocateSurface(int w, int h, int depth, int format) {
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ Migration Map: File Changes
|
||||
## Migration Map: File Changes
|
||||
|
||||
### Core Architecture Files (New)
|
||||
- `src/app/gfx/backend/irenderer.h` - Abstract renderer interface
|
||||
@@ -461,7 +453,7 @@ SDL_Surface* Arena::AllocateSurface(int w, int h, int depth, int format) {
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Critical Fixes Applied
|
||||
## Tool Critical Fixes Applied
|
||||
|
||||
### 1. Bitmap::SetPalette() Crash
|
||||
**Location**: `bitmap.cc:252-288`
|
||||
@@ -663,16 +655,16 @@ gfx::CreateTilemap(nullptr, data, ...); // Can pass nullptr in tests!
|
||||
```
|
||||
|
||||
**Test Coverage**:
|
||||
- ✅ `yaze` - Main application
|
||||
- ✅ `yaze_test` - Unit tests
|
||||
- ✅ `yaze_emu` - Standalone emulator
|
||||
- ✅ `z3ed` - Legacy editor mode
|
||||
- ✅ All integration tests
|
||||
- ✅ All benchmarks
|
||||
- `yaze` - Main application
|
||||
- `yaze_test` - Unit tests
|
||||
- `yaze_emu` - Standalone emulator
|
||||
- `z3ed` - Legacy editor mode
|
||||
- All integration tests
|
||||
- All benchmarks
|
||||
|
||||
---
|
||||
|
||||
## 🛣️ Road to SDL3
|
||||
## Road to SDL3
|
||||
|
||||
### Why This Migration Matters
|
||||
|
||||
@@ -781,24 +773,24 @@ renderer_ = std::make_unique<gfx::SDL3Renderer>();
|
||||
## 🐛 Bugs Fixed During Migration
|
||||
|
||||
### Critical Crashes
|
||||
1. ✅ **Graphics Editor SIGSEGV** - Null surface->format in SDL_ConvertSurfaceFormat
|
||||
2. ✅ **Emulator Audio Corruption** - Early SNES initialization before audio ready
|
||||
3. ✅ **Bitmap Palette Exception** - Setting palette before surface creation
|
||||
4. ✅ **Tile16 Editor White Graphics** - Textures never created from queue
|
||||
5. ✅ **Metal/CoreAnimation Crash** - Texture destruction during Initialize
|
||||
6. ✅ **Emulator Shutdown SIGSEGV** - Destroying texture after renderer destroyed
|
||||
1. **Graphics Editor SIGSEGV** - Null surface->format in SDL_ConvertSurfaceFormat
|
||||
2. **Emulator Audio Corruption** - Early SNES initialization before audio ready
|
||||
3. **Bitmap Palette Exception** - Setting palette before surface creation
|
||||
4. **Tile16 Editor White Graphics** - Textures never created from queue
|
||||
5. **Metal/CoreAnimation Crash** - Texture destruction during Initialize
|
||||
6. **Emulator Shutdown SIGSEGV** - Destroying texture after renderer destroyed
|
||||
|
||||
### Build Errors
|
||||
7. ✅ **87 Compilation Errors** - `core::Renderer` namespace references
|
||||
8. ✅ **Canvas Constructor Mismatch** - Legacy code broken by new constructors
|
||||
9. ✅ **CreateWindow Parameter Order** - Test files had wrong parameters
|
||||
10. ✅ **Duplicate main() Symbol** - Test file conflicts
|
||||
11. ✅ **Missing graphics_optimizer.cc** - CMake file reference
|
||||
12. ✅ **AssetLoader Namespace** - core::AssetLoader → AssetLoader
|
||||
7. **87 Compilation Errors** - `core::Renderer` namespace references
|
||||
8. **Canvas Constructor Mismatch** - Legacy code broken by new constructors
|
||||
9. **CreateWindow Parameter Order** - Test files had wrong parameters
|
||||
10. **Duplicate main() Symbol** - Test file conflicts
|
||||
11. **Missing graphics_optimizer.cc** - CMake file reference
|
||||
12. **AssetLoader Namespace** - core::AssetLoader → AssetLoader
|
||||
|
||||
---
|
||||
|
||||
## 💡 Key Design Patterns Used
|
||||
## Key Design Patterns Used
|
||||
|
||||
### 1. Dependency Injection
|
||||
**Pattern**: Pass dependencies through constructors
|
||||
@@ -959,31 +951,31 @@ void ProcessTextureQueue(IRenderer* renderer) {
|
||||
## 🏆 Success Metrics
|
||||
|
||||
### Build Health
|
||||
- ✅ All targets build: `yaze`, `yaze_emu`, `z3ed`, `yaze_test`
|
||||
- ✅ Zero compiler warnings (renderer-related)
|
||||
- ✅ Zero linter errors
|
||||
- ✅ All tests pass
|
||||
- All targets build: `yaze`, `yaze_emu`, `z3ed`, `yaze_test`
|
||||
- Zero compiler warnings (renderer-related)
|
||||
- Zero linter errors
|
||||
- All tests pass
|
||||
|
||||
### Runtime Stability
|
||||
- ✅ App starts without crashes
|
||||
- ✅ All editors load successfully
|
||||
- ✅ Emulator runs without corruption
|
||||
- ✅ Clean shutdown (no leaks)
|
||||
- ✅ ROM switching works
|
||||
- App starts without crashes
|
||||
- All editors load successfully
|
||||
- Emulator runs without corruption
|
||||
- Clean shutdown (no leaks)
|
||||
- ROM switching works
|
||||
|
||||
### Performance
|
||||
- ✅ 64% faster texture loading
|
||||
- ✅ 82% lower CPU usage (idle)
|
||||
- ✅ 60 FPS maintained across all editors
|
||||
- ✅ No frame drops during loading
|
||||
- ✅ Smooth emulator performance
|
||||
- 64% faster texture loading
|
||||
- 82% lower CPU usage (idle)
|
||||
- 60 FPS maintained across all editors
|
||||
- No frame drops during loading
|
||||
- Smooth emulator performance
|
||||
|
||||
### Code Quality
|
||||
- ✅ Removed global `core::Renderer` singleton
|
||||
- ✅ Dependency injection throughout
|
||||
- ✅ Testable architecture
|
||||
- ✅ SDL3-ready abstraction
|
||||
- ✅ Clear separation of concerns
|
||||
- Removed global `core::Renderer` singleton
|
||||
- Dependency injection throughout
|
||||
- Testable architecture
|
||||
- SDL3-ready abstraction
|
||||
- Clear separation of concerns
|
||||
|
||||
---
|
||||
|
||||
@@ -1008,7 +1000,7 @@ void ProcessTextureQueue(IRenderer* renderer) {
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
## Acknowledgments
|
||||
|
||||
This migration was a collaborative effort involving:
|
||||
- **Initial Design**: IRenderer interface and migration plan
|
||||
@@ -1035,11 +1027,11 @@ The YAZE rendering architecture has been successfully modernized with:
|
||||
4. **Flexibility**: Dependency injection allows testing and swapping
|
||||
5. **Compatibility**: Legacy code continues working unchanged
|
||||
|
||||
**The renderer refactor is complete and production-ready!** 🚀
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Known Issues & Next Steps
|
||||
## Known Issues & Next Steps
|
||||
|
||||
### macOS-Specific Issues (Not Renderer-Related)
|
||||
|
||||
@@ -1152,13 +1144,13 @@ This migration involved:
|
||||
- **12 runtime crashes** resolved
|
||||
- **64% performance improvement**
|
||||
|
||||
**Special Thanks** to Portal 2's soundtrack for powering through the final bugs! 🎮
|
||||
**Special Thanks** to Portal 2's soundtrack for powering through the final bugs! Game
|
||||
|
||||
The rendering system is now:
|
||||
- ✅ **Abstracted** - Ready for SDL3
|
||||
- ✅ **Optimized** - 82% lower CPU usage
|
||||
- ✅ **Stable** - All critical crashes fixed
|
||||
- ✅ **Documented** - Comprehensive guide written
|
||||
- **Abstracted** - Ready for SDL3
|
||||
- **Optimized** - 82% lower CPU usage
|
||||
- **Stable** - All critical crashes fixed
|
||||
- **Documented** - Comprehensive guide written
|
||||
|
||||
**Known Quirks:**
|
||||
- macOS resize with emulator may occasionally show loading indicator (macOS bug, not ours)
|
||||
@@ -1173,4 +1165,3 @@ The rendering system is now:
|
||||
*Last Updated: October 7, 2025 (Post-Grocery Edition)*
|
||||
*Authors: AI Assistant + User Collaboration*
|
||||
*Soundtrack: Portal 2 OST*
|
||||
|
||||
|
||||
Reference in New Issue
Block a user