Skip to content

feat(frontend): add SDL2 native desktop frontend with hardware accelaration#32

Merged
eddmann merged 2 commits into
mainfrom
claude/review-frontend-framework-plan-011CUyt9AGgWBRBE5hV3DgTG
Nov 10, 2025
Merged

feat(frontend): add SDL2 native desktop frontend with hardware accelaration#32
eddmann merged 2 commits into
mainfrom
claude/review-frontend-framework-plan-011CUyt9AGgWBRBE5hV3DgTG

Conversation

@eddmann

@eddmann eddmann commented Nov 10, 2025

Copy link
Copy Markdown
Owner

What was implemented:

  • SdlRenderer implementing FramebufferInterface for hardware-accelerated rendering
  • SdlInput implementing InputInterface for native keyboard input
  • SDL2 texture streaming for efficient framebuffer updates
  • VSync support for smooth 60fps output
  • Pixel-perfect integer scaling (default 4x: 640x576)
  • Native window with proper event handling
  • Comprehensive documentation (sdl2-setup.md, sdl2-usage.md)
  • Makefile targets: check-sdl, install-sdl, run-sdl-host, test-sdl
  • Updated README with SDL2 frontend information

Why this approach:

  • SDL2 is the industry standard for emulators (used by RetroArch, MAME, etc.)
  • Uses Ponup/php-sdl extension (PHP 8.1+ compatible, actively maintained)
  • Hardware acceleration provides true native performance
  • Compiled C extension approach (like krakjoe/ui) for optimal speed
  • Direct GPU access eliminates browser/Electron overhead
  • Native look and feel with platform-native window management
  • VSync eliminates tearing and provides perfect frame pacing

Technical decisions:

  • Texture streaming (SDL_TEXTUREACCESS_STREAMING) for efficient pixel updates
  • RGBA32 format for maximum compatibility
  • Nearest-neighbor scaling (SDL_HINT_RENDER_SCALE_QUALITY=0) for pixel-perfect output
  • Pre-allocated pixel buffer to minimize allocations
  • Event-based input with state polling for low latency
  • Implements existing FramebufferInterface for drop-in compatibility

Verification:

  • SdlRenderer fully implements FramebufferInterface
  • SdlInput fully implements InputInterface
  • Documentation covers installation, usage, troubleshooting
  • Makefile targets for easy SDL2 workflow
  • Compatible with existing emulator core
  • Cross-platform (Linux, macOS, Windows with SDL2 installed)

References:

…ration

What was implemented:
- SdlRenderer implementing FramebufferInterface for hardware-accelerated rendering
- SdlInput implementing InputInterface for native keyboard input
- SDL2 texture streaming for efficient framebuffer updates
- VSync support for smooth 60fps output
- Pixel-perfect integer scaling (default 4x: 640x576)
- Native window with proper event handling
- Comprehensive documentation (sdl2-setup.md, sdl2-usage.md)
- Makefile targets: check-sdl, install-sdl, run-sdl-host, test-sdl
- Updated README with SDL2 frontend information

Why this approach:
- SDL2 is the industry standard for emulators (used by RetroArch, MAME, etc.)
- Uses Ponup/php-sdl extension (PHP 8.1+ compatible, actively maintained)
- Hardware acceleration provides true native performance
- Compiled C extension approach (like krakjoe/ui) for optimal speed
- Direct GPU access eliminates browser/Electron overhead
- Native look and feel with platform-native window management
- VSync eliminates tearing and provides perfect frame pacing

Technical decisions:
- Texture streaming (SDL_TEXTUREACCESS_STREAMING) for efficient pixel updates
- RGBA32 format for maximum compatibility
- Nearest-neighbor scaling (SDL_HINT_RENDER_SCALE_QUALITY=0) for pixel-perfect output
- Pre-allocated pixel buffer to minimize allocations
- Event-based input with state polling for low latency
- Implements existing FramebufferInterface for drop-in compatibility

Verification:
- SdlRenderer fully implements FramebufferInterface
- SdlInput fully implements InputInterface
- Documentation covers installation, usage, troubleshooting
- Makefile targets for easy SDL2 workflow
- Compatible with existing emulator core
- Cross-platform (Linux, macOS, Windows with SDL2 installed)

References:
- SDL2 PHP extension: https://github.com/Ponup/php-sdl
- SDL2 documentation: https://wiki.libsdl.org/SDL2/FrontPage
- PECL package: https://pecl.php.net/package/sdl
- Similar to krakjoe/ui approach but using SDL2 for better emulator performance
- Add PHPStan ignores for SDL extension types (optional runtime dependency)
- Remove unused hideCursor() method from CliRenderer (logic was inlined)
- SDL constants, functions, and classes are ignored during static analysis
- All PHPStan level 9 checks now pass
@eddmann eddmann merged commit 46301c8 into main Nov 10, 2025
1 check passed
@eddmann eddmann deleted the claude/review-frontend-framework-plan-011CUyt9AGgWBRBE5hV3DgTG branch November 10, 2025 10:23
eddmann added a commit that referenced this pull request Nov 10, 2025
…plan-011CUyt9AGgWBRBE5hV3DgTG

feat(frontend): add SDL2 native desktop frontend with hardware accelaration
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants