logo

Struct rust_libretro::contexts::SetEnvironmentContext

source · [−]
pub struct SetEnvironmentContext<'a> { /* private fields */ }

Implementations

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.

Example entry:

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 first ; is 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.

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.

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.

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.

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 noticeand no guarantees about its stability can be made.

Checks whether the frontend supports the set_core_options interface.

Checks whether the frontend supports the set_core_options_v2 interface.

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.

Example entry:

{
    "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.

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_option_v2_category notes:
Example entry:
{
    "advanced_settings",
    "Advanced",
    "Options affecting low-level emulation performance and accuracy."
}
retro_core_option_v2_definition notes:

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.

Example entries:
  • 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.

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.

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.

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.

source

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

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

Performs the conversion.

Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.