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
|
## Phase 4: Visibility & Performance
|
||||||
|
|
||||||
### Task 3: Basic Profiling/Metrics (#104)
|
### 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