Core commit. Compile and run on the OpenPandora

[mupen64plus-pandora.git] / source / mupen64plus-core / doc / emuwiki-api-doc / Mupen64Plus_v2.0_Core_Front-End.txt

[[Mupen64Plus v2.0 Core API v1.0|Mupen64Plus v2.0 API]]

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

Most libmupen64plus functions return an <tt>m64p_error</tt> return code, which is an enumerated type defined in [[Mupen64Plus v2.0 headers#m64p_types.h|m64p_types.h]].  Front-end code should check the return value of each call to a libmupen64plus function.

== Startup/Shutdown Functions ==
{| border="1"
|Prototype
|'''<tt>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))</tt>'''
|-
|Input Parameters
|'''<tt>APIVersion</tt>''' Integer containing the version number of the Core API used by the front-end.<br />
'''<tt>ConfigPath</tt>''' File path to folder containing Mupen64Plus.cfg.  Can be NULL.<br />
'''<tt>DataPath</tt>''' Folder to search first when looking for shared data files.  Can be NULL.<br />
'''<tt>Context</tt>''' Pointer which will be passed back to the '''<tt>DebugCallback</tt>''' function.  Can be NULL.<br />
'''<tt>DebugCallback</tt>''' 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 <tt>level</tt> is 1 for an error, 2 for a warning, 3 for info, and 4 for verbose info.<br />
'''<tt>Context2</tt>''' Pointer which will be passed back to the '''<tt>StateCallback</tt>''' function.  Can be NULL.<br />
'''<tt>StateCallback</tt>''' 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 '''<tt>ConfigPath</tt>''' is NULL, libmupen64plus will search for the configuration file in its usual place (On Linux, in <tt>~/.config/mupen64plus/</tt>).  This function may return <tt>M64ERR_INCOMPATIBLE</tt> if older front-end is used with newer core.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error CoreShutdown(void)</tt>'''
|-
|Input Parameters
|N/A
|-
|Usage
|This function saves the configuration file, then destroys data structures and releases memory allocated by the core library.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error CoreAttachPlugin(m64p_plugin_type PluginType, m64p_dynlib_handle PluginLibHandle)</tt>'''
|-
|Input Parameters
|'''<tt>PluginType</tt>''' 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.<br />
'''<tt>PluginLibHandle</tt>''' Dynamic library handle (defined in [[Mupen64Plus v2.0 headers#m64p_types.h|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 <tt>CoreStartup()/PluginStartup()</tt> 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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error CoreDetachPlugin(m64p_plugin_type PluginType)</tt>'''
|-
|Input Parameters
|'''<tt>PluginType</tt>''' 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 <tt>M64ERR_SUCCESS</tt>.
|-
|Requirements
|Both the core library and the plugin library must already be initialized with the <tt>CoreStartup()/PluginStartup()</tt> 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 ==
{| border="1"
|Prototype
|'''<tt>m64p_error CoreDoCommand(m64p_command Command, int ParamInt, void *ParamPtr)</tt>'''
|-
|Input Parameters
|'''<tt>Command</tt>''' Enumerated type specifying which command should be executed.<br />
'''<tt>ParamInt</tt>''' An integer value which may be used as an input to the command.<br />
'''<tt>ParamPtr</tt>''' A pointer which may be used as an input to the command.<br />
|-
|Requirements
|The core library must already be initialized with the <tt>CoreStartup()</tt> 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.
|}
<br />

{| border="1"
!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.
|'''<tt>ParamPtr</tt>''' Pointer to the uncompressed ROM image in memory.<br />'''<tt>ParamInt</tt>''' 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.
|'''<tt>ParamPtr</tt>''' Pointer to a <tt>rom_header</tt> struct to receive the data.<br />'''<tt>ParamInt</tt>''' The size in bytes of the <tt>rom_header</tt> struct.
|A ROM image must be open.
|-
|M64CMD_ROM_GET_SETTINGS
|This will retrieve the settings data of the currently open ROM.
|'''<tt>ParamPtr</tt>''' Pointer to a <tt>rom_settings</tt> struct to receive the data.<br />'''<tt>ParamInt</tt>''' The size in bytes of the <tt>rom_settings</tt> 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
|'''<tt>ParamInt</tt>''' An <tt>m64p_core_param</tt> enumerated type specifying the desired state variable'''<br /><tt>ParamPtr</tt>''' 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
|'''<tt>ParamInt</tt>''' An <tt>m64p_core_param</tt> enumerated type specifying the desired state variable'''<br /><tt>ParamPtr</tt>''' 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 '''<tt>ParamPtr</tt>''' is not NULL, this function will load a state file from a full pathname specified by this pointer.  Otherwise ('''<tt>ParamPtr</tt>''' is NULL), it will load from the current slot.
|'''<tt>ParamInt</tt>''' Ignored'''<br /><tt>ParamPtr</tt>''' 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 '''<tt>ParamPtr</tt>''' is not NULL, this function will save a state file to a full pathname specified by this pointer.  Otherwise ('''<tt>ParamPtr</tt>''' is NULL), it will save to the current slot.
|'''<tt>ParamInt</tt>''' This parameter will only be used if '''<tt>ParamPtr</tt>''' 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. '''<br /><tt>ParamPtr</tt>''' Pointer to string containing state file path and name, or NULL<br />
|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
|'''<tt>ParamInt</tt>''' Value to set for the current slot index.  Must be between 0 and 9'''<br /><tt>ParamPtr</tt>''' Ignored<br />
|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.
|'''<tt>ParamInt</tt>''' 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.
|'''<tt>ParamInt</tt>''' 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 '''<tt>ParamPtr</tt>''' 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.
|'''<tt>ParamPtr</tt>''' Can be either NULL or a <tt>m64p_frame_callback</tt> 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 '''<tt>ParamPtr</tt>'''.
|'''<tt>ParamInt</tt>''' 1 to copy the buffer that is currently displayed (front buffer), 0 to copy the buffer that is being drawn (back buffer).'''<br /><tt>ParamPtr</tt>'''A 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.
|'''<tt>ParamInt</tt>''' 0 to do a soft reset, 1 to do a hard reset.'''<br /><tt>ParamPtr</tt>''' 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).
|'''<tt>ParamInt</tt>''' Ignored'''<br /><tt>ParamPtr</tt>''' Ignored
|The emulator must be currently running or paused.
|}
<br />


== 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 <tt>StateCallback</tt> function pointer given to the '''<tt>CoreStartup</tt>''' 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.
<br />
{| border="1"
!Name!!Readable!!Writable!!<tt>int</tt> Parameter Encoding!!Notes
|-
|M64CORE_EMU_STATE
|Yes
|Yes
|<tt>enum m64p_emu_state</tt>
|<tt>1</tt>=Stopped, <tt>2</tt>=Running, <tt>3</tt>=Paused
|-
|M64CORE_VIDEO_MODE
|Yes
|Yes
|<tt>enum m64p_video_mode</tt>
|<tt>1</tt>=None (video not running), <tt>2</tt>=Windowed, <tt>3</tt>=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
|<tt>1</tt> to enable speed limiter, or <tt>0</tt> to disable speed limiter.
|When speed limiter is disabled, emulator will run as fast as possible (useful for benchmarking).
|-
|M64CORE_VIDEO_SIZE
|Yes
|Yes
|<tt>(ScreenWidth << 16) + ScreenHeight</tt>
|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
|<tt>1</tt> if muted, otherwise <tt>0</tt>
|
|-
|M64CORE_INPUT_GAMESHARK
|Yes
|Yes
|<tt>1</tt> when Gameshark button pressed, <tt>0</tt> when button released.
|Callback function will be invoked on both button press and release.
|-
|M64CORE_STATE_LOADCOMPLETE
|No
|No
|<tt>1</tt> if state loading was successful, <tt>0</tt> 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
|<tt>1</tt> if state saving was successful, <tt>0</tt> 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.
|}
<br />

== ROM Handling Functions ==
{| border="1"
|Prototype
|'''<tt>m64p_error CoreGetRomSettings(m64p_rom_settings *RomSettings, int RomSettingsLength, int Crc1, int Crc2)</tt>'''
|-
|Input Parameters
|'''<tt>RomSettings</tt>''' Pointer to <tt>m64p_rom_settings</tt> object to be filled in with data.<br />
'''<tt>RomSettingsLength</tt>''' Size of the object pointed to by '''<tt>RomSettings</tt>''' in bytes.<br />
'''<tt>Crc1</tt>''' A 32-bit integer value containing the first CRC (taken from the ROM header) to identify the ROM.<br />
'''<tt>Crc2</tt>''' 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 <tt>CoreStartup()</tt> function.  The '''<tt>RomSettings</tt>''' pointer must not be NULL.  The '''<tt>RomSettingsLength</tt>''' value must be greater than or equal to the size of the <tt>m64p_rom_settings</tt> structure.  This function does not require any ROM image to be currently open.
|-
|Usage
|This function searches through the data in the <tt>Mupen64Plus.ini</tt> file to find an entry which matches the given '''<tt>Crc1</tt>''' and '''<tt>Crc2</tt>''' hashes, and if found, fills in the '''<tt>RomSettings</tt>''' structure with the data from the <tt>Mupen64Plus.ini</tt> file.
|}
<br />

== Video Extension Functions ==
{| border="1"
|Prototype
|'''<tt>m64p_error CoreOverrideVidExt(m64p_video_extension_functions *VideoFunctionStruct);</tt>'''
|-
|Input Parameters
|'''<tt>VideoFunctionStruct</tt>''' Pointer to a structure (defined in [[Mupen64Plus v2.0 headers#m64p_types.h|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 <tt>Functions</tt> struct member to be equal to 11 or more.
|}
<br />

== Cheat Functions ==
{| border="1"
|Prototype
|'''<tt>m64p_error CoreAddCheat(const char *CheatName, m64p_cheat_code *CodeList, int NumCodes)</tt>'''
|-
|Input Parameters
|'''<tt>CheatName</tt>''' Pointer to NULL-terminated string containing a unique name for this Cheat Function.<br />
'''<tt>CodeList</tt>''' Pointer to an array of <tt>m64p_cheat_code</tt> objects.<br />
'''<tt>NumCodes</tt>''' Number of <tt>m64p_cheat_code</tt> 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 <tt>m64p_cheat_code</tt> elements.  If a Cheat Function with the given '''<tt>CheatName</tt>''' already exists, it will be removed and the new Cheat Function will be added in its place.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error CoreCheatEnabled(const char *CheatName, int Enabled)</tt>'''
|-
|Input Parameters
|'''<tt>CheatName</tt>''' Pointer to NULL-terminated string containing the name of an existing Cheat Function.<br />
'''<tt>Enabled</tt>''' 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.
|}