Struct rust_libretro::contexts::GenericContext
source · [−]pub struct GenericContext<'a> { /* private fields */ }Expand description
Exposes environment callbacks that are safe to call in every context.
Implementations
Sets screen rotation of graphics.
👎 Deprecated: This function is considered deprecated in favor of using core options to manage overscan in a more nuanced, core-specific way
This function is considered deprecated in favor of using core options to manage overscan in a more nuanced, core-specific way
Boolean value whether or not the implementation should use overscan, or crop away overscan.
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_ENVIRONMENT_GET_LOG_INTERFACE (or as a
fallback, stderr).
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 NULL.
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 get_save_directory().
Sets an array of retro_input_descriptors.
It is up to the frontend to present this in a usable way.
The array is terminated by retro_input_descriptor::description
being set to NULL.
This function can be called at any time, but it is recommended
to call it as early as possible.
Sets a callback function used to notify core about keyboard events.
Sets an interface which frontend can use to eject and insert disk images. This is used for games which consist of multiple images and must be manually swapped out by the user (e.g. PSX).
Interface to acquire user-defined information from environment that cannot feasibly be supported in a multi-system way.
The key should be set to a key which has already been set by
set_variables or set_core_options.
Returns None if the variable could not be found.
Result is set to true if some variables are updated by
frontend since last call to get_variable.
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 set_support_no_game as assets can
be loaded without ugly hacks.
Sets an interface which is used to notify a libretro core about audio being available for writing. The callback can be called from any thread, so a core using this must have a thread safe audio implementation.
It is intended for games where audio and video are completely asynchronous and audio can be generated on the fly. This interface is not recommended for use with emulators which have highly synchronous audio.
The callback only notifies about writability; the libretro core still has to call the normal audio callbacks to write audio. The audio callbacks must be called from within the notification callback. The amount of audio data to write is up to the implementation. Generally, the audio callback will be called continously in a loop.
Due to thread safety guarantees and lack of sync between audio and video, a frontend can selectively disallow this interface based on internal configuration. A core using this interface must also implement the “normal” audio interface.
A libretro core using set_audio_callback should also make use of
set_frame_time_callback.
Unstable 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 input_state_callback API.
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.
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.
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.
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.
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.
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 (Core::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
get_system_directory.
This environment call lets a libretro core tell the frontend
which controller subclasses are recognized in calls to
Core::on_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 const struct retro_controller_info which
is terminated with a blanked out struct.
Each element of the retro_controller_info struct corresponds to the
ascending port index that is passed to Core::on_set_controller_port_device
when that function is called to indicate to the core that the frontend has
changed the active device subclass.
SEE ALSO: Core::on_set_controller_port_device
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.
The first inner element of each entry in the retro_controller_info array
is a retro_controller_description struct that 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 retro_controller_description.
NOTE: Even if special device types are set in the libretro core, libretro should only poll input based on the base input device types.
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 environment callback is used by a core that requires a valid username,
a default username should be specified by the core.
Returns the language of the frontend, if specified by the user. It can be used by the core for localization purposes.
Unstable
Returns a preallocated framebuffer which the core can use for rendering
the frame into when not using set_hw_render.
The framebuffer returned from this call must not be used
after the current call to Core::on_run returns.
The goal of this call is to allow zero-copy behavior where a core can render directly into video memory, avoiding extra bandwidth cost by copying memory from core to video memory.
If this call succeeds and the core renders into it,
the framebuffer pointer and pitch can be passed to RunContext::draw_framebuffer.
If the buffer from get_current_software_framebuffer is to be used,
the core must pass the exact
same pointer as returned by get_current_software_framebuffer;
i.e. passing a pointer which is offset from the
buffer is undefined. The width, height and pitch parameters
must also match exactly to the values obtained from get_current_software_framebuffer.
It is possible for a frontend to return a different pixel format
than the one used in set_pixel_format. This can happen if the frontend
needs to perform conversion.
It is still valid for a core to render to a different buffer
even if get_current_software_framebuffer succeeds.
A frontend must make sure that the pointer obtained from this function is writeable (and readable).
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.
Unstable TODO: GET_HW_RENDER_INTERFACE cannot be called before context_reset has been called. Similarly, after context_destroyed callback returns, the contents of the HW_RENDER_INTERFACE are invalidated.
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.
Unstable The frontend will try to use a ‘shared’ hardware context (mostly applicable to OpenGL) when a hardware context is being set up.
Returns true if the frontend supports shared hardware contexts and false
if the frontend does not support shared hardware contexts.
This will do nothing on its own until SET_HW_RENDER environment callbacks are
being used.
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.
Unstable Gets an interface which is used by a libretro core to set state of LEDs.
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.
Unstable Tells the core if the frontend wants audio or video. If disabled, the frontend will discard the audio or video, so the core may decide to skip generating a frame or generating audio. This is mainly used for increasing performance.
See AudioVideoEnable for descriptions of the flags.
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.
Unstable Returns a MIDI interface that can be used for raw data I/O.
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.
Unstable Boolean value that indicates whether or not the frontend is in fastforwarding mode.
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.
Unstable Float value that lets us know what target refresh rate is curently in use by the frontend.
The core can use the returned value to set an ideal refresh rate/framerate.
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.
Unstable
Boolean value that indicates whether or not the frontend supports
input bitmasks being returned by retro_input_state_t. The advantage
of this is that retro_input_state_t has to be only called once to
grab all button states instead of multiple times.
If it returns true, you can pass RETRO_DEVICE_ID_JOYPAD_MASK as id
to retro_input_state_t (make sure device is set to RETRO_DEVICE_JOYPAD).
It will return a bitmask of all the digital buttons.
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.
The returned value is the API version number of the core options interface supported by the frontend. If the underlying callback failed, API version is assumed to be 0.
In legacy code, core options are set by passing an array of
retro_variable structs to set_variables.
This may be still be done regardless of the core options
interface version.
If version is >= 1 however, core options may instead be set by
passing an array of retro_core_option_definition structs to
set_core_options, or a 2D array of
retro_core_option_definition structs to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL.
This allows the core to additionally set option sublabel information
and/or provide localisation support.
If version is >= 2, core options may instead be set by passing
a retro_core_options_v2 struct to set_core_options_v2,
or an array of retro_core_options_v2 structs to
set_core_options_v2_intl. This allows the core
to additionally set optional core option category information
for frontends with core option category support.
Allows an implementation to signal the environment to show or hide a variable when displaying core options. This is considered a suggestion. The frontend is free to ignore this callback, and its implementation not considered mandatory.
‘data’ points to a retro_core_option_display struct
retro_core_option_display::key is a variable identifier
which has already been set by set_variables / set_core_options.
retro_core_option_display::visible is a boolean, specifying
whether variable should be displayed
Note that all core option variables will be set visible by
default when calling set_variables / set_core_options.
Allows an implementation to ask frontend preferred hardware context to use. Core should use this information to deal with what specific context to request with SET_HW_RENDER.
‘data’ points to an unsigned variable
Unsigned value is the API version number of the disk control interface supported by the frontend. If callback return false, API version is assumed to be 0.
In legacy code, the disk control interface is defined by passing
a struct of type retro_disk_control_callback] to [set_disk_control_interface`.
This may be still be done regardless of the disk control
interface version.
If version is >= 1 however, the disk control interface may
instead be defined by passing a struct of type
retro_disk_control_ext_callback to
set_disk_control_ext_interface.
This allows the core to provide additional information about
disk images to the frontend and/or enables extra
disk control functionality by the frontend.
Sets an interface which frontend can use to eject and insert disk images, and also obtain information about individual disk image files registered by the core. This is used for games which consist of multiple images and must be manually swapped out by the user (e.g. PSX, floppy disk based systems).
The returned value is the API version number of the message interface supported by the frontend. If the underlying callback failed, API version is assumed to be 0.
In legacy code, messages may be displayed in an
implementation-specific manner by passing a struct
of type retro_message to set_message.
This may be still be done regardless of the message
interface version.
If version is >= 1 however, messages may instead be
displayed by calling set_message_ext.
This allows the core to specify message logging level, priority and
destination (OSD, logging interface or both).
pub fn set_message_ext(
&self,
message: &str,
duration: u32,
priority: u32,
level: retro_log_level,
target: retro_message_target,
type_: retro_message_type,
progress: MessageProgress
) -> bool
pub fn set_message_ext(
&self,
message: &str,
duration: u32,
priority: u32,
level: retro_log_level,
target: retro_message_target,
type_: retro_message_type,
progress: MessageProgress
) -> bool
Sets a message to be displayed in an implementation-specific
manner for a certain duration of milliseconds.
Additionally allows the core to specify message logging level, priority and
destination (OSD, logging interface or both).
Should not be used for trivial messages, which should simply be
logged via RETRO_ENVIRONMENT_GET_LOG_INTERFACE (or as a fallback, stderr).
The first returned value is the number of active input devices provided by the frontend. This may change between frames, but will remain constant for the duration of each frame.
If the second return value is true, a core does not need to
poll any input device with an index greater than or equal to
the number of active devices.
If the second return value is false, the number of active input
devices is unknown. In this case, all input devices
should be considered active.
pub fn set_audio_buffer_status_callback(
&self,
data: retro_audio_buffer_status_callback
) -> bool
pub fn set_audio_buffer_status_callback(
&self,
data: retro_audio_buffer_status_callback
) -> bool
Lets the core know the occupancy level of the frontend
audio buffer. Can be used by a core to attempt frame
skipping in order to avoid buffer under-runs.
A core may pass NULL to disable buffer status reporting
in the frontend.
Checks whether the frontend supports the set_fastforwarding_override interface.
Used by a libretro core to override the current fastforwarding mode of the frontend.
Allows an implementation to notify the frontend that a core option value has changed.
retro_variable::key and retro_variable::value
must match strings that have been set previously
via one of the following:
After changing a core option value via this
callback, get_variable_update
will return true.
If data is NULL, no changes will be registered
and the callback will return true; an
implementation may therefore pass NULL in order
to test whether the callback is supported.
Unstable
Allows an implementation to get details on the actual rate
the frontend is attempting to call Core::on_run.
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.
Trait Implementations
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.
Performs the conversion.