Trait Core

pub trait Core: CoreOptions {
    // Required methods
    fn get_info(&self) -> SystemInfo;
    fn on_get_av_info(
        &mut self,
        _ctx: &mut GetAvInfoContext<'_>,
    ) -> retro_system_av_info;

    // Provided methods
    fn on_set_environment(
        &mut self,
        _initial: bool,
        _ctx: &mut SetEnvironmentContext<'_>,
    ) { ... }
    fn on_init(&mut self, _ctx: &mut InitContext<'_>) { ... }
    fn on_deinit(&mut self, _ctx: &mut DeinitContext<'_>) { ... }
    fn on_set_controller_port_device(
        &mut self,
        _port: u32,
        _device: u32,
        _ctx: &mut GenericContext<'_>,
    ) { ... }
    fn on_reset(&mut self, _ctx: &mut ResetContext<'_>) { ... }
    fn on_run(&mut self, _ctx: &mut RunContext<'_>, _delta_us: Option<i64>) { ... }
    fn get_serialize_size(
        &mut self,
        _ctx: &mut GetSerializeSizeContext<'_>,
    ) -> usize { ... }
    fn on_serialize(
        &mut self,
        _slice: &mut [u8],
        _ctx: &mut SerializeContext<'_>,
    ) -> bool { ... }
    fn on_unserialize(
        &mut self,
        _slice: &mut [u8],
        _ctx: &mut UnserializeContext<'_>,
    ) -> bool { ... }
    fn on_load_game(
        &mut self,
        _game: Option<retro_game_info>,
        _ctx: &mut LoadGameContext<'_>,
    ) -> Result<(), Box<dyn Error>> { ... }
    fn on_load_game_special(
        &mut self,
        _game_type: c_uint,
        _info: *const retro_game_info,
        _num_info: usize,
        _ctx: &mut LoadGameSpecialContext<'_>,
    ) -> Result<(), Box<dyn Error>> { ... }
    fn on_unload_game(&mut self, _ctx: &mut UnloadGameContext<'_>) { ... }
    fn on_cheat_reset(&mut self, _ctx: &mut CheatResetContext<'_>) { ... }
    fn on_cheat_set(
        &mut self,
        _index: c_uint,
        _enabled: bool,
        _code: &CStr,
        _ctx: &mut CheatSetContext<'_>,
    ) { ... }
    fn on_get_region(&mut self, _ctx: &mut GetRegionContext<'_>) -> c_uint { ... }
    fn get_memory_data(
        &mut self,
        _id: c_uint,
        _ctx: &mut GetMemoryDataContext<'_>,
    ) -> *mut c_void { ... }
    fn get_memory_size(
        &mut self,
        _id: c_uint,
        _ctx: &mut GetMemorySizeContext<'_>,
    ) -> usize { ... }
    fn on_options_changed(&mut self, _ctx: &mut OptionsChangedContext<'_>) { ... }
    fn on_keyboard_event(
        &mut self,
        _down: bool,
        _keycode: retro_key,
        _character: u32,
        _key_modifiers: retro_mod,
    ) { ... }
    fn on_write_audio(&mut self, _ctx: &mut AudioContext<'_>) { ... }
    fn on_audio_set_state(&mut self, _enabled: bool) { ... }
    fn on_audio_buffer_status(
        &mut self,
        _active: bool,
        _occupancy: u32,
        _underrun_likely: bool,
    ) { ... }
    fn on_hw_context_reset(&mut self, _ctx: &mut GenericContext<'_>) { ... }
    fn on_hw_context_destroyed(&mut self, _ctx: &mut GenericContext<'_>) { ... }
    fn on_get_proc_address(
        &mut self,
        _symbol_name: &CStr,
    ) -> retro_proc_address_t { ... }
    fn on_location_lifetime_status_initialized(
        &mut self,
        _ctx: &mut GenericContext<'_>,
    ) { ... }
    fn on_location_lifetime_status_deinitialized(
        &mut self,
        _ctx: &mut GenericContext<'_>,
    ) { ... }
    fn on_camera_initialized(&mut self, _ctx: &mut GenericContext<'_>) { ... }
    fn on_camera_deinitialized(&mut self, _ctx: &mut GenericContext<'_>) { ... }
    fn on_camera_raw_framebuffer(
        &mut self,
        _buffer: &[u32],
        _width: u32,
        _height: u32,
        _pitch: usize,
    ) { ... }
    fn on_camera_gl_texture(
        &mut self,
        _texture_id: u32,
        _texture_target: u32,
        _affine_matrix: &[f32; 9],
    ) { ... }
    fn on_set_eject_state(&mut self, _ejected: bool) -> bool { ... }
    fn on_get_eject_state(&mut self) -> bool { ... }
    fn on_get_image_index(&mut self) -> u32 { ... }
    fn on_set_image_index(&mut self, _index: u32) -> bool { ... }
    fn on_get_num_images(&mut self) -> u32 { ... }
    fn on_replace_image_index(
        &mut self,
        _index: u32,
        _info: *const retro_game_info,
    ) -> bool { ... }
    fn on_add_image_index(&mut self) -> bool { ... }
    fn on_set_initial_image(&mut self, _index: u32, _path: &CStr) -> bool { ... }
    fn on_get_image_path(&mut self, _index: u32) -> Option<CString> { ... }
    fn on_get_image_label(&mut self, _index: u32) -> Option<CString> { ... }
    fn on_core_options_update_display(&mut self) -> bool { ... }
}

This trait defines the basic functions that every libretro core must implement. See also retro_core!().

Required Methods

fn get_info(&self) -> SystemInfo

Returns static info about this core.

fn on_get_av_info( &mut self, _ctx: &mut GetAvInfoContext<'_>, ) -> retro_system_av_info

Called when the frontend needs information about the audio and video timings and the video geometry.

Provided Methods

fn on_set_environment( &mut self, _initial: bool, _ctx: &mut SetEnvironmentContext<'_>, )

Called when the frontend set a new environment callback.

Guaranteed to be called before Core::on_init.

fn on_init(&mut self, _ctx: &mut InitContext<'_>)

Called when the libretro API has been initialized.

fn on_deinit(&mut self, _ctx: &mut DeinitContext<'_>)

Called when the libretro API gets destucted.

fn on_set_controller_port_device( &mut self, _port: u32, _device: u32, _ctx: &mut GenericContext<'_>, )

TODO: Documentation

fn on_reset(&mut self, _ctx: &mut ResetContext<'_>)

Called when the frontend requests resetting the system.

fn on_run(&mut self, _ctx: &mut RunContext<'_>, _delta_us: Option<i64>)

Called once per frame

If a frame is not rendered for reasons where a game “dropped” a frame, this still counts as a frame, and Core::on_run should explicitly dupe a frame if environment::can_dupe returns true. In this case, the video callback can take a NULL argument for data.

fn get_serialize_size( &mut self, _ctx: &mut GetSerializeSizeContext<'_>, ) -> usize

Returns the amount of data the implementation requires to serialize internal state (save states).

Between calls to Core::on_load_game and Core::on_unload_game, the returned size is never allowed to be larger than a previous returned value, to ensure that the frontend can allocate a save state buffer once.

fn on_serialize( &mut self, _slice: &mut [u8], _ctx: &mut SerializeContext<'_>, ) -> bool

Serializes internal state. If failed, or size is lower than Core::get_serialize_size, it should return false, [`true’] otherwise.

fn on_unserialize( &mut self, _slice: &mut [u8], _ctx: &mut UnserializeContext<'_>, ) -> bool

Deserializes internal state.

TODO: Documentation

fn on_load_game( &mut self, _game: Option<retro_game_info>, _ctx: &mut LoadGameContext<'_>, ) -> Result<(), Box<dyn Error>>

Called when a game should be loaded. Return true to indicate successful loading and false to indicate load failure.

fn on_load_game_special( &mut self, _game_type: c_uint, _info: *const retro_game_info, _num_info: usize, _ctx: &mut LoadGameSpecialContext<'_>, ) -> Result<(), Box<dyn Error>>

Loads a “special” kind of game. Should not be used, except in extreme cases.

TODO: Better documentation. What’s a “special” game?

fn on_unload_game(&mut self, _ctx: &mut UnloadGameContext<'_>)

Called when the currently loaded game should be unloaded. Called before Core::on_deinit.

fn on_cheat_reset(&mut self, _ctx: &mut CheatResetContext<'_>)

Instructs the core to remove all applied cheats.

fn on_cheat_set( &mut self, _index: c_uint, _enabled: bool, _code: &CStr, _ctx: &mut CheatSetContext<'_>, )

TODO: Documentation

fn on_get_region(&mut self, _ctx: &mut GetRegionContext<'_>) -> c_uint

Gets the region of the game.

Can be any of:

• RETRO_REGION_NTSC
• RETRO_REGION_PAL

fn get_memory_data( &mut self, _id: c_uint, _ctx: &mut GetMemoryDataContext<'_>, ) -> *mut c_void

TODO: Documentation

fn get_memory_size( &mut self, _id: c_uint, _ctx: &mut GetMemorySizeContext<'_>, ) -> usize

TODO: Documentation

fn on_options_changed(&mut self, _ctx: &mut OptionsChangedContext<'_>)

Gets called when the core options have been changed.

Options get checked before Core::on_load_game, Core::on_load_game_special and before each call of Core::on_run.

fn on_keyboard_event( &mut self, _down: bool, _keycode: retro_key, _character: u32, _key_modifiers: retro_mod, )

TODO: Documentation

fn on_write_audio(&mut self, _ctx: &mut AudioContext<'_>)

Called when the frontend needs more audio frames

fn on_audio_set_state(&mut self, _enabled: bool)

TODO: Documentation

fn on_audio_buffer_status( &mut self, _active: bool, _occupancy: u32, _underrun_likely: bool, )

TODO: Documentation

fn on_hw_context_reset(&mut self, _ctx: &mut GenericContext<'_>)

TODO: Documentation

fn on_hw_context_destroyed(&mut self, _ctx: &mut GenericContext<'_>)

TODO: Documentation

fn on_get_proc_address(&mut self, _symbol_name: &CStr) -> retro_proc_address_t

TODO: Documentation

fn on_location_lifetime_status_initialized( &mut self, _ctx: &mut GenericContext<'_>, )

TODO: Documentation

fn on_location_lifetime_status_deinitialized( &mut self, _ctx: &mut GenericContext<'_>, )

TODO: Documentation

fn on_camera_initialized(&mut self, _ctx: &mut GenericContext<'_>)

TODO: Documentation

fn on_camera_deinitialized(&mut self, _ctx: &mut GenericContext<'_>)

TODO: Documentation

fn on_camera_raw_framebuffer( &mut self, _buffer: &[u32], _width: u32, _height: u32, _pitch: usize, )

TODO: Documentation

fn on_camera_gl_texture( &mut self, _texture_id: u32, _texture_target: u32, _affine_matrix: &[f32; 9], )

TODO: Documentation

fn on_set_eject_state(&mut self, _ejected: bool) -> bool

TODO: Documentation

fn on_get_eject_state(&mut self) -> bool

TODO: Documentation

fn on_get_image_index(&mut self) -> u32

TODO: Documentation

fn on_set_image_index(&mut self, _index: u32) -> bool

TODO: Documentation

fn on_get_num_images(&mut self) -> u32

TODO: Documentation

fn on_replace_image_index( &mut self, _index: u32, _info: *const retro_game_info, ) -> bool

TODO: Documentation

fn on_add_image_index(&mut self) -> bool

TODO: Documentation

fn on_set_initial_image(&mut self, _index: u32, _path: &CStr) -> bool

TODO: Documentation

fn on_get_image_path(&mut self, _index: u32) -> Option<CString>

TODO: Documentation

fn on_get_image_label(&mut self, _index: u32) -> Option<CString>

TODO: Documentation

fn on_core_options_update_display(&mut self) -> bool

TODO: Documentation

Implementors