document env callbacks & continue sketching component api

examples/ffmpeg_recorder.rs

@@ -11,7 +11,7 @@ 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};
 
@@ -234,7 +234,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
     }
     
@@ -393,7 +393,7 @@ static bool ffmpeg_init_config(struct ff_config_param *params,
     }
 }
 
-impl retro::wrapper::Handler for MyEmulator {
+impl retro::wrapper::RetroCallbacks for MyEmulator {
     fn libretro_core(&mut self) -> &mut LibretroWrapper {
         &mut self.retro
     }
@@ -454,7 +454,7 @@ impl retro::wrapper::Handler for MyEmulator {
         true
     }
 
-    fn set_system_av_info(&mut self, system_av_info: SystemAvInfo) -> bool {
+    fn set_system_av_info(&mut self, system_av_info: &SystemAvInfo) -> bool {
         if self.frame_properties_locked {
             return true;
         }
@@ -466,11 +466,11 @@ impl retro::wrapper::Handler for MyEmulator {
             self.audio_encoder.set_rate(system_av_info.timing.sample_rate.round() as i32);
         }
         self.av_info.timing = system_av_info.timing;
-        self.set_geometry(system_av_info.geometry);
+        self.set_geometry(&system_av_info.geometry);
         true
     }
 
-    fn set_geometry(&mut self, geometry: GameGeometry) -> bool {
+    fn set_geometry(&mut self, geometry: &GameGeometry) -> bool {
         if self.frame_properties_locked {
             return true;
         }
@@ -478,7 +478,7 @@ impl retro::wrapper::Handler for MyEmulator {
         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,

examples/sdl2_emulator.rs

@@ -204,7 +204,7 @@ impl Drop for MyEmulator {
     }
 }
 
-impl retro::wrapper::Handler for MyEmulator {
+impl retro::wrapper::RetroCallbacks for MyEmulator {
     fn libretro_core(&mut self) -> &mut LibretroWrapper {
         &mut self.retro
     }
@@ -262,8 +262,6 @@ 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()
     }
@@ -305,9 +303,9 @@ impl retro::wrapper::Handler for MyEmulator {
         Some(std::env::temp_dir())
     }
 
-    fn set_system_av_info(&mut self, av_info: SystemAvInfo) -> bool {
-        self.set_geometry(av_info.geometry.clone());
-        self.av_info = av_info;
+    fn set_system_av_info(&mut self, av_info: &SystemAvInfo) -> bool {
+        self.set_geometry(&av_info.geometry);
+        self.av_info = av_info.clone();
         true
     }
 
@@ -334,10 +332,10 @@ impl retro::wrapper::Handler for MyEmulator {
         true
     }
 
-    fn set_geometry(&mut self, geom: GameGeometry) -> bool {
+    fn set_geometry(&mut self, geom: &GameGeometry) -> 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
     }
 

src/components/mod.rs

@@ -0,0 +1,261 @@
+use crate::prelude::*;
+use std::os::raw::c_uint;
+use std::rc::Rc;
+use crate::retro::ffi::{Message, PixelFormat, HwRenderCallback, SensorInterface, CameraCallback, LogCallback, PerfCallback, LocationCallback, SystemAvInfo, GetProcAddressInterface, MemoryMap, GameGeometry, Language, LogLevel, RumbleEffect, Time, PerfTick, PerfCounter, SensorAction};
+use std::path::PathBuf;
+
+#[rustfmt::skip]
+#[allow(unused)]
+pub trait RetroAvCommonComponent {
+    fn set_system_av_info(&mut self, system_av_info: &SystemAvInfo) -> bool { false }
+}
+
+#[rustfmt::skip]
+#[allow(unused)]
+pub trait RetroVideoComponent: RetroAvCommonComponent {
+    fn video_refresh(&mut self, data: &[u8], width: c_uint, height: c_uint, pitch: c_uint) {}
+    // -- environment callbacks --
+    fn set_rotation(&mut self, rotation: EnvRotation) -> bool { false }
+    fn get_overscan(&mut self) -> Option<bool> { None }
+    fn set_pixel_format(&mut self, format: PixelFormat) -> bool { false }
+    fn set_hw_render(&mut self, hw_render_callback: &HwRenderCallback) -> bool { false }
+    fn set_geometry(&mut self, game_geometry: &GameGeometry) -> bool { false }
+}
+
+#[rustfmt::skip]
+#[allow(unused)]
+pub trait RetroAudioComponent: RetroAvCommonComponent {
+    fn audio_sample(&mut self, left: i16, right: i16) {}
+    fn audio_sample_batch(&mut self, stereo_pcm: &[i16]) -> usize { 0 }
+}
+
+pub struct RetroComponentBase {
+    retro: LibretroWrapper,
+    pub video_comps: Vec<Rc<dyn RetroVideoComponent>>,
+    pub audio_comps: Vec<Rc<dyn RetroAudioComponent>>,
+}
+
+#[allow(unused)]
+impl RetroCallbacks for RetroComponentBase {
+    fn libretro_core(&mut self) -> &mut LibretroWrapper {
+        &mut self.retro
+    }
+
+    fn video_refresh(&mut self, data: &[u8], width: c_uint, height: c_uint, pitch: c_uint) {
+        for vc in &mut self.video_comps {
+            // FIXME: can't have more than 1 ref!
+            //  get_mut fails if one component struct impls both Audio&Video!
+            Rc::get_mut(vc).unwrap().video_refresh(data, width, height, pitch);
+        }
+    }
+
+    fn video_refresh_dupe(&mut self, width: c_uint, height: c_uint, pitch: c_uint) {
+        todo!()
+    }
+
+    fn audio_sample(&mut self, left: i16, right: i16) {
+        todo!()
+    }
+
+    fn audio_sample_batch(&mut self, stereo_pcm: &[i16]) -> usize {
+        todo!()
+    }
+
+    fn input_poll(&mut self) {
+        todo!()
+    }
+
+    fn input_state(&mut self, port: u32, device: InputDeviceId, index: InputIndex) -> i16 {
+        todo!()
+    }
+
+    fn set_rotation(&mut self, rotation: EnvRotation) -> bool {
+        self.video_comps.iter_mut()
+            .map(|x| Rc::get_mut(x).unwrap().set_rotation(rotation))
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+    }
+
+    fn get_overscan(&mut self) -> Option<bool> {
+        self.video_comps.iter_mut()
+            .map(|x| Rc::get_mut(x).unwrap().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) -> bool {
+        todo!()
+    }
+
+    fn shutdown(&mut self) -> bool {
+        todo!()
+    }
+
+    fn set_performance_level(&mut self, level: c_uint) -> bool {
+        todo!()
+    }
+
+    fn get_system_directory(&mut self) -> Option<PathBuf> {
+        todo!()
+    }
+
+    fn set_pixel_format(&mut self, format: PixelFormat) -> bool {
+        self.video_comps.iter_mut()
+            .map(|x| Rc::get_mut(x).unwrap().set_pixel_format(format))
+            .all(|x| x)
+    }
+
+    fn set_input_descriptors(&mut self, input_descriptors: Vec<InputDescriptor2>) -> bool {
+        todo!()
+    }
+
+    fn set_hw_render(&mut self, hw_render_callback: &HwRenderCallback) -> bool {
+        self.video_comps.iter_mut()
+            .map(|x| Rc::get_mut(x).unwrap().set_hw_render(hw_render_callback))
+            .all(|x| x)
+    }
+
+    fn get_variable(&mut self, key: &str) -> Option<String> {
+        todo!()
+    }
+
+    fn set_variables(&mut self, variables: Vec<Variable2>) -> bool {
+        todo!()
+    }
+
+    fn get_variable_update(&mut self) -> Option<bool> {
+        todo!()
+    }
+
+    fn set_support_no_game(&mut self, supports_no_game: bool) -> bool {
+        todo!()
+    }
+
+    fn get_libretro_path(&mut self) -> Option<PathBuf> {
+        todo!()
+    }
+
+    fn get_input_device_capabilities(&mut self) -> Option<u64> {
+        todo!()
+    }
+
+    fn get_sensor_interface(&mut self) -> Option<SensorInterface> {
+        todo!()
+    }
+
+    fn get_camera_interface(&mut self) -> Option<CameraCallback> {
+        todo!()
+    }
+
+    fn get_log_interface(&mut self) -> Option<LogCallback> {
+        todo!()
+    }
+
+    fn get_perf_interface(&mut self) -> Option<PerfCallback> {
+        todo!()
+    }
+
+    fn get_location_interface(&mut self) -> Option<LocationCallback> {
+        todo!()
+    }
+
+    fn get_core_assets_directory(&mut self) -> Option<PathBuf> {
+        todo!()
+    }
+
+    fn get_save_directory(&mut self) -> Option<PathBuf> {
+        todo!()
+    }
+
+    fn set_system_av_info(&mut self, system_av_info: &SystemAvInfo) -> bool {
+        // TODO: avoid calling twice for components that are registered in both simultaneously
+
+        let mut result = false;
+
+        for vc in &mut self.video_comps {
+            result |= Rc::get_mut(vc).unwrap().set_system_av_info(system_av_info);
+        }
+
+        for ac in &mut self.audio_comps {
+            result |= Rc::get_mut(ac).unwrap().set_system_av_info(system_av_info);
+        }
+
+        result
+    }
+
+    fn set_proc_address_callback(&mut self, cb: GetProcAddressInterface) -> bool {
+        todo!()
+    }
+
+    fn set_subsystem_info(&mut self, subsystem_info: Vec<SubsystemInfo2>) -> bool {
+        todo!()
+    }
+
+    fn set_controller_info(&mut self, controller_info: Vec<ControllerDescription2>) -> bool {
+        todo!()
+    }
+
+    fn set_memory_maps(&mut self, memory_map: MemoryMap) -> bool {
+        todo!()
+    }
+
+    fn set_geometry(&mut self, game_geometry: &GameGeometry) -> bool {
+        self.video_comps.iter_mut()
+            .map(|x| Rc::get_mut(x).unwrap().set_geometry(game_geometry))
+            .fold(false, |x, y| x || y) // not "any" because we don't short-circuit
+    }
+
+    fn get_username(&mut self) -> Option<String> {
+        todo!()
+    }
+
+    fn get_language(&mut self) -> Option<Language> {
+        todo!()
+    }
+
+    fn log_print(&mut self, level: LogLevel, msg: &str) {
+        todo!()
+    }
+
+    fn set_rumble_state(&mut self, port: c_uint, effect: RumbleEffect, strength: u16) -> bool {
+        todo!()
+    }
+
+    fn perf_get_time_usec_cb(&mut self) -> Time {
+        todo!()
+    }
+
+    fn perf_get_counter_cb(&mut self) -> PerfTick {
+        todo!()
+    }
+
+    fn perf_get_cpu_features_cb(&mut self) -> u64 {
+        todo!()
+    }
+
+    fn perf_log_cb(&mut self) {
+        todo!()
+    }
+
+    fn perf_register_cb(&mut self, counter: &mut PerfCounter) {
+        todo!()
+    }
+
+    fn perf_start_cb(&mut self, counter: &mut PerfCounter) {
+        todo!()
+    }
+
+    fn perf_stop_cb(&mut self, counter: &mut PerfCounter) {
+        todo!()
+    }
+
+    fn set_sensor_state(&mut self, port: c_uint, action: SensorAction, rate: c_uint) -> bool {
+        todo!()
+    }
+
+    fn get_sensor_input(&mut self, port: c_uint, id: c_uint) -> f32 {
+        todo!()
+    }
+}

src/lib.rs

@@ -2,3 +2,10 @@ extern crate failure;
 extern crate libloading;
 
 pub mod retro;
+pub mod components;
+
+pub mod prelude {
+    pub use crate::retro::constants::*;
+    pub use crate::retro::wrapped_types::*;
+    pub use crate::retro::wrapper::{RetroCallbacks, LibretroWrapper};
+}

src/retro/constants.rs

@@ -4,7 +4,7 @@ use super::ffi::*;
 
 // NB: commented-out stuff is from newer versions of libretro.h not yet represented in libretro-sys
 
-#[derive(TryFromPrimitive, IntoPrimitive, Debug, Clone, Copy)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum DeviceType {
     None = DEVICE_NONE,
@@ -23,7 +23,7 @@ impl DeviceType {
     }
 }
 
-#[derive(TryFromPrimitive, IntoPrimitive, Debug)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum InputIndex {
     Left = DEVICE_INDEX_ANALOG_LEFT,
@@ -31,7 +31,7 @@ pub enum InputIndex {
     // Button = DEVICE_INDEX_ANALOG_BUTTON,
 }
 
-#[derive(TryFromPrimitive, IntoPrimitive, Debug)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum JoypadButton {
     B = DEVICE_ID_JOYPAD_B,
@@ -52,14 +52,14 @@ pub enum JoypadButton {
     R3 = DEVICE_ID_JOYPAD_R3,
 }
 
-#[derive(TryFromPrimitive, IntoPrimitive, Debug)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum AnalogAxis {
     X = DEVICE_ID_ANALOG_X,
     Y = DEVICE_ID_ANALOG_Y,
 }
 
-#[derive(TryFromPrimitive, IntoPrimitive, Debug)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum MouseButton {
     X = DEVICE_ID_MOUSE_X,
@@ -73,7 +73,7 @@ pub enum MouseButton {
     HorizWheelDown = DEVICE_ID_MOUSE_HORIZ_WHEELDOWN,
 }
 
-#[derive(TryFromPrimitive, IntoPrimitive, Debug)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum LightGunButton {
     // ScreenX = DEVICE_ID_LIGHTGUN_SCREEN_X,
@@ -95,7 +95,7 @@ pub enum LightGunButton {
     Pause = DEVICE_ID_LIGHTGUN_PAUSE,
 }
 
-#[derive(TryFromPrimitive, IntoPrimitive, Debug)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum PointerStat {
     X = DEVICE_ID_POINTER_X,
@@ -103,7 +103,7 @@ pub enum PointerStat {
     Pressed = DEVICE_ID_POINTER_PRESSED,
 }
 
-#[derive(TryFromPrimitive, IntoPrimitive)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum EnvRotation {
     None = 0,
@@ -113,7 +113,7 @@ pub enum EnvRotation {
 }
 
 // TODO: experimental calls
-#[derive(TryFromPrimitive, IntoPrimitive, Debug)]
+#[derive(TryFromPrimitive, IntoPrimitive, Clone, Copy, Debug)]
 #[repr(u32)]
 pub enum EnvCmd {
     SetRotation = ENVIRONMENT_SET_ROTATION,

src/retro/wrapper.rs

@@ -30,48 +30,339 @@ extern "C" {
 
 #[rustfmt::skip]
 #[allow(unused)]
-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 }
+    fn delegate_handler(&self) -> Option<&mut dyn RetroCallbacks> { None }
 
     // -- main callbacks --
     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) {}
     fn audio_sample(&mut self, left: i16, right: i16) {}
     fn audio_sample_batch(&mut self, stereo_pcm: &[i16]) -> usize { stereo_pcm.len() }
     fn input_poll(&mut self) {}
     fn input_state(&mut self, port: u32, device: InputDeviceId, index: InputIndex) -> i16 { 0 }
 
     // -- environment callbacks --
+    /// 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) -> bool { false }
+    /// 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
+    /// for a certain amount of 'frames'.
+    /// Should not be used for trivial messages, which should simply be
+    /// logged via [Self::get_log_interface] (or as a
+    /// fallback, stderr).
     fn set_message(&mut self, message: Message) -> bool { false }
+    /// 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) -> bool { false }
+    /// 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) -> bool { false }
+    /// 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 }
+    /// Sets the internal pixel format used by the implementation.
+    /// The default pixel format is [libretro_sys::PixelFormat::ARGB1555].
+    /// 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) -> bool { false }
+    /// 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>) -> bool { false }
-    fn set_hw_render(&mut self, hw_render_callback: HwRenderCallback) -> bool { false }
+    /// 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) -> bool { false }
+    /// 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 }
+    /// 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>) -> bool { false }
+    /// 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 }
+    /// 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) -> bool { false }
+    /// 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 }
+    /// Gets access to the sensor interface.
+    /// The purpose of this interface is to allow
+    /// setting state related to sensors such as polling rate,
+    /// enabling/disable it entirely, etc.
+    /// Reading sensor state is done via the normal
+    /// [Self::input_state] API.
     fn get_sensor_interface(&mut self) -> Option<SensorInterface> { None }
+    /// Gets an interface to a video camera driver.
+    /// A libretro core can use this interface to get access to a
+    /// video camera.
+    /// New video frames are delivered in a callback in same
+    /// thread as [libretro_sys::CoreAPI::retro_run].
+    ///
+    /// GET_CAMERA_INTERFACE should be called in [libretro_sys::CoreAPI::retro_load_game]().
+    ///
+    /// Depending on the camera implementation used, camera frames
+    /// will be delivered as a raw framebuffer,
+    /// or as an OpenGL texture directly.
+    ///
+    /// The core has to tell the frontend here which types of
+    /// buffers can be handled properly.
+    /// An OpenGL texture can only be handled when using a
+    /// libretro GL core ([Self::set_hw_render]).
+    /// It is recommended to use a libretro GL core when
+    /// using camera interface.
+    ///
+    /// The camera is not started automatically. The retrieved start/stop
+    /// functions must be used to explicitly
+    /// start and stop the camera driver.
     fn get_camera_interface(&mut self) -> Option<CameraCallback> { None }
+    /// Gets an interface for logging. This is useful for
+    /// logging in a cross-platform way
+    /// as certain platforms cannot use stderr for logging.
+    /// It also allows the frontend to
+    /// show logging information in a more suitable way.
+    /// If this interface is not used, libretro cores should
+    /// log to stderr as desired.
     fn get_log_interface(&mut self) -> Option<LogCallback> { None }
+    /// Gets an interface for performance counters. This is useful
+    /// for performance logging in a cross-platform way and for detecting
+    /// architecture-specific features, such as SIMD support.
     fn get_perf_interface(&mut self) -> Option<PerfCallback> { None }
+    /// Gets access to the location interface.
+    /// The purpose of this interface is to be able to retrieve
+    /// location-based information from the host device,
+    /// such as current latitude / longitude.
     fn get_location_interface(&mut self) -> Option<LocationCallback> { None }
+    /// Returns the "core assets" directory of the frontend.
+    /// This directory can be used to store specific assets that the
+    /// core relies upon, such as art assets,
+    /// input data, etc 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.
     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
+    /// within [libretro_sys::CoreAPI::retro_run].
+    /// This should *only* be used if the core is completely altering the
+    /// internal resolutions, aspect ratios, timings, sampling rate, etc.
+    /// Calling this can require a full reinitialization of video/audio
+    /// 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) -> bool { false }
+    /// Allows a libretro core to announce support for the
+    /// get_proc_address() interface.
+    /// This interface allows for a standard way to extend libretro where
+    /// use of environment calls are too indirect,
+    /// e.g. for cases where the frontend wants to call directly into the core.
+    ///
+    /// If a core wants to expose this interface, [Self::set_proc_address_callback]
+    /// **MUST** be called from within [libretro_sys::CoreAPI::retro_set_environment].
     fn set_proc_address_callback(&mut self, cb: GetProcAddressInterface) -> bool { false }
+    /// 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>) -> bool { false }
+    /// 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>) -> bool { false }
+    /// 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) -> bool { false }
-    fn set_geometry(&mut self, game_geometry: GameGeometry) -> bool { false }
+    /// 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) -> bool { false }
+    /// 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 }
 
@@ -91,7 +382,7 @@ pub trait Handler: Unpin + 'static {
 
 #[derive(Default)]
 struct StaticCallbacks {
-    handler: Option<Pin<&'static mut dyn Handler>>,
+    handler: Option<Pin<&'static mut dyn RetroCallbacks>>,
 }
 
 unsafe impl Sync for StaticCallbacks {}
@@ -148,7 +439,7 @@ impl StaticCallbacks {
         match parsed_cmd? {
             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::Shutdown => handler.shutdown(),
             EnvCmd::SetPerformanceLevel => handler.set_performance_level(*Self::from_void(data)?),
@@ -277,7 +568,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)?;
@@ -309,7 +600,7 @@ impl StaticCallbacks {
             }
             // 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 +624,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 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);
             }
         }
     }
@@ -571,9 +864,9 @@ impl Deref for LibretroWrapper {
 
 // 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 RetroCallbacks + '_)>) {
     unsafe {
-        let ptr = handler.get_unchecked_mut() as *mut dyn Handler;
+        let ptr = handler.get_unchecked_mut() as *mut dyn RetroCallbacks;
         CB_SINGLETON
             .handler
             .replace(Pin::new_unchecked(ptr.as_mut().unwrap()));