# MDP - mdp.h: Basic Plugin Interface

#### Mega Drive Plugins v1.0.0-draft

Every plugin must export a struct of type mdp_t. This struct contains the basic information about the plugin. For internal plugins, the mdp_t struct is referenced in the host program's MDP implementation, so it can have any name. For external plugins, the mdp_t struct must be exported with the name mdp (_mdp on platforms that prefix C symbols with underscores).

Format of the mdp_t struct:

    #include "mdp/mdp.h"

    typedef struct _mdp_t
    {
    	// Plugin version information.
    	const uint32_t interfaceVersion;
    	const uint32_t pluginVersion;

    	// CPU flags.
    	const uint32_t cpuFlagsSupported;
    	const uint32_t cpuFlagsRequired;

    	// UUID - each plugin must have a unique ID.
    	const unsigned char uuid[16];

    	// Description.
    	mdp_desc_t *desc;

    	// Functions.
    	mdp_func_t *func;
    } mdp_t;

Fields:

Field | Type | Description
--- | --- | ---
interfaceVersion | uint32_t | The MDP interface version used by the plugin. Can be generated using the MDP_VERSION(major, minor, revision) macro, or by using the MDP_INTERFACE_VERSION macro, which is defined as the interface version specified in the MDP headers being used.
pluginVersion | uint32_t | Plugin version. This is a user-defined value and can be anything. Use the MDP_VERSION(major, minor, revision) macro to create the version number.
cpuFlagsSupported | uint32_t | Bitfield of CPU flags supported by the plugin. The CPU flag values are defined in mdp_cpuflags.h.
cpuFlagsRequired | uint32_t | Bitfield of CPU flags required by the plugin. If any of the flags specified in this field are not supported by the current CPU, the plugin will not be loaded.
uuid | unsigned char[16] | Universally Unique Identifier used to uniquely identify the plugin. Use a tool such as uuidgen to generate the UUID.
desc | mdp_desc_t | Pointer to mdp_desc_t with description information about the plugin.
func | mdp_func_t | Pointer to mdp_func_t with various plugin functions, such as initialization and shutdown.

## mdp_desc_t: MDP Description Field

The mdp_t.desc field points to a struct of type mdp_desc_t, which contains a description of the plugin.

Note: All strings are encoded using UTF-8.

    #include "mdp/mdp.h"

    typedef struct _mdp_desc_t
    {
    	const char* name;
    	const char* author_mdp;
    	const char* author_orig;
    	const char* description;
    	const char* website;
    	const char* license;

    	// Filler for alignment purposes.
    	const void* reserved1;
    	const void* reserved2;

    	// Icon data. (PNG format)
    	const unsigned char* icon;
    	const unsigned int iconLength;
    } mdp_desc_t;

Fields:

Field | Type | Description
--- | --- | ---
name | const char* | Name of the plugin.
author_mdp | const char* | Author of the plugin.
author_orig | const char* | Author of the original code. This is mainly used when porting a third-party renderer into the MDP plugin format. If the plugin author is the same as the code author, this field may be set to NULL.
description | const char* | A short description of the plugin.
website | const char* | The plugin author's website. May be NULL if no website is available.
license | const char* | Plugin license. Example licenses are "GPL-2", "GPL-3", "LGPL-2.1", and "BSD". See the Predefined Licenses section for more predefined licenses.
reserved1 | const void* | Reserved.
reserved2 | const void* | Reserved.
icon | const unsigned char* | Plugin icon. This field must point to a 32x32 PNG-format icon stored within the plugin as an unsigned char[] array. Alternatively, this field may be set to NULL to indicate no icon.
iconLength | const unsigned int | Length of the icon data pointed to by the icon field.

### Predefined Licenses

mdp.h has several licenses predefined as macros:

    #define MDP_LICENSE_GPL_2	"GPL-2"
    #define MDP_LICENSE_GPL_3	"GPL-3"
    #define MDP_LICENSE_LGPL_2	"LGPL-2"
    #define MDP_LICENSE_LGPL_21	"LGPL-2.1"
    #define MDP_LICENSE_LGPL_3	"LGPL-3"
    #define MDP_LICENSE_BSD		"BSD"
    #define MDP_LICENSE_PD		"Public Domain"

You may use any of these predefined licenses, or you may define your own.

## mdp_func_t: MDP Function Field

The mdp_t.func field points to a struct of type mdp_func_t, which contains pointers to various functions within the plugin.

    #include "mdp/mdp.h"
    #include "mdp/mdp_host.h"

    typedef void (MDP_FNCALL *mdp_init)(const mdp_host_t *host_srv);
    typedef void (MDP_FNCALL *mdp_end)(void);

    typedef struct _mdp_func_t
    {
    	// Init/Shutdown functions
    	mdp_init	init;
    	mdp_end		end;
    } mdp_func_t;

Fields:

Field | Type | Description
--- | --- | ---
init | mdp_init | Initialization function. The host_srv parameter is a pointer to the MDP Host Services struct.
end | mdp_end | Shutdown function.