Module environment 

Unsafe functions related to the libretro environment callback. For safe versions have a look at the contexts module and the context types you get in your core callbacks.

Functions

can_dupe^⚠

Boolean value whether or not frontend supports frame duping, passing NULL to video frame callback.

get^⚠

Gets a value from an environment callback.

get_audio_video_enable^⚠

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.

get_camera_interface^⚠

Unstable Gets an interface to a video camera driver. A libretro core can use this interface to get access to a video camera. New video frames are delivered in a callback in same thread as Core::on_run.

get_core_assets_directory^⚠

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.

get_core_options_version^⚠

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.

get_current_software_framebuffer^⚠

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.

get_disk_control_interface_version^⚠

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.

get_fastforwarding^⚠

Unstable Boolean value that indicates whether or not the frontend is in fastforwarding mode.

get_game_info_ext^⚠

Allows an implementation to fetch extended game information, providing additional content path and memory buffer status details. This function may only be called inside Core::on_load_game or Core::on_load_game_special.

get_hw_render_interface^⚠

Unstable Returns an API specific rendering interface for accessing API specific data. Not all HW rendering APIs support or need this. The contents of the returned pointer is specific to the rendering API being used. See the various headers like libretro_vulkan.h, etc.

get_hw_render_interface_vulkan^⚠

Unstable See get_hw_render_interface.

get_input_bitmasks^⚠

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.

get_input_device_capabilities^⚠

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 retro_input_state_t. Example bitmask: RetroDevice::JOYPAD | RetroDevice::ANALOG.

get_input_max_users^⚠

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.

get_language^⚠

Returns the language of the frontend, if specified by the user. It can be used by the core for localization purposes.

get_led_interface^⚠

Unstable Gets an interface which is used by a libretro core to set state of LEDs.

get_libretro_path^⚠

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.

get_location_callback^⚠

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.

get_log_callback^⚠

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.

get_message_interface_version^⚠

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.

get_midi_interface^⚠

Unstable Returns a MIDI interface that can be used for raw data I/O.

get_mut^⚠

Passes a value to the environment callback and returns the modified value.

get_overscan^⚠Deprecated

Boolean value whether or not the implementation should use overscan, or crop away overscan.

get_path^⚠

Helper function to query a string pointer and convert it into a Path.

get_perf_interface^⚠

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.

get_preferred_hw_render^⚠

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.

get_rumble_interface^⚠

Gets an interface which is used by a libretro core to set state of rumble motors in controllers. A strong and weak motor is supported, and they can be controlled indepedently. Should be called from either Core::on_init or Core::on_load_game. Should not be called from Core::on_set_environment. Returns false if rumble functionality is unavailable.

get_save_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).

get_savestate_context^⚠

Unstable Tells the core about the context the frontend is asking for savestate.

get_sensor_interface^⚠

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.

get_system_directory^⚠

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.

get_target_refresh_rate^⚠

Unstable Float value that lets us know what target refresh rate is curently in use by the frontend.

get_throttle_state^⚠

Unstable Allows an implementation to get details on the actual rate the frontend is attempting to call Core::on_run.

get_unchecked^⚠

Similar to get but uses uninitialized memory instead of the Default trait.

get_username^⚠

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.

get_variable^⚠

Interface to acquire user-defined information from environment that cannot feasibly be supported in a multi-system way.

get_variable_update^⚠

Result is set to true if some variables are updated by frontend since last call to get_variable.

get_vfs_interface^⚠

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.

set^⚠

Passes a value to the environment callback.

set_audio_buffer_status_callback^⚠

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.

set_audio_callback^⚠

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.

set_content_info_override^⚠

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.

set_controller_info^⚠

This environment call lets a libretro core tell the frontend which controller subclasses are recognized in calls to Core::on_set_controller_port_device.

set_core_options^⚠

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.

set_core_options_display^⚠

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.

set_core_options_intl^⚠

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

set_core_options_update_display_callback^⚠

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.

set_core_options_v2^⚠

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.

set_core_options_v2_intl^⚠

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

set_disk_control_ext_interface^⚠

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

set_disk_control_interface^⚠

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

set_fastforwarding_override^⚠

Used by a libretro core to override the current fastforwarding mode of the frontend.

set_frame_time_callback^⚠

Lets the core know how much time has passed since last invocation of Core::on_run. The frontend can tamper with the timing to fake fast-forward, slow-motion, frame stepping, etc. In this case the delta time will use the reference value in retro_frame_time_callback.

set_game_geometry^⚠

Sets a new game_geometry structure.

set_hw_render^⚠

Sets an interface to let a libretro core render with hardware acceleration.

set_hw_render_context_negotiation_interface^⚠

Unstable Sets an interface which lets the libretro core negotiate with frontend how a context is created. The semantics of this interface depends on which API is used in set_hw_render earlier. This interface will be used when the frontend is trying to create a HW rendering context, so it will be used after set_hw_render, but before the context_reset callback.

set_hw_shared_context^⚠

Unstable The frontend will try to use a ‘shared’ hardware context (mostly applicable to OpenGL) when a hardware context is being set up.

set_input_descriptors^⚠

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.

set_keyboard_callback^⚠

Sets a callback function used to notify core about keyboard events.

set_memory_maps^⚠

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

set_message^⚠

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

set_message_ext^⚠

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

set_minimum_audio_latency^⚠

Sets minimum frontend audio latency in milliseconds. Resultant audio latency may be larger than set value, or smaller if a hardware limit is encountered. A frontend is expected to honour requests up to 512 ms.

set_performance_level^⚠

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.

set_pixel_format^⚠

Sets the internal pixel format used by the implementation. The default pixel format is retro_pixel_format::RETRO_PIXEL_FORMAT_0RGB1555. This pixel format however, is deprecated (see enum retro_pixel_format). If the call returns false, the frontend does not support this pixel format.

set_proc_address_callback^⚠

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.

set_ptr^⚠

Passes a value (by a raw const pointer) to the environment callback.

set_rotation^⚠

Sets screen rotation of graphics.

set_serialization_quirks^⚠

Sets quirk flags associated with serialization. The frontend will zero any flags it doesn’t recognize or support.

set_subsystem_info^⚠

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.

set_support_achievements^⚠

Unstable If true, the Core implementation supports achievements.

set_support_no_game^⚠

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

set_system_av_info^⚠

Sets a new av_info structure.

set_variable^⚠

Allows an implementation to notify the frontend that a core option value has changed.

set_variables^⚠

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.

shutdown^⚠

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.

supports_fastforwarding_override^⚠

Checks whether the frontend supports the set_fastforwarding_override interface.

supports_set_core_options^⚠

Checks whether the frontend supports the set_core_options interface.

supports_set_core_options_v2^⚠

Checks whether the frontend supports the set_core_options_v2 interface.