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.