libretro_raylib

A Libretro frontend implementation using Raylib for macOS.

Created by mikedx

License

This project is licensed under the MIT License.

Third-Party Licenses

This project uses the following third-party libraries:

• libretro API: The official libretro.h header file is included from RetroArch's libretro-common repository. Copyright (C) 2010-2024 The RetroArch team. The libretro API is available under the MIT License (as stated in the header file). See https://www.libretro.com/ for details. Note: The libretro.h file in this repository is an unmodified copy and should not be edited.

• raylib: Used under the zlib/libpng license. See https://github.com/raysan5/raylib for details.

Building

Prerequisites

• macOS with Xcode Command Line Tools
• raylib installed in ../raylib/src
• A libretro core (.dylib file) for your target platform

Downloading Cores

You can use the included script to download cores:

./download_cores.sh

This will:

• Fetch the list of available cores from the libretro buildbot
• Display them in a menu
• Allow you to download individual cores or all cores
• Save them to the cores/ directory

Build Instructions

make

This will create the libretro_raylib executable.

Usage

./libretro_raylib <path_to_core.dylib> [rom_file]

Examples

# Load a core with a ROM file (using downloaded core)
./libretro_raylib cores/mgba_libretro.dylib mike_test.gba

# Load a core without a ROM (for cores that support no-game mode)
./libretro_raylib cores/mgba_libretro.dylib

# Atari 2600 (Stella core)
./libretro_raylib cores/stella_libretro.dylib pitfall.bin

# SNES (bsnes core)
./libretro_raylib cores/bsnes_libretro.dylib mario_kart.sfc

# SNES (snes9x core)
./libretro_raylib cores/snes9x_libretro.dylib super_mario_world.sfc

# Or use a core from any location
./libretro_raylib /path/to/core.dylib /path/to/rom.gba

Controls

• Arrow Keys / WASD - D-Pad
• X - A button
• Z - B button
• C - X button
• V - Y button
• Q - L button
• E - R button
• TAB - Select
• ENTER - Start
• ESC - Exit

Features

• Dynamic loading of libretro cores
• Video rendering with pixel format conversion and proper frame/display dimension handling
• Audio playback with ring buffer management and underrun/overflow protection
• Keyboard input mapping
• Aspect ratio preservation
• Modular architecture for maintainability and extensibility
• Support for multiple pixel formats (XRGB8888, RGB565, 0RGB1555, RGB555)

Architecture

The frontend is organized into modular components:

Core Modules

• libretro.h - Official libretro API header (unmodified copy from RetroArch)

  • All libretro constants, enums, structures, and type definitions
  • Callback type definitions
  • This file is maintained by the RetroArch/libretro team and should not be modified

• libretro_core_types.h - Custom core function pointer wrapper

  • retro_core_t structure for holding dynamically loaded core function pointers
  • Core symbol name definitions (SYM_RETRO_*)
  • This is our own structure, not part of the official libretro API

• libretro_frontend.h/c - Main public API

  • Coordinates all modules
  • Public API functions for core management
  • Frontend state management

Callback Modules

• libretro_environment.h/c - Environment callback implementation

  • Handles core requests for system information
  • Pixel format configuration
  • Directory paths and system settings
  • Log interface support

• libretro_video.h/c - Video refresh callback

  • Receives rendered frames from cores
  • Pixel format conversion (RGB565, XRGB8888, 0RGB1555)
  • Framebuffer management
  • Auto-detection of pixel formats

• libretro_audio.h/c - Audio callbacks

  • Single-sample and batch audio callbacks
  • Ring buffer management for audio streaming
  • Audio format conversion (int16_t to float)
  • Handles cores that use single-sample callbacks (e.g., xrick)

• libretro_input.h/c - Input handling

  • Input poll callback
  • Input state queries (joypad and keyboard)
  • Keyboard keycode mapping

Core Management

• libretro_core.h/c - Core loading and management
  • Dynamic library loading (dlopen)
  • Core symbol resolution
  • Core initialization
  • ROM loading (supports both fullpath and memory-based loading)
  • Audio/video info updates
  • Core cleanup and resource management

Application

• main.c - Main entry point and raylib integration
  • Window management
  • Input handling (keyboard to libretro mapping)
  • Audio stream management
  • Frame rendering loop

The modular design provides:

• Separation of concerns: Each module handles a specific aspect of the libretro API
• Maintainability: Easier to locate and modify specific functionality
• Testability: Modules can be tested independently
• Readability: Smaller, focused files are easier to understand

Notes

• The frontend supports pixel formats:
  • XRGB8888 (format 1): 32-bit format, 8 bits per channel
  • RGB565 (format 2): 16-bit format, 5-6-5 bits (R-G-B), used by mGBA
  • 0RGB1555 (format 0): 16-bit format, 5-5-5 bits (R-G-B), used by bsnes
  • RGB555 (format 12): 16-bit format, 5-5-5 bits (R-G-B), used by snes9x
• Audio is converted from int16_t samples to float for raylib
• Video frames are converted to RGBA8888 format for rendering
• Audio uses a ring buffer to handle timing variations between core and playback
• Single-sample audio callbacks are supported for cores like xrick

Tested Cores

The following cores have been tested and are working:

• mGBA - Game Boy Advance emulation
• bsnes - SNES emulation (including Super Mario Kart)
• snes9x - SNES emulation (tested with Super Mario World and Super Mario Kart)
• Stella - Atari 2600 emulation

Known Issues

None at this time. If you encounter issues with specific cores or games, please report them.