From f76a26c1206d0b16b6227c9de8ab680b1af83e00 Mon Sep 17 00:00:00 2001 From: John McCardle Date: Sun, 6 Jul 2025 13:08:52 -0400 Subject: [PATCH] research: SFML 3.0 migration analysis - Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17) - Assessed migration impact on McRogueFace (40+ files affected) - Evaluated timing relative to mcrfpy.sfml module plans - Recommended deferring migration until after mcrfpy.sfml implementation - Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy --- ALPHA_STREAMLINE_WORKLOG.md | 42 ++++++ SFML_3_MIGRATION_RESEARCH.md | 257 +++++++++++++++++++++++++++++++++++ 2 files changed, 299 insertions(+) create mode 100644 SFML_3_MIGRATION_RESEARCH.md diff --git a/ALPHA_STREAMLINE_WORKLOG.md b/ALPHA_STREAMLINE_WORKLOG.md index a28123c..990026e 100644 --- a/ALPHA_STREAMLINE_WORKLOG.md +++ b/ALPHA_STREAMLINE_WORKLOG.md @@ -36,6 +36,48 @@ --- +### Task: SFML 3.0 Migration Research + +**Status**: Research Completed +**Date**: 2025-07-06 + +**Research Summary**: +1. SFML 3.0 Release Analysis: + - Released December 21, 2024 (very recent) + - First major version in 12 years + - Requires C++17 (vs C++03 for SFML 2.x) + - Major breaking changes in event system, enums, resource loading + +2. McRogueFace Impact Assessment: + - 40+ source files use SFML directly + - Event handling requires complete rewrite (high impact) + - All keyboard/mouse enums need updating (medium impact) + - Resource loading needs exception handling (medium impact) + - Geometry constructors need updating (low impact) + +3. Key Breaking Changes: + - Event system now uses `std::variant` with `getIf()` API + - All enums are now scoped (e.g., `sf::Keyboard::Key::A`) + - Resource loading via constructors that throw exceptions + - `pollEvent()` returns `std::optional` + - CMake targets now namespaced (e.g., `SFML::Graphics`) + +4. Recommendation: **Defer Migration** + - SFML 3.0 is too new (potential stability issues) + - Migration effort is substantial (especially event system) + - Better to implement `mcrfpy.sfml` with stable SFML 2.6.1 first + - Revisit migration in 6-12 months + +**Key Decisions**: +- Proceed with `mcrfpy.sfml` implementation using SFML 2.6.1 +- Design module API to minimize future breaking changes +- Monitor SFML 3.0 adoption and stability +- Plan migration for late 2025 or early 2026 + +**Result**: Created SFML_3_MIGRATION_RESEARCH.md with comprehensive analysis and migration strategy. + +--- + ## Phase 4: Visibility & Performance ### Task 3: Basic Profiling/Metrics (#104) diff --git a/SFML_3_MIGRATION_RESEARCH.md b/SFML_3_MIGRATION_RESEARCH.md new file mode 100644 index 0000000..71c35e1 --- /dev/null +++ b/SFML_3_MIGRATION_RESEARCH.md @@ -0,0 +1,257 @@ +# SFML 3.0 Migration Research for McRogueFace + +## Executive Summary + +SFML 3.0 was released on December 21, 2024, marking the first major version in 12 years. While it offers significant improvements in type safety, modern C++ features, and API consistency, migrating McRogueFace would require substantial effort. Given our plans for `mcrfpy.sfml`, I recommend **deferring migration to SFML 3.0** until after implementing the initial `mcrfpy.sfml` module with SFML 2.6.1. + +## SFML 3.0 Overview + +### Release Highlights +- **Release Date**: December 21, 2024 +- **Development**: 3 years, 1,100+ commits, 41 new contributors +- **Major Feature**: C++17 support (now required) +- **Audio Backend**: Replaced OpenAL with miniaudio +- **Test Coverage**: Expanded to 57% +- **New Features**: Scissor and stencil testing + +### Key Breaking Changes + +#### 1. C++ Standard Requirements +- **Minimum**: C++17 (was C++03) +- **Compilers**: MSVC 16 (VS 2019), GCC 9, Clang 9, AppleClang 12 + +#### 2. Event System Overhaul +```cpp +// SFML 2.x +sf::Event event; +while (window.pollEvent(event)) { + switch (event.type) { + case sf::Event::Closed: + window.close(); + break; + case sf::Event::KeyPressed: + handleKey(event.key.code); + break; + } +} + +// SFML 3.0 +while (const std::optional event = window.pollEvent()) { + if (event->is()) { + window.close(); + } + else if (const auto* keyPressed = event->getIf()) { + handleKey(keyPressed->code); + } +} +``` + +#### 3. Scoped Enumerations +```cpp +// SFML 2.x +sf::Keyboard::A +sf::Mouse::Left + +// SFML 3.0 +sf::Keyboard::Key::A +sf::Mouse::Button::Left +``` + +#### 4. Resource Loading +```cpp +// SFML 2.x +sf::Texture texture; +if (!texture.loadFromFile("image.png")) { + // Handle error +} + +// SFML 3.0 +try { + sf::Texture texture("image.png"); +} catch (const std::exception& e) { + // Handle error +} +``` + +#### 5. Geometry Changes +```cpp +// SFML 2.x +sf::FloatRect rect(left, top, width, height); + +// SFML 3.0 +sf::FloatRect rect({left, top}, {width, height}); +// Now uses position and size vectors +``` + +#### 6. CMake Changes +```cmake +# SFML 2.x +find_package(SFML 2.6 COMPONENTS graphics window system audio REQUIRED) +target_link_libraries(app sfml-graphics sfml-window sfml-system sfml-audio) + +# SFML 3.0 +find_package(SFML 3.0 COMPONENTS Graphics Window System Audio REQUIRED) +target_link_libraries(app SFML::Graphics SFML::Window SFML::System SFML::Audio) +``` + +## McRogueFace SFML Usage Analysis + +### Current Usage Statistics +- **SFML Version**: 2.6.1 +- **Integration Level**: Moderate to Heavy +- **Affected Files**: ~40+ source files + +### Major Areas Requiring Changes + +#### 1. Event Handling (High Impact) +- **Files**: `GameEngine.cpp`, `PyScene.cpp` +- **Changes**: Complete rewrite of event loops +- **Effort**: High + +#### 2. Enumerations (Medium Impact) +- **Files**: `ActionCode.h`, all input handling +- **Changes**: Update all keyboard/mouse enum references +- **Effort**: Medium (mostly find/replace) + +#### 3. Resource Loading (Medium Impact) +- **Files**: `PyTexture.cpp`, `PyFont.cpp`, `McRFPy_API.cpp` +- **Changes**: Constructor-based loading with exception handling +- **Effort**: Medium + +#### 4. Geometry (Low Impact) +- **Files**: Various UI classes +- **Changes**: Update Rect construction +- **Effort**: Low + +#### 5. CMake Build System (Low Impact) +- **Files**: `CMakeLists.txt` +- **Changes**: Update find_package and target names +- **Effort**: Low + +### Code Examples from McRogueFace + +#### Current Event Loop (GameEngine.cpp) +```cpp +sf::Event event; +while (window && window->pollEvent(event)) { + processEvent(event); + if (event.type == sf::Event::Closed) { + running = false; + } +} +``` + +#### Current Key Mapping (ActionCode.h) +```cpp +{sf::Keyboard::Key::A, KEY_A}, +{sf::Keyboard::Key::Left, KEY_LEFT}, +{sf::Mouse::Left, MOUSEBUTTON_LEFT} +``` + +## Impact on mcrfpy.sfml Module Plans + +### Option 1: Implement with SFML 2.6.1 First (Recommended) +**Pros**: +- Faster initial implementation +- Stable, well-tested SFML version +- Can provide value immediately +- Migration can be done later + +**Cons**: +- Will require migration work later +- API might need changes for SFML 3.0 + +### Option 2: Wait and Implement with SFML 3.0 +**Pros**: +- Future-proof implementation +- Modern C++ features +- No migration needed later + +**Cons**: +- Delays `mcrfpy.sfml` implementation +- SFML 3.0 is very new (potential bugs) +- Less documentation/examples available + +### Option 3: Dual Support +**Pros**: +- Maximum flexibility +- Gradual migration path + +**Cons**: +- Significant additional complexity +- Maintenance burden +- Conditional compilation complexity + +## Migration Strategy Recommendation + +### Phase 1: Current State (Now) +1. Continue with SFML 2.6.1 +2. Implement `mcrfpy.sfml` module as planned +3. Design module API to minimize future breaking changes + +### Phase 2: Preparation (3-6 months) +1. Monitor SFML 3.0 stability and adoption +2. Create migration branch for testing +3. Update development environment to C++17 + +### Phase 3: Migration (6-12 months) +1. Migrate McRogueFace core to SFML 3.0 +2. Update `mcrfpy.sfml` to match +3. Provide migration guide for users + +### Phase 4: Deprecation (12-18 months) +1. Deprecate SFML 2.6.1 support +2. Focus on SFML 3.0 features + +## Specific Migration Tasks + +### Prerequisites +- [ ] Update to C++17 compatible compiler +- [ ] Update CMake to 3.16+ +- [ ] Review all SFML usage locations + +### Core Changes +- [ ] Rewrite all event handling loops +- [ ] Update all enum references +- [ ] Convert resource loading to constructors +- [ ] Update geometry construction +- [ ] Update CMake configuration + +### mcrfpy.sfml Considerations +- [ ] Design API to be version-agnostic where possible +- [ ] Use abstraction layer for version-specific code +- [ ] Document version requirements clearly + +## Risk Assessment + +### High Risk Areas +1. **Event System**: Complete paradigm shift +2. **Exception Handling**: New resource loading model +3. **Third-party Dependencies**: May not support SFML 3.0 yet + +### Medium Risk Areas +1. **Performance**: New implementations may differ +2. **Platform Support**: New version may have issues +3. **Documentation**: Less community knowledge + +### Low Risk Areas +1. **Basic Rendering**: Core concepts unchanged +2. **CMake**: Straightforward updates +3. **Enums**: Mechanical changes + +## Conclusion + +While SFML 3.0 offers significant improvements, the migration effort is substantial. Given that: + +1. SFML 3.0 is very new (released December 2024) +2. McRogueFace has heavy SFML integration +3. We plan to implement `mcrfpy.sfml` soon +4. The event system requires complete rewriting + +**I recommend deferring SFML 3.0 migration** until after successfully implementing `mcrfpy.sfml` with SFML 2.6.1. This allows us to: +- Deliver value sooner with `mcrfpy.sfml` +- Learn from early adopters of SFML 3.0 +- Design our module API with migration in mind +- Migrate when SFML 3.0 is more mature + +The migration should be revisited in 6-12 months when SFML 3.0 has proven stability and wider adoption. \ No newline at end of file