Merge branch 'liffy/api' of ssh://vvn.space:2222/cinnabon/rustro into viv/ffmpeg2

Cargo.toml

@@ -8,15 +8,21 @@ edition = "2018"
 cc = "^1"
 
 [dependencies]
-libretro-sys = "^0.1"
+libretro-sys = "0.1"
-failure = "^0.1"
+libloading = "0.5"
-libloading = "^0.5"
+num_enum = "0.4"
-num_enum = "^0.4"
+ffmpeg-next = { version = "4.3.8", optional = true }
+sdl2 = { version = "0.32", optional = true }
+crossbeam-channel = { version = "0.4", optional = true }
 
 [dev-dependencies]
 # example: sdl2_emulator
-sdl2 = "^0.32"
+sdl2 = "0.32"
-crossbeam-channel = "^0.4"
+crossbeam-channel = "0.4"
-structopt = "^0.3"
+structopt = "0.3"
 # example: ffmpeg_recorder
 ffmpeg-next = "4.3.8"
+
+[features]
+ffmpeg_comp = ["ffmpeg-next"]
+sdl2_comp = ["sdl2", "crossbeam-channel"]

examples/ffmpeg_recorder.rs

@@ -7,11 +7,10 @@ use std::path::{Path, PathBuf};
 use std::pin::Pin;
 
 use structopt::StructOpt;
-use failure::Fallible;
 
 use ferretro::retro;
 use ferretro::retro::ffi::{PixelFormat, GameGeometry, SystemAvInfo, SystemInfo};
-use ferretro::retro::wrapper::{LibretroWrapper, Handler};
+use ferretro::retro::wrapper::{LibretroWrapper, RetroCallbacks};
 
 use ferretro::retro::wrapped_types::{Variable2};
 
@@ -24,6 +23,7 @@ struct MyEmulator {
     av_info: SystemAvInfo,
     audio_buf: Vec<(i16, i16)>,
     video_pixel_format: format::Pixel,
+    prev_video_frame: Option<frame::Video>,
     video_frames: VecDeque<frame::Video>,
     video_encoder: ffmpeg::encoder::Video,
     audio_encoder: ffmpeg::encoder::Audio,
@@ -204,7 +204,7 @@ static bool ffmpeg_init_config(struct ff_config_param *params,
         audio_encoder.set_time_base(Rational::new(1, 60));
         audio_output.set_time_base(Rational::new(1, 60));
 
-        let mut audio_encoder = audio_encoder.open_as(acodec).unwrap();
+        let audio_encoder = audio_encoder.open_as(acodec).unwrap();
         //audio_output.set_parameters(&audio_encoder);
 
         let audio_filter = audio_filter(&audio_encoder, av_info.timing.sample_rate).unwrap();
@@ -220,6 +220,7 @@ static bool ffmpeg_init_config(struct ff_config_param *params,
             av_info: av_info.clone(),
             audio_buf: Default::default(),
             video_pixel_format: format::Pixel::RGB555,
+            prev_video_frame: None,
             video_frames: Default::default(),
             video_encoder,
             audio_encoder,
@@ -234,7 +235,7 @@ static bool ffmpeg_init_config(struct ff_config_param *params,
         let mut pin_emu = Box::pin(emu);
         retro::wrapper::set_handler(pin_emu.as_mut());
         pin_emu.retro.init();
-        pin_emu.set_system_av_info(av_info);
+        pin_emu.set_system_av_info(&av_info);
         pin_emu
     }
     
@@ -357,7 +358,7 @@ static bool ffmpeg_init_config(struct ff_config_param *params,
 
     }
 
-    pub fn load_game(&self, rom: impl AsRef<Path>) {
+    pub fn load_game(&mut self, rom: impl AsRef<Path>) {
         let path = rom.as_ref();
         let mut data = None;
         let mut v = Vec::new();
@@ -380,13 +381,26 @@ static bool ffmpeg_init_config(struct ff_config_param *params,
         self.receive_and_write_packets(EncoderToWriteFrom::Audio);
         self.octx.write_trailer().unwrap();
     }
+
+    pub fn unserialize(&mut self, state: impl AsRef<Path>) -> Result<(), Box<dyn std::error::Error>> {
+        let path = state.as_ref();
+        let mut v = Vec::new();
+        if let Ok(mut f) = std::fs::File::open(path) {
+            if f.read_to_end(&mut v).is_ok(){
+                return self.retro.unserialize(v.as_ref());
+            }
+        }
+        Err("Couldn't read file to unserialize".into())
+    }
 }
 
-impl retro::wrapper::Handler for MyEmulator {
+impl retro::wrapper::LibretroWrapperAccess for MyEmulator {
     fn libretro_core(&mut self) -> &mut LibretroWrapper {
         &mut self.retro
     }
+}
 
+impl retro::wrapper::RetroCallbacks for MyEmulator {
     fn video_refresh(&mut self, data: &[u8], width: u32, height: u32, pitch: u32) {
         let mut vframe = frame::Video::new(self.video_pixel_format, width, height);
 
@@ -409,9 +423,19 @@ impl retro::wrapper::Handler for MyEmulator {
 
         //vframe.set_pts(Some(self.frame as i64));
 
+        self.prev_video_frame.replace(vframe.clone());
         self.video_frames.push_back(vframe);
     }
 
+    fn video_refresh_dupe(&mut self, width: u32, height: u32, _pitch: u32) {
+        if let Some(frame) = &self.prev_video_frame {
+            self.video_frames.push_back(frame.clone());
+        } else {
+            let vframe = frame::Video::new(self.video_pixel_format, width, height);
+            self.video_frames.push_back(vframe);
+        }
+    }
+
     fn audio_sample(&mut self, left: i16, right: i16) {
         self.audio_buf.push((left, right));
     }
@@ -423,15 +447,13 @@ impl retro::wrapper::Handler for MyEmulator {
         stereo_pcm.len()
     }
 
-    fn get_can_dupe(&mut self) -> Option<bool> { Some(false) }
-
     fn get_system_directory(&mut self) -> Option<PathBuf> {
         self.sys_path.clone()
     }
 
-    fn set_pixel_format(&mut self, format: PixelFormat) -> bool {
+    fn set_pixel_format(&mut self, format: PixelFormat) -> Option<bool> {
         if self.frame_properties_locked {
-            return true;
+            return Some(true);
         }
 
         self.video_pixel_format = match format {
@@ -440,12 +462,12 @@ impl retro::wrapper::Handler for MyEmulator {
             PixelFormat::RGB565 => format::Pixel::RGB565,
         };
         self.video_filter = video_filter(&self.video_encoder, &self.av_info, format).unwrap();
-        true
+        Some(true)
     }
 
-    fn set_system_av_info(&mut self, system_av_info: SystemAvInfo) -> bool {
+    fn set_system_av_info(&mut self, system_av_info: &SystemAvInfo) -> Option<bool> {
         if self.frame_properties_locked {
-            return true;
+            return Some(true);
         }
 
         //self.video_encoder.set_frame_rate(system_av_info.timing.fps.into());
@@ -454,20 +476,20 @@ impl retro::wrapper::Handler for MyEmulator {
         if system_av_info.timing.sample_rate.round() as i32 > 0 {
             self.audio_encoder.set_rate(system_av_info.timing.sample_rate.round() as i32);
         }
-        self.av_info.timing = system_av_info.timing;
+        self.av_info.timing = system_av_info.timing.clone();
-        self.set_geometry(system_av_info.geometry);
+        self.set_geometry(&system_av_info.geometry);
-        true
+        Some(true)
     }
 
-    fn set_geometry(&mut self, geometry: GameGeometry) -> bool {
+    fn set_geometry(&mut self, geometry: &GameGeometry) -> Option<bool> {
         if self.frame_properties_locked {
-            return true;
+            return Some(true);
         }
 
         self.video_encoder.set_width(geometry.base_width);
         self.video_encoder.set_height(geometry.base_height);
         //self.video_encoder.set_aspect_ratio(geometry.aspect_ratio as f64);
-        self.av_info.geometry = geometry;
+        self.av_info.geometry = geometry.clone();
         let pixel_format = match self.video_pixel_format {
             format::Pixel::RGB555 => PixelFormat::ARGB1555,
             format::Pixel::RGB32 => PixelFormat::ARGB8888,
@@ -475,7 +497,7 @@ impl retro::wrapper::Handler for MyEmulator {
             _ => unimplemented!(),
         };
         self.video_filter = video_filter(&self.video_encoder, &self.av_info, pixel_format).unwrap();
-        true
+        Some(true)
     }
 
 
@@ -488,11 +510,11 @@ impl retro::wrapper::Handler for MyEmulator {
         }
     }
 
-    fn set_variables(&mut self, variables: Vec<Variable2>) -> bool {
+    fn set_variables(&mut self, variables: &Vec<Variable2>) -> Option<bool> {
         for v in variables {
             eprintln!("{:?}", v);
         }
-        true
+        Some(true)
     }
 
     fn log_print(&mut self, level: retro::ffi::LogLevel, msg: &str) {
@@ -511,12 +533,15 @@ struct Opt {
     /// Recorded video to write.
     #[structopt(short, long, parse(from_os_str))]
     video: PathBuf,
+    /// Save state to load at startup.
+    #[structopt(long, parse(from_os_str))]
+    state: Option<PathBuf>,
     /// System directory, often containing BIOS files
     #[structopt(short, long, parse(from_os_str))]
     system: Option<PathBuf>,
 }
 
-fn main() -> Fallible<()> {
+fn main() -> Result<(), Box<dyn std::error::Error>> {
     let opt: Opt = Opt::from_args();
     ffmpeg::log::set_level(ffmpeg::log::Level::Trace);
     ffmpeg::init().unwrap();
@@ -535,6 +560,10 @@ fn main() -> Fallible<()> {
 
     emu.frame_properties_locked = true;
 
+    if let Some(state) = opt.state {
+        emu.unserialize(state)?;
+    }
+
     //for frame in 0..60*10 {
     for frame in 0..800 {
         eprintln!("🖼️ frame: {}", frame);
@@ -542,7 +571,7 @@ fn main() -> Fallible<()> {
 
     }
     let mut packet = Packet::empty();
-    eprintln!("flushed: {:?}", emu.video_encoder.flush(&mut packet).unwrap());
+    eprintln!("flushed: {:?}", emu.video_encoder.flush(&mut packet)?);
 
     emu.end();
     //octx.write_trailer().unwrap();

examples/multifunction_emulator.rs

@@ -0,0 +1,66 @@
+extern crate crossbeam_channel;
+extern crate ferretro;
+extern crate ffmpeg_next as ffmpeg;
+extern crate sdl2;
+
+use std::path::PathBuf;
+use structopt::StructOpt;
+
+use ferretro::prelude::*;
+
+use ferretro::components::provided::{
+    ffmpeg::FfmpegComponent,
+    sdl2::Sdl2Component,
+    stdlib::{PathBufComponent, StderrLogComponent},
+};
+use ferretro::components::ControlFlow;
+use ferretro::components::provided::stdlib::StderrSysInfoLogComponent;
+
+#[derive(StructOpt)]
+struct Opt {
+    /// Core module to use.
+    #[structopt(short, long, parse(from_os_str))]
+    core: PathBuf,
+    /// ROM to load using the core.
+    #[structopt(short, long, parse(from_os_str))]
+    rom: PathBuf,
+    /// Save state to load at startup.
+    #[structopt(long, parse(from_os_str))]
+    state: Option<PathBuf>,
+    /// System directory, often containing BIOS files
+    #[structopt(short, long, parse(from_os_str))]
+    system: Option<PathBuf>,
+    /// Recorded video to write.
+    #[structopt(short, long, parse(from_os_str))]
+    video: Option<PathBuf>,
+}
+
+pub fn main() {
+    let opt: Opt = Opt::from_args();
+    let mut emu = RetroComponentBase::new(&opt.core);
+    let sdl2_comp = Sdl2Component::new(emu.libretro_core());
+    emu.register_component(sdl2_comp);
+    emu.register_component(StderrLogComponent::default());
+    emu.register_component(StderrSysInfoLogComponent::default());
+    emu.register_component(PathBufComponent {
+        sys_path: opt.system.clone(),
+        libretro_path: Some(opt.core.to_path_buf()),
+        core_assets_path: None,
+        save_path: Some(std::env::temp_dir()),
+    });
+    if let Some(video) = opt.video {
+        ffmpeg::log::set_level(ffmpeg::log::Level::Info);
+        ffmpeg::init().unwrap();
+        let ffmpeg_comp = FfmpegComponent::new(emu.libretro_core(), video);
+        emu.register_component(ffmpeg_comp);
+    }
+    emu.load_game(&opt.rom).unwrap();
+    if let Some(state) = opt.state {
+        emu.unserialize_path(state).unwrap();
+    }
+    let mut frame = 0;
+    while let ControlFlow::Continue = emu.run() {
+        frame += 1;
+    }
+    eprintln!("Ran for {} frames.", frame);
+}

examples/sdl2_emulator.rs

@@ -135,7 +135,7 @@ impl MyEmulator {
         pin_emu
     }
 
-    pub fn run(&mut self) {
+    pub fn run_loop(&mut self) {
         self.audio_device.resume();
         let mut event_pump = self.sdl_context.event_pump().unwrap();
         'running: loop {
@@ -167,7 +167,7 @@ impl MyEmulator {
         }
     }
 
-    pub fn load_game(&self, rom: impl AsRef<Path>) {
+    pub fn load_game(&mut self, rom: impl AsRef<Path>) {
         let path = rom.as_ref();
         let mut data = None;
         let mut v = Vec::new();
@@ -204,11 +204,13 @@ impl Drop for MyEmulator {
     }
 }
 
-impl retro::wrapper::Handler for MyEmulator {
+impl retro::wrapper::LibretroWrapperAccess for MyEmulator {
     fn libretro_core(&mut self) -> &mut LibretroWrapper {
         &mut self.retro
     }
+}
 
+impl retro::wrapper::RetroCallbacks for MyEmulator {
     fn video_refresh(&mut self, data: &[u8], width: u32, height: u32, pitch: u32) {
         let rect = Rect::new(0, 0, width, height);
 
@@ -262,19 +264,17 @@ impl retro::wrapper::Handler for MyEmulator {
         }
     }
 
-    fn get_can_dupe(&mut self) -> Option<bool> { Some(true) }
-
     fn get_system_directory(&mut self) -> Option<PathBuf> {
         self.sys_path.clone()
     }
 
-    fn set_pixel_format(&mut self, pix_fmt: retro::ffi::PixelFormat) -> bool {
+    fn set_pixel_format(&mut self, pix_fmt: retro::ffi::PixelFormat) -> Option<bool> {
         self.pixel_format = match pix_fmt {
             retro::ffi::PixelFormat::ARGB1555 => sdl2::pixels::PixelFormatEnum::RGB555,
             retro::ffi::PixelFormat::ARGB8888 => sdl2::pixels::PixelFormatEnum::ARGB8888,
             retro::ffi::PixelFormat::RGB565 => sdl2::pixels::PixelFormatEnum::RGB565,
         };
-        true
+        Some(true)
     }
     fn get_variable(&mut self, key: &str) -> Option<String> {
         match key {
@@ -285,11 +285,11 @@ impl retro::wrapper::Handler for MyEmulator {
         }
     }
 
-    fn set_variables(&mut self, variables: Vec<Variable2>) -> bool {
+    fn set_variables(&mut self, variables: &Vec<Variable2>) -> Option<bool> {
         for v in variables {
             eprintln!("{:?}", v);
         }
-        true
+        Some(true)
     }
 
     fn get_libretro_path(&mut self) -> Option<PathBuf> {
@@ -305,18 +305,18 @@ impl retro::wrapper::Handler for MyEmulator {
         Some(std::env::temp_dir())
     }
 
-    fn set_system_av_info(&mut self, av_info: SystemAvInfo) -> bool {
+    fn set_system_av_info(&mut self, av_info: &SystemAvInfo) -> Option<bool> {
-        self.set_geometry(av_info.geometry.clone());
+        self.set_geometry(&av_info.geometry);
-        self.av_info = av_info;
+        self.av_info = av_info.clone();
-        true
+        Some(true)
     }
 
-    fn set_subsystem_info(&mut self, subsystem_info: Vec<SubsystemInfo2>) -> bool {
+    fn set_subsystem_info(&mut self, subsystem_info: &Vec<SubsystemInfo2>) -> Option<bool> {
         println!("subsystem info: {:?}", subsystem_info);
-        true
+        Some(true)
     }
 
-    fn set_controller_info(&mut self, controller_info: Vec<ControllerDescription2>) -> bool {
+    fn set_controller_info(&mut self, controller_info: &Vec<ControllerDescription2>) -> Option<bool> {
         for ci in controller_info {
             // so we can have analog support in beetle/mednafen saturn
             if ci.name.as_str() == "3D Control Pad" {
@@ -324,21 +324,21 @@ impl retro::wrapper::Handler for MyEmulator {
                 break;
             }
         }
-        true
+        Some(true)
     }
 
-    fn set_input_descriptors(&mut self, descriptors: Vec<InputDescriptor2>) -> bool {
+    fn set_input_descriptors(&mut self, descriptors: &Vec<InputDescriptor2>) -> Option<bool> {
         for id in descriptors {
             println!("{:?}", id);
         }
-        true
+        Some(true)
     }
 
-    fn set_geometry(&mut self, geom: GameGeometry) -> bool {
+    fn set_geometry(&mut self, geom: &GameGeometry) -> Option<bool> {
         let _ = self.canvas.window_mut().set_size(geom.base_width, geom.base_height);
         let _ = self.canvas.set_logical_size(geom.base_width, geom.base_height);
-        self.av_info.geometry = geom;
+        self.av_info.geometry = geom.clone();
-        true
+        Some(true)
     }
 
     fn log_print(&mut self, level: retro::ffi::LogLevel, msg: &str) {
@@ -363,13 +363,11 @@ impl AudioCallback for MySdlAudio {
     }
 }
 
-pub fn main() -> failure::Fallible<()> {
+pub fn main() {
     let opt: Opt = Opt::from_args();
     let mut emu = MyEmulator::new(&opt.core, &opt.system);
     emu.load_game(&opt.rom);
-    emu.run();
+    emu.run_loop();
-
-    Ok(())
 }
 
 #[derive(StructOpt)]

src/components/mod.rs

@@ -0,0 +1,502 @@
+pub mod provided;
+
+use crate::prelude::*;
+use crate::retro::ffi::*;
+use std::os::raw::c_uint;
+use std::path::{PathBuf, Path};
+use std::pin::Pin;
+use std::io::Read;
+
+pub struct RetroComponentBase {
+    retro: LibretroWrapper,
+    libretro_path: PathBuf,
+    // TODO: control when things get added to this.
+    //  probably shouldn't be after load_game?
+    //  unless we invent a way to play back the latest set_pixel_format etc. metadata required.
+    components: Vec<Box<dyn RetroComponent>>,
+
+    // replaying env calls for late-added components
+    cached_rom_path: Option<PathBuf>,
+    cached_pixel_format: Option<PixelFormat>,
+    cached_input_descriptors: Option<Vec<InputDescriptor2>>,
+    cached_hw_render_callback: Option<HwRenderCallback>,
+    cached_variables: Option<Vec<Variable2>>,
+    cached_support_no_game: Option<bool>,
+    cached_system_av_info: Option<SystemAvInfo>,
+    cached_subsystem_info: Option<Vec<SubsystemInfo2>>,
+    cached_controller_info: Option<Vec<ControllerDescription2>>,
+    cached_memory_map: Option<MemoryMap>,
+    cached_geometry: Option<GameGeometry>,
+}
+
+// TODO: replace with std::ops::ControlFlow when it becomes stable
+pub enum ControlFlow {
+    Continue,
+    Break,
+}
+
+pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+
+#[rustfmt::skip]
+#[allow(unused_variables)]
+pub trait RetroComponent: RetroCallbacks {
+    fn pre_run(&mut self, retro: &mut LibretroWrapper) -> ControlFlow { ControlFlow::Continue }
+    fn post_run(&mut self, retro: &mut LibretroWrapper) -> ControlFlow { ControlFlow::Continue }
+    fn pre_load_game(&mut self, retro: &mut LibretroWrapper, rom: &Path) -> Result<()> { Ok(()) }
+    fn post_load_game(&mut self, retro: &mut LibretroWrapper, rom: &Path) -> Result<()> { Ok(()) }
+}
+
+impl RetroComponentBase {
+    // TODO: constructor & wrapper that uses a statically linked libretro?
+    pub fn new(core_path: impl AsRef<Path>) -> Pin<Box<Self>> {
+        let lib = libloading::Library::new(core_path.as_ref()).unwrap();
+        let raw_retro = crate::retro::loading::LibretroApi::from_library(lib).unwrap();
+        let retro = LibretroWrapper::from(raw_retro);
+
+        let emu = RetroComponentBase {
+            retro,
+            libretro_path: core_path.as_ref().to_path_buf(),
+            components: Vec::new(),
+            cached_rom_path: None,
+            cached_pixel_format: None,
+            cached_input_descriptors: None,
+            cached_hw_render_callback: None,
+            cached_variables: None,
+            cached_support_no_game: None,
+            cached_system_av_info: None,
+            cached_subsystem_info: None,
+            cached_controller_info: None,
+            cached_memory_map: None,
+            cached_geometry: None
+        };
+
+        let mut pin_emu = Box::pin(emu);
+        crate::retro::wrapper::set_handler(pin_emu.as_mut());
+        pin_emu.retro.init();
+        pin_emu
+    }
+
+    pub fn register_component<T>(&mut self, comp: T) -> Option<()> // TODO: Result
+        where T: RetroComponent
+    {
+        // TODO: match comp.schedule { BeforeInit, BeforeLoad, BeforeFirstRun, Anytime }
+        let mut comp = Box::new(comp);
+        if let Some(cached) = &self.cached_pixel_format {
+            if let Some(false) = comp.set_pixel_format(*cached) {
+                // TODO: error, and propagate this pattern downward
+            }
+        }
+        if let Some(cached) = &self.cached_input_descriptors {
+            comp.set_input_descriptors(cached);
+        }
+        if let Some(cached) = &self.cached_hw_render_callback {
+            comp.set_hw_render(cached);
+        }
+        if let Some(cached) = &self.cached_variables {
+            comp.set_variables(cached);
+        }
+        if let Some(cached) = &self.cached_support_no_game {
+            comp.set_support_no_game(*cached);
+        }
+        if let Some(cached) = &self.cached_system_av_info {
+            comp.set_system_av_info(cached);
+        }
+        if let Some(cached) = &self.cached_subsystem_info {
+            comp.set_subsystem_info(cached);
+        }
+        if let Some(cached) = &self.cached_controller_info {
+            comp.set_controller_info(cached);
+        }
+        if let Some(cached) = &self.cached_memory_map {
+            comp.set_memory_maps(cached);
+        }
+        if let Some(cached) = &self.cached_geometry {
+            comp.set_geometry(cached);
+        }
+
+        if let Some(cached) = &self.cached_rom_path {
+            comp.post_load_game(&mut self.retro, &cached);
+        }
+
+        self.components.push(comp);
+
+        Some(())
+    }
+
+    pub fn load_game(&mut self, rom: impl AsRef<Path>) -> Result<()> {
+        let path = rom.as_ref();
+        self.cached_rom_path = Some(path.to_path_buf());
+
+        for comp in &mut self.components {
+            comp.pre_load_game(&mut self.retro, path)?;
+        }
+
+        let mut data = None;
+        let mut v = Vec::new();
+        if !self.retro.get_system_info().need_fullpath {
+            if let Ok(mut f) = std::fs::File::open(path) {
+                if f.read_to_end(&mut v).is_ok() {
+                    data = Some(v.as_ref());
+                }
+            }
+        }
+        self.retro.load_game(Some(path), data, None)?;
+
+        for comp in &mut self.components {
+            comp.post_load_game(&mut self.retro, path)?;
+        }
+
+        Ok(())
+    }
+
+    pub fn run(&mut self) -> ControlFlow {
+        for comp in &mut self.components {
+            if let ControlFlow::Break = comp.pre_run(&mut self.retro) {
+                return ControlFlow::Break;
+            }
+        }
+        self.retro.run();
+        for comp in &mut self.components {
+            if let ControlFlow::Break = comp.post_run(&mut self.retro) {
+                return ControlFlow::Break;
+            }
+        }
+        ControlFlow::Continue
+    }
+
+    pub fn unserialize_path(&mut self, state: impl AsRef<Path>) -> Result<()> {
+        let path = state.as_ref();
+        let mut v = Vec::new();
+        if let Ok(mut f) = std::fs::File::open(path) {
+            if f.read_to_end(&mut v).is_ok(){
+                return self.unserialize_buf(v);
+            }
+        }
+        Err("Couldn't read file to unserialize".into())
+    }
+
+    pub fn unserialize_buf(&mut self, data: impl AsRef<[u8]>) -> Result<()> {
+        self.retro.unserialize(data.as_ref())
+    }
+}
+
+impl LibretroWrapperAccess for RetroComponentBase {
+    fn libretro_core(&mut self) -> &mut LibretroWrapper {
+        &mut self.retro
+    }
+}
+
+impl RetroCallbacks for RetroComponentBase {
+    fn video_refresh(&mut self, data: &[u8], width: c_uint, height: c_uint, pitch: c_uint) {
+        for comp in &mut self.components {
+            comp.video_refresh(data, width, height, pitch);
+        }
+    }
+
+    fn video_refresh_dupe(&mut self, width: c_uint, height: c_uint, pitch: c_uint) {
+        for comp in &mut self.components {
+            comp.video_refresh_dupe(width, height, pitch);
+        }
+    }
+
+    fn audio_sample(&mut self, left: i16, right: i16) {
+        for comp in &mut self.components {
+            comp.audio_sample(left, right);
+        }
+    }
+
+    fn audio_sample_batch(&mut self, stereo_pcm: &[i16]) -> usize {
+        self.components.iter_mut()
+            .map(|comp| comp.audio_sample_batch(stereo_pcm))
+            .max()
+            .unwrap_or_default()
+    }
+
+    fn input_poll(&mut self) {
+        for comp in &mut self.components {
+            comp.input_poll();
+        }
+    }
+
+    fn input_state(&mut self, port: u32, device: InputDeviceId, index: InputIndex) -> i16 {
+        self.components.iter_mut()
+            .map(|comp| comp.input_state(port, device, index))
+            .filter(|x| *x != 0)
+            // TODO: is this really the semantic we want?
+            .last()
+            .unwrap_or_default()
+    }
+
+    fn set_rotation(&mut self, rotation: EnvRotation) -> Option<bool> {
+        self.components.iter_mut()
+            .map(|comp| comp.set_rotation(rotation))
+            .flatten()
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+            .into()
+    }
+
+    fn get_overscan(&mut self) -> Option<bool> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_overscan())
+            .fold(None, |x, y| match (x, y) {
+                (Some(a), Some(b)) => Some(a || b),
+                (Some(a), None) | (None, Some(a)) => Some(a),
+                (None, None) => None,
+            })
+    }
+
+    fn set_message(&mut self, message: &Message) -> Option<bool> {
+        self.components.iter_mut()
+            .map(|comp| comp.set_message(message))
+            .flatten()
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+            .into()
+    }
+
+    fn shutdown(&mut self) -> Option<bool> {
+        self.components.iter_mut()
+            .map(|comp| comp.shutdown())
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    fn set_performance_level(&mut self, level: c_uint) -> Option<bool> {
+        self.components.iter_mut()
+            .map(|comp| comp.set_performance_level(level))
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    fn get_system_directory(&mut self) -> Option<PathBuf> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_system_directory())
+            .flatten()
+            .next()
+    }
+
+    fn set_pixel_format(&mut self, format: PixelFormat) -> Option<bool> {
+        self.cached_pixel_format = Some(format);
+        self.components.iter_mut()
+            .map(|comp| comp.set_pixel_format(format))
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    fn set_input_descriptors(&mut self, input_descriptors: &Vec<InputDescriptor2>) -> Option<bool> {
+        self.cached_input_descriptors = Some(input_descriptors.to_vec());
+        self.components.iter_mut()
+            .map(|comp| comp.set_input_descriptors(input_descriptors))
+            .flatten()
+            .fold(false, |x, y| x || y)
+            .into()
+    }
+
+    fn set_hw_render(&mut self, hw_render_callback: &HwRenderCallback) -> Option<bool> {
+        self.cached_hw_render_callback = Some(hw_render_callback.to_owned());
+        self.components.iter_mut()
+            .map(|comp| comp.set_hw_render(hw_render_callback))
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    fn get_variable(&mut self, key: &str) -> Option<String> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_variable(key))
+            .flatten()
+            .next()
+    }
+
+    fn set_variables(&mut self, variables: &Vec<Variable2>) -> Option<bool> {
+        self.cached_variables = Some(variables.to_vec());
+        self.components.iter_mut()
+            .map(|comp| comp.set_variables(variables))
+            .flatten()
+            .fold(false, |x, y| x || y)
+            .into()
+    }
+
+    fn get_variable_update(&mut self) -> Option<bool> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_variable_update())
+            .flatten()
+            .reduce(|x, y| x || y)
+    }
+
+    fn set_support_no_game(&mut self, supports_no_game: bool) -> Option<bool> {
+        self.cached_support_no_game = Some(supports_no_game);
+        self.components.iter_mut()
+            .map(|comp| comp.set_support_no_game(supports_no_game))
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    // allow it to be overridden, but we *do* have the answer at this level since we loaded it.
+    fn get_libretro_path(&mut self) -> Option<PathBuf> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_libretro_path())
+            .flatten()
+            .next()
+            .unwrap_or_else(|| self.libretro_path.clone())
+            .into()
+    }
+
+    fn get_input_device_capabilities(&mut self) -> Option<u64> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_input_device_capabilities())
+            .flatten()
+            .reduce(|x, y| x & y)
+    }
+
+    fn get_core_assets_directory(&mut self) -> Option<PathBuf> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_core_assets_directory())
+            .flatten()
+            .next()
+    }
+
+    fn get_save_directory(&mut self) -> Option<PathBuf> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_save_directory())
+            .flatten()
+            .next()
+    }
+
+    fn set_system_av_info(&mut self, system_av_info: &SystemAvInfo) -> Option<bool> {
+        self.cached_system_av_info = Some(system_av_info.to_owned());
+        self.cached_geometry = Some(system_av_info.geometry.clone());
+        self.components.iter_mut()
+            .map(|comp| comp.set_system_av_info(system_av_info))
+            .flatten()
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+            .into()
+    }
+
+    fn set_subsystem_info(&mut self, subsystem_info: &Vec<SubsystemInfo2>) -> Option<bool> {
+        self.cached_subsystem_info = Some(subsystem_info.to_vec());
+        self.components.iter_mut()
+            .map(|comp| comp.set_subsystem_info(subsystem_info))
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    fn set_controller_info(&mut self, controller_info: &Vec<ControllerDescription2>) -> Option<bool> {
+        self.cached_controller_info = Some(controller_info.to_vec());
+        self.components.iter_mut()
+            .map(|comp| comp.set_controller_info(controller_info))
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    fn set_memory_maps(&mut self, memory_map: &MemoryMap) -> Option<bool> {
+        self.cached_memory_map = Some(memory_map.to_owned());
+        self.components.iter_mut()
+            .map(|comp| comp.set_memory_maps(memory_map))
+            .flatten()
+            .all(|x| x)
+            .into()
+    }
+
+    fn set_geometry(&mut self, game_geometry: &GameGeometry) -> Option<bool> {
+        self.cached_geometry = Some(game_geometry.to_owned());
+        self.components.iter_mut()
+            .map(|comp| comp.set_geometry(game_geometry))
+            .flatten()
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+            .into()
+    }
+
+    fn get_username(&mut self) -> Option<String> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_username())
+            .flatten()
+            .next()
+    }
+
+    fn get_language(&mut self) -> Option<Language> {
+        self.components.iter_mut()
+            .map(|comp| comp.get_language())
+            .flatten()
+            .next()
+    }
+
+    fn log_print(&mut self, level: LogLevel, msg: &str) {
+        for comp in &mut self.components {
+            comp.log_print(level, msg);
+        }
+    }
+
+    fn set_rumble_state(&mut self, port: c_uint, effect: RumbleEffect, strength: u16) -> bool {
+        self.components.iter_mut()
+            .map(|comp| comp.set_rumble_state(port, effect, strength))
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+    }
+
+    fn perf_get_time_usec_cb(&mut self) -> Time {
+        self.components.first_mut()
+            .map(|comp| comp.perf_get_time_usec_cb())
+            .unwrap_or_default()
+    }
+
+    fn perf_get_counter_cb(&mut self) -> PerfTick {
+        self.components.first_mut()
+            .map(|comp| comp.perf_get_counter_cb())
+            .unwrap_or_default()
+    }
+
+    fn perf_get_cpu_features_cb(&mut self) -> u64 {
+        self.components.first_mut()
+            .map(|comp| comp.perf_get_cpu_features_cb())
+            .unwrap_or_default()
+    }
+
+    fn perf_log_cb(&mut self) {
+         if let Some(comp) = self.components.first_mut() {
+             comp.perf_log_cb()
+         }
+    }
+
+    fn perf_register_cb(&mut self, counter: &mut PerfCounter) {
+         if let Some(comp) = self.components.first_mut() {
+             comp.perf_register_cb(counter)
+         }
+    }
+
+    fn perf_start_cb(&mut self, counter: &mut PerfCounter) {
+         if let Some(comp) = self.components.first_mut() {
+             comp.perf_start_cb(counter)
+         }
+    }
+
+    fn perf_stop_cb(&mut self, counter: &mut PerfCounter) {
+         if let Some(comp) = self.components.first_mut() {
+             comp.perf_stop_cb(counter)
+         }
+    }
+
+    fn set_sensor_state(&mut self, port: c_uint, action: SensorAction, rate: c_uint) -> bool {
+        self.components.iter_mut()
+            .map(|comp| comp.set_sensor_state(port, action, rate))
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+    }
+
+    fn get_sensor_input(&mut self, port: c_uint, id: c_uint) -> f32 {
+        self.components.iter_mut()
+            .map(|comp| comp.get_sensor_input(port, id))
+            .filter(|x| *x != 0.0)
+            .last()
+            .unwrap_or_default()
+    }
+}
+
+impl Drop for RetroComponentBase {
+    fn drop(&mut self) {
+        crate::retro::wrapper::unset_handler();
+    }
+}

src/components/provided/ffmpeg.rs

@@ -0,0 +1,473 @@
+extern crate ffmpeg_next as ffmpeg;
+
+use std::collections::VecDeque;
+use std::error::Error;
+use std::path::Path;
+
+use crate::prelude::*;
+
+use ffmpeg::{ChannelLayout, Packet, filter, format, frame, media};
+use ffmpeg::util::rational::Rational;
+use crate::components::ControlFlow;
+
+enum EncoderToWriteFrom {
+    Video,
+    Audio,
+}
+
+pub struct FfmpegComponent {
+    av_info: SystemAvInfo,
+    audio_buf: Vec<(i16, i16)>,
+    video_pixel_format: format::Pixel,
+    prev_video_frame: Option<frame::Video>,
+    video_frames: VecDeque<frame::Video>,
+    video_encoder: ffmpeg::encoder::Video,
+    audio_encoder: ffmpeg::encoder::Audio,
+    video_filter: filter::Graph,
+    audio_filter: filter::Graph,
+    frame_properties_locked: bool,
+    octx: ffmpeg::format::context::Output,
+    frame: i64,
+}
+
+fn video_filter(
+    video_encoder: &ffmpeg::encoder::video::Video,
+    av_info: &SystemAvInfo,
+    pix_fmt: PixelFormat,
+) -> Result<filter::Graph, ffmpeg::Error> {
+    let mut vfilter = filter::Graph::new();
+    let pix_fmt = match pix_fmt {
+        PixelFormat::ARGB1555 => if cfg!(target_endian = "big") { "rgb555be" } else { "rgb555le" },
+        PixelFormat::ARGB8888 => "argb",
+        PixelFormat::RGB565 => if cfg!(target_endian = "big") { "rgb565be" } else { "rgb565le" },
+    };
+    let pixel_aspect = av_info.geometry.aspect_ratio / (av_info.geometry.base_width as f32 / av_info.geometry.base_height as f32);
+    let fps = if av_info.timing.fps == 0.0 { 60.0 } else { av_info.timing.fps };
+    let args = format!(
+        "width={}:height={}:pix_fmt={}:frame_rate={}:pixel_aspect={}:time_base=1/{}",
+        av_info.geometry.base_width,
+        av_info.geometry.base_height,
+        pix_fmt,
+        fps,
+        pixel_aspect,
+        fps,
+    );
+    eprintln!("🎥 filter args: {}", args);
+    vfilter.add(&filter::find("buffer").unwrap(), "in", &args)?;
+    //scale?
+    vfilter.add(&filter::find("buffersink").unwrap(), "out", "")?;
+
+    {
+        let mut out = vfilter.get("out").unwrap();
+        out.set_pixel_format(video_encoder.format());
+    }
+
+    vfilter.output("in", 0)?
+        .input("out", 0)?
+        .parse("null")?; // passthrough filter for video
+
+    vfilter.validate()?;
+    // human-readable filter graph
+    eprintln!("{}", vfilter.dump());
+
+    Ok(vfilter)
+}
+
+fn audio_filter(
+    audio_encoder: &ffmpeg::codec::encoder::Audio,
+    sample_rate: f64,
+) -> Result<filter::Graph, ffmpeg::Error> {
+    let mut afilter = filter::Graph::new();
+    let sample_rate = if sample_rate == 0.0 { 32040.0 } else { sample_rate };
+    let args = format!("sample_rate={}:sample_fmt=s16:channel_layout=stereo:time_base=1/60", sample_rate);
+    eprintln!("🔊 filter args: {}", args);
+    afilter.add(&filter::find("abuffer").unwrap(), "in", &args)?;
+    //aresample?
+    afilter.add(&filter::find("abuffersink").unwrap(), "out", "")?;
+
+    {
+        let mut out = afilter.get("out").unwrap();
+        out.set_sample_format(audio_encoder.format());
+        out.set_channel_layout(audio_encoder.channel_layout());
+        out.set_sample_rate(audio_encoder.rate());
+    }
+
+    afilter.output("in", 0)?
+        .input("out", 0)?
+        .parse("anull")?;
+    afilter.validate()?;
+    // human-readable filter graph
+    eprintln!("{}", afilter.dump());
+
+    if let Some(codec) = audio_encoder.codec() {
+        if !codec
+            .capabilities()
+            .contains(ffmpeg::codec::capabilities::Capabilities::VARIABLE_FRAME_SIZE)
+        {
+            eprintln!("setting constant frame size {}", audio_encoder.frame_size());
+            afilter
+                .get("out")
+                .unwrap()
+                .sink()
+                .set_frame_size(audio_encoder.frame_size());
+        }
+    }
+
+    Ok(afilter)
+}
+
+impl RetroComponent for FfmpegComponent {
+    fn pre_run(&mut self, _retro: &mut LibretroWrapper) -> ControlFlow {
+        self.frame += 1;
+        ControlFlow::Continue
+    }
+
+    fn post_run(&mut self, _retro: &mut LibretroWrapper) -> ControlFlow {
+        match self.video_frames.pop_front() {
+            Some(mut vframe) => {
+                vframe.set_pts(Some(self.frame));
+                eprintln!("🎞 queue frame pts {:?}", vframe.pts());
+                self.video_filter.get("in").unwrap().source().add(&vframe).unwrap();
+                let mut filtered_vframe = frame::Video::empty();
+
+                loop {
+                    match self.video_filter.get("out").unwrap().sink().frame(&mut filtered_vframe) {
+                        Ok(..) => {
+                            eprintln!("🎥 Got filtered video frame {}x{} pts {:?}", filtered_vframe.width(), filtered_vframe.height(), filtered_vframe.pts());
+                            if self.video_filter.get("in").unwrap().source().failed_requests() > 0 {
+                                println!("🎥 failed to put filter input frame");
+                            }
+                            //filtered_vframe.set_pts(Some(frame));
+                            self.video_encoder.send_frame(&filtered_vframe).unwrap();
+
+                            self.receive_and_write_packets(EncoderToWriteFrom::Video);
+                        },
+                        Err(e) => {
+                            eprintln!("Error getting filtered video frame: {:?}", e);
+                            break;
+                        }
+                    }
+                }
+
+                let mut aframe = frame::Audio::new(
+                    format::Sample::I16(format::sample::Type::Packed),
+                    self.audio_buf.len(),
+                    ChannelLayout::STEREO
+                );
+                if aframe.planes() > 0 {
+                    aframe.set_channels(2);
+                    aframe.set_rate(44100);
+                    aframe.set_pts(Some(self.frame));
+                    let aplane: &mut [(i16, i16)] = aframe.plane_mut(0);
+                    eprintln!("Audio buffer length {} -> {}", self.audio_buf.len(), aplane.len());
+                    aplane.copy_from_slice(self.audio_buf.as_ref());
+                    //eprintln!("src: {:?}, dest: {:?}", self.audio_buf, aplane);
+                    self.audio_buf.clear();
+
+                    eprintln!("frame audio: {:?}", aframe);
+
+                    eprintln!("🎞 queue frame pts {:?}", aframe.pts());
+                    self.audio_filter.get("in").unwrap().source().add(&aframe).unwrap();
+
+                    let mut filtered_aframe = frame::Audio::empty();
+                    loop {
+                        match self.audio_filter.get("out").unwrap().sink().frame(&mut filtered_aframe) {
+                            Ok(..) => {
+                                eprintln!("🔊 Got filtered audio frame {:?} pts {:?}", filtered_aframe, filtered_aframe.pts());
+                                if self.audio_filter.get("in").unwrap().source().failed_requests() > 0 {
+                                    println!("🎥 failed to put filter input frame");
+                                }
+                                //let faplane: &[f32] = filtered_aframe.plane(0);
+                                //filtered_aframe.set_pts(Some(frame));
+
+                                self.audio_encoder.send_frame(&filtered_aframe).unwrap();
+                                self.receive_and_write_packets(EncoderToWriteFrom::Audio);
+                            },
+                            Err(e) => {
+                                eprintln!("Error getting filtered audio frame: {:?}", e);
+                                break;
+                            }
+                        }
+                    }
+                }
+            },
+            None => println!("Video not ready during frame {}", self.frame)
+        }
+        ControlFlow::Continue
+    }
+
+    fn post_load_game(&mut self, _retro: &mut LibretroWrapper, _rom: &Path) -> Result<(), Box<dyn Error>> {
+        self.frame_properties_locked = true;
+        Ok(())
+    }
+}
+
+impl FfmpegComponent {
+    pub fn new(
+        retro: &LibretroWrapper,
+        video_path: impl AsRef<Path>,
+    ) -> Self {
+        let mut octx = format::output(&video_path).unwrap();
+
+        let mut av_info = retro.get_system_av_info();
+
+        let fps_int = av_info.timing.fps.round() as i32;
+        let fps_int = if fps_int == 0 { 60 } else { fps_int };
+
+        let detected_vcodec = octx.format().codec(&video_path, media::Type::Video);
+        //let detected_acodec = octx.format().codec(&video_path, media::Type::Audio);
+let wavname  = Path::new("out.wav");
+        let detected_acodec = octx.format().codec(&wavname, media::Type::Audio);
+
+        let vcodec = ffmpeg::encoder::find(detected_vcodec).unwrap().video().unwrap();
+        let acodec = ffmpeg::encoder::find(detected_acodec).unwrap().audio().unwrap();
+
+        let mut video_output = octx.add_stream(vcodec).unwrap();
+        video_output.set_time_base(Rational::new(1, 60));
+        let mut video_encoder = video_output.codec().encoder().video().unwrap();
+
+        video_encoder.set_bit_rate(2560000);
+        video_encoder.set_format(video_encoder.codec().unwrap().video().unwrap().formats().unwrap().nth(0).unwrap());
+
+        video_encoder.set_time_base(Rational::new(1, 60));
+        video_encoder.set_frame_rate(Some(Rational::new(fps_int, 1)));
+
+        //video_encoder.set_frame_rate(av_info.timing.fps.into());
+
+        if av_info.geometry.base_height == 0 && av_info.geometry.base_width == 0 {
+            av_info.geometry.base_width = 320;
+            av_info.geometry.base_height = 224;
+            av_info.geometry.aspect_ratio = 4.33;
+        }
+        if av_info.timing.sample_rate == 0.0 {
+            av_info.timing.sample_rate = 44100.0;
+        }
+        video_encoder.set_width(av_info.geometry.base_width);
+        video_encoder.set_height(av_info.geometry.base_height);
+        //video_encoder.set_aspect_ratio(av_info.geometry.aspect_ratio as f64);
+
+        let pix_fmt = PixelFormat::ARGB1555; // temporary until env call is made
+        let video_filter = video_filter(&video_encoder, &av_info, pix_fmt).unwrap();
+
+        let video_encoder = video_encoder.open_as(vcodec).unwrap();
+        //video_output.set_parameters(&video_encoder);
+
+        let mut audio_output = octx.add_stream(acodec).unwrap();
+        let mut audio_encoder = audio_output.codec().encoder().audio().unwrap();
+
+        //let mut video_encoder = octx.add_stream(vcodec).unwrap().codec().encoder().video().unwrap();
+    /*
+        let mut audio_output = octx.add_stream(acodec).unwrap();
+        let mut audio_encoder = audio_output.codec().encoder().audio().unwrap();
+        */
+        /*
+        retroarch inits
+static bool ffmpeg_init_config(struct ff_config_param *params,
+   if (!ffmpeg_init_muxer_pre(handle))
+   if (!ffmpeg_init_video(handle))
+   av_frame_alloc
+   */
+
+
+        audio_encoder.set_bit_rate(640000);
+        audio_encoder.set_max_bit_rate(990000);
+
+        //audio_encoder.set_rate(44100);
+        audio_encoder.set_rate(av_info.timing.sample_rate.round() as i32);
+        audio_encoder.set_channels(2);
+        audio_encoder.set_channel_layout(ChannelLayout::STEREO);
+        audio_encoder.set_format(audio_encoder.codec().unwrap().audio().unwrap().formats().unwrap().nth(0).unwrap());
+        audio_encoder.set_time_base(Rational::new(1, 60));
+        audio_output.set_time_base(Rational::new(1, 60));
+
+        let audio_encoder = audio_encoder.open_as(acodec).unwrap();
+        //audio_output.set_parameters(&audio_encoder);
+
+        let audio_filter = audio_filter(&audio_encoder, av_info.timing.sample_rate).unwrap();
+
+        //audio_encoder.set_rate(av_info.timing.sample_rate.round() as i32);
+
+        octx.write_header().unwrap();
+        ffmpeg::format::context::output::dump(&octx, 0, None);
+
+        let mut comp = FfmpegComponent {
+            av_info: av_info.clone(),
+            audio_buf: Default::default(),
+            video_pixel_format: format::Pixel::RGB555,
+            prev_video_frame: None,
+            video_frames: Default::default(),
+            video_encoder,
+            audio_encoder,
+            video_filter,
+            audio_filter,
+            frame_properties_locked: false,
+            octx,
+            frame: 0
+        };
+        comp.set_system_av_info(&av_info);
+        comp
+    }
+
+    fn receive_and_write_packets(&mut self, encoder: EncoderToWriteFrom)
+    {
+        let stream_index = match encoder {
+            EncoderToWriteFrom::Video => 0,
+            EncoderToWriteFrom::Audio => 1,
+        };
+        let mut encoded_packet = ffmpeg::Packet::empty();
+        loop
+        {
+            match match encoder {
+                EncoderToWriteFrom::Video => self.video_encoder.receive_packet(&mut encoded_packet),
+                EncoderToWriteFrom::Audio => self.audio_encoder.receive_packet(&mut encoded_packet),
+            } {
+                Ok(..) => {
+                    //if encoded_packet.size() > 0 {
+                        encoded_packet.set_stream(stream_index);
+                        eprintln!("📦 Writing packet, pts {:?} dts {:?} size {}", encoded_packet.pts(), encoded_packet.dts(), encoded_packet.size());
+                        if stream_index == 0 {
+                            encoded_packet.rescale_ts(Rational(1, 60), self.octx.stream(stream_index).unwrap().time_base());
+                        }
+                        eprintln!("📦 rescaled , pts {:?} dts {:?} size {}", encoded_packet.pts(), encoded_packet.dts(), encoded_packet.size());
+
+                        match encoded_packet.write_interleaved(&mut self.octx) {
+                            Ok(..) => eprintln!("Write OK"),
+                            Err(e) => eprintln!("Error writing: {}", e),
+                        }
+                        //encoded_packet.write_interleaved(&mut self.octx).unwrap(); // AAA
+                    //}
+                    //else {
+                        //eprintln!("Did not try to write 0-length packet");
+                    //}
+                },
+                Err(e) => {
+                    eprintln!("Error writing packet: {:?}", e);
+                    break;
+                }
+            }
+        }
+    }
+
+    pub fn end(&mut self) {
+        let mut packet = Packet::empty();
+        eprintln!("flushed: {:?}", self.video_encoder.flush(&mut packet).unwrap());
+
+        self.video_encoder.send_eof().unwrap();
+        self.receive_and_write_packets(EncoderToWriteFrom::Video);
+        self.audio_encoder.send_eof().unwrap();
+        self.receive_and_write_packets(EncoderToWriteFrom::Audio);
+        self.octx.write_trailer().unwrap();
+    }
+}
+
+impl Drop for FfmpegComponent {
+    fn drop(&mut self) {
+        self.end();
+    }
+}
+
+impl RetroCallbacks for FfmpegComponent {
+    fn video_refresh(&mut self, data: &[u8], width: u32, height: u32, pitch: u32) {
+        let mut vframe = frame::Video::new(self.video_pixel_format, width, height);
+
+        let stride = vframe.stride(0);
+        let pitch = pitch as usize;
+
+        let vplane = vframe.data_mut(0);
+        if data.len() == vplane.len() && pitch == stride {
+            vplane.copy_from_slice(&data);
+        } else {
+            for y in 0..(height as usize) {
+                let ffbegin = y * stride;
+                let lrbegin = y * pitch;
+                let min = usize::min(stride, pitch);
+                vplane[ffbegin..(ffbegin + min)].copy_from_slice(
+                    &data[lrbegin..(lrbegin + min)]
+                );
+            }
+        }
+
+        //vframe.set_pts(Some(self.frame as i64));
+
+        self.prev_video_frame.replace(vframe.clone());
+        self.video_frames.push_back(vframe);
+    }
+
+    fn video_refresh_dupe(&mut self, width: u32, height: u32, _pitch: u32) {
+        if let Some(frame) = &self.prev_video_frame {
+            self.video_frames.push_back(frame.clone());
+        } else {
+            let vframe = frame::Video::new(self.video_pixel_format, width, height);
+            self.video_frames.push_back(vframe);
+        }
+    }
+
+    fn audio_sample(&mut self, left: i16, right: i16) {
+        self.audio_buf.push((left, right));
+    }
+
+    fn audio_sample_batch(&mut self, stereo_pcm: &[i16]) -> usize {
+        let left_iter = stereo_pcm.iter().step_by(2).cloned();
+        let right_iter = stereo_pcm.iter().skip(1).step_by(2).cloned();
+        self.audio_buf.extend(Iterator::zip(left_iter, right_iter));
+        stereo_pcm.len()
+    }
+
+    fn set_pixel_format(&mut self, format: PixelFormat) -> Option<bool> {
+        if self.frame_properties_locked {
+            return Some(false);
+        }
+
+        self.video_pixel_format = match format {
+            PixelFormat::ARGB1555 => format::Pixel::RGB555,
+            PixelFormat::ARGB8888 => format::Pixel::RGB32,
+            PixelFormat::RGB565 => format::Pixel::RGB565,
+        };
+        self.video_filter = video_filter(&self.video_encoder, &self.av_info, format).unwrap();
+        Some(true)
+    }
+
+    fn get_variable(&mut self, key: &str) -> Option<String> {
+        match key {
+            "beetle_saturn_analog_stick_deadzone" => Some("15%".to_string()),
+            "parallel-n64-gfxplugin" => Some("angrylion".to_string()),
+            "parallel-n64-astick-deadzone" => Some("15%".to_string()),
+            _ => None,
+        }
+    }
+
+    fn set_system_av_info(&mut self, system_av_info: &SystemAvInfo) -> Option<bool> {
+        if self.frame_properties_locked {
+            return Some(false);
+        }
+
+        //self.video_encoder.set_frame_rate(system_av_info.timing.fps.into());
+        //self.video_encoder.set_time_base(Rational::new(1, 60));
+        //self.video_encoder.set_frame_rate(Some(Rational::new(1, 60)));
+        if system_av_info.timing.sample_rate.round() as i32 > 0 {
+            self.audio_encoder.set_rate(system_av_info.timing.sample_rate.round() as i32);
+        }
+        self.av_info.timing = system_av_info.timing.clone();
+        self.set_geometry(&system_av_info.geometry);
+        Some(true)
+    }
+
+    fn set_geometry(&mut self, geometry: &GameGeometry) -> Option<bool> {
+        if self.frame_properties_locked {
+            return Some(false);
+        }
+
+        self.video_encoder.set_width(geometry.base_width);
+        self.video_encoder.set_height(geometry.base_height);
+        //self.video_encoder.set_aspect_ratio(geometry.aspect_ratio as f64);
+        self.av_info.geometry = geometry.clone();
+        let pixel_format = match self.video_pixel_format {
+            format::Pixel::RGB555 => PixelFormat::ARGB1555,
+            format::Pixel::RGB32 => PixelFormat::ARGB8888,
+            format::Pixel::RGB565 => PixelFormat::RGB565,
+            _ => unimplemented!(),
+        };
+        self.video_filter = video_filter(&self.video_encoder, &self.av_info, pixel_format).unwrap();
+        Some(true)
+    }
+}

src/components/provided/mod.rs

@@ -0,0 +1,7 @@
+#[cfg(feature = "ffmpeg_comp")]
+pub mod ffmpeg;
+
+#[cfg(feature = "sdl2_comp")]
+pub mod sdl2;
+
+pub mod stdlib;

src/components/provided/sdl2.rs

@@ -0,0 +1,323 @@
+use std::error::Error;
+use std::ffi::CStr;
+use std::path::Path;
+use std::time::{Duration, Instant};
+
+use crate::prelude::*;
+use crate::components::ControlFlow;
+
+use sdl2::audio::{AudioCallback, AudioFormat, AudioSpec, AudioSpecDesired, AudioDevice};
+use sdl2::controller::{GameController, Button, Axis};
+use sdl2::event::Event;
+use sdl2::keyboard::Keycode;
+use sdl2::rect::Rect;
+use sdl2::render::WindowCanvas;
+
+// TODO: split up between video/audio/input!
+pub struct Sdl2Component {
+    preferred_pad: Option<u32>,
+
+    av_info: SystemAvInfo,
+
+    _sdl_context: sdl2::Sdl,
+
+    // video bits
+    canvas: WindowCanvas,
+    pixel_format: sdl2::pixels::PixelFormatEnum,
+
+    // audio bits
+    audio_buffer: Vec<i16>,
+    audio_spec: AudioSpec,
+    audio_device: AudioDevice<MySdlAudio>,
+    audio_sender: crossbeam_channel::Sender<Vec<i16>>,
+
+    // input bits
+    gamepad_subsys: sdl2::GameControllerSubsystem,
+    gamepads: Vec<GameController>,
+
+    // timing and events
+    frame_begin: Instant,
+    event_pump: sdl2::EventPump,
+}
+
+impl RetroComponent for Sdl2Component {
+    fn pre_run(&mut self, _retro: &mut LibretroWrapper) -> ControlFlow {
+        self.frame_begin = Instant::now();
+
+        for event in self.event_pump.poll_iter() {
+            match event {
+                Event::Quit { .. }
+                | Event::KeyDown {
+                    keycode: Some(Keycode::Escape),
+                    ..
+                } => return ControlFlow::Break,
+                _ => {}
+            }
+        }
+
+        ControlFlow::Continue
+    }
+
+    fn post_run(&mut self, _retro: &mut LibretroWrapper) -> ControlFlow {
+        // The rest of the game loop goes here...
+        self.canvas.present();
+
+        // similar hack to the sample rate, make sure we don't divide by zero.
+        let mut spf = 1.0 / self.av_info.timing.fps;
+        if spf.is_nan() || spf.is_infinite() {
+            spf = 1.0 / 60.0;
+        }
+        Duration::from_secs_f64(spf)
+            .checked_sub(self.frame_begin.elapsed())
+            .map(std::thread::sleep);
+
+
+        ControlFlow::Continue
+    }
+
+    fn post_load_game(&mut self, retro: &mut LibretroWrapper, _rom: &Path) -> Result<(), Box<dyn Error>> {
+        if let Some(device) = self.preferred_pad {
+            for port in 0..self.gamepads.len() as u32 {
+                retro.set_controller_port_device(port, device);
+            }
+        }
+        self.audio_device.resume();
+        Ok(())
+    }
+}
+
+impl Sdl2Component {
+    pub fn new(retro: &LibretroWrapper) -> Self {
+        let sys_info = retro.get_system_info();
+        let title = format!(
+            "{} - ferretro",
+            unsafe { CStr::from_ptr(sys_info.library_name) }.to_string_lossy()
+        );
+
+        let mut av_info = retro.get_system_av_info();
+        let pixel_format = sdl2::pixels::PixelFormatEnum::ARGB1555;
+
+        // HACK: some cores don't report this 'til we get an environ call to set_system_av_info...
+        //  which is too late for this constructor to pass along to SDL.
+        if av_info.timing.sample_rate == 0.0 {
+            av_info.timing.sample_rate = 32040.0;
+        }
+
+        let sdl_context = sdl2::init().unwrap();
+
+        let window = sdl_context
+            .video()
+            .unwrap()
+            .window(title.as_str(), av_info.geometry.base_width, av_info.geometry.base_height)
+            .opengl()
+            .build()
+            .unwrap();
+
+        let canvas = window.into_canvas().build().unwrap();
+
+        let (audio_sender, audio_receiver) = crossbeam_channel::bounded(2);
+
+        let audio = sdl_context.audio().unwrap();
+        let desired_spec = AudioSpecDesired {
+            freq: Some(av_info.timing.sample_rate.round() as i32),
+            channels: Some(2),
+            samples: None,
+        };
+        let mut audio_spec = None;
+        let audio_device = audio
+            .open_playback(None, &desired_spec, |spec| {
+                if spec.format != AudioFormat::S16LSB {
+                    eprintln!("unsupported audio format {:?}", spec.format);
+                }
+                audio_spec = Some(spec.clone());
+                MySdlAudio {
+                    audio_spec: spec,
+                    audio_receiver,
+                }
+            })
+            .unwrap();
+
+        let gamepad_subsys = sdl_context.game_controller().unwrap();
+        let mut gamepads = Vec::new();
+        for i in 0..gamepad_subsys.num_joysticks().unwrap() {
+            gamepads.extend(gamepad_subsys.open(i).into_iter());
+        }
+
+        let event_pump = sdl_context.event_pump().unwrap();
+
+        Sdl2Component {
+            preferred_pad: None,
+            av_info,
+            _sdl_context: sdl_context,
+            canvas,
+            pixel_format,
+            audio_buffer: Default::default(),
+            audio_spec: audio_spec.unwrap(),
+            audio_device,
+            audio_sender,
+            gamepad_subsys,
+            gamepads,
+            frame_begin: Instant::now(),
+            event_pump,
+        }
+    }
+
+    fn send_audio_samples(&mut self) {
+        let stereo_samples = self.audio_spec.samples as usize * 2;
+        while self.audio_buffer.len() >= stereo_samples {
+            let remainder = self.audio_buffer.split_off(stereo_samples);
+            let msg = std::mem::replace(&mut self.audio_buffer, remainder);
+            let _ = self.audio_sender.try_send(msg);
+        }
+    }
+}
+
+impl RetroCallbacks for Sdl2Component {
+    fn video_refresh(&mut self, data: &[u8], width: u32, height: u32, pitch: u32) {
+        let rect = Rect::new(0, 0, width, height);
+
+        if let Ok(mut tex) =
+            self.canvas
+                .texture_creator()
+                .create_texture_static(self.pixel_format, width, height)
+        {
+            if tex.update(rect, data, pitch as usize).is_ok() {
+                self.canvas.clear();
+                self.canvas.copy(&tex, None, None).unwrap();
+            }
+        }
+    }
+
+    fn audio_sample(&mut self, left: i16, right: i16) {
+        self.audio_buffer.push(left);
+        self.audio_buffer.push(right);
+        self.send_audio_samples()
+    }
+
+    fn audio_sample_batch(&mut self, stereo_pcm: &[i16]) -> usize {
+        self.audio_buffer.extend(stereo_pcm);
+        self.send_audio_samples();
+        stereo_pcm.len()
+    }
+
+    fn input_poll(&mut self) {
+        self.gamepad_subsys.update();
+    }
+
+    fn input_state(&mut self, port: u32, device: InputDeviceId, index: InputIndex) -> i16 {
+        match self.gamepads.get(port as usize) {
+            Some(gamepad) => {
+                match device {
+                    InputDeviceId::Joypad(button) => {
+                        match button_map(&button) {
+                            Some(x) => gamepad.button(x) as i16,
+                            None => match button {
+                                JoypadButton::L2 => gamepad.axis(Axis::TriggerLeft),
+                                JoypadButton::R2 => gamepad.axis(Axis::TriggerRight),
+                                _ => 0,
+                            }
+                        }
+                    }
+                    InputDeviceId::Analog(axis) => gamepad.axis(axis_map(index, axis)),
+                    _ => 0,
+                }
+            }
+            None => 0,
+        }
+    }
+
+    fn set_pixel_format(&mut self, pix_fmt: PixelFormat) -> Option<bool> {
+        self.pixel_format = match pix_fmt {
+            PixelFormat::ARGB1555 => sdl2::pixels::PixelFormatEnum::RGB555,
+            PixelFormat::ARGB8888 => sdl2::pixels::PixelFormatEnum::ARGB8888,
+            PixelFormat::RGB565 => sdl2::pixels::PixelFormatEnum::RGB565,
+        };
+        Some(true)
+    }
+
+    fn get_variable(&mut self, key: &str) -> Option<String> {
+        match key {
+            "beetle_saturn_analog_stick_deadzone" => Some("15%".to_string()),
+            "parallel-n64-gfxplugin" => Some("angrylion".to_string()),
+            "parallel-n64-astick-deadzone" => Some("15%".to_string()),
+            _ => None,
+        }
+    }
+
+    fn get_input_device_capabilities(&mut self) -> Option<u64> {
+        let bits = (1 << (DeviceType::Joypad as u32)) | (1 << (DeviceType::Analog as u32));
+        Some(bits as u64)
+    }
+
+    fn set_system_av_info(&mut self, av_info: &SystemAvInfo) -> Option<bool> {
+        self.set_geometry(&av_info.geometry);
+        self.av_info = av_info.clone();
+        Some(true)
+    }
+
+    fn set_controller_info(&mut self, controller_info: &Vec<ControllerDescription2>) -> Option<bool> {
+        for ci in controller_info {
+            // so we can have analog support in beetle/mednafen saturn
+            if ci.name.as_str() == "3D Control Pad" {
+                self.preferred_pad = Some(ci.device_id());
+                break;
+            }
+        }
+        Some(true)
+    }
+
+    fn set_geometry(&mut self, geom: &GameGeometry) -> Option<bool> {
+        let _ = self.canvas.window_mut().set_size(geom.base_width, geom.base_height);
+        let _ = self.canvas.set_logical_size(geom.base_width, geom.base_height);
+        self.av_info.geometry = geom.clone();
+        Some(true)
+    }
+}
+
+struct MySdlAudio {
+    audio_spec: AudioSpec,
+    audio_receiver: crossbeam_channel::Receiver<Vec<i16>>,
+}
+
+impl AudioCallback for MySdlAudio {
+    type Channel = i16;
+
+    fn callback(&mut self, out: &mut [Self::Channel]) {
+        if self.audio_spec.format == AudioFormat::S16LSB {
+            if let Ok(samples) = self.audio_receiver.recv() {
+                out.copy_from_slice(&samples[..out.len()]);
+            }
+        }
+    }
+}
+
+fn button_map(retro_button: &JoypadButton) -> Option<Button> {
+    match retro_button {
+        JoypadButton::B => Some(Button::A),
+        JoypadButton::Y => Some(Button::X),
+        JoypadButton::Select => Some(Button::Back),
+        JoypadButton::Start => Some(Button::Start),
+        JoypadButton::Up => Some(Button::DPadUp),
+        JoypadButton::Down => Some(Button::DPadDown),
+        JoypadButton::Left => Some(Button::DPadLeft),
+        JoypadButton::Right => Some(Button::DPadRight),
+        JoypadButton::A => Some(Button::B),
+        JoypadButton::X => Some(Button::Y),
+        JoypadButton::L => Some(Button::LeftShoulder),
+        JoypadButton::R => Some(Button::RightShoulder),
+         // SDL2 controller API doesn't have L2/R2 as buttons, they're considered axes
+        JoypadButton::L2 => None,
+        JoypadButton::R2 => None,
+        JoypadButton::L3 => Some(Button::LeftStick),
+        JoypadButton::R3 => Some(Button::RightStick),
+    }
+}
+
+fn axis_map(index: InputIndex, axis: AnalogAxis) -> Axis {
+    match (index, axis) {
+        (InputIndex::Left, AnalogAxis::X) => Axis::LeftX,
+        (InputIndex::Left, AnalogAxis::Y) => Axis::LeftY,
+        (InputIndex::Right, AnalogAxis::X) => Axis::RightX,
+        (InputIndex::Right, AnalogAxis::Y) => Axis::RightY,
+    }
+}

src/components/provided/stdlib.rs

@@ -0,0 +1,80 @@
+use std::path::PathBuf;
+use crate::prelude::*;
+
+#[derive(Default)]
+pub struct PathBufComponent {
+    pub sys_path: Option<PathBuf>,
+    pub libretro_path: Option<PathBuf>,
+    pub core_assets_path: Option<PathBuf>,
+    pub save_path: Option<PathBuf>,
+}
+
+impl RetroComponent for PathBufComponent {}
+impl RetroCallbacks for PathBufComponent {
+    fn get_system_directory(&mut self) -> Option<PathBuf> {
+        self.sys_path.clone()
+    }
+    fn get_libretro_path(&mut self) -> Option<PathBuf> {
+        self.libretro_path.clone()
+    }
+    fn get_core_assets_directory(&mut self) -> Option<PathBuf> {
+        self.core_assets_path.clone()
+    }
+    fn get_save_directory(&mut self) -> Option<PathBuf> {
+        self.save_path.clone()
+    }
+}
+
+#[derive(Default)]
+pub struct StderrLogComponent {
+    pub prefix: String,
+}
+
+impl RetroComponent for StderrLogComponent {}
+impl RetroCallbacks for StderrLogComponent {
+    fn log_print(&mut self, level: crate::retro::ffi::LogLevel, msg: &str) {
+        eprint!("{}[{:?}] {}", self.prefix, level, msg);
+    }
+}
+
+#[derive(Default)]
+pub struct StderrSysInfoLogComponent {
+    pub prefix: String,
+}
+
+impl RetroComponent for StderrSysInfoLogComponent {}
+impl RetroCallbacks for StderrSysInfoLogComponent {
+    fn set_input_descriptors(&mut self, descriptors: &Vec<InputDescriptor2>) -> Option<bool> {
+        for id in descriptors {
+            eprintln!("{}{:?}", self.prefix, id);
+        }
+        Some(true)
+    }
+
+    fn set_variables(&mut self, variables: &Vec<Variable2>) -> Option<bool> {
+        for v in variables {
+            eprintln!("{}{:?}", self.prefix, v);
+        }
+        Some(true)
+    }
+
+    fn set_subsystem_info(&mut self, subsystem_info: &Vec<SubsystemInfo2>) -> Option<bool> {
+        for s in subsystem_info {
+            eprintln!("{}{:?}", self.prefix, s);
+        }
+        Some(true)
+    }
+}
+
+#[derive(Default)]
+pub struct StderrCallTraceComponent {
+    pub prefix: String,
+}
+
+impl RetroComponent for StderrCallTraceComponent {}
+impl RetroCallbacks for StderrCallTraceComponent {
+    fn audio_sample(&mut self, left: i16, right: i16) {
+        eprintln!("{}audio_sample({}, {})", self.prefix, left, right);
+    }
+    // TODO: etc...
+}

src/lib.rs

@@ -1,4 +1,12 @@
-extern crate failure;
 extern crate libloading;
 
 pub mod retro;
+pub mod components;
+
+pub mod prelude {
+    pub use crate::retro::constants::*;
+    pub use crate::components::{RetroComponent, RetroComponentBase};
+    pub use crate::retro::wrapped_types::*;
+    pub use crate::retro::wrapper::{RetroCallbacks, LibretroWrapper, LibretroWrapperAccess};
+    pub use crate::retro::ffi::{PixelFormat, GameGeometry, SystemAvInfo, SystemInfo};
+}

src/retro/loading.rs

@@ -2,18 +2,19 @@ use std::ffi::CString;
 use std::os::raw::{c_char, c_void};
 use std::path::Path;
 
-use failure::Fallible;
 use libloading;
 
 use super::ffi::*;
 
+pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+
 pub struct LibretroApi {
     _lib: libloading::Library, // for tying our lifetime to its own
     pub core_api: CoreAPI,
 }
 
 impl LibretroApi {
-    pub fn from_library(lib: libloading::Library) -> Fallible<Self> {
+    pub fn from_library(lib: libloading::Library) -> Result<Self> {
         unsafe {
             let core_api = CoreAPI {
                 retro_set_environment: *lib.get(b"retro_set_environment")?,
@@ -46,31 +47,31 @@ impl LibretroApi {
         }
     }
     /// set_environment() must be called before init().
-    pub fn set_environment(&self, cb: EnvironmentFn) {
+    pub fn set_environment(&mut self, cb: EnvironmentFn) {
         unsafe { (&self.core_api.retro_set_environment)(cb) }
     }
-    /// video_refresh() must be called before run().
+    /// set_video_refresh() must be called before run().
-    pub fn set_video_refresh(&self, cb: VideoRefreshFn) {
+    pub fn set_video_refresh(&mut self, cb: VideoRefreshFn) {
         unsafe { (&self.core_api.retro_set_video_refresh)(cb) }
     }
-    pub fn set_audio_sample(&self, cb: AudioSampleFn) {
+    pub fn set_audio_sample(&mut self, cb: AudioSampleFn) {
         unsafe { (&self.core_api.retro_set_audio_sample)(cb) }
     }
-    pub fn set_audio_sample_batch(&self, cb: AudioSampleBatchFn) {
+    pub fn set_audio_sample_batch(&mut self, cb: AudioSampleBatchFn) {
         unsafe { (&self.core_api.retro_set_audio_sample_batch)(cb) }
     }
-    pub fn set_input_poll(&self, cb: InputPollFn) {
+    pub fn set_input_poll(&mut self, cb: InputPollFn) {
         unsafe { (&self.core_api.retro_set_input_poll)(cb) }
     }
-    pub fn set_input_state(&self, cb: InputStateFn) {
+    pub fn set_input_state(&mut self, cb: InputStateFn) {
         unsafe { (&self.core_api.retro_set_input_state)(cb) }
     }
     /// set_environment() must be called before init().
-    pub fn init(&self) {
+    pub fn init(&mut self) {
         // TODO assert!(called retro_set_environment);
         unsafe { (&self.core_api.retro_init)() }
     }
-    pub fn deinit(&self) {
+    pub fn deinit(&mut self) {
         unsafe { (&self.core_api.retro_deinit)() }
     }
     /// Must return RETRO_API_VERSION. Used to validate ABI compatibility when the API is revised.
@@ -85,11 +86,11 @@ impl LibretroApi {
             info
         }
     }
-    /** Gets information about system audio/video timings and geometry.
+    /// Gets information about system audio/video timings and geometry.
-     * Can be called only after load_game() has successfully completed.
+    /// Can be called only after load_game() has successfully completed.
-     * NOTE: The implementation of this function might not initialize every variable if needed.
+    /// NOTE: The implementation of this function might not initialize every variable if needed.
-     * E.g. geom.aspect_ratio might not be initialized if core doesn't
+    /// E.g. geom.aspect_ratio might not be initialized if core doesn't
-     * desire a particular aspect ratio. */
+    /// desire a particular aspect ratio.
     pub fn get_system_av_info(&self) -> SystemAvInfo {
         unsafe {
             let mut av_info = ::std::mem::zeroed::<SystemAvInfo>();
@@ -97,40 +98,38 @@ impl LibretroApi {
             av_info
         }
     }
-    /** Sets device to be used for player 'port'.
+    /// Sets device to be used for player 'port'.
-     * By default, RETRO_DEVICE_JOYPAD is assumed to be plugged into all
+    /// By default, RETRO_DEVICE_JOYPAD is assumed to be plugged into all
-     * available ports.
+    /// available ports.
-     * Setting a particular device type is not a guarantee that libretro cores
+    /// Setting a particular device type is not a guarantee that libretro cores
-     * will only poll input based on that particular device type. It is only a
+    /// will only poll input based on that particular device type. It is only a
-     * hint to the libretro core when a core cannot automatically detect the
+    /// hint to the libretro core when a core cannot automatically detect the
-     * appropriate input device type on its own. It is also relevant when a
+    /// appropriate input device type on its own. It is also relevant when a
-     * core can change its behavior depending on device type.
+    /// core can change its behavior depending on device type.
-     *
+    ///
-     * As part of the core's implementation of retro_set_controller_port_device,
+    /// As part of the core's implementation of retro_set_controller_port_device,
-     * the core should call RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS to notify the
+    /// the core should call RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS to notify the
-     * frontend if the descriptions for any controls have changed as a
+    /// frontend if the descriptions for any controls have changed as a
-     * result of changing the device type.
+    /// result of changing the device type.
-     */
+    pub fn set_controller_port_device(&mut self, port: u32, device: u32) {
-    pub fn set_controller_port_device(&self, port: u32, device: u32) {
         unsafe { (&self.core_api.retro_set_controller_port_device)(port, device) }
     }
     /// Resets the current game.
-    pub fn reset(&self) {
+    pub fn reset(&mut self) {
         unsafe { (&self.core_api.retro_reset)() }
     }
-    /** Runs the game for one video frame.
+    /// Runs the game for one video frame.
-     * During retro_run(), input_poll callback must be called at least once.
+    /// During retro_run(), input_poll callback must be called at least once.
-     *
+    ///
-     * If a frame is not rendered for reasons where a game "dropped" a frame,
+    /// If a frame is not rendered for reasons where a game "dropped" a frame,
-     * this still counts as a frame, and retro_run() should explicitly dupe
+    /// this still counts as a frame, and retro_run() should explicitly dupe
-     * a frame if GET_CAN_DUPE returns true.
+    /// a frame if GET_CAN_DUPE returns true.
-     * In this case, the video callback can take a NULL argument for data.
+    /// In this case, the video callback can take a NULL argument for data.
-     */
+    pub fn run(&mut self) {
-    pub fn run(&self) {
         unsafe { (&self.core_api.retro_run)() }
     }
     /// Serializes internal state.
-    pub fn serialize(&self) -> Fallible<Vec<u8>> {
+    pub fn serialize(&mut self) -> Result<Vec<u8>> {
         let size: usize = unsafe { (&self.core_api.retro_serialize_size)() };
         let mut vec = Vec::with_capacity(size);
         vec.resize(size, 0);
@@ -138,29 +137,35 @@ impl LibretroApi {
         if unsafe { (&self.core_api.retro_serialize)(vec.as_mut_ptr() as *mut c_void, size); true } {
             Ok(vec)
         } else {
-            Err(failure::err_msg("Serialize failed"))
+            Err("Serialize failed".into())
         }
     }
-    pub fn unserialize(&self, data: &[u8]) -> Fallible<()> {
+    pub fn unserialize(&mut self, data: &[u8]) -> Result<()> {
+        // validate size of the data
+        let size: usize = unsafe { (&self.core_api.retro_serialize_size)() };
+        if data.len() != size {
+            return Err(format!("Size of data {} doesn't match this core's expected size {}", data.len(), size).into())
+        }
+
         if unsafe { (&self.core_api.retro_unserialize)(data.as_ptr() as *const c_void, data.len()) } {
             Ok(())
         } else {
-            Err(failure::err_msg("Unserialize failed"))
+            Err("Unserialize failed".into())
         }
     }
-    pub fn cheat_reset(&self) {
+    pub fn cheat_reset(&mut self) {
         unsafe { (&self.core_api.retro_cheat_reset)() }
     }
-    pub fn cheat_set(&self, index: u32, enabled: bool, code: &str) {
+    pub fn cheat_set(&mut self, index: u32, enabled: bool, code: &str) {
         unsafe { (&self.core_api.retro_cheat_set)(index, enabled, code.as_bytes().as_ptr() as *const c_char) }
     }
     /// Loads a game.
     pub fn load_game(
-        &self,
+        &mut self,
         path: Option<&Path>,
         data: Option<&[u8]>,
         meta: Option<&str>,
-    ) -> Fallible<()> {
+    ) -> Result<()> {
         let mut game = GameInfo {
             path: std::ptr::null(),
             data: std::ptr::null(),
@@ -186,11 +191,11 @@ impl LibretroApi {
         if unsafe { (&self.core_api.retro_load_game)(&game) } {
             Ok(())
         } else {
-            Err(failure::err_msg("Failed to load game"))
+            Err("Failed to load game".into())
         }
     }
     /// Unloads the currently loaded game. Called before deinit().
-    pub fn unload_game(&self) {
+    pub fn unload_game(&mut self) {
         unsafe { (&self.core_api.retro_unload_game)() }
     }
     pub fn get_region(&self) -> Region {

src/retro/wrapped_types.rs

@@ -6,7 +6,7 @@ use std::slice::from_raw_parts;
 use super::constants::*;
 use super::ffi::*;
 
-#[derive(Debug)]
+#[derive(Clone, Copy, Debug)]
 pub enum InputDeviceId {
     None(c_uint),
     Joypad(JoypadButton),
@@ -21,9 +21,9 @@ impl<D> TryFrom<(D, c_uint)> for InputDeviceId
     where D: TryInto<DeviceType>,
           <D as std::convert::TryInto<DeviceType>>::Error: std::error::Error + Send + Sync + 'static,
 {
-    type Error = failure::Error;
+    type Error = Box<dyn std::error::Error>;
 
-    fn try_from(pair: (D, c_uint)) -> failure::Fallible<Self> {
+    fn try_from(pair: (D, c_uint)) -> Result<Self, Self::Error> {
         let (device, id) = pair;
         Ok(match device.try_into()? {
             DeviceType::None => InputDeviceId::None(id),
@@ -37,7 +37,7 @@ impl<D> TryFrom<(D, c_uint)> for InputDeviceId
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct Variable2 {
     pub key: String,
     pub description: String,
@@ -68,7 +68,7 @@ impl From<&Variable> for Variable2 {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct ControllerDescription2 {
     pub name: String,
     pub base_type: DeviceType,
@@ -104,7 +104,7 @@ impl TryFrom<&ControllerDescription> for ControllerDescription2 {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct InputDescriptor2 {
     pub port: c_uint,
     pub device_id: InputDeviceId,
@@ -131,7 +131,7 @@ impl TryFrom<&InputDescriptor> for InputDescriptor2 {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct SubsystemInfo2 {
     pub description: String,
     pub identifier: String,
@@ -155,7 +155,7 @@ impl From<&SubsystemInfo> for SubsystemInfo2 {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct SubsystemRomInfo2 {
     pub description: String,
     pub valid_extensions: Vec<String>,
@@ -185,7 +185,7 @@ impl From<&SubsystemRomInfo> for SubsystemRomInfo2 {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct SubsystemMemoryInfo2 {
     pub extension: String,
     pub kind: c_uint,

src/retro/wrapper.rs

@@ -4,8 +4,9 @@ use core::slice::from_raw_parts;
 
 use std::convert::TryFrom;
 use std::ffi::{CStr, CString};
-use std::ops::Deref;
+use std::ops::{Deref, DerefMut};
 use std::os::raw::{c_char, c_uint};
+use std::os::unix::ffi::OsStrExt;
 use std::path::{Path, PathBuf};
 use std::pin::Pin;
 use std::time::Duration;
@@ -28,70 +29,353 @@ extern "C" {
     fn c_ext_set_log_print_cb(cb: WrappedLogPrintFn);
 }
 
+// method docs largely copied/lightly-adapted-to-rust straight from libretro.h.
 #[rustfmt::skip]
-#[allow(unused)]
+#[allow(unused_variables)]
-pub trait Handler: Unpin + 'static {
+pub trait RetroCallbacks: Unpin + 'static {
-    fn libretro_core(&mut self) -> &mut LibretroWrapper;
-    fn delegate_handler(&self) -> Option<&mut dyn Handler> { None }
-
     // -- main callbacks --
+    /// Render a frame. Pixel format is 15-bit 0RGB1555 native endian
+    /// unless changed (see [Self::set_pixel_format]).
+    ///
+    /// Width and height specify dimensions of buffer.
+    /// Pitch specifices length in bytes between two lines in buffer.
+    ///
+    /// For performance reasons, it is highly recommended to have a frame
+    /// that is packed in memory, i.e. pitch == width * byte_per_pixel.
+    /// Certain graphic APIs, such as OpenGL ES, do not like textures
+    /// that are not packed in memory.
     fn video_refresh(&mut self, data: &[u8], width: c_uint, height: c_uint, pitch: c_uint) {}
+    /// Called instead of video_refresh when the core reports a duplicate frame (NULL).
+    fn video_refresh_dupe(&mut self, width: c_uint, height: c_uint, pitch: c_uint) {}
+    /// Renders a single audio frame. Should only be used if implementation
+    /// generates a single sample at a time.
+    /// Format is signed 16-bit native endian.
     fn audio_sample(&mut self, left: i16, right: i16) {}
+    /// Renders multiple audio frames in one go.
+    ///
+    /// One frame is defined as a sample of left and right channels, interleaved.
+    /// I.e. int16_t buf\[4\] = { l, r, l, r }; would be 2 frames.
+    /// Only one of the audio callbacks must ever be used.
     fn audio_sample_batch(&mut self, stereo_pcm: &[i16]) -> usize { stereo_pcm.len() }
+    /// Polls input.
     fn input_poll(&mut self) {}
+    /// Queries for input for player 'port'.
     fn input_state(&mut self, port: u32, device: InputDeviceId, index: InputIndex) -> i16 { 0 }
 
     // -- environment callbacks --
-    fn set_rotation(&mut self, rotation: EnvRotation) -> bool { false }
+    /// Sets screen rotation of graphics.
+    /// Is only implemented if rotation can be accelerated by hardware.
+    /// Valid values are 0, 1, 2, 3, which rotates screen by 0, 90, 180,
+    /// 270 degrees counter-clockwise respectively.
+    fn set_rotation(&mut self, rotation: EnvRotation) -> Option<bool> { None }
+    /// Boolean value whether or not the implementation should use overscan,
+    /// or crop away overscan.
     fn get_overscan(&mut self) -> Option<bool> { None }
-    fn get_can_dupe(&mut self) -> Option<bool> { None }
+    /// Sets a message to be displayed in implementation-specific manner
-    fn set_message(&mut self, message: Message) -> bool { false }
+    /// for a certain amount of 'frames'.
-    fn shutdown(&mut self) -> bool { false }
+    /// Should not be used for trivial messages, which should simply be
-    fn set_performance_level(&mut self, level: c_uint) -> bool { false }
+    /// logged via [Self::get_log_interface] (or as a
+    /// fallback, stderr).
+    fn set_message(&mut self, message: &Message) -> Option<bool> { None }
+    /// Requests the frontend to shutdown.
+    /// Should only be used if game has a specific
+    /// way to shutdown the game from a menu item or similar.
+    fn shutdown(&mut self) -> Option<bool> { None }
+    /// Gives a hint to the frontend how demanding this implementation
+    /// is on a system. E.g. reporting a level of 2 means
+    /// this implementation should run decently on all frontends
+    /// of level 2 and up.
+    ///
+    /// It can be used by the frontend to potentially warn
+    /// about too demanding implementations.
+    ///
+    /// The levels are "floating".
+    ///
+    /// This function can be called on a per-game basis,
+    /// as certain games an implementation can play might be
+    /// particularly demanding.
+    /// If called, it should be called in [libretro_sys::CoreAPI::retro_load_game].
+    fn set_performance_level(&mut self, level: c_uint) -> Option<bool> { None }
+    /// Returns the "system" directory of the frontend.
+    /// This directory can be used to store system specific
+    /// content such as BIOSes, configuration data, etc.
+    /// The returned value can be `None`.
+    /// If so, no such directory is defined,
+    /// and it's up to the implementation to find a suitable directory.
+    ///
+    /// NOTE: Some cores used this folder also for "save" data such as
+    /// memory cards, etc, for lack of a better place to put it.
+    /// This is now discouraged, and if possible, cores should try to
+    /// use the new [Self::get_save_directory].
     fn get_system_directory(&mut self) -> Option<PathBuf> { None }
-    fn set_pixel_format(&mut self, format: PixelFormat) -> bool { false }
+    /// Sets the internal pixel format used by the implementation.
-    fn set_input_descriptors(&mut self, input_descriptors: Vec<InputDescriptor2>) -> bool { false }
+    /// The default pixel format is [libretro_sys::PixelFormat::ARGB1555].
-    fn set_hw_render(&mut self, hw_render_callback: HwRenderCallback) -> bool { false }
+    /// This pixel format however, is deprecated (see enum retro_pixel_format).
+    /// If the call returns false, the frontend does not support this pixel
+    /// format.
+    ///
+    /// The core should call this function inside [libretro_sys::CoreAPI::retro_load_game] or
+    /// [Self::set_system_av_info].
+    fn set_pixel_format(&mut self, format: PixelFormat) -> Option<bool> { None }
+    /// Sets an array of [crate::prelude::InputDescriptor2].
+    /// It is up to the frontend to present this in a usable way.
+    /// This function can be called at any time, but it is recommended
+    /// for the core to call it as early as possible.
+    fn set_input_descriptors(&mut self, input_descriptors: &Vec<InputDescriptor2>) -> Option<bool> { None }
+    /// Sets an interface to let a libretro core render with
+    /// hardware acceleration.
+    /// The core should call this in [libretro_sys::CoreAPI::retro_load_game].
+    /// If successful, libretro cores will be able to render to a
+    /// frontend-provided framebuffer.
+    /// The size of this framebuffer will be at least as large as
+    /// max_width/max_height provided in [libretro_sys::CoreAPI::retro_get_system_av_info].
+    /// If HW rendering is used, pass only [libretro_sys::HW_FRAME_BUFFER_VALID] or
+    /// NULL to [libretro_sys::VideoRefreshFn].
+    fn set_hw_render(&mut self, hw_render_callback: &HwRenderCallback) -> Option<bool> { None }
+    /// Interface to acquire user-defined information from environment
+    /// that cannot feasibly be supported in a multi-system way.
+    /// 'key' should be set to a key which has already been set by
+    /// [Self::set_variables].
     fn get_variable(&mut self, key: &str) -> Option<String> { None }
-    fn set_variables(&mut self, variables: Vec<Variable2>) -> bool { false }
+    /// Allows an implementation to signal the environment
+    /// which variables it might want to check for later using
+    /// [Self::get_variable].
+    /// This allows the frontend to present these variables to
+    /// a user dynamically.
+    /// The core should call this for the first time as early as
+    /// possible (ideally in [libretro_sys::CoreAPI::retro_set_environment]).
+    /// Afterward it may be called again for the core to communicate
+    /// updated options to the frontend, but the number of core
+    /// options must not change from the number in the initial call.
+    ///
+    /// [crate::prelude::Variable2::key] should be namespaced to not collide
+    /// with other implementations' keys. E.g. A core called
+    /// 'foo' should use keys named as 'foo_option'.
+    ///
+    /// [crate::prelude::Variable2::description] should contain a human readable
+    /// description of the key.
+    ///
+    /// [crate::prelude::Variable2::options] should contain the list of expected values.
+    /// The number of possible options should be very limited,
+    /// i.e. it should be feasible to cycle through options
+    /// without a keyboard. The first entry should be treated as a default.
+    ///
+    /// Only strings are operated on. The possible values will
+    /// generally be displayed and stored as-is by the frontend.
+    fn set_variables(&mut self, variables: &Vec<Variable2>) -> Option<bool> { None }
+    /// Result is set to true if some variables are updated by
+    /// frontend since last call to [Self::get_variable].
+    /// Variables should be queried with [Self::get_variable].
     fn get_variable_update(&mut self) -> Option<bool> { None }
-    fn set_support_no_game(&mut self, supports_no_game: bool) -> bool { false }
+    /// If true, the libretro implementation supports calls to
+    /// [libretro_sys::CoreAPI::retro_load_game] with NULL as argument.
+    /// Used by cores which can run without particular game data.
+    /// This should be called within [libretro_sys::CoreAPI::retro_set_environment] only.
+    fn set_support_no_game(&mut self, supports_no_game: bool) -> Option<bool> { None }
+    /// Retrieves the absolute path from where this libretro
+    /// implementation was loaded.
+    /// `None` is returned if the libretro was loaded statically
+    /// (i.e. linked statically to frontend), or if the path cannot be
+    /// determined.
+    /// Mostly useful in cooperation with [Self::set_support_no_game] as assets can
+    /// be loaded without ugly hacks.
     fn get_libretro_path(&mut self) -> Option<PathBuf> { None }
+    /// Gets a bitmask telling which device type are expected to be
+    /// handled properly in a call to retro_input_state_t.
+    /// Devices which are not handled or recognized always return
+    /// 0 in [Self::input_state].
+    /// Example bitmask: caps = (1 << [libretro_sys::DEVICE_JOYPAD]) | (1 << [libretro_sys::DEVICE_ANALOG]).
+    /// Should only be called in [libretro_sys::CoreAPI::retro_run].
     fn get_input_device_capabilities(&mut self) -> Option<u64> { None }
-    fn get_sensor_interface(&mut self) -> Option<SensorInterface> { None }
+    /// Returns the "core assets" directory of the frontend.
-    fn get_camera_interface(&mut self) -> Option<CameraCallback> { None }
+    /// This directory can be used to store specific assets that the
-    fn get_log_interface(&mut self) -> Option<LogCallback> { None }
+    /// core relies upon, such as art assets,
-    fn get_perf_interface(&mut self) -> Option<PerfCallback> { None }
+    /// input data, etc etc.
-    fn get_location_interface(&mut self) -> Option<LocationCallback> { None }
+    /// The returned value can be `None`.
+    /// If so, no such directory is defined,
+    /// and it's up to the implementation to find a suitable directory.
     fn get_core_assets_directory(&mut self) -> Option<PathBuf> { None }
+    /// Returns the "save" directory of the frontend, unless there is no
+    /// save directory available. The save directory should be used to
+    /// store SRAM, memory cards, high scores, etc, if the libretro core
+    /// cannot use the regular memory interface ([libretro_sys::CoreAPI::retro_get_memory_data]).
+    ///
+    /// If the frontend cannot designate a save directory, it will return
+    /// `None` to indicate that the core should attempt to operate without a
+    /// save directory set.
+    ///
+    /// NOTE: early libretro cores used the system directory for save
+    /// files. Cores that need to be backwards-compatible can still check
+    /// [Self::get_system_directory].
     fn get_save_directory(&mut self) -> Option<PathBuf> { None }
-    fn set_system_av_info(&mut self, system_av_info: SystemAvInfo) -> bool { false }
+    /// Sets a new av_info structure. This can only be called from
-    fn set_proc_address_callback(&mut self, cb: GetProcAddressInterface) -> bool { false }
+    /// within [libretro_sys::CoreAPI::retro_run].
-    fn set_subsystem_info(&mut self, subsystem_info: Vec<SubsystemInfo2>) -> bool { false }
+    /// This should *only* be used if the core is completely altering the
-    fn set_controller_info(&mut self, controller_info: Vec<ControllerDescription2>) -> bool { false }
+    /// internal resolutions, aspect ratios, timings, sampling rate, etc.
-    fn set_memory_maps(&mut self, memory_map: MemoryMap) -> bool { false }
+    /// Calling this can require a full reinitialization of video/audio
-    fn set_geometry(&mut self, game_geometry: GameGeometry) -> bool { false }
+    /// drivers in the frontend,
+    ///
+    /// so it is important to call it very sparingly, and usually only with
+    /// the users explicit consent.
+    /// An eventual driver reinitialize will happen so that video and
+    /// audio callbacks
+    /// happening after this call within the same [libretro_sys::CoreAPI::retro_run] call will
+    /// target the newly initialized driver.
+    ///
+    /// This callback makes it possible to support configurable resolutions
+    /// in games, which can be useful to
+    /// avoid setting the "worst case" in `max_width`/`max_height`.
+    ///
+    /// ***HIGHLY RECOMMENDED*** Do not call this callback every time
+    /// resolution changes in an emulator core if it's
+    /// expected to be a temporary change, for the reasons of possible
+    /// driver reinitialization.
+    /// This call is not a free pass for not trying to provide
+    /// correct values in [libretro_sys::CoreAPI::retro_get_system_av_info]. If you need to change
+    /// things like aspect ratio or nominal width/height,
+    /// use [Self::set_geometry], which is a softer variant
+    /// of [Self::set_system_av_info].
+    ///
+    /// If this returns false, the frontend does not acknowledge a
+    /// changed av_info struct.
+    fn set_system_av_info(&mut self, system_av_info: &SystemAvInfo) -> Option<bool> { None }
+    /// This environment call introduces the concept of libretro "subsystems".
+    /// A subsystem is a variant of a libretro core which supports
+    /// different kinds of games.
+    /// The purpose of this is to support e.g. emulators which might
+    /// have special needs, e.g. Super Nintendo's Super GameBoy, Sufami Turbo.
+    /// It can also be used to pick among subsystems in an explicit way
+    /// if the libretro implementation is a multi-system emulator itself.
+    ///
+    /// Loading a game via a subsystem is done with [libretro_sys::CoreAPI::retro_load_game_special],
+    /// and this environment call allows a libretro core to expose which
+    /// subsystems are supported for use with [libretro_sys::CoreAPI::retro_load_game_special].
+    ///
+    /// If a core wants to expose this interface, [Self::set_subsystem_info]
+    /// **MUST** be called from within [libretro_sys::CoreAPI::retro_set_environment].
+    fn set_subsystem_info(&mut self, subsystem_info: &Vec<SubsystemInfo2>) -> Option<bool> { None }
+    /// This environment call lets a libretro core tell the frontend
+    /// which controller subclasses are recognized in calls to
+    /// [libretro_sys::CoreAPI::retro_set_controller_port_device].
+    ///
+    /// Some emulators such as Super Nintendo support multiple lightgun
+    /// types which must be specifically selected from. It is therefore
+    /// sometimes necessary for a frontend to be able to tell the core
+    /// about a special kind of input device which is not specifcally
+    /// provided by the Libretro API.
+    ///
+    /// In order for a frontend to understand the workings of those devices,
+    /// they must be defined as a specialized subclass of the generic device
+    /// types already defined in the libretro API.
+    ///
+    /// The core must pass an array of [crate::prelude::ControllerDescription2]. Each element of the
+    /// array corresponds to the ascending port index
+    /// that is passed to [libretro_sys::CoreAPI::retro_set_controller_port_device] when that function
+    /// is called to indicate to the core that the frontend has changed the
+    /// active device subclass.
+    /// 
+    /// The ascending input port indexes provided by the core in the struct
+    /// are generally presented by frontends as ascending User # or Player #,
+    /// such as Player 1, Player 2, Player 3, etc. Which device subclasses are
+    /// supported can vary per input port.
+    ///
+    /// Each entry in the controller_info array specifies the names and
+    /// codes of all device subclasses that are available for the corresponding
+    /// User or Player, beginning with the generic Libretro device that the
+    /// subclasses are derived from. The second inner element of each entry is the
+    /// total number of subclasses that are listed in the [crate::prelude::ControllerDescription2].
+    /// 
+    /// NOTE: Even if special device types are set in the libretro core,
+    /// libretro should only poll input based on the base input device types.
+    fn set_controller_info(&mut self, controller_info: &Vec<ControllerDescription2>) -> Option<bool> { None }
+    /// This environment call lets a libretro core tell the frontend
+    /// about the memory maps this core emulates.
+    /// This can be used to implement, for example, cheats in a core-agnostic way.
+    ///
+    /// Should only be used by emulators; it doesn't make much sense for
+    /// anything else.
+    /// It is recommended to expose all relevant pointers through
+    /// [libretro_sys::CoreAPI::retro_get_memory_data] and
+    /// [libretro_sys::CoreAPI::retro_get_memory_size] as well.
+    ///
+    /// Can be called from [libretro_sys::CoreAPI::retro_init] and [libretro_sys::CoreAPI::retro_load_game].
+    fn set_memory_maps(&mut self, memory_map: &MemoryMap) -> Option<bool> { None }
+    /// This environment call is similar to [Self::set_system_av_info] for changing
+    /// video parameters, but provides a guarantee that drivers will not be
+    /// reinitialized.
+    /// This can only be called from within [libretro_sys::CoreAPI::retro_run].
+    ///
+    /// The purpose of this call is to allow a core to alter nominal
+    /// width/heights as well as aspect ratios on-the-fly, which can be
+    /// useful for some emulators to change in run-time.
+    ///
+    /// max_width/max_height arguments are ignored and cannot be changed
+    /// with this call as this could potentially require a reinitialization or a
+    /// non-constant time operation.
+    /// If max_width/max_height are to be changed, [Self::set_system_av_info] is required.
+    ///
+    /// A frontend must guarantee that this environment call completes in
+    /// constant time.
+    fn set_geometry(&mut self, game_geometry: &GameGeometry) -> Option<bool> { None }
+    /// Returns the specified username of the frontend, if specified by the user.
+    /// This username can be used as a nickname for a core that has online facilities
+    /// or any other mode where personalization of the user is desirable.
+    /// The returned value can be `None`.
+    /// If this environ callback is used by a core that requires a valid username,
+    /// a default username should be specified by the core.
     fn get_username(&mut self) -> Option<String> { None }
+    /// Returns the specified language of the frontend, if specified by the user.
+    /// It can be used by the core for localization purposes.
     fn get_language(&mut self) -> Option<Language> { None }
-    // fn set_serialization_quirks(&mut self, quirks: &mut u64) -> bool { false }
+    // fn set_serialization_quirks(&mut self, quirks: &mut u64) -> Option<bool> { None }
 
     // -- environment-set callbacks (API extensions) --
+    /// Logging function.
     fn log_print(&mut self, level: LogLevel, msg: &str) {}
+    /// Sets rumble state for joypad plugged in port 'port'.
+    /// Rumble effects are controlled independently,
+    /// and setting e.g. strong rumble does not override weak rumble.
+    /// Strength has a range of \[0, 0xffff\].
+    /// 
+    /// Returns true if rumble state request was honored.
+    /// Calling this before first [libretro_sys::CoreAPI::retro_run] is likely to return false.
     fn set_rumble_state(&mut self, port: c_uint, effect: RumbleEffect, strength: u16) -> bool { false }
+    /// Returns current time in microseconds.
+    /// Tries to use the most accurate timer available.
     fn perf_get_time_usec_cb(&mut self) -> Time { 0 }
+    /// A simple counter. Usually nanoseconds, but can also be CPU cycles.
+    /// Can be used directly if desired (when creating a more sophisticated
+    /// performance counter system).
     fn perf_get_counter_cb(&mut self) -> PerfTick { 0 }
+    /// Returns a bit-mask of detected CPU features ([libretro_sys]::SIMD_*).
     fn perf_get_cpu_features_cb(&mut self) -> u64 { 0 }
+    /// Asks frontend to log and/or display the state of performance counters.
+    /// Performance counters can always be poked into manually as well.
     fn perf_log_cb(&mut self) {}
+    /// Register a performance counter.
+    /// ident field must be set with a discrete value and other values in
+    /// retro_perf_counter must be 0.
+    /// Registering can be called multiple times. To avoid calling to
+    /// frontend redundantly, you can check registered field first.
     fn perf_register_cb(&mut self, counter: &mut PerfCounter) {}
+    /// Starts a registered counter.
     fn perf_start_cb(&mut self, counter: &mut PerfCounter) {}
+    /// Stops a registered counter.
     fn perf_stop_cb(&mut self, counter: &mut PerfCounter) {}
     fn set_sensor_state(&mut self, port: c_uint, action: SensorAction, rate: c_uint) -> bool { false }
     fn get_sensor_input(&mut self, port: c_uint, id: c_uint) -> f32 { 0.0 }
 }
 
+pub trait LibretroWrapperAccess {
+    fn libretro_core(&mut self) -> &mut LibretroWrapper;
+}
+
+pub trait RootRetroCallbacks : RetroCallbacks + LibretroWrapperAccess {}
+impl<T: RetroCallbacks + LibretroWrapperAccess> RootRetroCallbacks for T {}
+
 #[derive(Default)]
 struct StaticCallbacks {
-    handler: Option<Pin<&'static mut dyn Handler>>,
+    handler: Option<Pin<&'static mut dyn RootRetroCallbacks>>,
 }
 
 unsafe impl Sync for StaticCallbacks {}
@@ -108,7 +392,9 @@ impl StaticCallbacks {
         Some(true)
     }
     fn path_into_void(data: *mut c_void, source: impl AsRef<Path>) -> Option<bool> {
-        Self::string_into_void(data, source.as_ref().to_string_lossy())
+        *unsafe { (data as *mut *const c_char).as_mut()? } =
+            CString::new(source.as_ref().as_os_str().as_bytes()).ok()?.into_raw();
+        Some(true)
     }
     fn from_void<T>(data: *mut c_void) -> Option<&'static mut T> {
         unsafe { (data as *mut T).as_mut() }
@@ -146,17 +432,17 @@ impl StaticCallbacks {
             );
         }
         match parsed_cmd? {
-            EnvCmd::SetRotation => handler.set_rotation(Self::enum_from_void(data)?),
+            EnvCmd::SetRotation => handler.set_rotation(Self::enum_from_void(data)?)?,
             EnvCmd::GetOverscan => Self::clone_into_void(data, &handler.get_overscan()?)?,
-            EnvCmd::GetCanDupe => Self::clone_into_void(data, &handler.get_can_dupe()?)?,
+            EnvCmd::GetCanDupe => Self::clone_into_void(data, &true)?,
-            EnvCmd::SetMessage => handler.set_message(Self::from_void::<Message>(data)?.clone()),
+            EnvCmd::SetMessage => handler.set_message(Self::from_void::<Message>(data)?)?,
-            EnvCmd::Shutdown => handler.shutdown(),
+            EnvCmd::Shutdown => handler.shutdown()?,
-            EnvCmd::SetPerformanceLevel => handler.set_performance_level(*Self::from_void(data)?),
+            EnvCmd::SetPerformanceLevel => handler.set_performance_level(*Self::from_void(data)?)?,
             EnvCmd::GetSystemDirectory => {
                 Self::path_into_void(data, handler.get_system_directory()?)?
             }
             EnvCmd::SetPixelFormat => {
-                handler.set_pixel_format(PixelFormat::from_uint(*Self::from_void(data)?)?)
+                handler.set_pixel_format(PixelFormat::from_uint(*Self::from_void(data)?)?)?
             }
             EnvCmd::SetInputDescriptors => {
                 let mut input_desc = data as *const InputDescriptor;
@@ -165,7 +451,7 @@ impl StaticCallbacks {
                     descriptors.push(unsafe { input_desc.as_ref() }?.try_into().ok()?);
                     input_desc = input_desc.wrapping_add(1);
                 }
-                handler.set_input_descriptors(descriptors)
+                handler.set_input_descriptors(&descriptors)?
             }
             EnvCmd::SetKeyboardCallback => {
                 let kc: &mut KeyboardCallback = Self::from_void(data)?;
@@ -217,12 +503,12 @@ impl StaticCallbacks {
                     descriptors.push(unsafe { var.as_ref() }?.into());
                     var = var.wrapping_add(1);
                 }
-                handler.set_variables(descriptors)
+                handler.set_variables(&descriptors)?
             }
             EnvCmd::GetVariableUpdate => {
                 Self::clone_into_void(data, &handler.get_variable_update()?)?
             }
-            EnvCmd::SetSupportNoGame => handler.set_support_no_game(*Self::from_void(data)?),
+            EnvCmd::SetSupportNoGame => handler.set_support_no_game(*Self::from_void(data)?)?,
             EnvCmd::GetLibretroPath => Self::path_into_void(data, handler.get_libretro_path()?)?,
             EnvCmd::SetFrameTimeCallback => {
                 let ftc: &mut FrameTimeCallback = Self::from_void(data)?;
@@ -277,7 +563,7 @@ impl StaticCallbacks {
             }
             EnvCmd::GetSaveDirectory => Self::path_into_void(data, handler.get_save_directory()?)?,
             EnvCmd::SetSystemAvInfo => {
-                handler.set_system_av_info(Self::from_void::<SystemAvInfo>(data)?.clone())
+                handler.set_system_av_info(Self::from_void::<SystemAvInfo>(data)?)?
             }
             EnvCmd::SetProcAddressCallback => {
                 let gpa = Self::from_void::<GetProcAddressInterface>(data)?;
@@ -294,7 +580,7 @@ impl StaticCallbacks {
                     descriptors.push(unsafe { info.as_ref() }?.into());
                     info = info.wrapping_add(1);
                 }
-                handler.set_subsystem_info(descriptors)
+                handler.set_subsystem_info(&descriptors)?
             }
             EnvCmd::SetControllerInfo => {
                 let info = unsafe { (data as *const ControllerInfo).as_ref() }?;
@@ -305,11 +591,11 @@ impl StaticCallbacks {
                     .map(TryInto::try_into)
                     .filter_map(|x| x.ok())
                     .collect();
-                handler.set_controller_info(controller_info)
+                handler.set_controller_info(&controller_info)?
             }
             // TODO (experimental) EnvCmd::SetMemoryMaps => {},
             EnvCmd::SetGeometry => {
-                handler.set_geometry(Self::from_void::<GameGeometry>(data)?.clone())
+                handler.set_geometry(Self::from_void::<GameGeometry>(data)?)?
             }
             EnvCmd::GetUsername => Self::string_into_void(data, handler.get_username()?)?,
             EnvCmd::GetLanguage => Self::clone_into_void(data, &handler.get_language()?)?,
@@ -333,12 +619,14 @@ impl StaticCallbacks {
         height: c_uint,
         pitch: usize,
     ) {
-        if !data.is_null() && data != HW_FRAME_BUFFER_VALID {
         if let Some(cb) = unsafe { CB_SINGLETON.handler.as_mut() } {
+            if data.is_null() {
+                cb.video_refresh_dupe(width, height, pitch as c_uint);
+            } else if data != HW_FRAME_BUFFER_VALID {
                 let data = data as *const u8;
                 let len = pitch * (height as usize);
                 let slice = unsafe { from_raw_parts(data, len) };
-                cb.video_refresh(slice, width, height, pitch as u32);
+                cb.video_refresh(slice, width, height, pitch as c_uint);
             }
         }
     }
@@ -569,11 +857,17 @@ impl Deref for LibretroWrapper {
     }
 }
 
+impl DerefMut for LibretroWrapper {
+    fn deref_mut(&mut self) -> &mut LibretroApi {
+        &mut self.api
+    }
+}
+
 // a note on lifetimes: we explicitly lie about them here because as long as they live as long as
 //  the library wrapper itself we're good (we wipe our 'static references on drop() too)
-pub fn set_handler(handler: Pin<&'_ mut (dyn Handler + '_)>) {
+pub fn set_handler(handler: Pin<&'_ mut (dyn RootRetroCallbacks + '_)>) {
     unsafe {
-        let ptr = handler.get_unchecked_mut() as *mut dyn Handler;
+        let ptr = handler.get_unchecked_mut() as *mut dyn RootRetroCallbacks;
         CB_SINGLETON
             .handler
             .replace(Pin::new_unchecked(ptr.as_mut().unwrap()));