Latest revision as of 11:55, 28 June 2020

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). `ParamPtr`A pointer to a buffer of at least widthheight3 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.
M64CMD_SET_MEDIA_LOADER	This command allow frontends to register their media (such as GameBoy cartridge or 64DD disk) loading functions. These functions will be called appropriately by the core at startup and when a new media is inserted.	`ParamInt` must be sizeof(m64p_media_loader). `ParamPtr` A pointer to the m64p_media_loader to register, cannot be NULL.	None
M64CMD_NETPLAY_INIT	This command will initilize the netplay subsystem. It will also attempt to make an initial connection to the netplay server. Returns M64ERR_SYSTEM_FAIL on failure, M64ERR_SUCCESS on success.	`ParamInt` This is the port number the netplay server is listening on. `ParamPtr` This is a string containing the IP or hostname of the netplay server.	Emulator should be stopped.
M64CMD_NETPLAY_CONTROL_PLAYER	This function is used for the client to request control of certain players. This function can be called more than once if a client would like to control multiple players. Local controllers are assigned in order. Returns M64ERR_INPUT_ASSERT if the server rejects the request. If this function is never called, the client is assumed to be a spectator.	`ParamInt` This is the player number (from 1-4) the client would like to control. `ParamPtr` This is a pointer to a uint32_t that contains a unique registration ID (for instance a random number) for the client. This number should be the same each time if this function is called multiple times. The registration ID cannot be 0.	Emulator should be stopped. The input plugin should be started.
M64CMD_NETPLAY_GET_VERSION	This function is used to check API and core versions, the server can use this information to make sure everyone is using the same version of the software. The function returns M64ERR_INCOMPATIBLE if the API versions don't match, and M64ERR_SUCCESS if they do.	`ParamInt` This is the Netplay API version that the frontend supports. `ParamPtr` This is a pointer to a uint32_t, the core fills this pointer with a core netplay version. This version number is incremented when changes are made to the core that would affect netplay sync.	None
M64CMD_NETPLAY_CLOSE	Closes the netplay subsystem, as well as any connections to the netplay server.	N/A	None

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.

@@ Line 186: / Line 186: @@
 |'''<tt>ParamInt</tt>''' Ignored'''<br /><tt>ParamPtr</tt>''' Ignored
 |The emulator must be currently running or paused.
+|-
+|M64CMD_SET_MEDIA_LOADER
+|This command allow frontends to register their media (such as GameBoy cartridge or 64DD disk) loading functions. These functions will be called appropriately by the core at startup and when a new media is inserted.
+|'''<tt>ParamInt</tt>''' must be sizeof(m64p_media_loader).'''<br /><tt>ParamPtr</tt>''' A pointer to the m64p_media_loader to register, cannot be NULL.
+|None
+|-
+|M64CMD_NETPLAY_INIT
+|This command will initilize the netplay subsystem. It will also attempt to make an initial connection to the netplay server. Returns M64ERR_SYSTEM_FAIL on failure, M64ERR_SUCCESS on success.
+|'''<tt>ParamInt</tt>''' This is the port number the netplay server is listening on.'''<br /><tt>ParamPtr</tt>''' This is a string containing the IP or hostname of the netplay server.
+|Emulator should be stopped.
+|-
+|M64CMD_NETPLAY_CONTROL_PLAYER
+|This function is used for the client to request control of certain players. This function can be called more than once if a client would like to control multiple players. Local controllers are assigned in order. Returns M64ERR_INPUT_ASSERT if the server rejects the request. If this function is never called, the client is assumed to be a spectator.
+|'''<tt>ParamInt</tt>''' This is the player number (from 1-4) the client would like to control.'''<br /><tt>ParamPtr</tt>''' This is a pointer to a uint32_t that contains a unique registration ID (for instance a random number) for the client. This number should be the same each time if this function is called multiple times. The registration ID cannot be 0.
+|Emulator should be stopped. The input plugin should be started.
+|-
+|M64CMD_NETPLAY_GET_VERSION
+|This function is used to check API and core versions, the server can use this information to make sure everyone is using the same version of the software. The function returns M64ERR_INCOMPATIBLE if the API versions don't match, and M64ERR_SUCCESS if they do.
+|'''<tt>ParamInt</tt>''' This is the Netplay API version that the frontend supports.'''<br /><tt>ParamPtr</tt>''' This is a pointer to a uint32_t, the core fills this pointer with a core netplay version. This version number is incremented when changes are made to the core that would affect netplay sync.
+|None
+|-
+|M64CMD_NETPLAY_CLOSE
+|Closes the netplay subsystem, as well as any connections to the netplay server.
+|N/A
+|None
 |}
 <br />

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

Latest revision as of 11:55, 28 June 2020

Contents

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

Startup/Shutdown Functions

Command Functions

Core State Parameters

ROM Handling Functions

Video Extension Functions

Cheat Functions

Navigation menu

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Tools