Crate libretro_core

Expand description

Minimal libretro wrapper for implementing Rust cores.

The crate exposes typed Rust wrappers for libretro.h plus a trait/macro pair for exporting the required retro_* symbols from a Rust core.

Methodology:

Keep public APIs Rust-first even when the underlying libretro ABI is C-first.
Prefer strings, slices, enums, and return values over raw pointers or mutable out-params whenever the wrapper can do that conversion centrally.
Keep raw ABI details private unless exposing them is necessary for a real core-development use case.
Match libretro/OpenGL naming where it helps recognition, but not at the cost of forcing callers back into manual FFI plumbing.

API map:

Core, Runtime, Environment, and export_core! are the primary core authoring surface.
ContentContract, SystemInfo, GameInfo, and SystemAvInfo describe startup metadata, content loading, geometry, and timing.
Input polling uses Runtime helpers with typed devices such as JoypadButton, AnalogStick, MouseButton, and PointerAxis.
Event-shaped frontend callbacks are registered through CoreEventConfig with DOM-style listener methods such as CoreEventConfig::add_keyboard_event_listener; callback-shaped frontend hooks with one active registration, such as frame timing, use explicit set_*_callback methods.
Optional frontend services are exposed as typed interfaces such as VfsInterface, MidiInterface, MicrophoneInterface, PerfInterface, SensorInterface, LocationInterface, and CameraInterface.
Hardware rendering uses HwRenderConfig for context negotiation and Gl for typed OpenGL access.

use libretro::{
    ContentContract, Core, CoreEventConfig, Environment, GameGeometry, HwRenderConfig,
    JoypadButton, KeyboardEvent, PixelFormat, Runtime, SystemAvInfo, SystemInfo, SystemTiming,
    VariableDefinition,
};

#[derive(Default)]
struct GlCore {
    width: u32,
    height: u32,
}

impl Core for GlCore {
    fn system_info(&self) -> SystemInfo {
        let mut info = SystemInfo::new("TestCore GL", "v1");
        info.need_fullpath = false;
        info
    }

    fn av_info(&self) -> SystemAvInfo {
        SystemAvInfo {
            geometry: GameGeometry {
                base_width: 320,
                base_height: 240,
                max_width: 1024,
                max_height: 1024,
                aspect_ratio: 4.0 / 3.0,
            },
            timing: SystemTiming {
                fps: 60.0,
                sample_rate: 0.0,
            },
        }
    }

    fn configure_events(&mut self, events: &mut CoreEventConfig<Self>) {
        events.add_keyboard_event_listener(Self::keyboard_event);
    }

    fn on_set_environment(&mut self, env: &mut Environment<'_>) {
        ContentContract::new("bin")
            .with_support_no_game(true)
            .with_persistent_data(true)
            .register_environment(env);
        env.set_variables(&[VariableDefinition::new(
            "testgl_resolution",
            "Internal resolution; 320x240|640x480|1024x768",
        )]);
    }

    fn load_game(
        &mut self,
        _game: Option<libretro::GameInfo<'_>>,
        runtime: &mut Runtime<'_>,
    ) -> bool {
        let mut env = runtime.environment();
        env.set_pixel_format(PixelFormat::Xrgb8888)
            && env
                .set_hw_render_from_candidates(&[
                    HwRenderConfig::opengl()
                        .with_depth(true)
                        .with_stencil(true)
                        .with_bottom_left_origin(true),
                    HwRenderConfig::opengles3()
                        .with_depth(true)
                        .with_stencil(true)
                        .with_bottom_left_origin(true),
                ])
                .is_some()
    }

    fn run(&mut self, runtime: &mut Runtime<'_>) {
        runtime.poll_input();
        if runtime.joypad_pressed(0, JoypadButton::Up) {
            // update state
        }
        runtime.video_refresh_hw(self.width, self.height, 0);
    }

    fn keyboard_event(&mut self, event: KeyboardEvent) {
        if event.down {
            // handle typed keyboard event
        }
    }
}

libretro::export_core!(GlCore::default());