<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>MDP - mdp_host.h: Host Services</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
<link rel='stylesheet' href='mdp.css' type='text/css'>
</head>
<body>
<h1 class='doc_title'>MDP - mdp_host.h: Host Services</h1>
<h4 class='doc_set'>Mega Drive Plugins v1.0.0<br>Revision 0</h4>
<div class='navbar'>
<span class='navitem'><a href="index.html">Index</a></span>
<span class='navarrow'>→</span>
<span class='navitem'><a href="mdp_host_h.html">mdp_host.h</a></span>
</div>
<p><strong>NOTE:</strong> This document is incomplete.</h1>
<p>
When a plugin is initialized, its <span class='struct'>mdp_t</span>-><span class='struct'>func</span>-><span class='function'>init()</span>
function is called with a pointer to the the emulator's <span class='struct'>mdp_host_t</span>
struct as a parameter. (See <a href="mdp_h.html"><span class='filename'>mdp.h</span></a> for
more information.) This struct contains pointers to useful functions within the emulator.
</p>
<p>Format of the <span class='struct'>mdp_host_t</span> struct:</p>
<pre class='code'>
#include "mdp/mdp_host.h"
typedef struct _mdp_host_t
{
/**
* interfaceVersion: MDP version implemented by the emulator.
*/
const uint32_t interfaceVersion;
const uint32_t reserved;
/*! BEGIN: MDP v1.0 functions. !*/
/**
* val_set(), val_get(): Set or get int values.
*/
int (MDP_FNCALL *val_set)(struct _mdp_t *plugin, uint32_t valID, int val);
int (MDP_FNCALL *val_get)(uint32_t valID);
/**
* osd_printf(): Print a message to the on-screen display.
*/
int (MDP_FNCALL *osd_printf)(const char *msg, ...)
__attribute__ ((format (printf, 1, 2)));
/**
* renderer_register(): Register a renderer.
* renderer_unregister(): Unregister a renderer.
*/
int (MDP_FNCALL *renderer_register)(struct _mdp_t *plugin, mdp_render_t *renderer);
int (MDP_FNCALL *renderer_unregister)(struct _mdp_t *plugin, mdp_render_t *renderer);
/**
* mem_read_*(): Memory read functions.
* @param memID Memory ID.
* @param address Address.
* @param ret_value Variable to store the return value in.
* @return MDP error code.
*/
int (MDP_FNCALL *mem_read_8) (int memID, uint32_t address, uint8_t *ret_value);
int (MDP_FNCALL *mem_read_16)(int memID, uint32_t address, uint16_t *ret_value);
int (MDP_FNCALL *mem_read_32)(int memID, uint32_t address, uint32_t *ret_value);
/**
* mem_write_*(): Memory write functions.
* @param plugin Plugin requesting memory write.
* @param memID Memory ID.
* @param address Address.
* @param data Data.
* @return MDP error code.
*/
int (MDP_FNCALL *mem_write_8) (struct _mdp_t *plugin, int memID, uint32_t address, uint8_t data);
int (MDP_FNCALL *mem_write_16)(struct _mdp_t *plugin, int memID, uint32_t address, uint16_t data);
int (MDP_FNCALL *mem_write_32)(struct _mdp_t *plugin, int memID, uint32_t address, uint32_t data);
/**
* mem_read_block_*: Memory block read functions.
* @param memID Memory ID.
* @param address Starting address.
* @param data Data buffer to store the data in.
* @param length Length of the data.
* @return MDP error code.
*/
int (MDP_FNCALL *mem_read_block_8) (int memID, uint32_t address, uint8_t *data, uint32_t length);
int (MDP_FNCALL *mem_read_block_16)(int memID, uint32_t address, uint16_t *data, uint32_t length);
int (MDP_FNCALL *mem_read_block_32)(int memID, uint32_t address, uint32_t *data, uint32_t length);
/**
* mem_write_block_*: Memory block write functions.
* @param plugin Plugin requesting memory write.
* @param memID Memory ID.
* @param address Starting address.
* @param data Data buffer containing the data to write.
* @param length Length of the data.
* @return MDP error code.
*/
int (MDP_FNCALL *mem_write_block_8) (struct _mdp_t *plugin, int memID, uint32_t address, uint8_t *data, uint32_t length);
int (MDP_FNCALL *mem_write_block_16)(struct _mdp_t *plugin, int memID, uint32_t address, uint16_t *data, uint32_t length);
int (MDP_FNCALL *mem_write_block_32)(struct _mdp_t *plugin, int memID, uint32_t address, uint32_t *data, uint32_t length);
/**
* mem_size_get(): Get the size of a memory block.
* @param memID Memory ID.
* @return Memory size, or negative on error.
*/
int (MDP_FNCALL *mem_size_get)(int memID);
/**
* mem_size_set(): Set the size of a memory block.
* @param plugin Plugin requesting memory size set.
* @param memID Memory ID.
* @param size New memory size.
* @return MDP error code.
*/
int (MDP_FNCALL *mem_size_set)(struct _mdp_t *plugin, int memID, unsigned int size);
/**
* reg_get(): Get a register value.
* @param icID ID of the IC to get a register value from.
* @param regID Register ID.
* @param ret_value Variable to store the return value in.
* @return MDP error code.
*/
int (MDP_FNCALL *reg_get)(int icID, int regID, uint32_t *ret_value);
/**
* reg_set(): Get a register value.
* @param plugin Plugin requesting register set.
* @param icID ID of the IC to set a register value in.
* @param regID Register ID.
* @param new_value New register value.
* @return MDP error code.
*/
int (MDP_FNCALL *reg_set)(struct _mdp_t *plugin, int icID, int regID, uint32_t new_value);
/**
* reg_get_all(): Get all register values for a given IC.
* @param icID ID of the IC to get all register values from.
* @param reg_struct Pointer to register struct for this IC.
* @return MDP error code.
*/
int (MDP_FNCALL *reg_get_all)(int icID, void *reg_struct);
/**
* reg_set_all(): Set all register values for a given IC.
* @param plugin Plugin requesting register set.
* @param icID ID of the IC to set all register values in.
* @param reg_struct Pointer to register struct for this IC.
* @return MDP error code.
*/
int (MDP_FNCALL *reg_set_all)(struct _mdp_t *plugin, int icID, void *reg_struct);
/**
* menu_item_add(): Add a menu item.
* menu_item_remove(): Remove a menu item.
* menu_item_set_text(): Set menu item text.
* menu_item_get_text(): Get menu item text.
* menu_item_set_checked(): Set menu item "checked" state.
* menu_item_get_checked(): Get menu item "checked" state.
*/
int (MDP_FNCALL *menu_item_add)(struct _mdp_t *plugin, mdp_menu_handler_fn handler, int menu_id, const char *text);
int (MDP_FNCALL *menu_item_remove)(struct _mdp_t *plugin, int menu_item_id);
int (MDP_FNCALL *menu_item_set_text)(struct _mdp_t *plugin, int menu_item_id, const char *text);
int (MDP_FNCALL *menu_item_get_text)(struct _mdp_t *plugin, int menu_item_id, char *text_buf, unsigned int size);
int (MDP_FNCALL *menu_item_set_checked)(struct _mdp_t *plugin, int menu_item_id, int checked);
int (MDP_FNCALL *menu_item_get_checked)(struct _mdp_t *plugin, int menu_item_id);
/* Event handler functions. */
int (MDP_FNCALL *event_register)(struct _mdp_t *plugin, int event_id, mdp_event_handler_fn handler);
int (MDP_FNCALL *event_unregister)(struct _mdp_t *plugin, int event_id, mdp_event_handler_fn handler);
/* Window registration. */
int (MDP_FNCALL *window_register)(struct _mdp_t *plugin, void *window);
int (MDP_FNCALL *window_unregister)(struct _mdp_t *plugin, void *window);
void* (MDP_FNCALL *window_get_main)(void);
/* Emulator control. */
int (MDP_FNCALL *emulator_control)(struct _mdp_t *plugin, MDP_EMUCTRL ctrl, void *param);
/* Configuration functions. */
int (MDP_FNCALL *config_get)(struct _mdp_t *plugin, const char* key, const char* def, char *out_buf, unsigned int size);
int (MDP_FNCALL *config_set)(struct _mdp_t *plugin, const char* key, const char* value);
/* Directory functions. */
int (MDP_FNCALL *dir_get_default_save_path)(char* buf, unsigned int size);
int (MDP_FNCALL *dir_register)(struct _mdp_t *plugin, const char *dir_name,
mdp_dir_get_fn get_fn, mdp_dir_set_fn set_fn);
int (MDP_FNCALL *dir_unregister)(struct _mdp_t *plugin, int dir_id);
/* Compression functions. */
int (MDP_FNCALL *crc32)(const uint8_t* buf, int length, uint32_t *crc32_out);
int (MDP_FNCALL *z_open)(const char* filename, mdp_z_t **z_out);
int (MDP_FNCALL *z_get_file)(mdp_z_t *z_file, mdp_z_entry_t *z_entry, void *buf, size_t size);
int (MDP_FNCALL *z_close)(mdp_z_t *z_file);
/*! END: MDP v1.0 functions. !*/
} mdp_host_t;
</pre>
<p>
Note that, unlike most other MDP structs, some fields in
<span class='struct'>mdp_host_t</span> are declared as optional.
That is, they do not have to be implemented by the emulator. The
"Required" field may contain one of the following three
values:
</p>
<ul>
<li>Yes: Function <strong>must</strong> be implemented.</li>
<li>
No (Not NULL): Function does not have to be implemented,
but must point to a valid function that returns
<span class='value'>-MDP_ERR_FUNCTION_NOT_IMPLEMENTED</span>.
</li>
<li>
No (NULL): Function does not have to be implemented,
and the pointer may be set to <span class='value'>NULL</span>.
</li>
</ul>
<p>Fields:</p>
<table class='mdp_host_t'>
<tr>
<th>Field</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td>interfaceVersion</td>
<td class='type'>uint32_t</td>
<td class='req_yes'>Yes</td>
<td>
The MDP interface version used by the emulator. Can be
generated using the
<span class="macro">MDP_VERSION(major, minor, revision)</span>
macro, or by using the MDP_INTERFACE_VERSION macro,
which is defined as the interface version specified in
the MDP headers being used.<br><br>
Plugins should check this value if they can take advantage
of functions from newer versions of MDP but want to retain
compatibility with older versions.
</td>
</tr>
<tr>
<td>reserved</td>
<td class='type'>uint32_t</td>
<td class='req_na'>N/A</td>
<td>
Reserved. Do not use this field.
</td>
</tr>
<tr>
<td>osd_printf</td>
<td class='type'>Function</td>
<td class='req_yes'>Yes</td>
<td>
Prints a message to the onscreen display. This function
supports printf()-style formatting.
</td>
</tr>
<tr>
<td>val_set<br>val_get</td>
<td class='type'>Function</td>
<td class='req_yes'>Yes</td>
<td>
Set/get emulator values. These values are defined in
<span class='enum'><a href="#MDP_VAL">MDP_VAL</a></span>.
</td>
</tr>
<tr>
<td>renderer_register<br>renderer_unregister</td>
<td class='type'>Function</td>
<td class='req_yes'>Yes</td>
<td>
Registers/unregisters a rendering plugin. See
<a href="mdp_render_h.html"><span class='filename'>mdp_render.h</span></a>
for more information about renderers.
</td>
</tr>
<tr>
<td>mem_read_8<br>mem_read_16<br>mem_read_32</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Reads a byte/word/dword from memory. Note that word and dword
memory reads must be on an aligned (even) boundary. Attempting
to read a word/dword on an unaligned boundary will result in
an error.
</td>
</tr>
<tr>
<td>mem_write_8<br>mem_write_16<br>mem_write_32</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Writes a byte/word/dword to memory. Note that word and dword
memory write must be on an aligned (even) boundary. Attempting
to write a word/dword on an unaligned boundary will result in
an error.
</td>
</tr>
<tr>
<td>mem_read_block_8<br>mem_read_block_16<br>mem_read_block_32</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Reads a block from memory. Note that word-sized and dword-sized
block reads must start on an aligned (even) boundary. Also, the
length parameter is in bytes/words/dwords. For example, a length
of <span class='value'>2</span> in the <span class='function'>mem_read_block_32()</span>
function will read 8 bytes.
</td>
</tr>
<tr>
<td>mem_write_block_8<br>mem_write_block_16<br>mem_write_block_32</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Writes a block to memory. Note that word-sized and dword-sized
block writes must start on an aligned (even) boundary. Also, the
length parameter is in bytes/words/dwords. For example, a length
of <span class='value'>2</span> in the <span class='function'>mem_write_block_32()</span>
function will write 8 bytes.
</td>
</tr>
<tr>
<td>reg_set<br>reg_get</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Set/get a register from an active IC. See
<a href="mdp_reg_h.html"><span class='filename'>mdp_reg.h</span></a>
for more information about registers.
</td>
</tr>
<tr>
<td>reg_set_all<br>reg_get_all</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Set/get all registers from an active IC. See
<a href="mdp_reg_h.html"><span class='filename'>mdp_reg.h</span></a>
for more information about registers.
</td>
</tr>
<tr>
<td>menu_item_add<br>menu_item_remove</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Adds or removes a menu item from the emulator's menu system.
Parameters include a callback function, a menu ID (e.g. if the
emulator supports more than one menu), and initial text. See
<span class='enum'><a href="#MDP_MENU">MDP_MENU</a></span>
for a list of valid menu IDs. (Note that if a menu ID that isn't
supported by the emulator is specified, it will map to the
default menu.)
</td>
</tr>
<tr>
<td>menu_item_set_text<br>menu_item_get_text</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Set/get the text of a menu item. If the text pointer
is NULL, the menu text will be cleared.
</td>
</tr>
<tr>
<td>menu_item_set_checked<br>menu_item_get_checked</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Set/get the checked state of a menu item.
<span class='value'>0</span> indicates not checked;
anything else indicates checked.
</td>
</tr>
<tr>
<td>event_register<br>event_unregister</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Registers/unregisters an event handler. See
<a href="mdp_event_h.html"><span class='filename'>mdp_event.h</span></a>
for more information about event handlers.
</td>
</tr>
<tr>
<td>window_register<br>window_unregister</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Registers/unregisters a window with the emulator's
window management system.
</td>
</tr>
<tr>
<td>window_get_main</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Returns a pointer to the main window. This is usually
of type <span class='type'>GtkWindow*</span> on GTK+ and
<span class='type'>HWND</span> on Win32, except it is
casted to <span class='type'>void*</span> in order for
the MDP headers to retain OS-independence. The active UI
system should be checked using the <span class='function'>val_get()</span>
MDP host services function.
</td>
</tr>
<tr>
<td>emulator_control</td>
<td class='type'>Function</td>
<td class='req_yes'>Yes</td>
<td>
Executes an emulator control function. See
<span class='enum'><a href="#MDP_EMUCTRL">MDP_EMUCTRL</a></span>
for a list of supported functions.
</td>
</tr>
<tr>
<td>config_get<br>config_set</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Get/set configuration information. Note that these
functions should be executed after the emulator has
loaded its configuration or before it saves its
configuration. Two events exist for this purpose; see
<a href="mdp_event_h.html"><span class='filename'>mdp_event.h</span></a>
for more information.
</td>
</tr>
<tr>
<td>dir_get_default_save_path</td>
<td class='type'>Function</td>
<td class='req_no_notnull'>No (Not NULL)</td>
<td>
Get the default save path for the emulator. This is
used by some plugins that save configuration files
separately from the main emulator configuration file.
</td>
</tr>
<tr>
<td>dir_register<br>dir_unregister</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Registers/unregisters a configurable directory
with the emulator. This allows the user to configure
all directories in a single window. Some plugins may
use this to separate certain types of dump files from
the rest of the save directory.
</td>
</tr>
<tr>
<td>crc32</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Calculates the CRC32 of a block of memory.
</td>
</tr>
<tr>
<td>z_open</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Opens a compressed (or uncompressed) file. If the file
is compressed and the emulator supports the compression
scheme used, then the compressed files can be accessed
by the plugin (read-only). Note that
<span class='function'>z_open()</span> supports multi-file
archives, so the <span class='struct'>mdp_z_t</span> struct
returned by this function may include a list of multiple files.
See <a href="mdp_z_h.html"><span class='filename'>mdp_z.h</span></a>
for more information about the MDP file compression structs.
</td>
</tr>
<tr>
<td>z_get_file</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Loads a file from an archive previously opened with the
<span class='function'>z_open()</span> function.
</td>
</tr>
<tr>
<td>z_close</td>
<td class='type'>Function</td>
<td class='req_no_null'>No (NULL)</td>
<td>
Closes an archive previously opened with the
<span class='function'>z_open()</span> function.
</td>
</tr>
</table>
</body>
</html>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
63e90c6f974301ed6e037d93940ef271
>
files
>
134
