RetroFlat Drawing API

Functions for drawing primitives on-screen. More...

Collaboration diagram for RetroFlat Drawing API:

Topics
	RetroFlat Colors
	Color definitions RetroFlat is aware of, for use with the RetroFlat Drawing API.

Macros
#define	RETROFLAT_FLAGS_FILL   0x01
	Flag for retroflat_rect() or retroflat_ellipse(), indicating drawn shape should be filled.
#define	RETROFLAT_FLAGS_OPAQUE   0x01
	Flag for retroflat_create_bitmap() to create a bitmap without transparency.
#define	RETROFLAT_FLAGS_ALL_CAPS   0x02
	Flag for retroflat_string() and retroflat_string_sz() to print text in all capital letters. Non-letters are unmodified.
#define	RETROFLAT_FLAGS_LITERAL_PATH   0x02
	Flag for retroflat_load_bitmap() to not use assets path.
#define	RETROFLAT_FLAGS_OUTLINE   0x04
	Flag for retroflat_string() and retroflat_string_sz() to print text as outline-only.
#define	RETROFLAT_FLAGS_SCREEN_BUFFER   0x80
	Flag for retroflat_create_bitmap() to create a WinG-backed bitmap.
#define	RETROFLAT_FLAGS_VIEWPORT_REFRESH   0x20
	Flag for args->flags, indicating that a viewport tile refresh grid should be allocated and used.
#define	RETROFLAT_LINE_THICKNESS   1
	Line drawing thickness (only works on some platforms). Is a RetroFlat Compiler Definitions.
#define	RETROFLAT_PI   3.14159

Functions
MERROR_RETVAL	retroflat_draw_lock (struct RETROFLAT_BITMAP *bmp)
	Lock a bitmap for drawing. This will be done automatically if necessary and not called explicitly, but performance should improve if done before a batch of drawing operations.
MERROR_RETVAL	retroflat_draw_release (struct RETROFLAT_BITMAP *bmp)
void	retroflat_px (struct RETROFLAT_BITMAP *target, const RETROFLAT_COLOR color, size_t x, size_t y, uint8_t flags)
void	retroflat_rect (struct RETROFLAT_BITMAP *target, const RETROFLAT_COLOR color, int16_t x, int16_t y, int16_t w, int16_t h, uint8_t flags)
	Draw a rectangle onto the target RETROFLAT_BITMAP.
void	retroflat_ellipse (struct RETROFLAT_BITMAP *target, const RETROFLAT_COLOR color, int16_t x, int16_t y, int16_t w, int16_t h, uint8_t flags)
	Draw an ellipse onto the target RETROFLAT_BITMAP.
void	retroflat_line (struct RETROFLAT_BITMAP *target, const RETROFLAT_COLOR color, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t flags)
	Draw a straight line onto the target RETROFLAT_BITMAP.
void	retroflat_cursor (struct RETROFLAT_BITMAP *target, uint8_t flags)
void	retroflat_string_sz (struct RETROFLAT_BITMAP *target, const char *str, size_t str_sz, const char *font_str, size_t *w_out, size_t *h_out, uint8_t flags)
	Get the size in pixels of a text string when drawn with a given font by retroflat_string().
void	retroflat_string (struct RETROFLAT_BITMAP *target, const RETROFLAT_COLOR color, const char *str, int str_sz, const char *font_str, int16_t x_orig, int16_t y_orig, uint8_t flags)
	Draw a text string at the specified location in the specified font and color on the target RETROFLAT_BITMAP.
void	retroflat_get_palette (uint8_t idx, uint32_t *rgb)
MERROR_RETVAL	retroflat_set_palette (uint8_t idx, uint32_t rgb)

Detailed Description

Functions for drawing primitives on-screen.

Warning

Drawing functions should not be used outside of the context of the main loop, as the platform may not have fully initialized the drawing window until the main loop is called for the first time!

Macro Definition Documentation

RETROFLAT_FLAGS_ALL_CAPS

#define RETROFLAT_FLAGS_ALL_CAPS   0x02

Flag for retroflat_string() and retroflat_string_sz() to print text in all capital letters. Non-letters are unmodified.

Todo

This has not yet been implemented and is present for backward compatibility.

RETROFLAT_FLAGS_OUTLINE

#define RETROFLAT_FLAGS_OUTLINE   0x04

Flag for retroflat_string() and retroflat_string_sz() to print text as outline-only.

Todo

This has not yet been implemented and is present for backward compatibility.

RETROFLAT_FLAGS_SCREEN_BUFFER

#define RETROFLAT_FLAGS_SCREEN_BUFFER   0x80

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

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

Function Documentation

retroflat_draw_lock()

MERROR_RETVAL retroflat_draw_lock

(

struct RETROFLAT_BITMAP *

bmp

)

Lock a bitmap for drawing. This will be done automatically if necessary and not called explicitly, but performance should improve if done before a batch of drawing operations.

Parameters

bmp	Pointer to a RETROFLAT_BITMAP struct to lock. If this is NULL, try to lock the screen.

Returns

RETROFLAT_OK if lock was successful or RetroFlat API Return Values otherwise.

retroflat_ellipse()

void retroflat_ellipse	(	struct RETROFLAT_BITMAP *	target,
		const RETROFLAT_COLOR	color,
		int16_t	x,
		int16_t	y,
		int16_t	w,
		int16_t	h,
		uint8_t	flags )

Draw an ellipse onto the target RETROFLAT_BITMAP.

Parameters

target	Pointer to the RETROFLAT_BITMAP to draw onto, or NULL to draw to the screen buffer.
color	RetroFlat Colors in which to draw.
x	Left X coordinate in pixels at which to draw on the target bitmap.
y	Top Y coordinate in pixels at which to draw on the target bitmap.
flags	Flags to control drawing. The following flags apply: RETROFLAT_FLAGS_FILL

retroflat_line()

void retroflat_line	(	struct RETROFLAT_BITMAP *	target,
		const RETROFLAT_COLOR	color,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		uint8_t	flags )

Draw a straight line onto the target RETROFLAT_BITMAP.

Parameters

target	Pointer to the RETROFLAT_BITMAP to draw onto, or NULL to draw to the screen buffer.
x1	Left X coordinate of the line to draw on the target bitmap.
y1	Top Y coordinate of the line to draw on the target bitmap.
x2	Right X coordinate of the line to draw on the target bitmap.
y2	Bottom Y coordinate of the line to draw on the target bitmap.
color	RetroFlat Colors in which to draw.
flags	Flags to control drawing. No flags currently apply.

retroflat_rect()

void retroflat_rect	(	struct RETROFLAT_BITMAP *	target,
		const RETROFLAT_COLOR	color,
		int16_t	x,
		int16_t	y,
		int16_t	w,
		int16_t	h,
		uint8_t	flags )

Draw a rectangle onto the target RETROFLAT_BITMAP.

Parameters

target	Pointer to the RETROFLAT_BITMAP to draw onto, or NULL to draw to the screen buffer.
color	RetroFlat Colors in which to draw.
x	Left X coordinate in pixels at which to draw on the target bitmap.
y	Top Y coordinate in pixels at which to draw on the target bitmap.
flags	Flags to control drawing. The following flags apply: RETROFLAT_FLAGS_FILL

retroflat_string()

void retroflat_string	(	struct RETROFLAT_BITMAP *	target,
		const RETROFLAT_COLOR	color,
		const char *	str,
		int	str_sz,
		const char *	font_str,
		int16_t	x_orig,
		int16_t	y_orig,
		uint8_t	flags )

Draw a text string at the specified location in the specified font and color on the target RETROFLAT_BITMAP.

Warning

Font specifications for font_str may vary by platform, so be sure to test with #ifdefs for each!

Parameters

target	Pointer to the RETROFLAT_BITMAP to draw onto, or NULL to draw to the screen buffer.
color	RetroFlat Colors in which to draw.
str	The text string to draw to the target bitmap.
str_sz	Length of the string to draw in characters.
font_str	Name of the font in which to draw the string.
x_orig	Left X coordinate in pixels at which to draw on the target bitmap.
y_orig	Top Y coordinate in pixels at which to draw on the target bitmap.
flags	Flags to control drawing. No flags currently apply.

retroflat_string_sz()

void retroflat_string_sz	(	struct RETROFLAT_BITMAP *	target,
		const char *	str,
		size_t	str_sz,
		const char *	font_str,
		size_t *	w_out,
		size_t *	h_out,
		uint8_t	flags )

Get the size in pixels of a text string when drawn with a given font by retroflat_string().

Warning

Font specifications for font_str may vary by platform, so be sure to test with #ifdefs for each!

Parameters

target	Pointer to the RETROFLAT_BITMAP on which drawing is planned.
str	The text string to get the size of.
str_sz	Length of the string to get the size of in characters.
font_str	Name of the font in which to size the string.
w_out	Pointer to an int in which to store the string width in pixels.
h_out	Pointer to an int in which to store the string height in pixels.