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
This commit is contained in:
parent
193294d3a7
commit
f76a26c120
|
|
@ -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<T>()` API
|
||||
- All enums are now scoped (e.g., `sf::Keyboard::Key::A`)
|
||||
- Resource loading via constructors that throw exceptions
|
||||
- `pollEvent()` returns `std::optional<sf::Event>`
|
||||
- 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)
|
||||
|
|
|
|||
|
|
@ -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<sf::Event::Closed>()) {
|
||||
window.close();
|
||||
}
|
||||
else if (const auto* keyPressed = event->getIf<sf::Event::KeyPressed>()) {
|
||||
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.
|
||||
Loading…
Reference in New Issue