Struct SetEnvironmentContext

pub struct SetEnvironmentContext<'a> {
    pub(crate) environment_callback: &'a retro_environment_t,
    pub(crate) interfaces: Arc<RwLock<InterfaceList>>,
}

Functions that are safe to be called in Core::on_set_environment

Fields

environment_callback: &'a retro_environment_t

interfaces: Arc<RwLock<InterfaceList>>

Implementations

impl<'a> SetEnvironmentContext<'a>

pub(crate) fn new( environment_callback: &'a retro_environment_t, interfaces: Arc<RwLock<InterfaceList>>, ) -> Self

impl<'a> SetEnvironmentContext<'a>

pub fn enable_proc_address_interface(&mut self) -> bool

pub fn enable_options_update_display_callback(&mut self) -> bool

pub unsafe fn enable_vfs_interface( &mut self, min_version: u32, ) -> Result<u32, Box<dyn Error>>

Unstable

This feature is unstable and guarded by the unstable-env-commands feature flag.

Please be advised that this feature might change without further notice and no guarantees about its stability can be made.

impl SetEnvironmentContext<'_>

pub fn set_variables(&self, variables: &[retro_variable]) -> bool

Allows an implementation to signal the environment which variables it might want to check for later using get_variable. This allows the frontend to present these variables to a user dynamically. This should be called the first time as early as possible (ideally in Core::on_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.

The passed array of retro_variable structs must be terminated by a

retro_variable {
    key:   0 as *const libc::c_char,
    value: 0 as *const libc::c_char,
}

element. retro_variable::key should be namespaced to not collide with other implementations’ keys. E.g. A core called ‘foo’ should use keys named as foo_option. retro_variable::value should contain a human readable description of the key as well as a | delimited 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.

First entry should be treated as a default.

Examples

retro_variable {
    key:   b"foo_option" as *const u8 as *const libc::c_char,
    value: b"Speed hack coprocessor X; false|true" as *const u8 as *const libc::c_char,
}

Text before the first ; is a description. This ; must be followed by a space, and followed by a list of possible values split up with |.

Only strings are operated on. The possible values will generally be displayed and stored as-is by the frontend.

impl SetEnvironmentContext<'_>

pub fn set_support_no_game(&self, value: bool) -> bool

Tell the frontend whether this Core can run without particular game data.

If true, the Core implementation supports calls to Core::on_load_game with None as argument.

impl SetEnvironmentContext<'_>

pub fn set_proc_address_callback( &self, data: retro_get_proc_address_interface, ) -> bool

Allows a libretro core to announce support for the retro_get_proc_address_interface 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, set_proc_address_callback MUST be called from within Core::on_set_environment.

impl SetEnvironmentContext<'_>

pub fn set_subsystem_info(&self, data: &[retro_subsystem_info]) -> bool

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 Core::on_load_game_special, and this environment call allows a libretro core to expose which subsystems are supported for use with Core::on_load_game_special. A core passes an array of retro_game_info which is terminated with a zeroed out retro_game_info struct.

If a core wants to use this functionality, set_subsystem_info MUST be called from within Core::on_set_environment.

impl SetEnvironmentContext<'_>

pub unsafe fn get_vfs_interface( &self, data: retro_vfs_interface_info, ) -> Option<retro_vfs_interface_info>

Unstable Gets access to the VFS interface. VFS presence needs to be queried prior to load_game or any get_system/save/other_directory being called to let front end know core supports VFS before it starts handing out paths. It is recomended to do so in Core::on_set_environment.

This feature is unstable and guarded by the unstable-env-commands feature flag.

Please be advised that this feature might change without further notice and no guarantees about its stability can be made.

impl SetEnvironmentContext<'_>

pub fn supports_set_core_options(&self) -> bool

Checks whether the frontend supports the set_core_options interface.

impl SetEnvironmentContext<'_>

pub fn supports_set_core_options_v2(&self) -> bool

Checks whether the frontend supports the set_core_options_v2 interface.

impl SetEnvironmentContext<'_>

pub fn set_core_options(&self, options: &[retro_core_option_definition]) -> bool

Allows an implementation to signal the environment which variables it might want to check for later using get_variable. This allows the frontend to present these variables to a user dynamically. This should only be called if get_core_options_version returns an API version of >= 1. This should be called instead of set_variables. This should be called the first time as early as possible (ideally in Core::on_set_environment). Afterwards 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.

‘data’ points to an array of retro_core_option_definition structs terminated by a { NULL, NULL, NULL, {{0}}, NULL } element. retro_core_option_definition::key should be namespaced to not collide with other implementations’ keys. e.g. A core called foo should use keys named as foo_option. retro_core_option_definition::desc should contain a human readable description of the key. retro_core_option_definition::info should contain any additional human readable information text that a typical user may need to understand the functionality of the option. retro_core_option_definition::values is an array of retro_core_option_value structs terminated by a { NULL, NULL } element.

retro_core_option_definition::values[index].value is an expected option value. retro_core_option_definition::values[index].label is a human readable label used when displaying the value on screen. If NULL, the value itself is used. retro_core_option_definition::default_value is the default core option setting. It must match one of the expected option values in the retro_core_option_definition::values array. If it does not, or the default value is NULL, the first entry in the retro_core_option_definition::values array is treated as the default.

The number of possible option values should be very limited, and must be less than RETRO_NUM_CORE_OPTION_VALUES_MAX. i.e. it should be feasible to cycle through options without a keyboard.

Examples

{
    "foo_option",
    "Speed hack coprocessor X",
    "Provides increased performance at the expense of reduced accuracy",
    {
        { "false",    NULL },
        { "true",     NULL },
        { "unstable", "Turbo (Unstable)" },
        { NULL, NULL },
    },
    "false"
}

Only strings are operated on. The possible values will generally be displayed and stored as-is by the frontend.

impl SetEnvironmentContext<'_>

pub fn set_core_options_v2(&self, options: &retro_core_options_v2) -> bool

Allows an implementation to signal the environment which variables it might want to check for later using get_variable. This allows the frontend to present these variables to a user dynamically.

This should only be called if get_core_options_version returns an API version of >= 2.

This should be called instead of set_variables.

This should be called instead of set_core_options.

This should be called the first time as early as possible (ideally in Core::on_set_environment).

Afterwards 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.

If get_core_options_version returns an API version of >= 2, this callback is guaranteed to succeed (i.e. callback return value does not indicate success)

If callback returns true, frontend has core option category support.

If callback returns false, frontend does not have core option category support.

‘data’ points to a retro_core_options_v2 struct, containing of two pointers:

• retro_core_options_v2::categories is an array of retro_core_option_v2_category structs terminated by a { NULL, NULL, NULL } element. If retro_core_options_v2::categories is `NULL , all core options will have no category and will be shown at the top level of the frontend core option interface. If frontend does not have core option category support, categories array will be ignored.
• retro_core_options_v2::definitions is an array of retro_core_option_v2_definition structs terminated by a { NULL, NULL, NULL, NULL, NULL, NULL, {{0}}, NULL } element.

retro_core_option_v2_category notes:

• retro_core_option_v2_category::key should contain string that uniquely identifies the core option category. Valid key characters are [a-z, A-Z, 0-9, _, -].

  Namespace collisions with other implementations’ category keys are permitted.

• retro_core_option_v2_category::desc should contain a human readable description of the category key.

• retro_core_option_v2_category::info should contain any additional human readable information text that a typical user may need to understand the nature of the core option category.

Examples

{
    "advanced_settings",
    "Advanced",
    "Options affecting low-level emulation performance and accuracy."
}

retro_core_option_v2_definition notes:

• retro_core_option_v2_definition::key should be namespaced to not collide with other implementations’ keys. e.g. A core called foo should use keys named as foo_option. Valid key characters are [a-z, A-Z, 0-9, _, -].

• retro_core_option_v2_definition::desc should contain a human readable description of the key. Will be used when the frontend does not have core option category support. Examples: Aspect Ratio or Video > Aspect Ratio.

• retro_core_option_v2_definition::desc_categorized should contain a human readable description of the key, which will be used when frontend has core option category support. Example: Aspect Ratio, where associated retro_core_option_v2_category::desc is Video.

  If empty or NULL, the string specified by retro_core_option_v2_definition::desc will be used instead.

  retro_core_option_v2_definition::desc_categorized will be ignored if retro_core_option_v2_definition::category_key is empty or NULL.

• retro_core_option_v2_definition::info should contain any additional human readable information text that a typical user may need to understand the functionality of the option.

• retro_core_option_v2_definition::info_categorized should contain any additional human readable information text that a typical user may need to understand the functionality of the option, and will be used when frontend has core option category support. This is provided to accommodate the case where info text references an option by name/desc, and the desc/desc_categorized text for that option differ.

  If empty or NULL, the string specified by retro_core_option_v2_definition::info will be used instead.

  retro_core_option_v2_definition::info_categorized will be ignored if retro_core_option_v2_definition::category_key is empty or NULL.

• retro_core_option_v2_definition::category_key should contain a category identifier (e.g. video or audio) that will be assigned to the core option if frontend has core option category support. A categorized option will be shown in a subsection/ submenu of the frontend core option interface.

  If key is empty or NULL, or if key does not match one of the retro_core_option_v2_category::key values in the associated retro_core_option_v2_category array, option will have no category and will be shown at the top level of the frontend core option interface.

• retro_core_option_v2_definition::values is an array of retro_core_option_value structs terminated by a { NULL, NULL } element.

  • retro_core_option_v2_definition::values[index].value is an expected option value.

  • retro_core_option_v2_definition::values[index].label is a human readable label used when displaying the value on screen. If NULL, the value itself is used.

• retro_core_option_v2_definition::default_value is the default core option setting.

  It must match one of the expected option values in the retro_core_option_v2_definition::values array.

  If it does not, or the default value is NULL, the first entry in the retro_core_option_v2_definition::values array is treated as the default.

The number of possible option values should be very limited, and must be less than RETRO_NUM_CORE_OPTION_VALUES_MAX. i.e. it should be feasible to cycle through options without a keyboard.

Examples

• Uncategorized:

 {
     "foo_option",
     "Speed hack coprocessor X",
     NULL,
     "Provides increased performance at the expense of reduced accuracy.",
     NULL,
     NULL,
     {
         { "false",    NULL },
         { "true",     NULL },
         { "unstable", "Turbo (Unstable)" },
         { NULL, NULL },
     },
     "false"
 }

• Categorized:

 {
     "foo_option",
     "Advanced > Speed hack coprocessor X",
     "Speed hack coprocessor X",
     "Setting 'Advanced > Speed hack coprocessor X' to 'true' or 'Turbo' provides increased performance at the expense of reduced accuracy",
     "Setting 'Speed hack coprocessor X' to 'true' or 'Turbo' provides increased performance at the expense of reduced accuracy",
     "advanced_settings",
     {
         { "false",    NULL },
         { "true",     NULL },
         { "unstable", "Turbo (Unstable)" },
         { NULL, NULL },
     },
     "false"
 }

Only strings are operated on. The possible values will generally be displayed and stored as-is by the frontend.

impl SetEnvironmentContext<'_>

pub fn set_core_options_intl(&self, options: retro_core_options_intl) -> bool

Allows an implementation to signal the environment which variables it might want to check for later using get_variable.

This allows the frontend to present these variables to a user dynamically.

This should only be called if get_core_options_version returns an API version of >= 1.

This should be called instead of set_variables.

This should be called instead of set_core_options.

This should be called the first time as early as possible (ideally in Core::on_set_environment).

Afterwards 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.

This is fundamentally the same as set_core_options, with the addition of localisation support. The description of set_core_options callback should be consulted for further details.

‘data’ points to a retro_core_options_intl struct.

retro_core_options_intl::us is a pointer to an array of retro_core_option_definition structs defining the US English core options implementation. It must point to a valid array.

retro_core_options_intl::local is a pointer to an array of retro_core_option_definition structs defining core options for the current frontend language. It may be NULL (in which case retro_core_options_intl::us is used by the frontend). Any items missing from this array will be read from retro_core_options_intl::us instead.

NOTE: Default core option values are always taken from the retro_core_options_intl::us array. Any default values in retro_core_options_intl::local array will be ignored.

impl SetEnvironmentContext<'_>

pub fn set_core_options_v2_intl( &self, options: retro_core_options_v2_intl, ) -> bool

Allows an implementation to signal the environment which variables it might want to check for later using get_variable.

This allows the frontend to present these variables to a user dynamically.

This should only be called if get_core_options_version returns an API version of >= 2.

This should be called instead of set_variables.

This should be called instead of set_core_options.

This should be called instead of set_core_options_intl.

This should be called instead of set_core_options_v2.

This should be called the first time as early as possible (ideally in Core::on_set_environment).

Afterwards 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.

If get_core_options_version returns an API version of >= 2, this callback is guaranteed to succeed (i.e. callback return value does not indicate success)

If callback returns true, frontend has core option category support.

If callback returns false, frontend does not have core option category support.

This is fundamentally the same as set_core_options_v2, with the addition of localisation support. The description of the set_core_options_v2 callback should be consulted for further details.

‘data’ points to a retro_core_options_v2_intl struct.

• retro_core_options_v2_intl::us is a pointer to a retro_core_options_v2 struct defining the US English core options implementation. It must point to a valid struct.

• retro_core_options_v2_intl::local is a pointer to a retro_core_options_v2 struct defining core options for the current frontend language.

  It may be NULL (in which case retro_core_options_v2_intl::us is used by the frontend). Any items missing from this struct will be read from retro_core_options_v2_intl::us instead.

NOTE: Default core option values are always taken from the retro_core_options_v2_intl::us struct. Any default values in the retro_core_options_v2_intl::local struct will be ignored.

impl SetEnvironmentContext<'_>

pub fn set_content_info_override( &self, value: retro_system_content_info_override, ) -> bool

Allows an implementation to override ‘global’ content info parameters reported by Core::get_info. Overrides also affect subsystem content info parameters set via set_subsystem_info. This function must be called inside Core::on_set_environment. If callback returns false, content info overrides are unsupported by the frontend, and will be ignored. If callback returns true, extended game info may be retrieved by calling get_game_info_ext in Core::on_load_game or Core::on_load_game_special.

‘data’ points to an array of retro_system_content_info_override structs terminated by a { NULL, false, false } element. If ‘data’ is NULL, no changes will be made to the frontend; a core may therefore pass NULL in order to test whether the set_content_info_override and get_game_info_ext callbacks are supported by the frontend.

For struct member descriptions, see the definition of struct retro_system_content_info_override.

Example:

• struct retro_system_info:

{
   "My Core",                      // library_name
   "v1.0",                         // library_version
   "m3u|md|cue|iso|chd|sms|gg|sg", // valid_extensions
   true,                           // need_fullpath
   false                           // block_extract
}

• Array of struct retro_system_content_info_override:

{
   {
      "md|sms|gg", // extensions
      false,       // need_fullpath
      true         // persistent_data
   },
   {
      "sg",        // extensions
      false,       // need_fullpath
      false        // persistent_data
   },
   { NULL, false, false }
}

Result:

• Files of type m3u, cue, iso, chd will not be loaded by the frontend. Frontend will pass a valid path to the core, and core will handle loading internally
• Files of type md, sms, gg will be loaded by the frontend. A valid memory buffer will be passed to the core. This memory buffer will remain valid until Core::on_deinit returns
• Files of type sg will be loaded by the frontend. A valid memory buffer will be passed to the core. This memory buffer will remain valid until Core::on_load_game (or Core::on_load_game_special) returns

NOTE: If an extension is listed multiple times in an array of retro_system_content_info_override structs, only the first instance will be registered

impl SetEnvironmentContext<'_>

pub fn set_core_options_update_display_callback( &self, data: retro_core_options_update_display_callback, ) -> bool

Allows a frontend to signal that a core must update the visibility of any dynamically hidden core options, and enables the frontend to detect visibility changes.

Used by the frontend to update the menu display status of core options without requiring a call of Core::on_run. Must be called in Core::on_set_environment.

Trait Implementations

impl<'a> From<&SetEnvironmentContext<'a>> for GenericContext<'a>

fn from(other: &SetEnvironmentContext<'a>) -> GenericContext<'a>

Converts to this type from the input type.

impl<'a> From<&mut SetEnvironmentContext<'a>> for GenericContext<'a>

fn from(other: &mut SetEnvironmentContext<'a>) -> GenericContext<'a>

Converts to this type from the input type.