source/mupen64plus-core/doc/emuwiki-api-doc/Mupen64Plus_v2.0_Plugin_API.txt

   1 [[Mupen64Plus v2.0 Core API v1.0|Mupen64Plus v2.0 API]]
   2
   3 = Mupen64Plus v2.0 Plugin API =
   4
   5 This section lists all of the functions which are exported by the plugins. The front-end application should only use the PluginStartup, PluginShutdown, and PluginGetVersion functions. All other functions will only be called from the core.
   6
   7 == Common Plugin API ==
   8 These functions are present in all of the plugins.
   9
  10 {| border="1"
  11 |Prototype
  12 |'''<tt>m64p_error PluginStartup(m64p_dynlib_handle CoreLibHandle, void *Context, void (*DebugCallback)(void *Context, int level, const char *Message))</tt>'''
  13 |-
  14 |Input Parameters
  15 |'''<tt>CoreLibHandle</tt>''' Dynamic library handle (defined in [[Mupen64Plus v2.0 headers#m64p_types.h|m64p_types.h]]) corresponding with the core mupen64plus library.<br />
  16 '''<tt>Context</tt>''' Pointer which will be passed back to the '''<tt>DebugCallback</tt>''' function.  Can be NULL.<br />
  17 '''<tt>DebugCallback</tt>''' Pointer to function in front-end for receiving debug information and warnings from the plugin.  This function must be thread-safe.  Can be NULL.
  18 |-
  19 |Requirements
  20 |This function must be called before any other plugin functions.  The Core library must already be started before calling this function.  This function must be called before attaching the plugin to the core.
  21 |-
  22 |Usage
  23 |This function initializes plugin for use by allocating memory, creating data structures, and loading the configuration data.  This function may return <tt>M64ERR_INCOMPATIBLE</tt> if an older core library is used with a newer plugin.
  24 |}
  25 <br />
  26 {| border="1"
  27 |Prototype
  28 |'''<tt>m64p_error PluginShutdown(void)</tt>'''
  29 |-
  30 |Requirements
  31 |This plugin should be detached from the core before calling this function.
  32 |-
  33 |Usage
  34 |This function destroys data structures and releases memory allocated by the plugin library.
  35 |}
  36 <br />
  37 {| border="1"
  38 |Prototype
  39 |'''<tt>m64p_error PluginGetVersion(m64p_plugin_type *PluginType, int *PluginVersion, int *APIVersion, const char **PluginNamePtr, int *Capabilities)</tt>'''
  40 |-
  41 |Input Parameters
  42 |'''<tt>PluginType</tt>''' Pointer to an enumerated type to store the plugin type of this plugin.<br />
  43 '''<tt>PluginVersion</tt>''' Pointer to an integer to store the version number of this plugin.  Version number 2.1.3 would be stored as 0x00020103.<br />
  44 '''<tt>APIVersion</tt>''' Pointer to an integer to store the version number of the Core-Plugin API for this type of plugin used by this plugin.<br />
  45 '''<tt>PluginNamePtr</tt>''' Pointer to a const character pointer to receive the name of this plugin.  The const char * which is returned must point to a persistent string (ie, not stored on the stack).<br />
  46 '''<tt>Capabilities</tt>''' Pointer to an integer to store a logically-or'd set of flags which specify the capabilities of the plugin which were built into the library during compilation.  These are currently only defined for the core, so this will always return 0 for a plugin.
  47 |-
  48 |Usage
  49 |This function retrieves version information from the plugin.  This function is the same for the core library and the plugins, so that a front-end may examine all shared libraries in a directory and determine their types.  Any of the input parameters may be set to NULL and this function will succeed but won't return the corresponding information.
  50 |}
  51
  52 == Video Plugin API ==
  53
  54 === Mupen64Plus v2.0 Video Plugin API ===
  55 {|
  56 |<tt>void ChangeWindow(void);</tt>
  57 |Toggle Fullscreen/Windowed mode
  58 |-
  59 |<tt>BOOL InitiateGFX(GFX_INFO Gfx_Info);</tt>
  60 |Called during <tt>CoreAttachPlugin</tt> to send info about the emulator core to the graphics plugin and start up the graphics sub-system.  This should create the rendering window and the OpenGL context.
  61 |-
  62 |<tt>void MoveScreen(int xpos, int ypos);</tt>
  63 |This function is called in response to the emulator receiving a WM_MOVE, passing the xpos and ypos from that message.
  64 |-
  65 |<tt>void ProcessDList(void);</tt>
  66 |Process high-level graphics D-list.  (not currently used)
  67 |-
  68 |<tt>void ProcessRDPList(void);</tt>
  69 |Process low-level graphics D-list.
  70 |-
  71 |<tt>void RomClosed(void);</tt>
  72 |Called after the emulator is stopped.
  73 |-
  74 |<tt>int RomOpen(void);</tt>
  75 |Called just before the emulator begins executing a ROM.  '''***changed*** - this function now returns an int (boolean)'''
  76 |-
  77 |<tt>void ShowCFB (void);</tt>
  78 |Called from the RSP plugin to signal a condition to the video plugin.
  79 |-
  80 |<tt>void UpdateScreen(void);</tt>
  81 |This function is called in response to a VSync condition if the VI bit in MI_INTR_REG is set
  82 |-
  83 |<tt>void ViStatusChanged(void);</tt>
  84 |This function is called to notify the video plugin that the ViStatus registers value has been changed.
  85 |-
  86 |<tt>void ViWidthChanged(void);</tt>
  87 |This function is called to notify the video plugin that the ViWidth registers value has been changed.
  88 |-
  89 |<tt>void ReadScreen2(void *dest, int *width, int *height, int front);</tt>
  90 |This function reads the pixels of the frame buffer that is either currently displayed (front != 0) or being drawn (front == 0)
  91 |-
  92 |<tt>void SetRenderingCallback(void (*callback)(int bScreenRedrawn));</tt>
  93 |Allows the core to register a callback function that will be called by the graphics plugin just before the the frame buffers are swapped. '''***changed*** - as of video api v2.1.0, the callback function must take a single int (boolean) parameter, which tells the core whether or not the screen has been redrawn since the last time the callback was called.  This is used to prevent screenshots from containing OSD text.'''
  94 |-
  95 |<tt>void ResizeVideoOutput(int width, int height);</tt>
  96 |'''***new*** function added in video api v2.2.0'''  This function notifies the video plugin that the output video window has changed size.  If resizing is supported, the video plugin should update its internal state to reflect the new window size, and then call the ResizeWindow function in the Video Extension API.
  97 |-
  98 |<tt>void FBRead(unsigned int addr)</tt>
  99 |Read data from frame buffer into emulated RAM space
 100 |-
 101 |<tt>void FBWrite(unsigned int addr, unsigned int size)</tt>
 102 |Write data from emulated RAM space into frame buffer
 103 |-
 104 |<tt>void FBGetFrameBufferInfo(void *p)</tt>
 105 |Get some information about the frame buffer
 106 |}
 107
 108 === Remove From Older Video API ===
 109 {|
 110 |-
 111 |<tt>void CaptureScreen (char * Directory);</tt>
 112 |-
 113 |<tt>void CloseDLL(void);</tt>
 114 |-
 115 |<tt>void DllAbout(HWND hParent);</tt>
 116 |-
 117 |<tt>void DllConfig(HWND hParent);</tt>
 118 |-
 119 |<tt>void DllTest(HWND hParent);</tt>
 120 |-
 121 |<tt>void DrawScreen(void);</tt>
 122 |-
 123 |<tt>void GetDllInfo(PLUGIN_INFO *PluginInfo);</tt>
 124 |-
 125 |<tt>void ReadScreen(void **dest, int *width, int *height);</tt>
 126 |-
 127 |<tt>void SetConfigDir(char *configDir);</tt>
 128 |-
 129 |<br />
 130 <tt>typedef struct {...} PLUGIN_INFO</tt>
 131 |}
 132
 133 == Audio Plugin API ==
 134
 135 === Mupen64Plus v2.0 Audio Plugin API ===
 136 {|
 137 |<tt>void AiDacrateChanged(int SystemType);</tt>
 138 |This function is called to notify the audio plugin that the AiDacrate register's value has been changed.
 139 |-
 140 |<tt>void AiLenChanged(void);</tt>
 141 |This function is called to notify the audio plugin that the AiLen register's value has been changed.
 142 |-
 143 |<tt>BOOL InitiateAudio(AUDIO_INFO Audio_Info);</tt>
 144 |Called during <tt>CoreAttachPlugin</tt> to send info about the emulator core to the audio plugin.
 145 |-
 146 |<tt>void ProcessAList(void);</tt>
 147 |Signal that there is an A-list to be processed.  (not currently used)
 148 |-
 149 |<tt>int RomOpen(void);</tt>
 150 |Called just before the emulator begins executing a ROM.  '''***changed*** - this function now returns an int (boolean)'''
 151 |-
 152 |<tt>void RomClosed(void);</tt>
 153 |Called after the emulator is stopped.
 154 |-
 155 |<tt>void SetSpeedFactor(int percent);</tt>
 156 |Called when the emulator playback speed changes.
 157 |-
 158 |<tt>void VolumeUp(void);</tt><br />
 159 <tt>void VolumeDown(void);</tt>
 160 |Increase or decrease volume level
 161 |-
 162 |<tt>int VolumeGetLevel(void);</tt>
 163 |Get current volume level in percentage, between 0 and 100.  '''***NEW***'''
 164 |-
 165 |<tt>void VolumeSetLevel(int level);</tt>
 166 |Set current volume level.  <tt>level</tt> must be between 0 and 100.  '''***NEW***'''
 167 |-
 168 |<tt>void VolumeMute(void);</tt>
 169 |Toggle between audio muted and un-muted
 170 |-
 171 |<tt>const char * VolumeGetString(void);</tt>
 172 |Return a string describing the current volume level
 173 |}
 174
 175 === Remove From Older Audio API ===
 176 {|
 177 |-
 178 |<tt>DWORD AiReadLength(void);</tt>
 179 |-
 180 |<tt>void AiUpdate(BOOL Wait);</tt>
 181 |-
 182 |<tt>void CloseDLL(void);</tt>
 183 |-
 184 |<tt>void DllAbout(HWND hParent);</tt>
 185 |-
 186 |<tt>void DllConfig(HWND hParent);</tt>
 187 |-
 188 |<tt>void DllTest(HWND hParent);</tt>
 189 |-
 190 |<tt>void GetDllInfo(PLUGIN_INFO *PluginInfo);</tt>
 191 |-
 192 |<tt>BOOL PauseAudio(BOOL Pause);</tt>
 193 |-
 194 |<tt>void SetConfigDir(char *configDir);</tt>
 195 |-
 196 |<br />
 197 <tt>typedef struct {...} PLUGIN_INFO</tt>
 198 |}
 199
 200 == Input Plugin API ==
 201
 202 === Mupen64Plus v2.0 Input Plugin API ===
 203 {|
 204 |<tt>void ControllerCommand(int Control, BYTE * Command);</tt>
 205 |Process the raw data that has just been sent to a specific controller.
 206 |-
 207 |<tt>void GetKeys(int Control, BUTTONS * Keys);</tt>
 208 |Get the current state of the controller's buttons
 209 |-
 210 |<tt>void InitiateControllers(CONTROL_INFO ControlInfo);</tt>
 211 |Setup controller data structures
 212 |-
 213 |<tt>void ReadController(int Control, BYTE *Command);</tt>
 214 |Process the raw data in the pif ram that is about to be read. (not currently used)
 215 |-
 216 |<tt>int RomOpen(void);</tt>
 217 |Called just before the emulator begins executing a ROM.  '''***changed*** - this function now returns an int (boolean)'''
 218 |-
 219 |<tt>void RomClosed(void);</tt>
 220 |Called after the emulator is stopped.
 221 |-
 222 |<tt>void SDL_KeyDown(int keymod, int keysym);</tt>
 223 |Pass a SDL_KEYDOWN-style message to the input plugin
 224 |-
 225 |<tt>void SDL_KeyUp(int keymod, int keysym);</tt>
 226 |Pass a SDL_KEYUP-style message to the input plugin
 227 |}
 228
 229 === Remove From Older Input API ===
 230 {|
 231 |-
 232 |<tt>void CloseDLL(void);</tt>
 233 |-
 234 |<tt>void DllAbout(HWND hParent);</tt>
 235 |-
 236 |<tt>void DllConfig(HWND hParent);</tt>
 237 |-
 238 |<tt>void DllTest(HWND hParent);</tt>
 239 |-
 240 |<tt>void GetDllInfo(PLUGIN_INFO *PluginInfo);</tt>
 241 |-
 242 |<tt>void SetConfigDir(char *configDir);</tt>
 243 |-
 244 |<tt>void WM_KeyDown(WPARAM wParam, LPARAM lParam);</tt>
 245 |-
 246 |<tt>void WM_KeyUp(WPARAM wParam, LPARAM lParam);</tt>
 247 |-
 248 |<br />
 249 <tt>typedef struct {...} PLUGIN_INFO</tt>
 250 |}
 251
 252 == RSP Plugin API ==
 253
 254 === Mupen64Plus v2.0 RSP Plugin API ===
 255 {|
 256 |<tt>DWORD DoRspCycles(DWORD Cycles);</tt>
 257 |Process pending RSP tasks.
 258 |-
 259 |<tt>void InitiateRSP(RSP_INFO Rsp_Info, DWORD *CycleCount);</tt>
 260 |Called during <tt>CoreAttachPlugin</tt> to send info about the emulator core to the audio plugin.
 261 |-
 262 |<tt>void RomClosed(void);</tt>
 263 |Called after the emulator is stopped.
 264 |}
 265
 266 === Remove From Older RSP API ===
 267 {|
 268 |-
 269 |<tt>void CloseDLL(void);</tt>
 270 |-
 271 |<tt>void DllAbout(HWND hParent);</tt>
 272 |-
 273 |<tt>void DllConfig(HWND hParent);</tt>
 274 |-
 275 |<tt>void DllTest(HWND hParent);</tt>
 276 |-
 277 |<tt>void GetDllInfo(PLUGIN_INFO *PluginInfo);</tt>
 278 |-
 279 |<tt>void GetRspDebugInfo(RSPDEBUG_INFO * RSPDebugInfo);</tt>
 280 |-
 281 |<tt>void InitiateRSPDebugger(DEBUG_INFO DebugInfo);</tt>
 282 |-
 283 |<br />
 284 <tt>typedef struct {...} PLUGIN_INFO</tt><br />
 285 <tt>typedef struct {...} RSPDEBUG_INFO</tt><br />
 286 <tt>typedef struct {...} DEBUG_INFO</tt>
 287 |}
 288