257 lines
6.9 KiB
Markdown
257 lines
6.9 KiB
Markdown
# 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. |