RetroFlat Bitmap API

Tools for loading bitmaps from disk and drawing them on-screen. More...

Collaboration diagram for RetroFlat Bitmap API:

Data Structures
struct	RETROFLAT_BITMAP
	Platform-specific bitmap structure. retroflat_bitmap_ok() can be used on a pointer to it to determine if a valid bitmap is loaded. More...

Macros
#define	RETROFLAT_FLAGS_SCREEN_LOCK   0x02
#define	RETROFLAT_BITMAP_EXT   "bmp"
	The filename suffix to be appended with a "." to filenames passed to retroflat_load_bitmap(). Is a RetroFlat Compiler Definitions.
#define	RETROFLAT_OPENGL_BPP   32
#define	RETROFLAT_TXP_R   0x00
	Compiler-define-overridable constant indicating the Red value of the transparency color on platforms that support it (mainly Win16/SDL). Is a RetroFlat Compiler Definitions.
#define	RETROFLAT_TXP_G   0x00
	Compiler-define-overridable constant indicating the Green value of the transparency color on platforms that support it (mainly Win16/SDL). Is a RetroFlat Compiler Definitions.
#define	RETROFLAT_TXP_B   0x00
	Compiler-define-overridable constant indicating the Blue value of the transparency color on platforms that support it (mainly Win16/SDL). Is a RetroFlat Compiler Definitions.
#define	RETROFLAT_TXP_PAL_IDX   0
#define	retroflat_bitmap_ok(bitmap)   (NULL != (bitmap)->b)
	Check to see if a bitmap is loaded.

Functions
MERROR_RETVAL	retroflat_load_bitmap (const char *filename, struct RETROFLAT_BITMAP *bmp_out, uint8_t flags)
	Load a bitmap into the given RETROFLAT_BITMAP structure if it is available. Bitmaps are subject to the limitations enumerated in RetroFlat Bitmap API.
MERROR_RETVAL	retroflat_create_bitmap (size_t w, size_t h, struct RETROFLAT_BITMAP *bmp_out, uint8_t flags)
void	retroflat_destroy_bitmap (struct RETROFLAT_BITMAP *bitmap)
	Unload a bitmap from a RETROFLAT_BITMAP struct. The struct, itself, is not freed (in case it is on the stack).
void	retroflat_blit_bitmap (struct RETROFLAT_BITMAP *target, struct RETROFLAT_BITMAP *src, int s_x, int s_y, int d_x, int d_y, int16_t w, int16_t h)
	Blit the contents of a RETROFLAT_BITMAP onto another RETROFLAT_BITMAP.

Detailed Description

Tools for loading bitmaps from disk and drawing them on-screen.

Bitmaps handled by retroflat are subject to certain constraints, due to the limitations of the underyling layers:

• They must have a 16-color palette.
• The colors must be in the order specified in RetroFlat Colors.
• The first color (black) is the transparency color.

RETROFLAT_BITMAP structs loaded with retroflat_load_bitmap() should later be freed using retroflat_destroy_bitmap().

Locking from the RetroFlat Drawing API also applies here. Please see that page for more information on retroflat_draw_lock() and retroflat_draw_release().

Warning

The screen MUST be locked by calling retroflat_draw_lock() with NULL before it is drawn to, and released with retroflat_draw_release() when drawing is finished before the retroflat_loop_iter() ends!

Function Documentation

retroflat_blit_bitmap()

void retroflat_blit_bitmap	(	struct RETROFLAT_BITMAP *	target,
		struct RETROFLAT_BITMAP *	src,
		int	s_x,
		int	s_y,
		int	d_x,
		int	d_y,
		int16_t	w,
		int16_t	h )

Blit the contents of a RETROFLAT_BITMAP onto another RETROFLAT_BITMAP.

Parameters

target	Pointer to the RETROFLAT_BITMAP to blit src onto.
src	Pointer to the RETROFLAT_BITMAP to blit onto target.
s_x	Left X coordinate to blit starting from on the source bitmap.
s_y	Top Y coordinate to blit starting from on the source bitmap.
d_x	Left X coordinate to blit to on the target bitmap.
d_y	Top Y coordinate to blit to on the target bitmap.
w	Pixel width of the region to blit.
h	Pixel height of the region to blit.

Todo

Currently s_x, s_y, w, and h are not functional on all platforms!

retroflat_destroy_bitmap()

void retroflat_destroy_bitmap

(

struct RETROFLAT_BITMAP *

bitmap

)

Unload a bitmap from a RETROFLAT_BITMAP struct. The struct, itself, is not freed (in case it is on the stack).

Parameters

bitmap

Pointer to the RETROFLAT_BITMAP to unload.

retroflat_load_bitmap()

MERROR_RETVAL retroflat_load_bitmap	(	const char *	filename,
		struct RETROFLAT_BITMAP *	bmp_out,
		uint8_t	flags )

Load a bitmap into the given RETROFLAT_BITMAP structure if it is available. Bitmaps are subject to the limitations enumerated in RetroFlat Bitmap API.

Parameters

filename	Filename of the bitmap under RETROFLAT_ARGS::assets_path with no separator, ".", or RETROFLAT_BITMAP_EXT.
bmp_out	Pointer to a RETROFLAT_BITMAP to load the bitmap into.

Returns

RETROFLAT_OK if the bitmap was loaded or RETROFLAT_ERROR_TIMER if there was a problem (e.g. the bitmap was not found).