RetroFlat API

Abstraction layer header for retro systems. More...

Collaboration diagram for RetroFlat API:

Topics
	RetroFlat Example
	An extremely simple single-file annotated example program written with the RetroFlat API.
	RetroFlat Compilation
	Makefile examples and compiler considerations for using RetroFlat.
	Maug_retroflt_color
	RetroFlat API Return Values
	Standardized return values from RetroFlat API functions.
	RetroFlat Drawing API
	Functions for drawing primitives on-screen.
	Global Flags
	Flags that may be present on RETROFLAT_STATE::retroflat_flags.
	RetroFlat Message API
	These flags can be passed to retroflat_message() to indicate the type of message being conveyed.
	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 Assets API
	Functions and macros for handling graphical asset files.
	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.
	RetroSound API
	Abstraction layer header for sound on retro systems.
	Maug_retro3d_util

Files
file	retroflt.h
	Abstraction layer header for retro systems.

Macros
#define	RETROFLAT_BITMAP_TRACE_LVL   0
#define	RETROFLAT_KB_TRACE_LVL   0
#define	RETROFLAT_DEFAULT_SCREEN_W   320
#define	RETROFLAT_DEFAULT_SCREEN_H   200
#define	retroflat_on_resize(w, h)
#define	retroflat_wait_for_frame()
#define	retroflat_is_waiting_for_frame()
#define	RETRO2D_TRACE_LVL   0

Typedefs
typedef MERROR_RETVAL(*	retroflat_proc_resize_t) (uint16_t new_w, uint16_t new_h, void *data)
typedef void(*	retroflat_loop_iter) (void *data)
	Prototype for the main loop function passed to retroflat_loop().
typedef size_t	retroflat_pxxy_t
	Type used for surface pixel coordinates.

Variables
int	RETROFLAT_INPUT::mouse_x
	X-coordinate of the mouse pointer in pixels if the returned event is a mouse click.
int	RETROFLAT_INPUT::mouse_y
	Y-coordinate of the mouse pointer in pixels if the returned event is a mouse click.
uint8_t	RETROFLAT_INPUT::key_flags
uint8_t	RETROFLAT_3DTEX::flags
MAUG_MHANDLE	RETROFLAT_3DTEX::bytes_h
uint8_t *	RETROFLAT_3DTEX::bytes
uint32_t	RETROFLAT_3DTEX::bpp
uint32_t	RETROFLAT_3DTEX::sz
uint8_t *	RETROFLAT_3DTEX::px
uint32_t	RETROFLAT_3DTEX::id
size_t	RETROFLAT_3DTEX::w
size_t	RETROFLAT_3DTEX::h
uint8_t	RETROFLAT_ARGS::flags
char *	RETROFLAT_ARGS::title
	Title to set for the main program Window if applicable on the target platform.
char *	RETROFLAT_ARGS::assets_path
	Relative path under which bitmap assets are stored.
char *	RETROFLAT_ARGS::config_path
	Relative path of local config file (if not using registry).
int	RETROFLAT_ARGS::screen_w
int	RETROFLAT_ARGS::screen_h
	Desired screen or window height in pixels.
int	RETROFLAT_ARGS::screen_x
	Desired window X position in pixels.
int	RETROFLAT_ARGS::screen_y
	Desired window Y position in pixels.
struct RETROFLAT_PLATFORM_ARGS	RETROFLAT_ARGS::platform
struct RETROFLAT_SOUND_ARGS	RETROFLAT_ARGS::sound
int16_t	RETROFLAT_VIEWPORT::screen_x
	X position of the viewport in real screen memory in pixels. Should only be retrieved through retroflat_viewport_screen_x() and set through retroflat_viewport_set_pos_size().
int16_t	RETROFLAT_VIEWPORT::screen_y
	Y position of the viewport in real screen memory in pixels. Should only be retrieved through retroflat_viewport_screen_y() and set through retroflat_viewport_set_pos_size()
int16_t	RETROFLAT_VIEWPORT::world_x
	The X offset, in pixels, of the viewport on the world tilemap. Should only be retrieved through retroflat_viewport_world_x() and set through retroflat_viewport_set_world_pos().
int16_t	RETROFLAT_VIEWPORT::world_y
	The Y offset, in pixels, of the viewport on the world tilemap. Should only be retrieved through retroflat_viewport_world_y() and set through retroflat_viewport_set_world_pos().
int16_t	RETROFLAT_VIEWPORT::world_w
	The width of the entire world tilemap in pixels. Should only be retrieved through retroflat_viewport_world_w() and set through retroflat_viewport_set_world().
int16_t	RETROFLAT_VIEWPORT::world_h
	The height of the entire world tilemap in pixels. Should only be retrieved through retroflat_viewport_world_h() and set through retroflat_viewport_set_world().
uint16_t	RETROFLAT_VIEWPORT::screen_w
	Viewport width in pixels. Should only be retrieved through retroflat_viewport_screen_w() and set through retroflat_viewport_set_pos_size().
uint16_t	RETROFLAT_VIEWPORT::screen_h
	Viewport height in pixels. Should only be retrieved through retroflat_viewport_screen_w() and set through retroflat_viewport_set_pos_size().
uint16_t	RETROFLAT_VIEWPORT::screen_w_remainder
	Difference between viewport width and screen width in pixels. Should only be retrieved through retroflat_viewport_screen_w_remainder() and calculated through retroflat_viewport_set_pos_size().
uint16_t	RETROFLAT_VIEWPORT::screen_h_remainder
	Difference between viewport height and screen height in pixels. Should only be retrieved through retroflat_viewport_screen_h_remainder() and calculated through retroflat_viewport_set_pos_size().
int16_t	RETROFLAT_VIEWPORT::screen_tile_w
	The number of tiles across that fit in the viewport. Should only be retrieved through retroflat_viewport_screen_tile_w() and calculated through retroflat_viewport_set_pos_size().
int16_t	RETROFLAT_VIEWPORT::screen_tile_h
	The number of tiles high that fit in the viewport. Should only be retrieved through retroflat_viewport_screen_tile_h() and calculated through retroflat_viewport_set_pos_size().
int16_t	RETROFLAT_VIEWPORT::world_tile_x
int16_t	RETROFLAT_VIEWPORT::world_tile_y
MAUG_MHANDLE	RETROFLAT_VIEWPORT::refresh_grid_h
retroflat_tile_t *	RETROFLAT_VIEWPORT::refresh_grid
	A grid of tile values representing the last-drawn values on-screen.
size_t	RETROFLAT_STATE::sz
size_t	RETROFLAT_STATE::offset_pal
size_t	RETROFLAT_STATE::offset_tex_pal
void *	RETROFLAT_STATE::loop_data
MERROR_RETVAL	RETROFLAT_STATE::retval
uint8_t	RETROFLAT_STATE::retroflat_flags
	Global Flags indicating current system status.
char	RETROFLAT_STATE::config_path [RETROFLAT_PATH_MAX+1]
char	RETROFLAT_STATE::assets_path [RETROFLAT_ASSETS_PATH_MAX+1]
struct RETROFLAT_BITMAP	RETROFLAT_STATE::buffer
	Off-screen buffer bitmap.
int	RETROFLAT_STATE::scale
struct RETROFLAT_BITMAP *	RETROFLAT_STATE::vdp_buffer
	A buffer assembled and passed to the RetroFlat VDP API for it to modify, or NULL if no VDP is loaded.
void *	RETROFLAT_STATE::vdp_exe
	A handle for the loaded RetroFlat VDP API module.
void *	RETROFLAT_STATE::vdp_data
	Pointer to data defined by the RetroFlat VDP API for its use.
char	RETROFLAT_STATE::vdp_args [RETROFLAT_VDP_ARGS_SZ_MAX]
	CLI args passed with -vdp to the RetroFlat VDP API.
uint8_t	RETROFLAT_STATE::vdp_flags
	Flags set by the RetroFlat VDP API.
struct RETROFLAT_VIEWPORT	RETROFLAT_STATE::viewport
size_t	RETROFLAT_STATE::screen_v_w
	The screen width as seen by our program, before scaling.
size_t	RETROFLAT_STATE::screen_v_h
	The screen height as seen by our program, before scaling.
size_t	RETROFLAT_STATE::screen_w
	The screen width as seen by the system, after scaling.
size_t	RETROFLAT_STATE::screen_h
	The screen height as seen by the system, after scaling.
size_t	RETROFLAT_STATE::screen_colors
	The number of colors the screen is capable of displaying.
retroflat_ms_t	RETROFLAT_STATE::heartbeat_next
uint16_t	RETROFLAT_STATE::heartbeat_len
	Number of ms to stay on current value of RETROFLAT_STATE::heartbeat_frame before incrementing. Modify with retroflat_heartbeat_set().
uint8_t	RETROFLAT_STATE::heartbeat_frame
	Simple iteration loop that can be used to time e.g. perpetual sprite animations. Modify parameters with retroflat_heartbeat_set().
uint8_t	RETROFLAT_STATE::heartbeat_max
	When RETROFLAT_STATE::heartbeat_frame reaches this value, it will reset to 0.
retroflat_proc_resize_t	RETROFLAT_STATE::on_resize
void *	RETROFLAT_STATE::on_resize_data
RETROFLAT_COLOR_DEF	RETROFLAT_STATE::palette [RETROFLAT_COLORS_SZ]
	Index of available colors, initialized on platform init.
retroflat_loop_iter	RETROFLAT_STATE::loop_iter
retroflat_loop_iter	RETROFLAT_STATE::frame_iter
struct RETROFLAT_PLATFORM	RETROFLAT_STATE::platform
struct RETROFLAT_INPUT_STATE	RETROFLAT_STATE::input
struct RETROFLAT_SOUND_STATE	RETROFLAT_STATE::sound
#define	RETROSND_ARGS_FLAG_LIST_DEVS   0x01

Detailed Description

Abstraction layer header for retro systems.

Macro Definition Documentation

retroflat_is_waiting_for_frame

#define retroflat_is_waiting_for_frame

(

)

Value:

   (RETROFLAT_FLAGS_WAIT_FOR_FPS == \
      (g_retroflat_state->retroflat_flags & RETROFLAT_FLAGS_WAIT_FOR_FPS))

retroflat_on_resize

#define retroflat_on_resize	(		w,
			h )

Value:

   g_retroflat_state->screen_w = w; \
   g_retroflat_state->screen_h = h;

retroflat_wait_for_frame

#define retroflat_wait_for_frame

(

)

Value:

   (g_retroflat_state->retroflat_flags |= RETROFLAT_FLAGS_WAIT_FOR_FPS)

Typedef Documentation

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.

Variable Documentation

refresh_grid

retroflat_tile_t* RETROFLAT_VIEWPORT::refresh_grid

A grid of tile values representing the last-drawn values on-screen.

If the value for a tile in this grid matches the value about to be drawn, the draw will be skipped. This increases performance a LOT on systems with slow video memory access.

This functionality may be disabled by defining the macro RETROFLAT_NO_VIEWPORT_REFRESH on build.

screen_v_h

size_t RETROFLAT_STATE::screen_v_h

The screen height as seen by our program, before scaling.

This is the scale of the buffer, which the platform-specific code should then scale to match screen_v_w on blit.

screen_v_w

size_t RETROFLAT_STATE::screen_v_w

The screen width as seen by our program, before scaling.

This is the scale of the buffer, which the platform-specific code should then scale to match screen_v_h on blit.