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_LOCK   0x01
#define	RETROFLAT_FLAGS_SCREEN_LOCK   0x02
#define	RETROFLAT_FLAGS_BITMAP_RO   0x04
#define	RETROFLAT_INSTANCE_NULL   (0)
	Pass to retroflat_blit_bitmap() instance arg if this is not a sprite (i.e. if it is a background tile).
#define	retroflat_instance_tile(instance)
#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_TILE_W   16
#define	RETROFLAT_TILE_W_BITS   4
#define	RETROFLAT_TILE_H   16
#define	RETROFLAT_TILE_H_BITS   4
#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_constrain_px(x, y, bmp, retact)
	Ensure x and y (which must be unsigned!) are inside image boundaries.
#define	retroflat_bitmap_ok(bitmap)
	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).
MERROR_RETVAL	retroflat_blit_bitmap (struct RETROFLAT_BITMAP *target, struct RETROFLAT_BITMAP *src, size_t s_x, size_t s_y, int16_t d_x, int16_t d_y, size_t w, size_t h, int16_t instance)
	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!

Macro Definition Documentation

retroflat_bitmap_ok

#define retroflat_bitmap_ok

(

bitmap

)

Value:

(NULL != (bitmap)->b)

Check to see if a bitmap is loaded.

retroflat_constrain_px

#define retroflat_constrain_px	(		x,
			y,
			bmp,
			retact )

Value:

   if( \
      x >= retroflat_bitmap_w( bmp ) || y >= retroflat_bitmap_h( bmp ) \
   ) { retact; }

Ensure x and y (which must be unsigned!) are inside image boundaries.

This also relies on the platform-specific retroflat_bitmap_w() and retroflat_bitmap_h() macros being smart enough to measure the screen buffer if bmp is NULL.

retroflat_instance_tile

#define retroflat_instance_tile

(

instance

)

Value:

  (instance * -1)

Function Documentation

retroflat_blit_bitmap()

MERROR_RETVAL retroflat_blit_bitmap	(	struct RETROFLAT_BITMAP *	target,
		struct RETROFLAT_BITMAP *	src,
		size_t	s_x,
		size_t	s_y,
		int16_t	d_x,
		int16_t	d_y,
		size_t	w,
		size_t	h,
		int16_t	instance )

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).