378 lines
20 KiB
Rust
378 lines
20 KiB
Rust
use std::os::raw::{c_char, c_uint};
|
|
use std::path::PathBuf;
|
|
|
|
use crate::retro::constants::*;
|
|
use crate::retro::ffi::*;
|
|
use crate::retro::wrapped_types::*;
|
|
use crate::retro::wrapper::LibretroWrapper;
|
|
|
|
// stable Rust doesn't have varargs, so we can't represent a callback with the signature of
|
|
// void (*retro_log_printf_t)(enum retro_log_level level, const char* fmt, ...)
|
|
// without a little help from an Actual-C wrapper.
|
|
pub type WrappedLogPrintFn = extern "C" fn(level: LogLevel, fmt: *const c_char);
|
|
|
|
extern "C" {
|
|
pub(crate) fn c_ext_handle_get_log_interface(cb: *mut LogCallback) -> bool;
|
|
pub(crate) fn c_ext_set_log_print_cb(cb: WrappedLogPrintFn);
|
|
}
|
|
|
|
/// This trait represents all the callbacks in the libretro API (including `retro_environment`
|
|
/// extensions), wrapped as methods on `&mut self`, all optional with default no-op implementations.
|
|
///
|
|
/// NOTE: Most of the method docs provided here are adapted to Rust from the ones written in
|
|
/// libretro.h, and many of them are descriptions of the API contract written with an intended
|
|
/// audience of backend/core authors.
|
|
//noinspection RsSelfConvention
|
|
#[rustfmt::skip]
|
|
#[allow(unused_variables)]
|
|
pub trait RetroCallbacks: Unpin + 'static {
|
|
// -- 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, frame: &VideoFrame) {}
|
|
/// Renders audio frames.
|
|
///
|
|
/// 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.
|
|
/// Format is signed 16-bit native endian PCM.
|
|
///
|
|
/// The frontend should return the number of frames used (stereo slice length divided by two!)
|
|
fn audio_samples(&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 --
|
|
/// 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 }
|
|
/// 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 `retro_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 [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 }
|
|
/// 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 [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 [InputDescriptor2](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: &[InputDescriptor2]) -> Option<bool> { None }
|
|
/// Sets an interface to let a libretro core render with
|
|
/// hardware acceleration.
|
|
/// The core should call this in [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 [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 }
|
|
/// 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 [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.
|
|
///
|
|
/// [Variable2::key](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'.
|
|
///
|
|
/// [Variable2::description](crate::prelude::Variable2::description) should contain a human readable
|
|
/// description of the key.
|
|
///
|
|
/// [Variable2::options](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: &[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 }
|
|
/// If true, the libretro implementation supports calls to
|
|
/// [CoreAPI::retro_load_game] with NULL as argument.
|
|
/// Used by cores which can run without particular game data.
|
|
/// This should be called within [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 [CoreAPI::retro_run].
|
|
fn get_input_device_capabilities(&mut self) -> Option<u64> { 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 ([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 }
|
|
/// Sets a new av_info structure. This can only be called from
|
|
/// within [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 [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 [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 [CoreAPI::retro_load_game_special],
|
|
/// and this environment call allows a libretro core to expose which
|
|
/// subsystems are supported for use with [CoreAPI::retro_load_game_special].
|
|
///
|
|
/// If a core wants to expose this interface, [Self::set_subsystem_info]
|
|
/// **MUST** be called from within [CoreAPI::retro_set_environment].
|
|
fn set_subsystem_info(&mut self, subsystem_info: &[SubsystemInfo2]) -> Option<bool> { None }
|
|
/// This environment call lets a libretro core tell the frontend
|
|
/// which controller subclasses are recognized in calls to
|
|
/// [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 [ControllerDescription2](crate::prelude::ControllerDescription2). Each element of the
|
|
/// array corresponds to the ascending port index
|
|
/// that is passed to [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 [ControllerDescription2](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: &[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
|
|
/// [CoreAPI::retro_get_memory_data] and
|
|
/// [CoreAPI::retro_get_memory_size] as well.
|
|
///
|
|
/// Can be called from [CoreAPI::retro_init] and [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 [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) -> 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 [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(&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(&mut self) -> PerfTick { 0 }
|
|
/// Returns a bit-mask of detected CPU features ([libretro_sys]::SIMD_*).
|
|
fn perf_get_cpu_features(&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(&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(&mut self, counter: &mut PerfCounter) {}
|
|
/// Starts a registered counter.
|
|
fn perf_start(&mut self, counter: &mut PerfCounter) {}
|
|
/// Stops a registered counter.
|
|
fn perf_stop(&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 }
|
|
fn get_camera_interface(&mut self, width: c_uint, height: c_uint, cap_raw_fb: bool, cap_gl_tex: bool) -> Option<bool> { None }
|
|
/// Starts the camera driver. Can only be called in retro_run().
|
|
fn camera_start(&mut self) -> Option<bool> { None }
|
|
/// Stops the camera driver. Can only be called in retro_run().
|
|
fn camera_stop(&mut self) -> Option<()> { None }
|
|
/// Gets current framebuffer which is to be rendered to.
|
|
/// Could change every frame potentially.
|
|
fn hw_get_current_framebuffer(&mut self) -> Option<usize> { None }
|
|
/// Get a symbol from HW context.
|
|
fn hw_get_proc_address(&mut self, sym: &str) -> Option<*const ()> { None }
|
|
}
|
|
|
|
pub trait LibretroWrapperAccess {
|
|
fn libretro_core(&mut self) -> &mut LibretroWrapper;
|
|
}
|
|
|
|
pub trait RootRetroCallbacks: RetroCallbacks + LibretroWrapperAccess {}
|
|
|
|
impl<T: RetroCallbacks + LibretroWrapperAccess> RootRetroCallbacks for T {}
|