RetroFlat Bitmap API

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

Collaboration diagram for RetroFlat Bitmap API:

Macros
#define	RETROFLAT_BITMAP_FLAG_OPAQUE   0x01
	Flag for retroflat_create_bitmap() or retroflat_load_bitmap() to create or load a bitmap without transparency.
#define	RETROFLAT_BITMAP_FLAG_LITERAL_PATH   0x02
	Flag for retroflat_load_bitmap() to not use assets path.
#define	RETROFLAT_BITMAP_FLAG_RO   0x04
#define	RETROFLAT_BITMAP_FLAG_SCREEN_BUFFER   0x08
	Flag for retroflat_create_bitmap() to create a VRAM-backed bitmap.
#define	RETROFLAT_BITMAP_FLAG_SCREEN_LOCK   0x20
#define	RETROFLAT_BITMAP_FLAG_LOCK   0x40
#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)
	Declare that a given instance ID is for a tile, rather than a sprite.
#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

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 (retroflat_pxxy_t w, retroflat_pxxy_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, retroflat_pxxy_t s_x, retroflat_pxxy_t s_y, retroflat_pxxy_t d_x, retroflat_pxxy_t d_y, retroflat_pxxy_t w, retroflat_pxxy_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 Maug_retroflt_color.
• 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_FLAG_SCREEN_BUFFER

#define RETROFLAT_BITMAP_FLAG_SCREEN_BUFFER   0x08

Flag for retroflat_create_bitmap() to create a VRAM-backed bitmap.

Also may be present in RETROFLAT_BITMAP::flags to indicate that a bitmap is screen-backed.

retroflat_instance_tile

#define retroflat_instance_tile

(

instance

)

Value:

(0 - (instance))

Declare that a given instance ID is for a tile, rather than a sprite.

Function Documentation

retroflat_blit_bitmap()

MERROR_RETVAL retroflat_blit_bitmap	(	struct RETROFLAT_BITMAP *	target,
		struct RETROFLAT_BITMAP *	src,
		retroflat_pxxy_t	s_x,
		retroflat_pxxy_t	s_y,
		retroflat_pxxy_t	d_x,
		retroflat_pxxy_t	d_y,
		retroflat_pxxy_t	w,
		retroflat_pxxy_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. This bitmap should be locked!
src	Pointer to the ::RETROFLAT_BITMAP to blit onto target. This bitmap must not be locked.
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).