/[pcsx2_0.9.7]/trunk/common/include/PluginCallbacks.h
ViewVC logotype

Annotation of /trunk/common/include/PluginCallbacks.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 10 - (hide annotations) (download)
Mon Sep 6 11:40:06 2010 UTC (9 years, 11 months ago) by william
File MIME type: text/plain
File size: 65499 byte(s)
exported r3113 from ./upstream/trunk
1 william 10 /* PCSX2 - PS2 Emulator for PCs
2     * Copyright (C) 2002-2010 PCSX2 Dev Team
3     *
4     * PCSX2 is free software: you can redistribute it and/or modify it under the terms
5     * of the GNU Lesser General Public License as published by the Free Software Found-
6     * ation, either version 3 of the License, or (at your option) any later version.
7     *
8     * PCSX2 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9     * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
10     * PURPOSE. See the GNU General Public License for more details.
11     *
12     * You should have received a copy of the GNU General Public License along with PCSX2.
13     * If not, see <http://www.gnu.org/licenses/>.
14     */
15    
16    
17     #ifndef __PLUGINCALLBACKS_H__
18     #define __PLUGINCALLBACKS_H__
19    
20     // --------------------------------------------------------------------------------------
21     // PS2E - Version 2.xx!
22     // --------------------------------------------------------------------------------------
23     // This header file defines the new PS2E interface, which is laid out to be a little more
24     // efficient and easy to use, and boasts significantly improved APIs over the original
25     // PS2E v1.xx, which was mostly a series of hacked additions on top of PS1E. In summary:
26     // this API is designed from the ground up to suit PS2 emulation, instead of being built
27     // on top of a PS1 API.
28     //
29     // Design Philosophies:
30     //
31     // 1. Core APIs are established using a pair of DLL/library bindings (one for plugin callbacks
32     // and one for emulator callbacks), which pass structures of function pointers.
33     //
34     // 2. Plugin instance data should be attached to the end of the plugin's callback api
35     // data structure (see PS2E_ComponentAPI), and the PS2E_ComponentAPI struct is
36     // passed along with every callback defined in the structure.
37     //
38     // 3. All plugin callbacks use __fastcall calling convention (which passes the first
39     // two parameters int he ECX and EDX registers). Most compilers support this, and
40     // register parameter passing is actually the standard convention on x86/64.
41     //
42     // Rationale: This design improves code generation efficiency, especially when using
43     // points 2 and 3 together (typically reduces 2 or 3 dereferences to 1 dereference).
44     // The drawback is that not all compilers support x86/32 __fastcall, and such compilers
45     // will be unable to create PS2Ev2 plugins. GCC, MSVC, Intel, and Borland (as
46     // __msfastcall) do support it, and Watcom as well using #pragma aux. Anything else
47     // we just don't care about. Sorry. ;)
48     //
49     // 4. Emulation is restricted to a single instance per-process, which means that use of
50     // static/global instance variables by plugins is perfectly valid (however discouraged
51     // due to efficiency reasons, see 2 and 3).
52     //
53     // Rationale: Due to complexities in implementing an optimized PS2 emulator (dynamic
54     // recompilation, memory protection, console pipe management, thread management, etc.)
55     // it's really just better this way. The drawback is that every geeks' dream of having
56     // 6 different games emulating at once, with each output texture mapped to the side of
57     // a rotating cube, will probably never come true. Tsk.
58     //
59    
60     // --------------------------------------------------------------------------------------
61     // <<< Important Notes to Plugin Authors >>>
62     // --------------------------------------------------------------------------------------
63     // * C++ only: C++ Exceptions must be confined to your plugin! Exceptions thrown by plugins
64     // may not be handled correctly if allowed to escape the scope of the plugin, and could
65     // result in unexpected behavior or odd crashes (this especially true on non-Windows
66     // operating systems). For C++ plugins this means ensuring that any code that uses
67     // 'new' or STL containers (string, list, vector, etc) are contained within a try{}
68     // block, since the STL can throw std::bad_alloc.
69     //
70     // * C++ on MSW only: SEH Exceptions must not be swallowed "blindly." In simple terms this
71     // means do not use these without proper re-throws, as the emulator may rely on SEH
72     // for either PS2 VM cache validation or thread cancellation:
73     // - catch(...)
74     // - __except(EXCEPTION_EXECUTE_HANDLER)
75     //
76     // * Many callbacks are optional, and have been marked as such. Any optional callback can be
77     // left NULL. Any callback not marked optional and left NULL will cause the emulator to
78     // invalidate the plugin on either enumeration or initialization.
79     //
80    
81     // --------------------------------------------------------------------------------------
82     // <<< Important Notes to All Developers >>>
83     // --------------------------------------------------------------------------------------
84     // * Callback APIs cannot involve LIB-C or STL objects (such as FILE or std::string). The
85     // internal layout of these structures can vary between versions of GLIB-C / MSVCRT, and
86     // in the case of STL and other C++ objects, can vary based on seemingly mundane compiler
87     // switches.
88     //
89     // * Callback APIs cannot alloc/free memory across dynamic library boundaries. An object
90     // allocated by a plugin must be freed by that plugin, and cannot be freed by the emu.
91     //
92     // * C++ exception handling cannot be used by either plugin callbacks or emulator callbacks.
93     // This includes the emulator's Console callbacks, for example, since the nature of C++
94     // ID-based RTTI could cause a C++ plugin with its own catch handlers to catch exceptions
95     // of mismatched types from the emulator.
96     //
97     // * Addendum to Exception Handling: On most OS's, pthreads relies on C++ exceptions to
98     // cancel threads. On Windows, this uses SEH so it works safely even across plugin stack
99     // frames. On all other non-MSW platforms pthreads cancelation *must* be disabled in
100     // both emulator and plugin except for a single explicit cancelation point (usually
101     // provided during vsync).
102     //
103     // * If following all these rules, then it shouldn't matter if you mix debug/release builds
104     // of plugins, SEH options (however it's recommended to ALWAYS have SEH enabled, as it
105     // hardly has any impact on performance on modern CPUs), compile with different versions
106     // of your MSVC/GCC compiler, or use different versions of LibC or MSVCRT. :)
107    
108    
109     #ifndef BOOL
110     typedef int BOOL;
111     #endif
112    
113     // --------------------------------------------------------------------------------------
114     // PS2E_HWND - OS-independent window handle
115     // --------------------------------------------------------------------------------------
116     // HWND is our only operating system dependent type. For it to be defined as accurately
117     // as possible, this header file needs to be included after whatever window/GUI platform
118     // headers you need (wxWidgets, Windows.h, GTK, etc).
119     //
120     // We could be lazy with this typedef, because window handles are always a (void*) on all
121     // platforms that matter to us (windows, gtk, OSX). But Windows has some type strictness
122     // on its HWND define that could be useful, and well it's probably good practice to use
123     // platform available defines when they exist.
124     //
125     #if defined( _WX_DEFS_H_ )
126     typedef WXWidget PS2E_HWND;
127     #elif defined( _WINDEF_ )
128     // For Windows let's use HWND, since it has some type strictness applied to it.
129     typedef HWND PS2E_HWND;
130     #else
131     // Unsupported platform... use void* as a best guess. Should work fine for almost
132     // any GUI platform, and certainly works for any currently supported one.
133     typedef void* PS2E_HWND;
134     #endif
135    
136     // --------------------------------------------------------------------------------------
137     // PS2E_THISPTR - (ps2 component scope 'this' object pointer type)
138     // --------------------------------------------------------------------------------------
139     // This macro provides C++ plugin authors with a reasonably friendly way to automatically
140     // typecast the session objects for your plugin to your internal type. Just #define
141     // PS2E_THISPTR to your internal structure type prior to loading this header file, and all
142     // APIs will assume your struct type in their signature. Since all pointer types are inter-
143     // changeable, plugin APIs will retain full compatibility as long as PS2E_THISPTR is a
144     // pointer type.
145     //
146     #ifndef PS2E_THISPTR
147     # define PS2E_THISPTR struct _PS2E_ComponentAPI*
148     #else
149     // Ensure the user's defined PS2E_THISPTR retains the correct signature for our
150     // plugin API.
151     C_ASSERT( sizeof(PS2E_THISPTR) == sizeof(void*) );
152     #endif
153    
154     // PS2E_LIB_THISPTR - (library scope version of PS2E_THISPTR)
155     #ifndef PS2E_LIB_THISPTR
156     # define PS2E_LIB_THISPTR void*
157     #else
158     // Ensure the user's defined PS2E_THISPTR retains the correct signature for our
159     // plugin API.
160     C_ASSERT( sizeof(PS2E_LIB_THISPTR) == sizeof(void*) );
161     #endif
162    
163     // Use fastcall by default, since under most circumstances the object-model approach of the
164     // API will benefit considerably from it. (Yes, this means that compilers that do not
165     // support fastcall are basically unusable for plugin creation. Too bad. :p
166     #define PS2E_CALLBACK __fastcall
167    
168    
169     #ifndef __cplusplus
170     extern "C" {
171     #endif
172    
173     // ------------------------------------------------------------------------------------
174     // Plugin Type / Version Enumerations
175     // ------------------------------------------------------------------------------------
176    
177     enum PS2E_ComponentTypes
178     {
179     PS2E_TYPE_GS = 0,
180     PS2E_TYPE_PAD,
181     PS2E_TYPE_SPU2,
182     PS2E_TYPE_CDVD,
183     PS2E_TYPE_DEV9,
184     PS2E_TYPE_USB,
185     PS2E_TYPE_FW,
186     PS2E_TYPE_SIO,
187     PS2E_TYPE_Mcd,
188     };
189    
190     enum PluginLibVersion
191     {
192     PS2E_VER_GS = 0x1000,
193     PS2E_VER_PAD = 0x1000,
194     PS2E_VER_SPU2 = 0x1000,
195     PS2E_VER_CDVD = 0x1000,
196     PS2E_VER_DEV9 = 0x1000,
197     PS2E_VER_USB = 0x1000,
198     PS2E_VER_FW = 0x1000,
199     PS2E_VER_SIO = 0x1000
200     };
201    
202     enum OSDIconTypes
203     {
204     OSD_Icon_None = 0,
205     OSD_Icon_Error,
206     OSD_Icon_Notice, // An exclamation point maybe?
207    
208     // [TODO] -- dunno. What else?
209    
210     // Emulators implementing their own custom non-standard icon extensions should do so
211     // somewhere after OSD_Icon_ReserveEnd. All values below this are reserved.
212     // .
213     // .
214     // .
215     OSD_Icon_ReserveEnd = 0x1000
216     };
217    
218     enum PS2E_MenuItemStyle
219     {
220     MenuType_Normal = 0,
221     MenuType_Checked,
222     MenuType_Radio,
223     MenuType_Separator
224     };
225    
226     typedef void* PS2E_MenuHandle;
227     typedef void* PS2E_MenuItemHandle;
228     typedef void PS2E_CALLBACK PS2E_OnMenuItemClicked( PS2E_THISPTR* thisptr, void* userptr );
229    
230     // --------------------------------------------------------------------------------------
231     // PS2E_ConsoleWriterAPI
232     // --------------------------------------------------------------------------------------
233     // APIs for writing text to the console. Typically the emulator will write the text to
234     // both a console window and to a disk file, however actual implementation is up to the
235     // emulator. All text must be either 7-bit ASCII or UTF8 encoded. Other codepages or
236     // MBCS encodings will not be displayed properly.
237     //
238     // Standard streams STDIO and STDERR can be used instead, however there is no guarantee
239     // that they will be handled in a convenient fashion. Different platforms and operating
240     // systems have different methods of standard stream pipes, which is why the ConsoleWriter
241     // API has been exposed to plugins.
242     //
243     // Development Notes:
244     // 'char' was chosen over 'wchar_t' because 'wchar_t' is a very loosely defined type that
245     // can vary greatly between compilers (it can be as small as 8 bits and as large as a
246     // compiler wants it to be). Because of this we can't even make assumptions about its
247     // size within the context of a single operating system; so it just won't do. Just make
248     // sure everything going into the function is UTF8 encoded and all is find.
249     //
250     typedef struct _PS2E_ConsoleWriterAPI
251     {
252     // Writes text to console; no newline is appended.
253     void (PS2E_CALLBACK* Write)( const char* fmt, ... );
254    
255     // Appends an automatic newline to the specified formatted output.
256     void (PS2E_CALLBACK* WriteLn)( const char* fmt, ... );
257    
258     // This function always appends a newline.
259     void (PS2E_CALLBACK* Error)( const char* fmt, ... );
260    
261     // This function always appends a newline.
262     void (PS2E_CALLBACK* Warning)( const char* fmt, ... );
263    
264     void* reserved[4];
265    
266     } PS2E_ConsoleWriterAPI;
267    
268     // --------------------------------------------------------------------------------------
269     // PS2E_ConsoleWriterWideAPI
270     // --------------------------------------------------------------------------------------
271     // This is the wide character version of the ConsoleWriter APi. Please see the description
272     // of PS2E_ConsoleWriterAPI for details.
273     //
274     // Important Usage Note to Plugin Authors:
275     // Before using the functions in this structure, you *must* confirm that the emulator's
276     // size of wchar_t matches the size provided by your own compiler. The size of wchar_t
277     // is provided in the PS2E_EmulatorInfo struct.
278     //
279     typedef struct _PS2E_ConsoleWriterWideAPI
280     {
281     // Writes text to console; no newline is appended.
282     void (PS2E_CALLBACK* Write)( const wchar_t* fmt, ... );
283    
284     // Appends an automatic newline to the specified formatted output.
285     void (PS2E_CALLBACK* WriteLn)( const wchar_t* fmt, ... );
286    
287     // This function always appends a newline.
288     void (PS2E_CALLBACK* Error)( const wchar_t* fmt, ... );
289    
290     // This function always appends a newline.
291     void (PS2E_CALLBACK* Warning)( const wchar_t* fmt, ... );
292    
293     void* reserved[4];
294    
295     } PS2E_ConsoleWriterWideAPI;
296    
297    
298     // --------------------------------------------------------------------------------------
299     // PS2E_Image
300     // --------------------------------------------------------------------------------------
301     // Simple RGBA image data container, for passing surface textures to the GS plugin, and
302     // for receiving snapshots from the GS plugin.
303     //
304     // fixme - this might be more ideal as BGRA or ABGR format on Windows platforms?
305     //
306     typedef struct _PS2E_Image
307     {
308     u32 width;
309     u32 height;
310     u8* data; // RGBA data. top to bottom.
311    
312     } PS2E_Image;
313    
314     // --------------------------------------------------------------------------------------
315     // PS2E_MenuItemInfo
316     // --------------------------------------------------------------------------------------
317     typedef struct _PS2E_MenuItemInfo
318     {
319     const char* LabelText;
320     const char* HelpText;
321    
322     // Optional image displayed with the menu option. The emulator may not support
323     // this option, or may choose to ignore or resize the image if the size parameters
324     // are outside a valid threshold.
325     const PS2E_Image* Image;
326    
327     // Specifies the style of the menu, either Normal, Checked, Radio, or Separator.
328     // This option is overridden if the SubMenu field is non-NULL (in such case the
329     // menu assumes submenu mode).
330     PS2E_MenuItemStyle Style;
331    
332     // Specifies the handle of a sub menu to bind to this menu. If NULL, the menu is
333     // created normally. If non-NULL, the menu item will use sub-menu mode and will
334     // ignore the Style field.
335     PS2E_MenuHandle SubMenu;
336    
337     // Menu that this item is attached to. When this struct is passed into AddMenuItem,
338     // the menu item will be automatically appended to the menu specified in this field
339     // if the field is non-NULL (if the field is NULL, then no action is taken).
340     PS2E_MenuHandle OwnerMenu;
341    
342     // When FALSE the menu item will appear grayed out to the user, and unselectable.
343     BOOL Enabled;
344    
345     // Optional user data pointer (or typecast integer value)
346     void* UserPtr;
347    
348     // Callback issued when the menu is clicked/activated. If NULL, the menu will be
349     // disabled (grayed).
350     PS2E_OnMenuItemClicked* OnClicked;
351    
352     } PS2E_MenuItemInfo;
353    
354     // --------------------------------------------------------------------------------------
355     // PS2E_MenuItemAPI
356     // --------------------------------------------------------------------------------------
357     typedef struct _PS2E_MenuItemAPI
358     {
359     // Allocates a new MenuItem and returns its handle. The returned item can be added to any
360     // menu.
361     PS2E_MenuItemHandle (PS2E_CALLBACK* MenuItem_Create)( PS2E_THISPTR thisptr );
362    
363     // Deletes the menu item and frees allocated resources. The menu item will be removed from
364     // whatever menu it is attached to. If the menu item has a SubMenu, the SubMenu is not
365     // deleted.
366     void (PS2E_CALLBACK* MenuItem_Delete)( PS2E_MenuItemHandle mitem );
367    
368     // (Re-)Assigns all properties for a menu. Assignment generally takes effect immediately.
369     void (PS2E_CALLBACK* MenuItem_SetEverything)( PS2E_MenuItemHandle mitem, const PS2E_MenuItemInfo* info );
370    
371     // Sets the text label of a menu item.
372     void (PS2E_CALLBACK* MenuItem_SetText)( PS2E_MenuItemHandle mitem, const char* text );
373    
374     // Assigns the help text for a menu item. This text is typically shown in a status
375     // bar at the bottom of the current window. This value may be ignored if the emu
376     // interface does not have a context for help text.
377     void (PS2E_CALLBACK* MenuItem_SetHelpText)( PS2E_MenuItemHandle mitem, const char* helptxt );
378    
379     // Gives the menu item an accompanying image (orientation of the image may depend
380     // on the operating system platform).
381     void (PS2E_CALLBACK* MenuItem_SetImage)( PS2E_MenuItemHandle mitem, const PS2E_Image* image );
382    
383     // Gives the menu item an accompanying image (orientation of the image may depend
384     // on the operating system platform).
385     //
386     // Returns:
387     // TRUE if the image was loaded successfully, or FALSE if the image was not found,
388     // could not be opened, or the image data is invalid (not a PNG, or data corrupted).
389     BOOL (PS2E_CALLBACK* MenuItem_SetImagePng_FromFile)( PS2E_MenuItemHandle mitem, const char* filename );
390    
391     // Gives the menu item an accompanying image (orientation of the image may depend on
392     // the operating system platform). Image is loaded from memory using a memory stream
393     // reader. This method is useful for loading image data embedded into the dll.
394     //
395     // Returns:
396     // TRUE if the image was loaded successfully, or FALSE if the image data is invalid
397     // (not a PNG, or data corrupted).
398     BOOL (PS2E_CALLBACK* MenuItem_SetImagePng_FromMemory)( PS2E_MenuItemHandle mitem, const u8* data );
399    
400     // Assigns the menu item's style.
401     void (PS2E_CALLBACK* MenuItem_SetStyle)( PS2E_MenuItemHandle mitem, PS2E_MenuItemStyle style );
402    
403     // Assigns a pointer value that the plugin can use to attach user-defined data to
404     // specific menu items. The value can be any integer typecast if you don't actually
405     // need more than an integers worth of data.
406     void (PS2E_CALLBACK* MenuItem_SetUserData)( PS2E_MenuItemHandle mitem, void* dataptr );
407    
408     // Assigns a submenu to the menu item, causing it to open the sub menu in cascade
409     // fashion. When a submenu is assigned, the Style attribute of the menu will be
410     // ignored. Passing NULL into this function will clear the submenu and return the
411     // menu item to whatever its current Style attribute is set to.
412     void (PS2E_CALLBACK* MenuItem_SetSubMenu)( PS2E_MenuItemHandle mitem, PS2E_MenuHandle submenu );
413    
414     // Assigns the callback function for this menu (important!). If passed NULL, the menu
415     // item will be automatically disabled (grayed out) by the emulator.
416     void (PS2E_CALLBACK* MenuItem_SetCallback)( PS2E_MenuItemHandle mitem, PS2E_OnMenuItemClicked* onClickedCallback );
417    
418     // Assigns the enabled status of a MenuItem. Use FALSE to gray out the menuitem option.
419     void (PS2E_CALLBACK* MenuItem_Enable)( PS2E_MenuItemHandle mitem, BOOL enable );
420    
421     // Returns the current enable status of the specified menu item.
422     BOOL (PS2E_CALLBACK* MenuItem_IsEnabled)( PS2E_MenuItemHandle mitem );
423    
424     void* reserved[4];
425    
426     } PS2E_MenuItemAPI;
427    
428     // --------------------------------------------------------------------------------------
429     // PS2E_VersionInfo
430     // --------------------------------------------------------------------------------------
431     // This structure is populated by the plugin via the PS2E_PluginLibAPI::GetVersion()
432     // callback. Specify -1 for any Version or Revision to disable/ignore it. The emulator
433     // will not factor that info into the display name of the plugin.
434     //
435     typedef struct _PS2E_VersionInfo
436     {
437     // Low/Mid/High versions combine to form a number in the format of: 2.3.1
438     // ... where 2 is the high version, 3 mid, and 1 low.
439     s16 VersionHigh;
440     s16 VersionMid;
441     s16 VersionLow;
442    
443     // Revision typically refers a revision control system (such as SVN). When displayed
444     // by the emulator it will have an 'r' prefixed before it.
445     s32 Revision;
446    
447     } PS2E_VersionInfo;
448    
449     // --------------------------------------------------------------------------------------
450     // PS2E_SessionInfo
451     // --------------------------------------------------------------------------------------
452     // This struct is populated by the emulator prior to starting emulation, and is passed to
453     // each plugin via a call to PS2E_PluginLibAPI::EmuOpen().
454     //
455     typedef struct _PS2E_SessionInfo
456     {
457     PS2E_HWND window;
458    
459     u32* CycleEE; // current EE cycle count
460     u32* CycleIOP; // current IOP cycle count
461    
462     u32 ElfCRC; // CRC of the ELF header for this app/game
463    
464     // Sony's assigned serial number, valid only for CD/CDVD games (ASCII-Z string).
465     // Ex: SLUS-2932
466     //
467     // (if the running app is not a sony-registered game, the serial will be a zero
468     // length string).
469     char Serial[16];
470    
471     } PS2E_SessionInfo;
472    
473     // --------------------------------------------------------------------------------------
474     // PS2E_EmulatorInfo
475     // --------------------------------------------------------------------------------------
476     // This struct is populated by the emulator when the application is started, and is passed
477     // to plugins via PS2E_InitAPI. Plugins may optionally use this information to determine
478     // compatibility or to select which special CPU-oriented builds and/or functions to bind
479     // to callbacks.
480     //
481     // The GetInt/GetBoolean/GetString/etc methods Provide an interface through which a plugin
482     // can retrieve special emulator-specific settings and information, or fetch options straight
483     // from the emulator's ini file itself. These are intended for advanced plugin/emu binding
484     // only, and should generally be accompanied with the appropriate version/name checks.
485     //
486     // Emulators may implement this as a direct match to the emu's ini file/registry contents
487     // (recommended), or may provide additional and/or alternative custom strings. Direct
488     // ini.registry relationships are preferred since those are easy for a plugin author to
489     // reference without documentation.
490     //
491     typedef struct _PS2E_EmulatorInfo
492     {
493     // Brief name of the emulator (ex: "PCSX2") [required]
494     // Depending on the design of the emulator, this string may optionally include version
495     // information, however that is not recommended since it can inhibit backward support.
496     const char* EmuName;
497    
498     // Version information. All fields besides the emulator's name are optional.
499     PS2E_VersionInfo EmuVersion;
500    
501     // Number of Physical Cores, as detected by the emulator.
502     // This should always match the real # of cores supported by hardware.
503     int PhysicalCores;
504    
505     // Number of Logical Cores, as detected and/or managed by the emulator.
506     // This is not necessarily a reflection of real hardware capabilities. The emu reserves
507     // the right to report this value as it deems appropriate, in management of threading
508     // resources.
509     int LogicalCores;
510    
511     // Specifies the size of the wchar_t of the emulator, in bytes. Plugin authors should be
512     // sure to check this against your own sizeof(wchar_t) before using any API that has
513     // a wchar_t parameter (such as the ConsoleWriterWide interface). wchar_t is a loosely
514     // defined type that can range from 8 bits to 32 bits (realistically, although there is
515     // no actual limit on size), and can vary between compilers for the same platform.
516     int Sizeof_wchar_t;
517    
518    
519     // Reserved area for future expansion of the structure (avoids having to upgrade the
520     // plugin api for amending new extensions).
521     int reserved1[6];
522    
523     // GetInt
524     // Self-explanatory.
525     //
526     // Returns:
527     // 0 - Value was retrieved successfully.
528     // 1 - Unknown value. Contents of dest are unchanged.
529     BOOL (PS2E_CALLBACK* GetInt)( const char* name, int* dest );
530    
531     // GetBoolean
532     // Assigns *dest either 1 (true) or 0 (false). Note to Emulators: Returning any non-
533     // zero value for true probably "works" but is not recommended, since C/C++ standard
534     // specifically defines the result of bool->int conversions as a 0 or 1 result.
535     //
536     // Returns:
537     // 0 - Value was retrieved successfully.
538     // 1 - Unknown value. Contents of dest are unchanged.
539     BOOL (PS2E_CALLBACK* GetBoolean)( const char* name, BOOL* result );
540    
541     // GetString
542     // Copies an ASCII-Z string into the dest pointer, to max length allowed. The result
543     // is always safely zero-terminated (none of that snprintf crap where you have to
544     // zero-terminate yourself >_<).
545     //
546     // Returns:
547     // 0 - Value was retrieved successfully.
548     // 1 - Unknown value. Contents of dest are unchanged.
549     BOOL (PS2E_CALLBACK* GetString)( const char* name, char* dest, int maxlen );
550    
551     // GetStringAlloc
552     // Provides an alternative to GetString, that can retrieve strings of arbitrary length.
553     // The plugin must provide a valid allocator callback, which takes a size parameter and
554     // returns a pointer to an allocation large enough to hold the size.
555     //
556     // It is then the responsibility of the plugin to free the allocated pointer when it
557     // is done with it.
558     //
559     char* (PS2E_CALLBACK* GetStringAlloc)( const char* name, void* (PS2E_CALLBACK *allocator)(int size) );
560    
561     // OSD_WriteLn
562     // This function allows the plugin to post messages to the emulator's On-Screen Display.
563     // The OSD message will be displayed with the specified icon (optional) for the duration
564     // of a few seconds, or until other messages have scrolled it out of view.
565     // Implementation of the OSD is emulator specific, and there is no guarantee that the
566     // OSD will be honored at all. If the emulator does not support OSD then this function
567     // call is treated as a NOP.
568     //
569     // Typically a plugin author should only use the OSD for infrequent notices that are
570     // potentially useful to users playing games (particularly at fullscreen). Trouble-
571     // shooting and debug information is best dumped to console or to disk log, or displayed
572     // using a native popup window managed by the plugin.
573     //
574     // Parameters:
575     // icon - an icon identifier, typically from the PS2E_OSDIconTypes enumeration. Specific
576     // versions of emulators may provide their own icon extensions. The emulator will
577     // silently ignore unrecognized icon identifiers, thus retaining cross-compat.
578     //
579     // msg - string message displayed to the user.
580     //
581     void (PS2E_CALLBACK* OSD_WriteLn)( int icon, const char* msg );
582    
583     // ----------------------------------------------------------------------------
584     // Menu / MenuItem Section
585     // ----------------------------------------------------------------------------
586    
587     void (PS2E_CALLBACK* AddMenuItem)( const PS2E_MenuItemInfo* item );
588    
589     // Allocates a new menu handle and returns it. The returned menu can have any valid existing
590     // menu items bound to it, and can be assigned as a submenu to any created MenuItem. The menu
591     // can belong to multiple menu items, however menu items can only belong to a single menu.
592     PS2E_MenuHandle (PS2E_CALLBACK* Menu_Create)( PS2E_THISPTR thisptr );
593    
594     // Deletes the specified menu and frees its allocated memory resources. NULL pointers are
595     // safely ignored. Any menu items also attached to this menu will be deleted. Even if you
596     // do not explicitly delete your plugin's menu resources, the emulator will do automatic
597     // cleanup after the plugin's instance is freed.
598     void (PS2E_CALLBACK* Menu_Delete)( PS2E_MenuHandle handle );
599    
600     // Adds the specified menu item to this menu. Menu items can only belong to one menu at a
601     // time. If you assign an item to a created menu that already belongs to another menu, it
602     // will be removed from the other menu and moved to this one. To append a menu item to
603     // multiple menus, you will need to create multiple instances of the item.
604     void (PS2E_CALLBACK* Menu_AddItem)( PS2E_MenuHandle menu, PS2E_MenuItemHandle mitem );
605    
606     // Interface for creating menu items and modifying their properties.
607     PS2E_MenuItemAPI MenuItem;
608    
609     // Provides a set of basic console functions for writing text to the emulator's
610     // console. Some emulators may not support a console, in which case these functions
611     // will be NOPs. For plain and simple to-disk logging, plugins should create and use
612     // their own logging facilities.
613     PS2E_ConsoleWriterAPI Console;
614    
615     // Optional wide-version of the Console API. Use with caution -- wchar_t is platform and
616     // compiler dependent, and so plugin authors should be sure to check the emulator's wchar_t
617     // side before using this interface. See PS2E_ConsoleWriterWideAPI comments for more info.
618     PS2E_ConsoleWriterWideAPI ConsoleW;
619    
620     void* reserved2[8];
621    
622     } PS2E_EmulatorInfo;
623    
624    
625     // --------------------------------------------------------------------------------------
626     // PS2E_FreezeData
627     // --------------------------------------------------------------------------------------
628     // Structure used to pass savestate info between emulator and plugin.
629     //
630     typedef struct _PS2E_FreezeData
631     {
632     u32 Size; // size of the data being frozen or thawed. This value is allowed to be changed by Freeze().
633     void* Data; // pointer to the data target (freeze) or source (thaw)
634    
635     } PS2E_FreezeData;
636    
637    
638     // --------------------------------------------------------------------------------------
639     // PS2E_ComponentAPI
640     // --------------------------------------------------------------------------------------
641     // The PluginTypeAPI is provided for every PS2 component plugin (see PS2E_ComponentTypes
642     // enumeration). For typical dlls which only provide one plugin type of functionality,
643     // the plugin only needs one instance of this struct. For multi-type plugins, for example
644     // a plugin that supports both DEV9 and FW together, an interface must be provided for
645     // each component supported.
646     //
647     // These are functions provided to the PS2 emulator from the plugin. The emulator will
648     // call these functions and expect the plugin to perform defined tasks.
649     //
650     typedef struct _PS2E_ComponentAPI
651     {
652     // EmuOpen
653     // This function is called by the emulator when an emulation session is started. The
654     // plugin should take this opportunity to bind itself to the given window handle, open
655     // necessary audio/video/input devices, etc.
656     //
657     // Parameters:
658     // session - provides relevant emulation session information. Provided pointer is
659     // valid until after the subsequent call to EmuClose()
660     //
661     // Threading: EmuOpen is called from the GUI thread. All other emulation threads are
662     // guaranteed to be suspended or closed at the time of this call (no locks required).
663     //
664     void (PS2E_CALLBACK* EmuOpen)( PS2E_THISPTR thisptr, const PS2E_SessionInfo *session );
665    
666     // EmuClose
667     // This function is called by the emulator prior to stopping emulation. The window
668     // handle specified in EmuOpen is guaranteed to be valid at the time EmuClose is called,
669     // and the plugin should unload/unbind all window dependencies at this time.
670     //
671     // Threading: EmuClose is called from the GUI thread. All other emulation threads are
672     // guaranteed to be suspended or closed at the time of this call (no locks required).
673     //
674     void (PS2E_CALLBACK* EmuClose)( PS2E_THISPTR thisptr );
675    
676     // CalcFreezeSize
677     // This function should calculate and return the amount of memory needed for the plugin
678     // to freeze its complete emulation state. The value can be larger than the required
679     // amount of space, but cannot be smaller.
680     //
681     // The emulation state when this function is called is guaranteed to be the same as
682     // the following call to Freeze.
683     //
684     // Thread Safety:
685     // May be called from any thread (GUI, Emu, GS, Unknown, etc).
686     // All Emulation threads are halted at a PS2 logical vsync-end event.
687     // No locking is necessary.
688     u32 (PS2E_CALLBACK* CalcFreezeSize)( PS2E_THISPTR thisptr );
689    
690     // Freeze
691     // This function should make a complete copy of the plugin's emulation state into the
692     // provided dest->Data pointer. The plugin is allowed to reduce the dest->Size value
693     // but is not allowed to make it larger. The plugin will only receive calls to Freeze
694     // and Thaw while a plugin is in an EmuOpen() state.
695     //
696     // Parameters:
697     // dest - a pointer to the Data/Size destination buffer (never NULL).
698     //
699     // Thread Safety:
700     // May be called from any thread (GUI, Emu, GS, Unknown, etc).
701     // All Emulation threads are halted at a PS2 logical vsync-end event.
702     // No locking is necessary.
703     void (PS2E_CALLBACK* Freeze)( PS2E_THISPTR thisptr, PS2E_FreezeData* dest );
704    
705     // Thaw
706     // Plugin should restore a complete emulation state from the given FreezeData. The
707     // plugin will only receive calls to Freeze and Thaw while a plugin is in an EmuOpen()
708     // state.
709     //
710     // Thread Safety:
711     // May be called from any thread (GUI, Emu, GS, Unknown, etc).
712     // All Emulation threads are halted at a PS2 logical vsync-end event.
713     // No locking is necessary.
714     void (PS2E_CALLBACK* Thaw)( PS2E_THISPTR thisptr, const PS2E_FreezeData* src );
715    
716     // Configure
717     // The plugin should open a modal dialog box with plugin-specific settings and prop-
718     // erties. This function can be NULL, in which case the user's Configure option for
719     // this plugin is grayed out.
720     //
721     // All emulation is suspended and the plugin's state is saved to memory prior to this
722     // function being called. Configure is only called outside the context of EmuOpen()
723     // (after a call to EmuClose()).
724     //
725     // Plugin authors should ensure to re-read and re-apply all settings on EmuOpen(),
726     // which will ensure that any user changes will be applied immediately. For changes
727     // that can be applied without emulation suspension, see/use the GUI extensions for
728     // menu and toolbar shortcuts.
729     //
730     // Thread Safety:
731     // Always called from the GUI thread, with emulation in a halted state (no locks
732     // needed).
733     void (PS2E_CALLBACK* Configure)( PS2E_THISPTR thisptr );
734    
735     // GetLastError
736     // This is an optional method with allows the emulator to retrieve extended formatted
737     // error information about a recent failed plugin call. If implemented by the plugin,
738     // it should store message information in it's PS2E_THISPTR allocation, and free the
739     // string buffers when the plugin's instance is deleted.
740     //
741     // The plugin is allowed to return NULL for either msg_diag or msg_user (or both).
742     // Returned pointers should be static global arrays, and must be NULL terminated. If
743     // only one message is provided, it will be used for both console log and popup.
744     //
745     // Parameters:
746     // msg_diag - diagnostic message, which is english only and typically intended for
747     // console or disk logging.
748     //
749     // msg_user - optional translated user message, which is displayed as a popup to explain
750     // to the user why the plugin failed to initialize.
751     //
752     // Thread safety:
753     // * Thread Affinity: none. May be called from any thread.
754     // * Interlocking: Instance. All calls from the emu are fully interlocked against
755     // the plugin instance.
756     //
757     void (PS2E_CALLBACK* GetLastError)( PS2E_THISPTR thisptr, char* const* msg_diag, wchar_t* const* msg_user );
758    
759     // Reserved area at the end of the structure, for future API expansion.
760     void* reserved[8];
761    
762     } PS2E_ComponentAPI;
763    
764    
765     // --------------------------------------------------------------------------------------
766     // PS2E_LibraryAPI
767     // --------------------------------------------------------------------------------------
768     // The LibraryAPI is an overall library-scope set of functions that perform basic Init,
769     // Shutdown, and global configuration operations.
770     //
771     // These are functions provided to the PS2 emulator from the plugin. The emulator will
772     // call these functions and expect the plugin to perform defined tasks.
773     //
774     // Threading:
775     // - get* callbacks in this struct are not bound to any particular thread. Implementations
776     // should not assume any specific thread affinity.
777     //
778     // - set* callbacks in this struct are bound to the GUI thread of the emulator, and will
779     // always be invoked from that thread.
780     //
781     typedef struct _PS2E_LibraryAPI
782     {
783     // GetName
784     // Returns an ASCII-Z (zero-terminated) string name of the plugin. The name should
785     // *not* include version or build information. That info is returned separately
786     // via GetVersion. The return value cannot be NULL (if it is NULL, the emulator
787     // will assume the DLL is invalid and ignore it).
788     //
789     // The pointer should reference a static/global scope char array, or an allocated
790     // heap pointer (not recommended).
791     //
792     // This function may be called multiple times by the emulator, so it should accommodate
793     // for such if it performs heap allocations or other initialization procedures.
794     const char* (PS2E_CALLBACK* GetName)();
795    
796     // GetVersion
797     // This function returns name and version information for the requested PS2 component.
798     // If the plugin does not support the requested component, it should return NULL.
799     // The returned pointer, if non-NULL, must be either a static value [recommended] or a
800     // heap-allocated value, and valid for the lifetime of the plugin.
801     //
802     // This function may be called multiple times by the emulator, so it should accommodate
803     // for such if it performs heap allocations or other initialization procedures.
804     //
805     // Typically a plugin will return the same version for all supported components. The
806     // component parameter is mostly provided to allow this function to serve a dual purpose
807     // of both component versioning and as a component enumerator.
808     //
809     // See PS2E_VersionInfo for more details.
810     //
811     // Parameters:
812     // component - indicates the ps2 component plugin to be versioned. If the plugin
813     // does not support the requested component, the function should return NULL.
814     //
815     const PS2E_VersionInfo* (PS2E_CALLBACK* GetVersion)( u32 component );
816    
817     // Test
818     // Called by the plugin enumerator to check the hardware availability of the specified
819     // component. The function should return 1 if the plugin appears to be supported, or
820     // 0 if the test failed.
821     //
822     // While a plugin is welcome to use its own CPU capabilities information, it is recommended
823     // that you use the emulator provided CPU capabilities structure instead. The emulator may
824     // have provisions in its interface to allow for the forced disabling of extended CPU cap-
825     // abilities, for testing purposes.
826     //
827     BOOL (PS2E_CALLBACK* Test)( u32 component, const PS2E_EmulatorInfo* xinfo );
828    
829     // NewComponentInstance
830     // The emulator calls this function to fetch the API for the requested component.
831     // The plugin is expected to perform an "availability test" (the same test as performed
832     // by Test()) and return NULL if the plugin does not support the host machine's hardware
833     // or software installations.
834     //
835     // This function is only called for components which the plugin returned a non-NULL
836     // version information struct for in GetVersion().
837     //
838     // Plugin Allocation Strategy:
839     // The Component API has been designed with function invocation efficiency in mind.
840     // To allocate your plugin's component instance you should create a structure that
841     // contains PS2E_ComponentAPI_* as the first member (where * refers to the PS2
842     // component type), and plugin-specific instance data is stored as any number of
843     // subsequent members in the struct.
844     //
845     // Parameters:
846     // component - indicates the ps2 component API to return.
847     // dest - structure to fill with plugin function implementations. Dest should
848     // be manually typecast by the plugin to match the requested component.
849     //
850     // OnError:
851     // Plugins may optionally prepare more detailed information on why the plugin failed
852     // it's availability test which the emu can request via GetLastError.
853     //
854     PS2E_THISPTR (PS2E_CALLBACK* NewComponentInstance)( u32 component );
855    
856     // DeleteComponentInstance
857     // Called by the emulator when the plugin component is to be shutdown. The component API
858     // instance pointer can be safely deleted here.
859     void (PS2E_CALLBACK* DeleteComponentInstance)( PS2E_THISPTR instance );
860    
861     // SetSettingsFolder
862     // Callback is passed an ASCII-Z string representing the folder where the emulator's
863     // settings files are stored (may either be under the user's documents folder, or a
864     // location relative to the CWD of the emu application).
865     //
866     // Typically this callback is only issued once per plugin session, aand prior to the
867     // opening of any PS2 components. It is the responsibility of the emu to save the
868     // emulation state, shutdown plugins, and restart everything anew from the new settings
869     // in such an event as a dynamic change of the settings folder.
870     //
871     void (PS2E_CALLBACK* SetSettingsFolder)( const char* folder );
872    
873     // SetLogFolder
874     // This callback may be issued at any time. It is the responsibility of the plugin
875     // to do the necessary actions to close existing disk logging facilities and re-open
876     // new facilities.
877     //
878     // Thread Safety:
879     // This function is always called from the GUI thread. All emulation threads are
880     // suspended during the call, so no locking is required.
881     //
882     void (PS2E_CALLBACK* SetLogFolder)( const char* folder );
883    
884     // Reserved area at the end of the structure, for future API expansion. This area
885     // should always be zeroed out, so that future versions of emulators that may have
886     // defined functions here will recognize the functions as not supported by the plugin.
887     void* reserved[12];
888    
889     } PS2E_LibraryAPI;
890    
891     // --------------------------------------------------------------------------------------
892     // PS2E_ComponentAPI_GS
893     // --------------------------------------------------------------------------------------
894     // Thread Safety:
895     // Most GS callbacks are issued from the GS thread only, and are always called synchronously
896     // with all other component API functions. No locks are needed, and DirectX-based GS
897     // plugins can safely disable DX multithreading support for speedup (unless the plugin
898     // utilizes multiple threads of its own internally).
899     //
900     typedef struct _PS2E_ComponentAPI_GS
901     {
902     // Base Component API (inherited structure)
903     struct _PS2E_ComponentAPI Base;
904    
905     // SetSnapshotsFolder
906     // Callback is passed an ASCII-Z string representing the folder where the emulator's
907     // snapshots are to be saved (typically located under user documents, but may be CWD
908     // or any user-specified location).
909     //
910     // Thread Safety:
911     // This function may be called from either GUI thread or GS thread. Emulators calling
912     // it from non-GS threads must ensure mutex locking with TakeSnapshot (meaning the
913     // plugin should be free to disregard threading concerns).
914     void (PS2E_CALLBACK* GsSetSnapshotsFolder)( PS2E_THISPTR thisptr, const char* folder );
915    
916     // TakeSnapshot
917     // The GS plugin is to save the current frame into the given target image. This
918     // function is always called immediately after a GSvsync(), ensuring that the current
919     // framebuffer is safely intact for capture.
920     //
921     // Returns TRUE if the snapshot succeeded, or FALSE if it failed (contents of dest
922     // are considered indeterminate and will be ignored by the emu).
923     BOOL (PS2E_CALLBACK* GsTakeSnapshot)( PS2E_THISPTR thisptr, PS2E_Image* dest );
924    
925     // OSD_QueueMessage
926     // Queues a message to the GS for display to the user. The GS can print the message
927     // where-ever it pleases, though it's suggested that the messages be printed either
928     // near the top or the bottom of the window (and in the black/empty area if the
929     // game's display is letterboxed).
930     //
931     // Parameters:
932     // message - text to queue (UTF8 format); will always be a single line (emulator
933     // is responsible for pre-processing linebreaks into multiple messages). The pointer
934     // will become invalid after this call retunrs, so be sure to make a local copy of the
935     // text.
936     //
937     // timeout - Suggested timeout period, in milliseconds. This is a hint and need
938     // not be strictly adhered to by the GS.
939     //
940     void (PS2E_CALLBACK* OSD_QueueMessage)( PS2E_THISPTR thisptr, const char* msg, int timeout );
941    
942     // OSD_IconStatus
943     // Sets the visibility status of an icon. Icon placement can be determined by the GS,
944     // although it's recommended that the icon be displayed near a corner of the screen, and
945     // be displayed in the empty/black areas if present (letterboxing).
946     //
947     // Parameters:
948     // iconId - Icon status to change
949     // alpha - 0.0 is hdden, 1.0 is visible. Other alpha values may be used as either
950     // transparency or as a scrolling factor (ie, to scroll the icon in and out of view, in
951     // any way the GS plugin sees fit).
952     void (PS2E_CALLBACK* OSD_IconStatus)( PS2E_THISPTR thisptr, OSDIconTypes iconId, float alpha );
953    
954     // GSvsync
955     //
956     // Returns FALSE if the plugin encountered a critical error while updating the display;
957     // indicating a device or emulation failure that should terminate the current emulation.
958     // (if any critical errors accumulated during GStransferTags or GStransferImage, they
959     // should also be handled here by returning FALSE)
960     //
961     BOOL (PS2E_CALLBACK* GsVsync)(int field);
962    
963     // GSwriteRegs
964     // Sends a GIFtag and associated register data. This is the main transfer method for all
965     // GIF register data. REGLIST mode is unpacked into the forat described below.
966     //
967     // Note that SIGNAL, FINISH, and LABEL tags are handled internally by the emulator in a
968     // thread-safe manner -- the GS plugin should ignore those tags when processing.
969     //
970     // Returns FALSE if the plugin encountered a critical error while setting texture;
971     // indicating a device failure.
972     //
973     // Parameters:
974     // pMem - pointer to source memory for the register descriptors and register data.
975     // The first 128 bits (1 qwc) is the descriptors unrolled into 16x8 format. The
976     // following data is (regcnt x tagcnt) QWCs in length.
977     //
978     // regcnt - number of registers per loop packet (register descriptors are filled
979     // low->high). Valid range is 1->16, and will never be zero.
980     //
981     // nloop - number of loops of register data. Valid range is 1->32767 (upper 17
982     // bits are always zero). This value will never be zero.
983     void (PS2E_CALLBACK* GsWriteRegs)(const u128 *pMem, int regcnt, int nloop);
984    
985     // GSwritePrim
986     // Starts a new prim by sending the specified value to the PRIM register. The emulator
987     // only posts this data to the GS s per the rules of GIFpath processing (note however
988     // that packed register data can also contain PRIM writes).
989     //
990     // Parameters:
991     // primData - value to write to the PRIM register. Only the bottom 10 bits are
992     // valid. Upper bits are always zero.
993     void (PS2E_CALLBACK* GsWritePrim)(int primData);
994    
995     // GSwriteImage
996     // Uploads new image data. Data uploaded may be in any number of partial chunks, for
997     // which the GS is responsible for managing the state machine for writes to GS memory.
998     //
999     // Plugin authors: Note that it is valid for games to only modify a small portion of a
1000     // larger texture buffer, or for games to modify several portions of a single large
1001     // buffer, by using mid-transfer writes to TRXPOS and TRXDIR (TRXPOS writes only become
1002     // effective once TRXDIR has been written).
1003     void (PS2E_CALLBACK* GsWriteImage)(const u128 *pMem, int qwc_cnt);
1004    
1005     // GSreadImage
1006     // This special callback is for implementing the Read mode direction of the GIFpath.
1007     // The GS plugin writes the texture data as requested by it's internally managed state
1008     // values for TRXPOS/TRXREG to the buffer provided by pMem. The buffer size is qwc_cnt
1009     // and the GS must not write more than that.
1010     void (PS2E_CALLBACK* GsReadImage)(u128 *pMem, int qwc_cnt);
1011    
1012     void* reserved[8];
1013    
1014     } PS2E_ComponentAPI_GS;
1015    
1016    
1017     // --------------------------------------------------------------------------------------
1018     // PS2E_McdSizeInfo
1019     // --------------------------------------------------------------------------------------
1020     struct PS2E_McdSizeInfo
1021     {
1022     u16 SectorSize; // Size of each sector, in bytes. (only 512 and 1024 are valid)
1023     u16 EraseBlockSizeInSectors; // Size of the erase block, in sectors (max is 16)
1024     u32 McdSizeInSectors; // Total size of the card, in sectors (no upper limit)
1025     };
1026    
1027     // --------------------------------------------------------------------------------------
1028     // PS2E_ComponentAPI_Mcd
1029     // --------------------------------------------------------------------------------------
1030     // Thread Safety:
1031     // * Thread affinity is not guaranteed. Calls may be made from either the main emu thread
1032     // or an IOP child thread (if the emulator uses one).
1033     //
1034     // * No locking required: All calls to the memory cards are interlocked by the emulator.
1035     //
1036     typedef struct _PS2E_ComponentAPI_Mcd
1037     {
1038     // Base Component API (inherited structure)
1039     struct _PS2E_ComponentAPI Base;
1040    
1041     // McdIsPresent
1042     // Called by the emulator to detect the availability of a memory card. This function
1043     // will be called frequently -- essentially whenever the SIO port for the memory card
1044     // has its status polled - so its overhead should be minimal when possible.
1045     //
1046     // Returns:
1047     // False if the card is not available, or True if it is available.
1048     //
1049     BOOL (PS2E_CALLBACK* McdIsPresent)( PS2E_THISPTR thisptr, uint port, uint slot );
1050    
1051     // McdGetSectorSize (can be NULL)
1052     // Requests memorycard formatting information from the Mcd provider. See the description of
1053     // PS2E_McdSizeInfo for details on each field. If the Mcd provider supports only standard 8MB
1054     // carts, then this function can be NULL.
1055     //
1056     // Returns:
1057     // Assigned values for memorycard sector size and sector count in 'outways.'
1058     //
1059     void (PS2E_CALLBACK* McdGetSizeInfo)( PS2E_THISPTR thisptr, uint port, uint slot, PS2E_McdSizeInfo* outways );
1060    
1061     // McdRead
1062     // Requests that a block of data be loaded from the memorycard into the specified dest
1063     // buffer (which is allocated by the caller). Bytes read should match the requested
1064     // size. Reads *must* be performed synchronously (function cannot return until the
1065     // read op has finished).
1066     //
1067     // Returns:
1068     // False on failure, and True on success. Emulator may use GetLastError to retrieve additional
1069     // information for logging or displaying to the user.
1070     //
1071     BOOL (PS2E_CALLBACK* McdRead)( PS2E_THISPTR thisptr, uint port, uint slot, u8 *dest, u32 adr, int size );
1072    
1073     // McdSave
1074     // Saves the provided block of data to the memorycard at the specified seek address.
1075     // Writes *must* be performed synchronously (function cannot return until the write op
1076     // has finished). Write cache flushing is optional.
1077     //
1078     // Returns:
1079     // False on failure, and True on success. Emulator may use GetLastError to retrieve additional
1080     // information for logging or displaying to the user.
1081     //
1082     BOOL (PS2E_CALLBACK* McdSave)( PS2E_THISPTR thisptr, uint port, uint slot, const u8 *src, u32 adr, int size );
1083    
1084     // McdEraseBlock
1085     // Saves "cleared" data to the memorycard at the specified seek address. Cleared data
1086     // is a series of 0xff values (all bits set to 1).
1087     // Writes *must* be performed synchronously (function cannot return until the write op
1088     // has finished). Write cache flushing is optional.
1089     //
1090     // Returns:
1091     // False on failure, and True on success. Emulator may use GetLastError to retrieve additional
1092     // information for logging or displaying to the user.
1093     //
1094     BOOL (PS2E_CALLBACK* McdEraseBlock)( PS2E_THISPTR thisptr, uint port, uint slot, u32 adr );
1095    
1096     u64 (PS2E_CALLBACK* McdGetCRC)( PS2E_THISPTR thisptr, uint port, uint slot );
1097    
1098     void* reserved[8];
1099    
1100     } PS2E_ComponentAPI_Mcd;
1101    
1102    
1103     // ------------------------------------------------------------------------------------
1104     // KeyEvent type enumerations
1105     // ------------------------------------------------------------------------------------
1106    
1107     enum PS2E_KeyEventTypes
1108     {
1109     PS2E_KEY_UP = 0,
1110     PS2E_KEY_DOWN
1111     };
1112    
1113     enum PS2E_KeyModifiers
1114     {
1115     PS2E_SHIFT = 1,
1116     PS2E_CONTROL = 2,
1117     PS2E_ALT = 4
1118     };
1119    
1120     // --------------------------------------------------------------------------------------
1121     // PS2E_KeyEvent
1122     // --------------------------------------------------------------------------------------
1123     // Structure used to key event data from pad plugin to emulator.
1124     //
1125     typedef struct _PS2E_KeyEvent
1126     {
1127     PS2E_KeyEventTypes event;
1128    
1129     // Value of the key being pressed or released
1130     uint value;
1131    
1132     // Combination of PS2E_SHIFT, PS2E_CONTROL, and/or PS2E_ALT, indicating which
1133     // modifier keys were also down when the key was pressed.
1134     uint flags;
1135    
1136     } PS2E_KeyEvent;
1137    
1138    
1139     // --------------------------------------------------------------------------------------
1140     // PS2E_ComponentAPI_Pad
1141     // --------------------------------------------------------------------------------------
1142     // Thread Safety:
1143     // * Thread affinity is not guaranteed. Even PadKeyEvent may be called from a thread not
1144     // belonging to the active window (the window where the GA is output). Other calls may
1145     // be made from either the main emu thread or an EE/IOP/GS child thread (if the emulator
1146     // uses them).
1147     //
1148     typedef struct _PS2E_ComponentAPI_Pad
1149     {
1150     // Base Component API (inherited structure)
1151     struct _PS2E_ComponentAPI Base;
1152    
1153     // PadIsPresent
1154     // Called by the emulator to detect the availability of a pad. This function will
1155     // be called frequently -- essentially whenever the SIO port for the pad has its
1156     // status polled - so its overhead should be minimal when possible.
1157     //
1158     // A plugin should behave reasonably when a pad that's not plugged in is polled.
1159     //
1160     // Returns:
1161     // False if the card/pad is not available, or True if it is available.
1162     //
1163     BOOL (PS2E_CALLBACK* PadIsPresent)( PS2E_THISPTR thisptr, uint port, uint slot );
1164    
1165     // PadStartPoll
1166     // Called by the emulator to start polling the specified pad.
1167     //
1168     // Returns:
1169     // First byte in response to the poll (Typically 0xff).
1170     //
1171     // Threading:
1172     // Called from the EEcore thread. The emulator performs no locking of its own, so
1173     // calls to this may occur concurrently with calls to PadUpdate.
1174     //
1175     u8 (PS2E_CALLBACK* PadStartPoll)( PS2E_THISPTR thisptr, uint port, uint slot );
1176    
1177     // PadPoll
1178     // Continues polling the specified pad, sending the given value.
1179     //
1180     // Returns:
1181     // Next byte in response to the poll.
1182     //
1183     // Threading:
1184     // Called from the EEcore thread. The emulator performs no locking of its own, so
1185     // calls to this may occur concurrently with calls to PadUpdate.
1186     //
1187     u8 (PS2E_CALLBACK* PadPoll)( PS2E_THISPTR thisptr, u8 value );
1188    
1189     // PadKeyEvent
1190     // Called by the emulator in the gui thread to check for keys being pressed or released.
1191     //
1192     // Returns:
1193     // PS2E_KeyEvent: Key being pressed or released. Should stay valid until next call to
1194     // PadKeyEvent or plugin is closed with EmuClose.
1195     //
1196     // Threading:
1197     // May be called from any thread. The emulator performs no locking of its own, so
1198     // calls to this may occur concurrently with calls to PadUpdate.
1199     //
1200     PS2E_KeyEvent* (PS2E_CALLBACK* PadGetKeyEvent)( PS2E_THISPTR thisptr );
1201    
1202     // PadUpdate
1203     // This callback is issued from the thread that owns the GSwindow, at roughly 50/60hz,
1204     // allowing the Pad plugin to use it for update logic that expects thread affinity with
1205     // the GSwindow.
1206     //
1207     // Threading:
1208     // Called from the same thread that owns the GSwindow (typically either a GUI thread
1209     // or an MTGS thread). The emulator performs no locking of its own, so calls to this
1210     // may occur concurrently with calls to PadKeyEvent and PadPoll.
1211     //
1212     void (PS2E_CALLBACK* PadUpdate)( PS2E_THISPTR thisptr );
1213    
1214     void* reserved[8];
1215    
1216     } PS2E_ComponentAPI_Pad;
1217    
1218    
1219     // --------------------------------------------------------------------------------------
1220     // PS2E_InitAPI
1221     // --------------------------------------------------------------------------------------
1222     // Called by the emulator when the plugin is loaded into memory. The emulator uses the
1223     // presence of this function to detect PS2E-v2 plugin API, and will direct all subsequent
1224     // calls through the returned LibraryAPI. The function is allowed to return NULL if the
1225     // emulator's version information or machine capabilities are insufficient for the
1226     // plugin's needs.
1227     //
1228     // Note: It is recommended that plugins query machine capabilities from the emulator rather
1229     // than the operating system or CPUID directly, since it allows the emulator the option of
1230     // overriding the reported capabilities, for diagnostic purposes. (such behavior is not
1231     // required, however)
1232     //
1233     // This function is called *once* for the duration of a loaded plugin.
1234     //
1235     // Returns:
1236     // A pointer to a static structure that contains the API for this plugin, or NULL if
1237     // the plugin explicitly does not support the emulator version or machine specs.
1238     //
1239     // OnError:
1240     // Plugins may optionally prepare more detailed information on why the plugin failed
1241     // it's availability test which the emu can request via PS2E_GetLastError.
1242     //
1243     // Thread Safety:
1244     // * Affinity: Called only from the Main/GUI thread.
1245     // * Interlocking: Full interlocking garaunteed.
1246     //
1247     typedef const PS2E_LibraryAPI* (PS2E_CALLBACK* _PS2E_InitAPI)( const PS2E_EmulatorInfo* emuinfo );
1248    
1249     // --------------------------------------------------------------------------------------
1250     // PS2E_GetLastError
1251     // --------------------------------------------------------------------------------------
1252     // Optional method which may be called by the emulator if the plugin returned NULL on
1253     // PS2E_InitAPI. Plugins may return NULL for either/both msg_diag and msg_user. Returned
1254     // pointers should be static global arrays, and must be NULL terminated. If only one
1255     // message is provided, it will be used for both console log and popup.
1256     //
1257     // Parameters:
1258     // msg_diag - diagnostic message, which is english only and typically intended for console
1259     // or disk logging.
1260     //
1261     // msg_user - optional translated user message, which is displayed as a popup to explain
1262     // to the user why the plugin failed to initialize.
1263     //
1264     typedef void (PS2E_CALLBACK* _PS2E_GetLastError)( char* const* msg_diag, wchar_t* const* msg_user );
1265    
1266     //////////////////////////////////////////////////////////////////////////////////////////
1267     //////////////////////////////////////////////////////////////////////////////////////////
1268     // Begin old legacy API here (present for reference purposes only, until all plugin API
1269     // specifics have been accounted for)
1270     //////////////////////////////////////////////////////////////////////////////////////////
1271     //////////////////////////////////////////////////////////////////////////////////////////
1272    
1273     #if 0
1274     // SPU2
1275     // NOTE: The read/write functions CANNOT use XMM/MMX regs
1276     // If you want to use them, need to save and restore current ones
1277     typedef s32 (CALLBACK* _SPU2init)(char *configpath);
1278     typedef s32 (CALLBACK* _SPU2open)(void *pDisplay);
1279     typedef void (CALLBACK* _SPU2close)();
1280     typedef void (CALLBACK* _SPU2shutdown)();
1281     typedef void (CALLBACK* _SPU2write)(u32 mem, u16 value);
1282     typedef u16 (CALLBACK* _SPU2read)(u32 mem);
1283    
1284     typedef void (CALLBACK* _SPU2readDMA4Mem)(u16 *pMem, u32 size);
1285     typedef void (CALLBACK* _SPU2writeDMA4Mem)(u16 *pMem, u32 size);
1286     typedef void (CALLBACK* _SPU2interruptDMA4)();
1287     typedef void (CALLBACK* _SPU2readDMA7Mem)(u16 *pMem, u32 size);
1288     typedef void (CALLBACK* _SPU2writeDMA7Mem)(u16 *pMem, u32 size);
1289     typedef void (CALLBACK* _SPU2interruptDMA7)();
1290    
1291     typedef void (CALLBACK* _SPU2readDMAMem)(u16 *pMem, u32 size, u8 core);
1292     typedef void (CALLBACK* _SPU2writeDMAMem)(u16 *pMem, u32 size, u8 core);
1293     typedef void (CALLBACK* _SPU2interruptDMA)(u8 core);
1294     typedef void (CALLBACK* _SPU2setDMABaseAddr)(uptr baseaddr);
1295     typedef void (CALLBACK* _SPU2irqCallback)(void (*SPU2callback)(),void (*DMA4callback)(),void (*DMA7callback)());
1296     typedef bool (CALLBACK* _SPU2setupRecording)(bool start);
1297    
1298     typedef void (CALLBACK* _SPU2setClockPtr)(u32*ptr);
1299     typedef void (CALLBACK* _SPU2setTimeStretcher)(short int enable);
1300    
1301     typedef u32 (CALLBACK* _SPU2ReadMemAddr)(u8 core);
1302     typedef void (CALLBACK* _SPU2WriteMemAddr)(u8 core,u32 value);
1303     typedef void (CALLBACK* _SPU2async)(u32 cycles);
1304     typedef s32 (CALLBACK* _SPU2freeze)(u8 mode, freezeData *data);
1305     typedef void (CALLBACK* _SPU2keyEvent)(keyEvent* ev);
1306     typedef void (CALLBACK* _SPU2configure)();
1307     typedef s32 (CALLBACK* _SPU2test)();
1308     typedef void (CALLBACK* _SPU2about)();
1309    
1310     // CDVD
1311     // NOTE: The read/write functions CANNOT use XMM/MMX regs
1312     // If you want to use them, need to save and restore current ones
1313     typedef s32 (CALLBACK* _CDVDinit)(char *configpath);
1314     typedef s32 (CALLBACK* _CDVDopen)(const char* pTitleFilename);
1315     typedef void (CALLBACK* _CDVDclose)();
1316     typedef void (CALLBACK* _CDVDshutdown)();
1317     typedef s32 (CALLBACK* _CDVDreadTrack)(u32 lsn, int mode);
1318     typedef u8* (CALLBACK* _CDVDgetBuffer)();
1319     typedef s32 (CALLBACK* _CDVDreadSubQ)(u32 lsn, cdvdSubQ* subq);
1320     typedef s32 (CALLBACK* _CDVDgetTN)(cdvdTN *Buffer);
1321     typedef s32 (CALLBACK* _CDVDgetTD)(u8 Track, cdvdTD *Buffer);
1322     typedef s32 (CALLBACK* _CDVDgetTOC)(void* toc);
1323     typedef s32 (CALLBACK* _CDVDgetDiskType)();
1324     typedef s32 (CALLBACK* _CDVDgetTrayStatus)();
1325     typedef s32 (CALLBACK* _CDVDctrlTrayOpen)();
1326     typedef s32 (CALLBACK* _CDVDctrlTrayClose)();
1327    
1328     typedef void (CALLBACK* _CDVDkeyEvent)(keyEvent* ev);
1329     typedef s32 (CALLBACK* _CDVDfreeze)(u8 mode, freezeData *data);
1330     typedef void (CALLBACK* _CDVDconfigure)();
1331     typedef s32 (CALLBACK* _CDVDtest)();
1332     typedef void (CALLBACK* _CDVDabout)();
1333     typedef void (CALLBACK* _CDVDnewDiskCB)(void (*callback)());
1334    
1335     // DEV9
1336     // NOTE: The read/write functions CANNOT use XMM/MMX regs
1337     // If you want to use them, need to save and restore current ones
1338     typedef s32 (CALLBACK* _DEV9init)(char *configpath);
1339     typedef s32 (CALLBACK* _DEV9open)(void *pDisplay);
1340     typedef void (CALLBACK* _DEV9close)();
1341     typedef void (CALLBACK* _DEV9shutdown)();
1342     typedef u8 (CALLBACK* _DEV9read8)(u32 mem);
1343     typedef u16 (CALLBACK* _DEV9read16)(u32 mem);
1344     typedef u32 (CALLBACK* _DEV9read32)(u32 mem);
1345     typedef void (CALLBACK* _DEV9write8)(u32 mem, u8 value);
1346     typedef void (CALLBACK* _DEV9write16)(u32 mem, u16 value);
1347     typedef void (CALLBACK* _DEV9write32)(u32 mem, u32 value);
1348     typedef void (CALLBACK* _DEV9readDMA8Mem)(u32 *pMem, int size);
1349     typedef void (CALLBACK* _DEV9writeDMA8Mem)(u32 *pMem, int size);
1350     typedef void (CALLBACK* _DEV9irqCallback)(DEV9callback callback);
1351     typedef DEV9handler (CALLBACK* _DEV9irqHandler)(void);
1352    
1353     typedef void (CALLBACK* _DEV9keyEvent)(keyEvent* ev);
1354     typedef s32 (CALLBACK* _DEV9freeze)(int mode, freezeData *data);
1355     typedef void (CALLBACK* _DEV9configure)();
1356     typedef s32 (CALLBACK* _DEV9test)();
1357     typedef void (CALLBACK* _DEV9about)();
1358    
1359     // USB
1360     // NOTE: The read/write functions CANNOT use XMM/MMX regs
1361     // If you want to use them, need to save and restore current ones
1362     typedef s32 (CALLBACK* _USBinit)(char *configpath);
1363     typedef s32 (CALLBACK* _USBopen)(void *pDisplay);
1364     typedef void (CALLBACK* _USBclose)();
1365     typedef void (CALLBACK* _USBshutdown)();
1366     typedef u8 (CALLBACK* _USBread8)(u32 mem);
1367     typedef u16 (CALLBACK* _USBread16)(u32 mem);
1368     typedef u32 (CALLBACK* _USBread32)(u32 mem);
1369     typedef void (CALLBACK* _USBwrite8)(u32 mem, u8 value);
1370     typedef void (CALLBACK* _USBwrite16)(u32 mem, u16 value);
1371     typedef void (CALLBACK* _USBwrite32)(u32 mem, u32 value);
1372     typedef void (CALLBACK* _USBasync)(u32 cycles);
1373    
1374    
1375     typedef void (CALLBACK* _USBirqCallback)(USBcallback callback);
1376     typedef USBhandler (CALLBACK* _USBirqHandler)(void);
1377     typedef void (CALLBACK* _USBsetRAM)(void *mem);
1378    
1379     typedef void (CALLBACK* _USBkeyEvent)(keyEvent* ev);
1380     typedef s32 (CALLBACK* _USBfreeze)(int mode, freezeData *data);
1381     typedef void (CALLBACK* _USBconfigure)();
1382     typedef s32 (CALLBACK* _USBtest)();
1383     typedef void (CALLBACK* _USBabout)();
1384    
1385     //FW
1386     typedef s32 (CALLBACK* _FWinit)(char *configpath);
1387     typedef s32 (CALLBACK* _FWopen)(void *pDisplay);
1388     typedef void (CALLBACK* _FWclose)();
1389     typedef void (CALLBACK* _FWshutdown)();
1390     typedef u32 (CALLBACK* _FWread32)(u32 mem);
1391     typedef void (CALLBACK* _FWwrite32)(u32 mem, u32 value);
1392     typedef void (CALLBACK* _FWirqCallback)(void (*callback)());
1393    
1394     typedef void (CALLBACK* _FWkeyEvent)(keyEvent* ev);
1395     typedef s32 (CALLBACK* _FWfreeze)(int mode, freezeData *data);
1396     typedef void (CALLBACK* _FWconfigure)();
1397     typedef s32 (CALLBACK* _FWtest)();
1398     typedef void (CALLBACK* _FWabout)();
1399    
1400     // General
1401     extern _PS2EgetLibType PS2EgetLibType;
1402     extern _PS2EgetLibVersion2 PS2EgetLibVersion2;
1403     extern _PS2EgetLibName PS2EgetLibName;
1404     extern _PS2EpassConfig PS2EpassConfig;
1405    
1406     #endif
1407    
1408     #ifndef __cplusplus
1409     }
1410     #endif
1411    
1412     #endif // __PLUGINCALLBACKS_H__

  ViewVC Help
Powered by ViewVC 1.1.22