RetroFlat 2D Wrapper API

Wrappers to call appropriate 2D surface functions for bitmaps or textures, depending on if the engine is in 2D or 3D mode. More...

Collaboration diagram for RetroFlat 2D Wrapper API:

Topics
	RetroSound API
	Abstraction layer header for sound on retro systems.
	RetroFlat Viewport API
	A flexible API to facilitate tile-based views using hardware acceleration where available.
	RetroFlat VDP API
	Video Display Processor tools for modifying display output.
	RetroFlat Bitmap API
	Tools for loading bitmaps from disk and drawing them on-screen.
	RetroFlat Drawing API
	Functions for drawing primitives on-screen.
	RetroFlat Input API
	Functions and constants for polling and interpreting user input.
	RetroFlat Direction API
	Macros and constants for definition cardinal directions in screen and world space.

Data Structures
struct	RETROFLAT_ARGS
	Struct containing configuration values for a RetroFlat program. More...
struct	RETROFLAT_STATE
	Global singleton containing state for the current platform. More...

Macros
#define	retroflat_2d_px(...)
	Wrapper macro to call appropriate 2D surface blitter for pixels.
#define	retroflat_2d_line(...)
#define	retroflat_2d_rect(...)
#define	retroflat_2d_bitmap_ok(...)
#define	retroflat_2d_bitmap_w(...)
#define	retroflat_2d_bitmap_h(...)
#define	retroflat_2d_blit_bitmap(...)
#define	retroflat_2d_blit_win(src, d_x, d_y)
#define	retroflat_2d_lock_bitmap(...)
#define	retroflat_2d_release_bitmap(...)
#define	retroflat_2d_load_bitmap(...)
#define	retroflat_2d_create_bitmap(...)
#define	retroflat_2d_destroy_bitmap(...)
#define	API_TRACE_LVL   0
#define	retroflat_heartbeat_set(len, max)
	Set parameters for the RETROFLAT_STATE::heartbeat_frame.
#define	retroflat_heartbeat()
	Get current value of RETROFLAT_STATE::heartbeat_frame.
#define	retroflat_heartbeat_update()
	Check and update RETROFLAT_STATE::heartbeat_frame. This should be called in the API HAL on every iteration of the main loop (this is done automatically in the generic main loop).
#define	RETROFLAT_COLOR_TABLE_CONSTS(idx, name_l, name_u, r, g, b, cgac, cgad)

Typedefs
typedef size_t	retroflat_pxxy_t
	Type used for surface pixel coordinates.
typedef maug_ms_t	retroflat_ms_t
typedef struct RETROFLAT_BITMAP	retroflat_blit_t
typedef void(*	retroflat_px_cb) (retroflat_blit_t *target, const RETROFLAT_COLOR color_idx, size_t x, size_t y, uint8_t flags)
	Type of callback function used to produce pixels on a surface.

Functions
MERROR_RETVAL	retroflat_loop (retroflat_loop_iter frame_iter, retroflat_loop_iter loop_iter, void *data)
	This should be called once in the main body of the program in order to enter the main loop. The main loop will continuously call loop_iter with data as an argument until retroflat_quit() is called.
void	retroflat_message (uint8_t flags, const char *title, const char *format,...)
	Display a message in a dialog box and/or on stderr.
MERROR_RETVAL	retroflat_init (int argc, char *argv[], struct RETROFLAT_ARGS *args)
	Initialize RetroFlat and its underlying layers. This should be called once at the beginning of the program and should quit if the return value indicates any failures.
void	retroflat_shutdown (int retval)
	Deinitialize RetroFlat and its underlying layers. This should be called once at the end of the program, after retroflat_loop().
void	retroflat_set_title (const char *format,...)
retroflat_ms_t	retroflat_get_ms ()
uint32_t	retroflat_get_rand ()
char	retroflat_vk_to_ascii (RETROFLAT_IN_KEY k, uint8_t flags)
void	retroflat_set_proc_resize (retroflat_proc_resize_t on_resize_in, void *data_in)
	Set the procedure to call when the window is resized (on platforms that support resizing).
void	retroflat_resize_v ()
	Platform-specific function to resize virtual screen to match physical window size.

Variables
MAUG_CONST char *SEG_MCONST	gc_retroflat_color_names []
struct RETROFLAT_STATE *	g_retroflat_state
retroflat_px_cb	g_retroflat_px
	Directly addressable callback to produce pixels on a surface.

Detailed Description

Wrappers to call appropriate 2D surface functions for bitmaps or textures, depending on if the engine is in 2D or 3D mode.

This wrapper system is necessary so that high-level internal library functions (e.g. retrosoft, retrofont, or retroani) are able to continue functioning on textures in 3D mode.

Formerly, this was accomplished by shunts inside of the lower-level RetroFlat Drawing API, but these shunts were removed in order to facilitate platform-agnostic software-only 3D (and they were messy).

Macro Definition Documentation

retroflat_2d_bitmap_h

#define retroflat_2d_bitmap_h

(

...

)

Value:

retro3d_texture_h( __VA_ARGS__ )

retroflat_2d_bitmap_ok

#define retroflat_2d_bitmap_ok

(

...

)

Value:

retro3d_texture_ok( __VA_ARGS__ )

retroflat_2d_bitmap_w

#define retroflat_2d_bitmap_w

(

...

)

Value:

retro3d_texture_w( __VA_ARGS__ )

retroflat_2d_blit_bitmap

#define retroflat_2d_blit_bitmap

(

...

)

Value:

retro3d_texture_blit( __VA_ARGS__ )

retroflat_2d_blit_win

#define retroflat_2d_blit_win	(		src,
			d_x,
			d_y )

Value:

   retro3d_draw_window( src, d_x, d_y )

retroflat_2d_create_bitmap

#define retroflat_2d_create_bitmap

(

...

)

Value:

   retro3d_texture_create( __VA_ARGS__ )

retroflat_2d_destroy_bitmap

#define retroflat_2d_destroy_bitmap

(

...

)

Value:

   retro3d_texture_destroy( __VA_ARGS__ )

retroflat_2d_line

#define retroflat_2d_line

(

...

)

Value:

retrosoft_line( __VA_ARGS__ )

retroflat_2d_load_bitmap

#define retroflat_2d_load_bitmap

(

...

)

Value:

   retro3d_texture_load_bitmap( __VA_ARGS__ )

retroflat_2d_lock_bitmap

#define retroflat_2d_lock_bitmap

(

...

)

Value:

   retro3d_texture_lock( __VA_ARGS__ )

retroflat_2d_px

#define retroflat_2d_px

(

...

)

Value:

retro3d_texture_px( __VA_ARGS__ )

Wrapper macro to call appropriate 2D surface blitter for pixels.

retroflat_2d_rect

#define retroflat_2d_rect

(

...

)

Value:

retrosoft_rect( __VA_ARGS__ )

retroflat_2d_release_bitmap

#define retroflat_2d_release_bitmap

(

...

)

Value:

   retro3d_texture_release( __VA_ARGS__ )

RETROFLAT_COLOR_TABLE_CONSTS

#define RETROFLAT_COLOR_TABLE_CONSTS	(		idx,
			name_l,
			name_u,
			r,
			g,
			b,
			cgac,
			cgad )

Value:

   extern MAUG_CONST RETROFLAT_COLOR RETROFLAT_COLOR_ ## name_u;

retroflat_heartbeat

#define retroflat_heartbeat ( )

related

Value:

(g_retroflat_state->heartbeat_frame)

Get current value of RETROFLAT_STATE::heartbeat_frame.

retroflat_heartbeat_set

#define retroflat_heartbeat_set ( len, max )

related

Value:

   g_retroflat_state->heartbeat_max = max; \
   g_retroflat_state->heartbeat_len = len;

Set parameters for the RETROFLAT_STATE::heartbeat_frame.

Parameters

len	Number of ms between updates to RETROFLAT_STATE::heartbeat_frame.
max	Value of RETROFLAT_STATE::heartbeat_frame on which to reset to 0.

retroflat_heartbeat_update

#define retroflat_heartbeat_update ( )

related

Value:

   /* Update the heartbeat animation frame. */ \
   if( g_retroflat_state->heartbeat_next <= retroflat_get_ms() ) { \
      g_retroflat_state->heartbeat_frame++; \
      if( \
         g_retroflat_state->heartbeat_frame >= \
            g_retroflat_state->heartbeat_max \
      ) { \
         g_retroflat_state->heartbeat_frame = 0; \
      } \
      g_retroflat_state->heartbeat_next = \
         retroflat_get_ms() + g_retroflat_state->heartbeat_len; \
   }

Check and update RETROFLAT_STATE::heartbeat_frame. This should be called in the API HAL on every iteration of the main loop (this is done automatically in the generic main loop).

Typedef Documentation

retroflat_px_cb

typedef void(* retroflat_px_cb) (retroflat_blit_t *target, const RETROFLAT_COLOR color_idx, size_t x, size_t y, uint8_t flags)

Type of callback function used to produce pixels on a surface.

This is switched between RETROFLAT_3DTEX and RETROFLAT_BITMAP, depending on whether this is a 3D or 2D engine.

retroflat_pxxy_t

typedef size_t retroflat_pxxy_t

Type used for surface pixel coordinates.

Todo

Make this signed when most of the library uses it. Right now, it causes too many issues with passed references.

Function Documentation

retroflat_init()

MERROR_RETVAL retroflat_init	(	int	argc,
		char *	argv[],
		struct RETROFLAT_ARGS *	args )

Initialize RetroFlat and its underlying layers. This should be called once at the beginning of the program and should quit if the return value indicates any failures.

Returns

RETROFLAT_OK if there were no problems or other RetroFlat API Return Values if there were.

retroflat_message()

void retroflat_message	(	uint8_t	flags,
		const char *	title,
		const char *	format,
			... )

Display a message in a dialog box and/or on stderr.

Parameters

title	A string with the title to use for a dialog box.
format	A format string to be passed to vsnprintf().

Todo

This should display a dialog box on every platform if possible.

retroflat_set_proc_resize()

void retroflat_set_proc_resize	(	retroflat_proc_resize_t	on_resize_in,
		void *	data_in )

Set the procedure to call when the window is resized (on platforms that support resizing).

Parameters

on_resize_in	Procedure to call when window is resized.
data_in	Data to pass to on_resize_in.

If this is not set, no procedure is called. Some platforms may stretch the "virtual" screen to fill the physical window.

retroflat_shutdown()

void retroflat_shutdown

(

int

retval

)

Deinitialize RetroFlat and its underlying layers. This should be called once at the end of the program, after retroflat_loop().

Parameters

retval

Return value from retroflat_init(), so we know what layers are in what state.

Variable Documentation

g_retroflat_px

retroflat_px_cb g_retroflat_px

extern

Directly addressable callback to produce pixels on a surface.

This is assigned in retroflat_init(), as that is when all of the _px() callback functions are defined and available.