Unilayer Graphics Layer

Simple abstract unified graphics drawing layer designed for resource-constrained systems. More...

Collaboration diagram for Unilayer Graphics Layer:

Modules
	Unilayer Graphics String Flags
	Flags for modifying string display options.
	Unilayer Graphics Bitmap Flags
	Unilayer Graphics Cache
	Interface to cache that holds/deduplicates sprites and tiles.
	Unilayer Graphics Colors
	Platform-defined colors in which to draw graphical elements.

Files
file	graphics.h
	Platform-general abstractions for graphics.
file	nullg.h
	Platform-overridden typedefs and macros for drawing graphics.

Data Structures
struct	GRAPHICS_RECT
	Struct representing a graphical rectangle. More...
struct	GRAPHICS_BITMAP_BASE
	Struct representing a bitmap. Should be overridden by platform. More...
struct	GRAPHICS_BITMAP
	Struct representing a bitmap on the current platform. More...
struct	GRAPHICS_ARGS
	Platform-overridden struct supporting graphics engine. More...

Macros
#define	GRAPHICS_ERROR_NOT_FOUND   -1
#define	GRAPHICS_INSTANCE_NONE   -1
#define	GRAPHICS_INSTANCE_WINDOW   -2
#define	GRAPHICS_INSTANCE_TILEMAP   -3
#define	GRAPHICS_FLAG_SHAKING_MASK   0x03
#define	GRAPHICS_FLAG_ZOOM_MASK   0x0c
#define	GRAPHICS_TXP_R   0xff
	Red value for transparency color in VGA DEPTH.
#define	GRAPHICS_TXP_G   0x55
	Green value for transparency color in VGA DEPTH.
#define	GRAPHICS_TXP_B   0xff
	Blue value for transparency color in VGA DEPTH.
#define	graphics_char_is_printable(c)   (('a' <= c && 'z' >= c) || ('A' <= c && 'Z' >= c) || ('0' <= c && '9' >= c) || '.' == c || ',' == c || ':' == c || ';' == c || '!' == c || '/' == c || ' ' == c)
#define	graphics_draw_char_outline(x, y, flags)   if( GRAPHICS_STRING_FLAG_OUTLINE == (GRAPHICS_STRING_FLAG_OUTLINE & flags) ) { graphics_draw_px( x, y, GRAPHICS_COLOR_BLACK ); }
#define	graphics_set_screen_shake(shake)   g_screen_flags &= ~GRAPHICS_FLAG_SHAKING_MASK; g_screen_flags |= (GRAPHICS_FLAG_SHAKING_MASK & shake);
#define	graphics_set_screen_zoom(zoom)   g_screen_flags &= ~GRAPHICS_FLAG_ZOOM_MASK; g_screen_flags |= (((zoom) << 2) & GRAPHICS_FLAG_ZOOM_MASK)
#define	graphics_clear_screen()    graphics_draw_block( 0, 0, SCREEN_W, SCREEN_H, GRAPHICS_COLOR_BLACK );
#define	graphics_clear_block(x, y, w, h)    graphics_draw_block( x, y, w, h, GRAPHICS_COLOR_BLACK );
	Erase a portion of the screen to black.

Typedefs
typedef int	GRAPHICS_COLOR
	Representation for specific colors on the current platform.

Functions
int16_t	graphics_init () SECTION_SETUP
void	graphics_shutdown () SECTION_SETUP
void	graphics_lock ()
void	graphics_release ()
	Draw the current graphics buffer on-screen.
uint32_t	graphics_get_ms ()
	Get the number of ticks since the program started.
void	graphics_loop_start ()
	Mark the beginning of rendering the current graphical frame.
void	graphics_loop_end ()
	Mark the end of rendering the current graphical frame.
void	graphics_draw_px (uint16_t x, uint16_t y, const GRAPHICS_COLOR color)
	Plot a discrete point on screen.
void	graphics_draw_block (uint16_t x_orig, uint16_t y_orig, uint16_t w, uint16_t h, const GRAPHICS_COLOR color)
	Draw a filled rectangle on screen.
void	graphics_draw_rect (uint16_t x_orig, uint16_t y_orig, uint16_t w, uint16_t h, uint16_t thickness, const GRAPHICS_COLOR color)
	Draw a hollowed rectangle on screen.
void	graphics_draw_line (uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2, uint16_t thickness, const GRAPHICS_COLOR color)
	Draw a line on screen.
void	graphics_char_at (char c, uint16_t x_orig, uint16_t y_orig, GRAPHICS_COLOR color, uint8_t flags)
	Draw a text character at the specified coordinates.
void	graphics_string_at (const char *str, uint16_t str_sz, uint16_t x_orig, uint16_t y_orig, GRAPHICS_COLOR color, uint8_t flags)
	Draw a text string on screen.
void	graphics_string_sz (const char *str, uint16_t str_sz, uint8_t flags, struct GRAPHICS_RECT *sz_out)
	Get width and height of a text string in pixels if drawn on screen.
int16_t	graphics_get_random (int16_t start, int16_t range)
	Get a random integer.
void	graphics_on_resize (int16_t new_w, int16_t new_h)

Variables
uint16_t	g_screen_real_w
uint16_t	g_screen_real_h
uint8_t	g_screen_flags

Detailed Description

Simple abstract unified graphics drawing layer designed for resource-constrained systems.

Macro Definition Documentation

graphics_clear_block

#define graphics_clear_block	(		x,
			y,
			w,
			h
	)		graphics_draw_block( x, y, w, h, GRAPHICS_COLOR_BLACK );

Erase a portion of the screen to black.

This may be overridden on certain platforms with more complicated graphics engines.

Warning

X and Y MUST be divisible by TILE_W and TILE_H, respectively.

Function Documentation

graphics_char_at()

void graphics_char_at	(	char	c,
		uint16_t	x_orig,
		uint16_t	y_orig,
		GRAPHICS_COLOR	color,
		uint8_t	flags
	)

Draw a text character at the specified coordinates.

Parameters

c	Text character to draw.
x_orig	X coordinate to draw at, in pixels.
y_orig	Y coordinate to draw at, in pixels.
color	Unilayer Graphics Colors in which to draw the character.
flags	Unilayer Graphics String Flags to modify how the string is displayed.

graphics_draw_block()

void graphics_draw_block	(	uint16_t	x_orig,
		uint16_t	y_orig,
		uint16_t	w,
		uint16_t	h,
		const GRAPHICS_COLOR	color
	)

Draw a filled rectangle on screen.

Parameters

x_orig	Horizontal coordinate of left side in pixels.
y_orig	Vertical coordinate of top side in pixels.
w	Width of rectangle in pixels.
h	Height of rectangle in pixels.
color	Unilayer Graphics Colors of the rectangle to draw.

This uses the platform's native methods to draw a line if available, or a general software emulation that relies on graphics_draw_px() if not.

graphics_draw_line()

void graphics_draw_line	(	uint16_t	x1,
		uint16_t	y1,
		uint16_t	x2,
		uint16_t	y2,
		uint16_t	thickness,
		const GRAPHICS_COLOR	color
	)

Draw a line on screen.

Parameters

x1	Horizontal coordinate of the starting point in pixels.
y1	Vertical coordinate of the starting point in pixels.
x2	Horizontal coordinate of the ending point in pixels.
y2	Vertical coordinate of the ending point in pixels.
thickness	Thickness of the line in pixels.
color	Unilayer Graphics Colors of the borders of the line to draw.

This uses the platform's native methods to draw a line if available, or a general software emulation that relies on graphics_draw_px() if not.

graphics_draw_px()

void graphics_draw_px	(	uint16_t	x,
		uint16_t	y,
		const GRAPHICS_COLOR	color
	)

Plot a discrete point on screen.

Parameters

x	Horizontal coordinate of point to plot.
y	Vertical coordinate of point to plot.
color	Unilayer Graphics Colors of the point to plot.

On some platforms, namely those using USE_SOFTWARE_TEXT and USE_SOFTWARE_LINES, this is the only primitive that must be defined in the implementation-specific module (e.g. nullg.h). Other primitives are then implemented using this (e.g. graphics_draw_line()).

graphics_draw_rect()

void graphics_draw_rect	(	uint16_t	x_orig,
		uint16_t	y_orig,
		uint16_t	w,
		uint16_t	h,
		uint16_t	thickness,
		const GRAPHICS_COLOR	color
	)

Draw a hollowed rectangle on screen.

Parameters

x_orig	Horizontal coordinate of left side in pixels.
y_orig	Vertical coordinate of top side in pixels.
w	Width of rectangle in pixels.
h	Height of rectangle in pixels.
thickness	Thickness of the rectangle border in pixels.
color	Unilayer Graphics Colors of the borders of the rectangle to draw.

This uses the platform's native methods to draw a line if available, or a general software emulation that relies on graphics_draw_px() if not.

graphics_get_ms()

uint32_t graphics_get_ms

(

)

Get the number of ticks since the program started.

Returns

A constantly increasing number of ticks since program start.

graphics_get_random()

int16_t graphics_get_random	(	int16_t	start,
		int16_t	range
	)

Get a random integer.

Parameters

start	Inclusive start of range.
range

Returns

Random integer higher than or equal to start and within range.

graphics_loop_end()

void graphics_loop_end

(

)

Mark the end of rendering the current graphical frame.

This should be called from the main loop, and is critical to maintaining timing.

graphics_loop_start()

void graphics_loop_start

(

)

Mark the beginning of rendering the current graphical frame.

This should be called from the main loop, and is critical to maintaining timing.

graphics_string_at()

void graphics_string_at	(	const char *	str,
		uint16_t	str_sz,
		uint16_t	x_orig,
		uint16_t	y_orig,
		GRAPHICS_COLOR	color,
		uint8_t	flags
	)

Draw a text string on screen.

Parameters

str	String to draw on-screen.
str_sz	Maximum length of the string in characters.
x_orig	Left origin of the string drawn in pixels.
y_orig	Top origin of the string drawn in pixels.
color	Unilayer Graphics Colors in which to draw the string.
flags	Unilayer Graphics String Flags to modify how the string is displayed.

graphics_string_sz()

void graphics_string_sz	(	const char *	str,
		uint16_t	str_sz,
		uint8_t	flags,
		struct GRAPHICS_RECT *	sz_out
	)

Get width and height of a text string in pixels if drawn on screen.

Parameters

str	String to get the dimensions for.
str_sz	Maximum length of the string in characters.
flags	String options.
sz_out	MEMORY_PTR to the GRAPHICS_RECT to hold the output size.