Difference between revisions of "Mupen64Plus v2.0 Core Front-End"

From Mupen64Plus Wiki
Jump to: navigation, search
(Created page with "Mupen64Plus v2.0 API = Mupen64Plus v2.0 Core<-->Front-End API = Most libmupen64plus functions return an <tt>m64p_error</tt> return code, w...")
(No difference)

Revision as of 21:47, 21 July 2015

Mupen64Plus v2.0 API

Mupen64Plus v2.0 Core<-->Front-End API

Most libmupen64plus functions return an m64p_error return code, which is an enumerated type defined in m64p_types.h. Front-end code should check the return value of each call to a libmupen64plus function.

Startup/Shutdown Functions

Prototype m64p_error CoreStartup(int APIVersion, const char *ConfigPath, const char *DataPath, void *Context, void (*DebugCallback)(void *Context, int level, const char *message), void *Context2, void (*StateCallback)(void *Context2, m64p_core_param ParamChanged, int NewValue))
Input Parameters APIVersion Integer containing the version number of the Core API used by the front-end.

ConfigPath File path to folder containing Mupen64Plus.cfg. Can be NULL.
DataPath Folder to search first when looking for shared data files. Can be NULL.
Context Pointer which will be passed back to the DebugCallback function. Can be NULL.
DebugCallback Pointer to function in front-end for receiving debug information and warnings from the core. This function must be thread-safe. Can be NULL. The value of level is 1 for an error, 2 for a warning, 3 for info, and 4 for verbose info.
Context2 Pointer which will be passed back to the StateCallback function. Can be NULL.
StateCallback Pointer to function in front-end for receiving core state change notifications. This function must be thread-safe. Can be NULL.

Requirements This function must be called before any other libmupen64plus functions.
Usage This function initializes libmupen64plus for use by allocating memory, creating data structures, and loading the configuration file. If ConfigPath is NULL, libmupen64plus will search for the configuration file in its usual place (On Linux, in ~/.config/mupen64plus/). This function may return M64ERR_INCOMPATIBLE if older front-end is used with newer core.


Prototype m64p_error CoreShutdown(void)
Input Parameters N/A
Usage This function saves the configuration file, then destroys data structures and releases memory allocated by the core library.


Prototype m64p_error CoreAttachPlugin(m64p_plugin_type PluginType, m64p_dynlib_handle PluginLibHandle)
Input Parameters PluginType Enumerated type specifying the plugin type to attach to the core. If this type of plugin is currently attached to the core, an error will be returned.

PluginLibHandle Dynamic library handle (defined in m64p_types.h) corresponding with the plugin object to attach.

Requirements Both the core library and the plugin library must already be initialized with the CoreStartup()/PluginStartup() functions, and a ROM must be open. This function cannot be called while the emulator is running. The plugins must be attached in the following order: Video, Audio, Input, RSP.
Usage This function attaches the given plugin to the emulator core. There can only be one plugin of each type attached to the core at any given time.


Prototype m64p_error CoreDetachPlugin(m64p_plugin_type PluginType)
Input Parameters PluginType Enumerated type specifying the plugin type to detach from the core. If no plugin of this type is currently attached to the core, this function will exit with a return value of M64ERR_SUCCESS.
Requirements Both the core library and the plugin library must already be initialized with the CoreStartup()/PluginStartup() functions. This function cannot be called while the emulator is running.
Usage This function detaches the given plugin from the emulator core, and re-attaches the 'dummy' plugin functions.

Command Functions

Prototype m64p_error CoreDoCommand(m64p_command Command, int ParamInt, void *ParamPtr)
Input Parameters Command Enumerated type specifying which command should be executed.

ParamInt An integer value which may be used as an input to the command.
ParamPtr A pointer which may be used as an input to the command.

Requirements The core library must already be initialized with the CoreStartup() function. Each command may have its own requirements as well.
Usage This function sends a command to the emulator core. A table of all commands is given below.


Command Function Input Parameters Requirements
M64CMD_ROM_OPEN This will cause the core to read in a binary ROM image provided by the front-end. ParamPtr Pointer to the uncompressed ROM image in memory.
ParamInt The size in bytes of the ROM image. 		The emulator cannot be currently running. A ROM image must not be currently opened.
M64CMD_ROM_CLOSE This will close any currently open ROM. The current cheat code list will also be deleted. N/A The emulator cannot be currently running. A ROM image must have been previously opened. There should be no plugins currently attached.
M64CMD_ROM_GET_HEADER This will retrieve the header data of the currently open ROM. ParamPtr Pointer to a rom_header struct to receive the data.
ParamInt The size in bytes of the rom_header struct. 		A ROM image must be open.
M64CMD_ROM_GET_SETTINGS This will retrieve the settings data of the currently open ROM. ParamPtr Pointer to a rom_settings struct to receive the data.
ParamInt The size in bytes of the rom_settings struct. 		A ROM image must be open.
M64CMD_EXECUTE This command will start the emulator and begin executing the ROM image. This function call will not return until the game has been stopped. N/A The emulator cannot be currently running. A ROM image must have been previously opened.
M64CMD_STOP This will stop the emulator, if it is currently running. N/A This command will execute asynchronously.
M64CMD_PAUSE This command will pause the emulator if it is running. N/A This function will return a non-successful error code if the emulator is in the stopped state. This command may execute asynchronously.
M64CMD_RESUME This command will resume execution of the emulator if it is paused. N/A This function will return a non-successful error code if the emulator is in the stopped state. This command may execute asynchronously.
M64CMD_CORE_STATE_QUERY This command will query the emulator core for the value of a state parameter ParamInt An m64p_core_param enumerated type specifying the desired state variable
ParamPtr Pointer to an integer to receive the value of the requested state variable. 		None
M64CMD_CORE_STATE_SET This command will set the value of a state parameter in the emulator core ParamInt An m64p_core_param enumerated type specifying the desired state variable
ParamPtr Pointer to an integer to containing the value of the requested state variable. 		The initial requirements vary depending upon the variable being set. Setting some variables requires the emulator to be running.
M64CMD_STATE_LOAD This command will attempt to load a saved state file. If ParamPtr is not NULL, this function will load a state file from a full pathname specified by this pointer. Otherwise (ParamPtr is NULL), it will load from the current slot. ParamInt Ignored
ParamPtr Pointer to string containing state file path and name, or NULL 		The emulator must be currently running or paused. This command will execute asynchronously.
M64CMD_STATE_SAVE This command will save a state file. If ParamPtr is not NULL, this function will save a state file to a full pathname specified by this pointer. Otherwise (ParamPtr is NULL), it will save to the current slot. ParamInt This parameter will only be used if ParamPtr is not NULL. If 1, a Mupen64Plus state file will be saved. If 2, a Project64 compressed state file will be saved. If 3, a Project64 uncompressed state file will be saved.
ParamPtr Pointer to string containing state file path and name, or NULL
 The emulator must be currently running or paused. This command will execute asynchronously.
M64CMD_STATE_SET_SLOT This command will set the currently selected save slot index ParamInt Value to set for the current slot index. Must be between 0 and 9
ParamPtr Ignored
 None
M64CMD_SEND_SDL_KEYDOWN This command will inject an SDL_KEYDOWN event into the emulator's core event loop. Keys not handled by the core will be passed to the input plugin. ParamInt Key value of the keypress event to inject, with SDLMod in the upper 16 bits and SDLKey in the lower 16 bits. The emulator must be currently running or paused.
M64CMD_SEND_SDL_KEYUP This command will inject an SDL_KEYUP event into the emulator's core event loop. ParamInt Key value of the keypress event to inject, with SDLMod in the upper 16 bits and SDLKey in the lower 16 bits. The emulator must be currently running or paused.
M64CMD_SET_FRAME_CALLBACK This command either registers or removes (if ParamPtr is NULL) a frame callback function. This function will be called after each video frame is rendered. The front-end callback function may call the video plugin's ReadScreen2() function to retrieve the frame if desired. ParamPtr Can be either NULL or a m64p_frame_callback object. None
M64CMD_TAKE_NEXT_SCREENSHOT This will cause the core to save a screenshot at the next possible opportunity. N/A The emulator must be currently running or paused. This command will execute asynchronously.
M64CMD_READ_SCREEN This command will copy the current contents of the video display to the buffer pointer by ParamPtr. ParamInt 1 to copy the buffer that is currently displayed (front buffer), 0 to copy the buffer that is being drawn (back buffer).
ParamPtrA pointer to a buffer of at least width*height*3 bytes. The buffer will be filled with the current display. The format is RGB888 with the origin in the lower left corner. 		The emulator must be currently running or paused.
M64CMD_RESET Reset the emulated machine. ParamInt 0 to do a soft reset, 1 to do a hard reset.
ParamPtr Ignored 		The emulator must be currently running or paused.
M64CMD_ADVANCE_FRAME Advance one frame (the emulator will run until the next frame, then pause). ParamInt Ignored
ParamPtr Ignored 		The emulator must be currently running or paused.



Core State Parameters

These core parameters may be read and/or written using the M64CMD_CORE_STATE_QUERY and M64CMD_CORE_STATE_SET commands. The front-end application will receive a callback (via the StateCallback function pointer given to the CoreStartup function) when these parameters change value. This callback will be sent even if the function which caused the state change was called by the front-end application itself. Not all of these parameters are readable or writable. Each parameter's value is held in a single 32-bit integer. The meaning of this integer is given in the Parameter Encoding column. See the table below for details on these core parameters.

Name Readable Writable int Parameter Encoding Notes
M64CORE_EMU_STATE Yes Yes enum m64p_emu_state 1=Stopped, 2=Running, 3=Paused
M64CORE_VIDEO_MODE Yes Yes enum m64p_video_mode 1=None (video not running), 2=Windowed, 3=Fullscreen
M64CORE_SAVESTATE_SLOT Yes Yes Valid values are 0 through 9.
M64CORE_SPEED_FACTOR Yes Yes Emulator playback speed in percent Valid values are 1 to 1000.
M64CORE_SPEED_LIMITER Yes Yes 1 to enable speed limiter, or 0 to disable speed limiter. When speed limiter is disabled, emulator will run as fast as possible (useful for benchmarking).
M64CORE_VIDEO_SIZE Yes Yes (ScreenWidth << 16) + ScreenHeight This parameter can only be read or written when the emulator is running or paused. This parameter may be written by the front-end application in response to a window resizing event. Upon receiving this command, the core will pass the new width and height to the ResizeVideoOutput function in the video plugin (video API v2.2.0). If the video plugin supports resizing, it will update its viewport and then call the video extension function VidExt_ResizeWindow to update the window manager.
M64CORE_AUDIO_VOLUME Yes Yes Volume level in percent, 0 - 100
M64CORE_AUDIO_MUTE Yes Yes 1 if muted, otherwise 0
M64CORE_INPUT_GAMESHARK Yes Yes 1 when Gameshark button pressed, 0 when button released. Callback function will be invoked on both button press and release.
M64CORE_STATE_LOADCOMPLETE No No 1 if state loading was successful, 0 if state loading failed. This parameter cannot be read or written. It is only used for callbacks, because the state load/save operations are asynchronous.
M64CORE_STATE_SAVECOMPLETE No No 1 if state saving was successful, 0 if state saving failed. This parameter cannot be read or written. It is only used for callbacks, because the state load/save operations are asynchronous.


ROM Handling Functions

Prototype m64p_error CoreGetRomSettings(m64p_rom_settings *RomSettings, int RomSettingsLength, int Crc1, int Crc2)
Input Parameters RomSettings Pointer to m64p_rom_settings object to be filled in with data.

RomSettingsLength Size of the object pointed to by RomSettings in bytes.
Crc1 A 32-bit integer value containing the first CRC (taken from the ROM header) to identify the ROM.
Crc2 A 32-bit integer value containing the second CRC (taken from the ROM header) to identify the ROM.

Requirements The core library must already be initialized with the CoreStartup() function. The RomSettings pointer must not be NULL. The RomSettingsLength value must be greater than or equal to the size of the m64p_rom_settings structure. This function does not require any ROM image to be currently open.
Usage This function searches through the data in the Mupen64Plus.ini file to find an entry which matches the given Crc1 and Crc2 hashes, and if found, fills in the RomSettings structure with the data from the Mupen64Plus.ini file.


Video Extension Functions

Prototype m64p_error CoreOverrideVidExt(m64p_video_extension_functions *VideoFunctionStruct);
Input Parameters VideoFunctionStruct Pointer to a structure (defined in m64p_types.h) containing pointers to the Front-end's custom Video Extension functions to override the default SDL functions
Requirements The Mupen64Plus library must already be initialized before calling this function. This function cannot be called while the emulator is running.
Usage This function overrides the core's internal SDL-based OpenGL functions which are called from the video plugin to perform various basic tasks like opening the video window, toggling between windowed and fullscreen modes, and swapping frame buffers after a frame has been rendered. This override functionality allows a front-end to define its own video extension functions to be used instead of the SDL functions, such as for the purpose of embedding the emulator display window inside of a Qt GUI window. If any of the function pointers in the structure are NULL, the override function will be disabled and the core's internal SDL functions will be used. The core library with a Video Extension API v3.0 expects the Functions struct member to be equal to 11 or more.


Cheat Functions

Prototype m64p_error CoreAddCheat(const char *CheatName, m64p_cheat_code *CodeList, int NumCodes)
Input Parameters CheatName Pointer to NULL-terminated string containing a unique name for this Cheat Function.

CodeList Pointer to an array of m64p_cheat_code objects.
NumCodes Number of m64p_cheat_code elements in the cheat code array.

Requirements The Mupen64Plus library must already be initialized before calling this function. A ROM image must be currently opened.
Usage This function will add a Cheat Function to a list of currently active cheats which are applied to the open ROM, and set its state to Enabled. This function may be called before a ROM begins execution or while a ROM is currently running. Some cheat codes must be applied before the ROM begins executing, and may not work correctly if added after the ROM begins execution. A Cheat Function consists of a list of one or more m64p_cheat_code elements. If a Cheat Function with the given CheatName already exists, it will be removed and the new Cheat Function will be added in its place.


Prototype m64p_error CoreCheatEnabled(const char *CheatName, int Enabled)
Input Parameters CheatName Pointer to NULL-terminated string containing the name of an existing Cheat Function.

Enabled Boolean value to which to set the enabled state of the specified Cheat Function.

Requirements The Mupen64Plus library must already be initialized before calling this function. A ROM image must be currently opened.
Usage This function enables or disables a specified Cheat Function.
Retrieved from "https://mupen64plus.org/wiki/index.php?title=Mupen64Plus_v2.0_Core_Front-End&oldid=10"