# MDP - mdp_render.h: Renderers

#### Mega Drive Plugins v1.0.0
Revision 0

The primary motivation for creating MDP was to allow renderers to be loaded from outside of the main emulator. mdp_render.h provides the structs and constants needed to create a renderer using MDP.

The mdp_render_t struct defines the basic renderer information structure that is used to register a given rendering plugin with the emulator via mdp_host_t->renderer_register().

Format of the mdp_render_t struct:

    #include "mdp/mdp_render.h"

    typedef struct PACKED _mdp_render_t
    {
    	/*! BEGIN: MDP v1.0 render plugin definition struct. !*/

    	mdp_render_fn blit;	/* Blit function. */
    	const char* tag;	/* Render tag. */

    	int scale;		/* Scaling ratio. (1 == 320x240; 2 = 640x480; etc) */
    	uint32_t flags;		/* Render flags. */

    	void *data;		/* Extra data. */

    	/*! END: MDP v1.0 render plugin definition struct. !*/
    } mdp_render_t;

Fields:

Field | Type | Description
--- | --- | ---
blit | mdp_render_fn | Pointer to the main rendering function. The function prototype for mdp_render_fn is defined as: typedef int (MDP_FNCALL *mdp_render_fn)(const mdp_render_info_t *renderInfo);
tag | const char* | A short tag describing the renderer, e.g. "2xSaI".
scale | int | Scaling ratio. This indicates the integer zoom that the renderer performs on the source image. It must be greater than zero.
flags | uint32_t | Render flags. See Render Flags for more information.
data | void* | User-defined data passed to the rendering function, blit(), when rendering an image.

## Render Flags

The mdp_render_t struct has a field flags, which indicates various features that the renderer supports. This is a bitfield, so individual features can be OR'd together to indicate that the renderer supports multiple features.

Note: Color modes indicated are RGB555 (15-bit), RGB565 (16-bit), and RGB888 (32-bit). 24-bit color is not supported by MDP.

Render Flag bits:

Flag | Value | Description
--- | --- | ---
MDP_RENDER_FLAG_RGB_555to555 | (1 << 0) | Renderer suppots blitting an RGB555 source to an RGB555 destination.
MDP_RENDER_FLAG_RGB_555to565 | (1 << 1) | Renderer suppots blitting an RGB555 source to an RGB565 destination.
MDP_RENDER_FLAG_RGB_555to888 | (1 << 2) | Renderer suppots blitting an RGB555 source to an RGB888 destination.
MDP_RENDER_FLAG_RGB_565to555 | (1 << 3) | Renderer suppots blitting an RGB565 source to an RGB555 destination.
MDP_RENDER_FLAG_RGB_565to565 | (1 << 4) | Renderer suppots blitting an RGB565 source to an RGB565 destination.
MDP_RENDER_FLAG_RGB_565to888 | (1 << 5) | Renderer suppots blitting an RGB565 source to an RGB888 destination.
MDP_RENDER_FLAG_RGB_888to555 | (1 << 6) | Renderer suppots blitting an RGB888 source to an RGB555 destination.
MDP_RENDER_FLAG_RGB_888to565 | (1 << 7) | Renderer suppots blitting an RGB888 source to an RGB565 destination.
MDP_RENDER_FLAG_RGB_888to888 | (1 << 8) | Renderer suppots blitting an RGB888 source to an RGB888 destination.

## mdp_render_info_t

The mdp_render_info_t struct is passed to mdp_render_fn functions when the emulator wants to render an image.

Format of the mdp_render_t struct:

    #include "mdp/mdp_render.h"

    typedef struct PACKED _mdp_render_info_t
    {
    	/*! BEGIN: MDP v1.0 render information struct. !*/

    	void *destScreen;	/* Destination screen buffer. */
    	void *mdScreen;		/* Source screen buffer. */

    	int destPitch;		/* Destination screen buffer pitch. */
    	int srcPitch;		/* Source screen buffer pitch. */

    	int width;		/* Image width. */
    	int height;		/* Image height. */

    	uint32_t cpuFlags;	/* CPU flags. */
    	uint32_t vmodeFlags;	/* Video mode flags. */

    	void *data;		/* Extra data set by the plugin. */

    	/*! END: MDP v1.0 render information struct. !*/
    } mdp_render_info_t;

Fields:

Field | Type | Description
--- | --- | ---
destScreen | void* | Pointer to the destination screen buffer.
mdScreen | void* | Pointer to the source screen buffer.
destPitch | int | Pitch of the destination screen buffer, in bytes.
srcPitch | int | Pitch of the source screen buffer, in bytes.
width | int | Width of the image to blit, in pixels.
height | int | Height of the image to blit, in pixels.
cpuFlags | uint32_t | System CPU flags. See mdp_cpuflags.h for a description of the CPU flags field.
vmodeFlags | uint32_t | Video mode flags. See Video Mode Flags for more information.
data | void* | User-defined data specified in the mdp_render_t struct.

## Video Mode Flags

The Video Mode Flags are specified in the mdp_render_info_t struct in order to tell the rendering plugin what the current video mode is. In MDP v1.0, there are currently four bits indicatin what the source and destination video modes are. Two bits are used for each one.

Video Modes:

Flag | Value | Description
--- | --- | ---
MDP_RENDER_VMODE_RGB_555 | 0x00 | RGB555 (15-bit).
MDP_RENDER_VMODE_RGB_565 | 0x01 | RGB565 (16-bit).
MDP_RENDER_VMODE_RGB_888 | 0x02 | RGB888 (32-bit).

Two convenience macros are provided for retrieving the video mode flags from the vmodeFlags field:

Macro | Description
--- | ---
MDP_RENDER_VMODE_GET_SRC(x) | Get the source video mode.
MDP_RENDER_VMODE_GET_DST(x) | Get the destination video mode.

The plugin should check both the source and destination video modes and act appropriately. If the plugin doesn't support a specific combination, it should return the error code --MDP_ERR_RENDER_UNSUPPORTED_VMODE.