A simple interface to draw graphical primitives and images in a multi-threaded application. More...

Classes
struct	coord
	Holds a pixel co-ordinate. More...

Macros
#define	WINDOW_TITLE "FreeRTOS Emulator"

#define	SCREEN_WIDTH 640

#define	SCREEN_HEIGHT 480

Typedefs
typedef struct coord	coord_t
	Holds a pixel co-ordinate. More...

typedef void *	gfx_image_handle_t
	Handle used to reference loaded images, an invalid image will have a NULL handle. More...

typedef void *	gfx_animation_handle_t
	Handle used to reference a loaded animation spritesheet, an invalid spritesheet will have a NULL handle. More...

typedef void *	gfx_sequence_handle_t
	Returns an instance of an animation. More...

typedef void *	gfx_spritesheet_handle_t
	Returns an instance of a spritesheet. More...

Enumerations
enum	sprite_sequence_direction { SPRITE_SEQUENCE_HORIZONTAL_POS , SPRITE_SEQUENCE_HORIZONTAL_NEG , SPRITE_SEQUENCE_VERTICAL_POS , SPRITE_SEQUENCE_VERTICAL_NEG }
	Defines the direction that the animation appears on the spritesheet. More...

Functions
char *	gfxGetErrorMessage (void)
	Returns a string error message from the gfx_draw back end. More...

int	gfxDrawInit (char *path)
	Initializes the gfx_draw backend. More...

int	gfxDrawBindThread (void)
	Transfers the drawing ability to the calling thread/taskd. More...

void	gfxDrawExit (void)
	Exits the GFX Draw backend. More...

int	gfxDrawUpdateScreen (void)
	Executes the queued draw jobs. More...

int	gfxDrawClear (unsigned int colour)
	Sets the screen to a solid colour. More...

void	gfxDrawDuplicateBuffer (void)

int	gfxDrawEllipse (signed short x, signed short y, signed short rx, signed short ry, unsigned int colour)
	Draws an ellipse on the screen. More...

int	gfxDrawArc (signed short x, signed short y, signed short radius, signed short start, signed short end, unsigned int colour)
	Draws an arc on the screen. More...

int	gfxDrawText (char *str, signed short x, signed short y, unsigned int colour)
	Prints a string to the screen. More...

int	gfxGetTextSize (char str, int width, int *height)
	Finds the width and height of a strings bounding box. More...

int	gfxDrawCenteredText (char *str, signed short x, signed short y, unsigned int colour)
	Prints a string to the screen. More...

int	gfxDrawBox (signed short x, signed short y, signed short w, signed short h, unsigned int colour)
	Draws a filled box on the screen. More...

int	gfxDrawFilledBox (signed short x, signed short y, signed short w, signed short h, unsigned int colour)
	Draws an unfilled box on the screen. More...

int	gfxDrawCircle (signed short x, signed short y, signed short radius, unsigned int colour)
	Draws a filled circle on the screen. More...

int	gfxDrawLine (signed short x1, signed short y1, signed short x2, signed short y2, unsigned char thickness, unsigned int colour)
	Draws a line on the screen. More...

int	gfxDrawPoly (coord_t *points, int n, unsigned int colour)
	Draws a polygon on the screen. More...

int	gfxDrawTriangle (coord_t *points, unsigned int colour)
	Draws a triangle on the screen. More...

gfx_image_handle_t	gfxDrawLoadImage (char *filename)
	Loads an image file from disk, loaded image file can be closed using gfxDrawFreeLoadedImage() More...

gfx_image_handle_t	gfxDrawLoadScaledImage (char *filename, float scale)
	Loads an image from disk and scales the image, loaded image file can be closed using gfxDrawFreeLoadedImage(). Note that scaled images have large overheads compared to manually scaled images (changing image file's dimensions) More...

int	gfxDrawFreeLoadedImage (gfx_image_handle_t *img)
	Closes a loaded image and frees all memory used by the image structure. More...

int	gfxDrawSetLoadedImageScale (gfx_image_handle_t img, float scale)
	Scales a loaded image, the scale is a value where, for example, 1.0 represents the original image's size. The scaling factor scales the image relative to the image file's dimensions on disk. More...

float	gfxDrawGetLoadedImageScale (gfx_image_handle_t img)
	Retrieves the current scaling factor of an image. More...

int	gfxDrawGetLoadedImageWidth (gfx_image_handle_t img)
	Retrieves the image's width when drawn to screen, ie. after scaling. More...

int	gfxDrawGetLoadedImageHeight (gfx_image_handle_t img)
	Retrieves the image's height when drawn to screen, ie. after scaling. More...

int	gfxDrawGetLoadedImageSize (gfx_image_handle_t img, int w, int h)
	Retrieves bother the image's width and height when drawn to screen, ie. after scaling. More...

int	gfxDrawLoadedImage (gfx_image_handle_t img, signed short x, signed short y)
	Draws a loaded image to the screen. More...

int	gfxDrawImage (char *filename, signed short x, signed short y)
	Draws an image on the screen. More...

gfx_spritesheet_handle_t	gfxDrawLoadSpritesheetFromEntireImageUnpadded (gfx_image_handle_t img, unsigned sprite_cols, unsigned sprite_rows)
	Creates a spritesheet object from a loaded image where each sprite is not padded and the sprite sheet is divided into an number of equal sized rows and columns. More...

gfx_spritesheet_handle_t	gfxDrawLoadSpritesheetFromEntireImagePadded (gfx_image_handle_t img, unsigned sprite_cols, unsigned sprite_rows, unsigned sprite_padding_x, unsigned sprite_padding_y)
	Creates a spritesheet object from a loaded image where sprites are padded. More...

gfx_spritesheet_handle_t	gfxDrawLoadSpritesheetFromEntireImagePaddedSpacing (gfx_image_handle_t img, unsigned sprite_cols, unsigned sprite_rows, unsigned sprite_spacing_x, unsigned sprite_spacing_y)
	Creates a spritesheet object from a loaded image where sprites are padded. More...

gfx_spritesheet_handle_t	gfxDrawLoadSpritesheetFromPortionOfImageUnpadded (gfx_image_handle_t img, unsigned sprite_cols, unsigned sprite_rows, unsigned sprite_width, unsigned sprite_height, unsigned bounding_box_left_x_pixel, unsigned bounding_box_top_y_pixel)
	Creates a spritesheet object from a portion of a loaded image where sprites are unpadded. More...

gfx_spritesheet_handle_t	gfxDrawLoadSpritesheetFromPortionOfImagePadded (gfx_image_handle_t img, unsigned sprite_cols, unsigned sprite_rows, unsigned sprite_width, unsigned sprite_height, unsigned sprite_padding_x, unsigned sprite_padding_y, unsigned bounding_box_left_x_pixel, unsigned bounding_box_top_y_pixel)
	Creates a spritesheet object from a portion of loaded image where sprites are padded. More...

gfx_spritesheet_handle_t	gfxDrawLoadSpritesheetFromPortionOfImagePaddedSpacing (gfx_image_handle_t img, unsigned sprite_cols, unsigned sprite_rows, unsigned sprite_width, unsigned sprite_height, unsigned sprite_spacing_x, unsigned sprite_spacing_y, unsigned bounding_box_left_x_pixel, unsigned bounding_box_top_y_pixel)
	Creates a spritesheet object from a portion of loaded image where sprites are padded. More...

int	gfxDrawSprite (gfx_spritesheet_handle_t spritesheet, char column, char row, signed short x, signed short y)
	Draws a sprite from a spritesheet. More...

int	gfxGetImageSize (char filename, int w, int *h)
	Gets the width and height of an image. More...

int	gfxDrawScaledImage (char *filename, signed short x, signed short y, float scale)
	Draws a scaled image on the screen. More...

int	gfxDrawArrow (signed short x1, signed short y1, signed short x2, signed short y2, signed short head_length, unsigned char thickness, unsigned int colour)
	Draws an arrow on the screen. More...

gfx_animation_handle_t	gfxDrawAnimationCreate (gfx_spritesheet_handle_t spritesheet)
	Creates an animation object with an attached spritesheet that must be loaded prior as an image. More...

int	gfxDrawAnimationAddSequence (gfx_animation_handle_t animation, char *name, unsigned start_row, unsigned start_col, enum sprite_sequence_direction sprite_step_direction, unsigned frames)
	Adds an animation sequence to a previously created animation. More...

gfx_sequence_handle_t	gfxDrawAnimationSequenceInstantiate (gfx_animation_handle_t animation, char *sequence_name, unsigned frame_period_ms)
	Creates an instance of an animation from a loaded animation object and a sequence name of a sequence previously added to the animation object. More...

void	gfxDrawAnimationReset (gfx_sequence_handle_t sequence)
	Resets the time and frame of an animation back to its initial configuration. More...

int	gfxDrawAnimationDrawFrame (gfx_sequence_handle_t sequence, unsigned ms_timestep, int x, int y)
	Draws the target intantiated animation sequence at a given location. More...

int	gfxDrawSetGlobalXOffset (int offset)
	Sets the global draw position offset's X axis value. More...

int	gfxDrawSetGlobalYOffset (int offset)
	Sets the global draw position offset's Y axis value. More...

int	gfxDrawGetGlobalXOffset (int *offset)
	Retrieves a copy of the current global X axis drawing offset. More...

int	gfxDrawGetGlobalYOffset (int *offset)
	Retrieves a copy of the current global X axis drawing offset. More...

Hex RGB colours
RRGGBB colours used by GFX Draw backend, colour standard is the same as the common html standard
#define	TUMBlue (unsigned int)(0x0065bd)

#define	Red (unsigned int)(0xFF0000)

#define	Green (unsigned int)(0x00FF00)

#define	Blue (unsigned int)(0x0000FF)

#define	Yellow (unsigned int)(0xFFFF00)

#define	Aqua (unsigned int)(0x00FFFF)

#define	Fuchsia (unsigned int)(0xFF00FF)

#define	White (unsigned int)(0xFFFFFF)

#define	Black (unsigned int)(0x000000)

#define	Gray (unsigned int)(0x808080)

#define	Grey Gray

#define	Magenta Fuchsia

#define	Cyan Aqua

#define	Lime (unsigned int)(0x00FF00)

#define	Maroon (unsigned int)(0x800000)

#define	Navy (unsigned int)(0x000080)

#define	Olive (unsigned int)(0x808000)

#define	Purple (unsigned int)(0x800080)

#define	Silver (unsigned int)(0xC0C0C0)

#define	Teal (unsigned int)(0x008080)

#define	Orange (unsigned int)(0xFFA500)

#define	Pink (unsigned int)(0xFFC0CB)

#define	Skyblue (unsigned int)(0x87CEEB)

Detailed Description

A simple interface to draw graphical primitives and images in a multi-threaded application.

This API allows for the creation of various draw jobs and image management that enables thread-safe drawing using the inherently single-threaded SDL2 graphics library.

Macro Definition Documentation

◆ Aqua

#define Aqua (unsigned int)(0x00FFFF)

◆ Black

#define Black (unsigned int)(0x000000)

◆ Blue

#define Blue (unsigned int)(0x0000FF)

◆ Cyan

#define Cyan Aqua

◆ Fuchsia

#define Fuchsia (unsigned int)(0xFF00FF)

◆ Gray

#define Gray (unsigned int)(0x808080)

◆ Green

#define Green (unsigned int)(0x00FF00)

◆ Grey

#define Grey Gray

◆ Lime

#define Lime (unsigned int)(0x00FF00)

◆ Magenta

#define Magenta Fuchsia

◆ Maroon

#define Maroon (unsigned int)(0x800000)

◆ Navy

#define Navy (unsigned int)(0x000080)

◆ Olive

#define Olive (unsigned int)(0x808000)

◆ Orange

#define Orange (unsigned int)(0xFFA500)

◆ Pink

#define Pink (unsigned int)(0xFFC0CB)

◆ Purple

#define Purple (unsigned int)(0x800080)

◆ Red

#define Red (unsigned int)(0xFF0000)

◆ SCREEN_HEIGHT

#define SCREEN_HEIGHT 480

Sets the height (in pixels) of the screen

◆ SCREEN_WIDTH

#define SCREEN_WIDTH 640

Sets the width (in pixels) of the screen

◆ Silver

#define Silver (unsigned int)(0xC0C0C0)

◆ Skyblue

#define Skyblue (unsigned int)(0x87CEEB)

◆ Teal

#define Teal (unsigned int)(0x008080)

◆ TUMBlue

#define TUMBlue (unsigned int)(0x0065bd)

◆ White

#define White (unsigned int)(0xFFFFFF)

◆ WINDOW_TITLE

#define WINDOW_TITLE "FreeRTOS Emulator"

The string that is shown on the window's status bar

◆ Yellow

#define Yellow (unsigned int)(0xFFFF00)

Typedef Documentation

◆ coord_t

typedef struct coord coord_t

Holds a pixel co-ordinate.

◆ gfx_animation_handle_t

typedef void* gfx_animation_handle_t

Handle used to reference a loaded animation spritesheet, an invalid spritesheet will have a NULL handle.

Sprite sheets are loaded as images and contain many individua sprites that are cycled to make animations. Thus a sequence of frames must be defined using gfxDrawAnimationAddSequence() and this must be added to an animation that has been created by passing in a loaded sprite sheet.

◆ gfx_image_handle_t

typedef void* gfx_image_handle_t

Handle used to reference loaded images, an invalid image will have a NULL handle.

◆ gfx_sequence_handle_t

typedef void* gfx_sequence_handle_t

Returns an instance of an animation.

After an animation has been created and a sequence added, an instance of the sequence must be created. This allows for the same animation sequence to be run within the same frame.

◆ gfx_spritesheet_handle_t

typedef void* gfx_spritesheet_handle_t

Returns an instance of a spritesheet.

A grid of images make up a sprite sheet, drawing partiular sprites can then be done by simply specifying the column and row of the particular image.

Enumeration Type Documentation

◆ sprite_sequence_direction

enum sprite_sequence_direction

Defines the direction that the animation appears on the spritesheet.

Enumerator
SPRITE_SEQUENCE_HORIZONTAL_POS
SPRITE_SEQUENCE_HORIZONTAL_NEG
SPRITE_SEQUENCE_VERTICAL_POS
SPRITE_SEQUENCE_VERTICAL_NEG

Function Documentation

◆ gfxDrawAnimationAddSequence()

int gfxDrawAnimationAddSequence	(	gfx_animation_handle_t	animation,
		char *	name,
		unsigned	start_row,
		unsigned	start_col,
		enum sprite_sequence_direction	sprite_step_direction,
		unsigned	frames
	)

Adds an animation sequence to a previously created animation.

An animation is the combination of a sprite sheet and one of more sequences. Sequences detail how the spritesheet should be parsed, in accordance to time, to create a desired animation. Thus after creating an animation (with an appropriate spritesheet) one or more sequences must be added to the animation in order for the animation to be able to render actual animations.

Parameters

animation	Handle to the prviously created animation object
name	Ascii name to be given to the sequence. Used to reference the sequence
start_row	The row at which the start sprite can be found (0 indexed)
start_col	The col at which the start sprite can be found (0 indexed)
sprite_step_direction	Defines the direction with which the sprite frames can be found on the spritesheet
frames	The number of sprite frames that make up the animation

Returns: 0 on success

◆ gfxDrawAnimationCreate()

gfx_animation_handle_t gfxDrawAnimationCreate ( gfx_spritesheet_handle_t spritesheet )

Creates an animation object with an attached spritesheet that must be loaded prior as an image.

Parameters

spritesheet The loaded image that contains the spritesheet

Returns: A handle to the created animation object

◆ gfxDrawAnimationDrawFrame()

int gfxDrawAnimationDrawFrame	(	gfx_sequence_handle_t	sequence,
		unsigned	ms_timestep,
		int	x,
		int	y
	)

Draws the target intantiated animation sequence at a given location.

Animation sequences update which frame to show based upon how much time has passed since they were last rendered. This is tracked incrementally and as such each call to this function should pass in the number of milliseconds that has transpired since the last call to gfxDrawAnimationDrawFrame() so that the sprite frame can be selected appropriately.

Parameters

sequence	Sequence instance that is to be rendered
ms_timestep	The number of milliseconds that have transpired since the last call to this function for the given animation sequence
x	The X axis location, in pixels, refernced from the top left of the sprite frame
y	The Y axis location, in pixels, refernced from the top left of the sprite frame

Returns: 0 on success

◆ gfxDrawAnimationReset()

void gfxDrawAnimationReset ( gfx_sequence_handle_t sequence )

Resets the time and frame of an animation back to its initial configuration.

Parameters

sequence Animation sequence that should be reset

◆ gfxDrawAnimationSequenceInstantiate()

gfx_sequence_handle_t gfxDrawAnimationSequenceInstantiate	(	gfx_animation_handle_t	animation,
		char *	sequence_name,
		unsigned	frame_period_ms
	)

Creates an instance of an animation from a loaded animation object and a sequence name of a sequence previously added to the animation object.

Parameters

animation	The animation object countaining the target spritesheet and animation sequence
sequence_name	Ascii string name of the sequence to be instantiated
frame_period_ms	The number of milliseconds that should transpire between sprite frames

Returns: A handle to the instantiated animation sequence, NULL otherwise

◆ gfxDrawArc()

int gfxDrawArc	(	signed short	x,
		signed short	y,
		signed short	radius,
		signed short	start,
		signed short	end,
		unsigned int	colour
	)

Draws an arc on the screen.

Draws an arc on the screen, the arc is determined from the starting and ending angles.

Parameters

x	X coordinate of the center of the arc
y	Y coordinate of the cente of the arc
radius	Radius of the arc in pixels
start	Starting radius of the arc, 0 degrees is down
end	Ending radius of the arc, 0 degrees is down
colour	RGB colour of the arc

Returns: 0 on success

◆ gfxDrawArrow()

int gfxDrawArrow	(	signed short	x1,
		signed short	y1,
		signed short	x2,
		signed short	y2,
		signed short	head_length,
		unsigned char	thickness,
		unsigned int	colour
	)

Draws an arrow on the screen.

Parameters

x1	X coordinate of the tail of the arrow
y1	Y coordinate of the tail of the arrow
x2	X coordinate of the head of the arrow
y2	Y coordinate of the head of the arrow
head_length	Length in pixels of the arrow's head
thickness	Thickness in pixels of the arrow's lines
colour	RGB colour of the ellipse

Returns: 0 on success

◆ gfxDrawBindThread()

int gfxDrawBindThread ( void )

Transfers the drawing ability to the calling thread/taskd.

Returns: 0 on success

◆ gfxDrawBox()

int gfxDrawBox	(	signed short	x,
		signed short	y,
		signed short	w,
		signed short	h,
		unsigned int	colour
	)

Draws a filled box on the screen.

Parameters

x	X coordinate of the top left point of the box
y	Y coordinate of the top left point of the box
w	Width of the box
h	Height of the box
colour	RGB colour of the box

Returns: 0 on success

◆ gfxDrawCenteredText()

int gfxDrawCenteredText	(	char *	str,
		signed short	x,
		signed short	y,
		unsigned int	colour
	)

Prints a string to the screen.

The given string is printed in the given colour centered at the location x,y. The location is centered at the center of the text.

Parameters

str	String to print
x	X coordinate of the middle of the text's bounding box
y	Y coordinate of the middle of the text's bounding box
colour	RGB colour of the text

Returns: 0 on success

◆ gfxDrawCircle()

int gfxDrawCircle	(	signed short	x,
		signed short	y,
		signed short	radius,
		unsigned int	colour
	)

Draws a filled circle on the screen.

Parameters

x	X coordinate of the center of the circle
y	Y coordinate of the center of the circle
radius	Radius of the circle in pixels
colour	RGB colour of the ellipse

Returns: 0 on success

◆ gfxDrawClear()

int gfxDrawClear ( unsigned int colour )

Sets the screen to a solid colour.

Parameters

colour RGB colour to fill the screen with

Returns: 0 on success

◆ gfxDrawDuplicateBuffer()

void gfxDrawDuplicateBuffer ( void )

◆ gfxDrawEllipse()

int gfxDrawEllipse	(	signed short	x,
		signed short	y,
		signed short	rx,
		signed short	ry,
		unsigned int	colour
	)

Draws an ellipse on the screen.

Parameters

x	X coordinate of the center of the ellipse
y	Y coordinate of the cente of the ellipse
rx	Horizontal radius in pixels
ry	Vertical radius in pixels
colour	RGB colour of the ellipse

Returns: 0 on success

◆ gfxDrawExit()

void gfxDrawExit ( void )

Exits the GFX Draw backend.

◆ gfxDrawFilledBox()

int gfxDrawFilledBox	(	signed short	x,
		signed short	y,
		signed short	w,
		signed short	h,
		unsigned int	colour
	)

Draws an unfilled box on the screen.

Parameters

x	X coordinate of the top left point of the box
y	Y coordinate of the top left point of the box
w	Width of the box
h	Height of the box
colour	RGB colour of the filled box

Returns: 0 on success

◆ gfxDrawFreeLoadedImage()

int gfxDrawFreeLoadedImage ( gfx_image_handle_t * img )

Closes a loaded image and frees all memory used by the image structure.

Parameters

img	Handle to the loaded image

Returns: 0 on success

◆ gfxDrawGetGlobalXOffset()

int gfxDrawGetGlobalXOffset ( int * offset )

Retrieves a copy of the current global X axis drawing offset.

Parameters

offset Refernce to the int where the value should be stored

Returns: 0 on success

◆ gfxDrawGetGlobalYOffset()

int gfxDrawGetGlobalYOffset ( int * offset )

Retrieves a copy of the current global X axis drawing offset.

Parameters

offset Refernce to the int where the value should be stored

Returns: 0 on success

◆ gfxDrawGetLoadedImageHeight()

int gfxDrawGetLoadedImageHeight ( gfx_image_handle_t img )

Retrieves the image's height when drawn to screen, ie. after scaling.

Parameters

img	Handle to the image for which the height is to be retrieved

Returns: Height of the image in pixels

◆ gfxDrawGetLoadedImageScale()

float gfxDrawGetLoadedImageScale ( gfx_image_handle_t img )

Retrieves the current scaling factor of an image.

Parameters

img	Handle to the image for which the scaling factor is to be retrieved

Returns: Current scaling factor

◆ gfxDrawGetLoadedImageSize()

int gfxDrawGetLoadedImageSize	(	gfx_image_handle_t	img,
		int *	w,
		int *	h
	)

Retrieves bother the image's width and height when drawn to screen, ie. after scaling.

Parameters

img	Handle to the image of interest
w	Reference to the variable to store the retrieved width
h	Reference to the variable to store the retrieved height

Returns: 0 on success

◆ gfxDrawGetLoadedImageWidth()

int gfxDrawGetLoadedImageWidth ( gfx_image_handle_t img )

Retrieves the image's width when drawn to screen, ie. after scaling.

Parameters

img	Handle to the image for which the width is to be retrieved

Returns: Width of the image in pixels

◆ gfxDrawImage()

int gfxDrawImage	(	char *	filename,
		signed short	x,
		signed short	y
	)

Draws an image on the screen.

Parameters

filename	Filename of the image to be drawn
x	X coordinate of the top left corner of the image
y	Y coordinate of the top left corner of the image

Returns: 0 on success

◆ gfxDrawInit()

int gfxDrawInit ( char * path )

Initializes the gfx_draw backend.

Parameters

path	Path to the folder's location where the program's binary is located

Returns: 0 on success

◆ gfxDrawLine()

int gfxDrawLine	(	signed short	x1,
		signed short	y1,
		signed short	x2,
		signed short	y2,
		unsigned char	thickness,
		unsigned int	colour
	)

Draws a line on the screen.

Parameters

x1	X coordinate of the starting point of the line
y1	Y coordinate of the starting point of the line
x2	X coordinate of the starting point of the line
y2	x coordinate of the starting point of the line
thickness	The thickness of the line in pixels
colour	RGB colour of the ellipse

Returns: 0 on success

◆ gfxDrawLoadedImage()

int gfxDrawLoadedImage	(	gfx_image_handle_t	img,
		signed short	x,
		signed short	y
	)

Draws a loaded image to the screen.

Parameters

img	Handle to the image to be drawn to the screen
x	X coordinate of the top left corner of the image
y	Y coordinate of the top left corner of the image

Returns: 0 on success

◆ gfxDrawLoadImage()

gfx_image_handle_t gfxDrawLoadImage ( char * filename )

Loads an image file from disk, loaded image file can be closed using gfxDrawFreeLoadedImage()

Resources are searched for inside the RESOURCES_DIRECTORY, specified in EmulatorConfig.h, otherwise realtive or absolute filepaths can be give. Relative paths are relative to the executed binary's location on the file system

Parameters

filename Name of the image file to be loaded

Returns: Returns a gfx_image_handle_t handle to the image

◆ gfxDrawLoadScaledImage()

gfx_image_handle_t gfxDrawLoadScaledImage	(	char *	filename,
		float	scale
	)

Loads an image from disk and scales the image, loaded image file can be closed using gfxDrawFreeLoadedImage(). Note that scaled images have large overheads compared to manually scaled images (changing image file's dimensions)

See gfxDrawLoadImage() for information on filenames.

Parameters

filename	Name of the image file to be loaded
scale	Scaling factor with which the image should be drawn

Returns: Returns a gfx_image_handle_t handle to the image

◆ gfxDrawLoadSpritesheetFromEntireImagePadded()

gfx_spritesheet_handle_t gfxDrawLoadSpritesheetFromEntireImagePadded	(	gfx_image_handle_t	img,
		unsigned	sprite_cols,
		unsigned	sprite_rows,
		unsigned	sprite_padding_x,
		unsigned	sprite_padding_y
	)

Creates a spritesheet object from a loaded image where sprites are padded.

Creates a spritesheet and returns a handle to the spritesheet, requires the sprite sheet to be evenly divisable by a number of columns and rows, where each entry contains padding around the sprite. Eg. if your source image is 200 pixels wide and 20 pixels high, containing ten 20x20 sprites, then you must specify that there are 10 sprite columns and 1 row.

The padding size is specified as the number of pixels around each sprite on the X and Y, if you would rather just specify the spacing between each image then use, gfxDrawLoadSpritesheetFromEntireImagePadded

Parameters

img	Loaded image to be used as the sprite sheet
sprite_cols	Number of columns on the sprite sheet
sprite_rows	Number of rows on the sprite sheet
sprite_padding_x	Number of pixels padding each sprite on one edge on the X axis
sprite_padding_y	Number of pixels padding each sprite on one edge on the Y axis

Returns: None NULL handle to reference spritesheet object

◆ gfxDrawLoadSpritesheetFromEntireImagePaddedSpacing()

gfx_spritesheet_handle_t gfxDrawLoadSpritesheetFromEntireImagePaddedSpacing	(	gfx_image_handle_t	img,
		unsigned	sprite_cols,
		unsigned	sprite_rows,
		unsigned	sprite_spacing_x,
		unsigned	sprite_spacing_y
	)

Creates a spritesheet object from a loaded image where sprites are padded.

Creates a spritesheet and returns a handle to the spritesheet, requires the sprite sheet to be evenly divisable by a number of columns and rows, where each entry contains padding around the sprite. Eg. if your source image is 200 pixels wide and 20 pixels high, containing ten 20x20 sprites, then you must specify that there are 10 sprite columns and 1 row.

It is assumed here that half the spacing can be found as padding around sprites bordering the edge of the sprite sheet. If this is not the case, it is reccomended to modify your sprite sheet to add appropriate padding.

Parameters

img	Loaded image to be used as the sprite sheet
sprite_cols	Number of columns on the sprite sheet
sprite_rows	Number of rows on the sprite sheet
sprite_spacing_x	Spacing, in pixels, between images on the X axis
sprite_spacing_y	Spacing, in pixels, between images on the Y axis

Returns: None NULL handle to reference spritesheet object

◆ gfxDrawLoadSpritesheetFromEntireImageUnpadded()

gfx_spritesheet_handle_t gfxDrawLoadSpritesheetFromEntireImageUnpadded	(	gfx_image_handle_t	img,
		unsigned	sprite_cols,
		unsigned	sprite_rows
	)

Creates a spritesheet object from a loaded image where each sprite is not padded and the sprite sheet is divided into an number of equal sized rows and columns.

Creates a spritesheet and returns a handle to the spritesheet, requires the sprite sheet to be evenly divisable by a number of columns and rows. Eg. if your source image is 200 pixels wide and 20 pixels high, containing ten 20x20 sprites, then you must specify that there are 10 sprite columns and 1 row. If your sprite sequence is part of a large and less sorted sprite sheet, or had image padding, see the other LoadSpritesheet functions.

Parameters

img	Loaded image to be used as the sprite sheet
sprite_cols	Number of columns on the sprite sheet
sprite_rows	Number of rows on the sprite sheet

Returns: None NULL handle to reference spritesheet object

◆ gfxDrawLoadSpritesheetFromPortionOfImagePadded()

gfx_spritesheet_handle_t gfxDrawLoadSpritesheetFromPortionOfImagePadded	(	gfx_image_handle_t	img,
		unsigned	sprite_cols,
		unsigned	sprite_rows,
		unsigned	sprite_width,
		unsigned	sprite_height,
		unsigned	sprite_padding_x,
		unsigned	sprite_padding_y,
		unsigned	bounding_box_left_x_pixel,
		unsigned	bounding_box_top_y_pixel
	)

Creates a spritesheet object from a portion of loaded image where sprites are padded.

Creates a spritesheet and returns a handle to the spritesheet, the sprite sheet here is assumed to be a mix of sprite sequences, as such you can create a spritesheet that specifies a portion of the image where a sprite sequence is contained. Assumed here is that the sprites are padded.

Parameters

img	Loaded image to be used as the sprite sheet
sprite_cols	Number of columns on the sprite sheet
sprite_rows	Number of rows on the sprite sheet
sprite_width	Width, in pixels, of each sprite
sprite_height	Height, in pixels, of each sprite
sprite_padding_x	Number of pixels padding each sprite on one edge on the X axis
sprite_padding_y	Number of pixels padding each sprite on one edge on the Y axis
bounding_box_left_x_pixel	The X pixel location of the bounding box, bounding the portion of the image to be used, starts (top left point) NOTE: this location should be the start of the first sprite, without padding!
bounding_box_top_y_pixel	The Y pixel location where the bounding box, bounding the portion of the image to be used, starts (top left point) NOTE: this location should be the start of the first sprite, without padding!

Returns: None NULL handle to reference spritesheet object

◆ gfxDrawLoadSpritesheetFromPortionOfImagePaddedSpacing()

gfx_spritesheet_handle_t gfxDrawLoadSpritesheetFromPortionOfImagePaddedSpacing	(	gfx_image_handle_t	img,
		unsigned	sprite_cols,
		unsigned	sprite_rows,
		unsigned	sprite_width,
		unsigned	sprite_height,
		unsigned	sprite_spacing_x,
		unsigned	sprite_spacing_y,
		unsigned	bounding_box_left_x_pixel,
		unsigned	bounding_box_top_y_pixel
	)

Creates a spritesheet object from a portion of loaded image where sprites are padded.

Creates a spritesheet and returns a handle to the spritesheet, the sprite sheet here is assumed to be a mix of sprite sequences, as such you can create a spritesheet that specifies a portion of the image where a sprite sequence is contained. Assumed here is that the sprites are padded.

It is assumed here that half the spacing can be found as padding around sprites bordering the edge of the sprite sheet. If this is not the case, it is reccomended to modify your sprite sheet to add appropriate padding.

Parameters

img	Loaded image to be used as the sprite sheet
sprite_cols	Number of columns on the sprite sheet
sprite_rows	Number of rows on the sprite sheet
sprite_width	Width, in pixels, of each sprite
sprite_height	Height, in pixels, of each sprite
sprite_spacing_x	Spacing, in pixels, between images on the X axis
sprite_spacing_y	Spacing, in pixels, between images on the Y axis
bounding_box_left_x_pixel	The X pixel location of the bounding box, bounding the portion of the image to be used, starts (top left point). NOTE: this location should be the start of the first sprite, without padding!
bounding_box_top_y_pixel	The Y pixel location where the bounding box, bounding the portion of the image to be used, starts (top left point) NOTE: this location should be the start of the first sprite, without padding!

Returns: None NULL handle to reference spritesheet object

◆ gfxDrawLoadSpritesheetFromPortionOfImageUnpadded()

gfx_spritesheet_handle_t gfxDrawLoadSpritesheetFromPortionOfImageUnpadded	(	gfx_image_handle_t	img,
		unsigned	sprite_cols,
		unsigned	sprite_rows,
		unsigned	sprite_width,
		unsigned	sprite_height,
		unsigned	bounding_box_left_x_pixel,
		unsigned	bounding_box_top_y_pixel
	)

Creates a spritesheet object from a portion of a loaded image where sprites are unpadded.

Creates a spritesheet and returns a handle to the spritesheet, the sprite sheet here is assumed to be a mix of sprite sequences, as such you can create a spritesheet that specifies a portion of the image where a sprite sequence is contained. Assumed here is that the sprites are unpadded.

Parameters

img	Loaded image to be used as the sprite sheet
sprite_cols	Number of columns on the sprite sheet
sprite_rows	Number of rows on the sprite sheet
sprite_width	Width, in pixels, of each sprite
sprite_height	Height, in pixels, of each sprite
bounding_box_left_x_pixel	The X pixel location of the bounding box, bounding the portion of the image to be used, starts (top left point) NOTE: this location should be the start of the first sprite, without padding!
bounding_box_top_y_pixel	The Y pixel location where the bounding box, bounding the portion of the image to be used, starts (top left point) NOTE: this location should be the start of the first sprite, without padding!

Returns: None NULL handle to reference spritesheet object

◆ gfxDrawPoly()

int gfxDrawPoly	(	coord_t *	points,
		int	n,
		unsigned int	colour
	)

Draws a polygon on the screen.

Drawing a polygon requires an array of points, each given by a coord. The number of points passed through in the coord array must also be passed to the function.

Parameters

points	Points array specifying each point in the polygon
n	Number of points in the points array
colour	RGB colour of the ellipse

Returns: 0 on success

◆ gfxDrawScaledImage()

int gfxDrawScaledImage	(	char *	filename,
		signed short	x,
		signed short	y,
		float	scale
	)

Draws a scaled image on the screen.

Parameters

filename	Filename of the image to be drawn
x	X coordinate of the top left corner of the image
y	Y coordinate of the top left corner of the image
scale	The scale factor of the image

Returns: 0 on success

◆ gfxDrawSetGlobalXOffset()

int gfxDrawSetGlobalXOffset ( int offset )

Sets the global draw position offset's X axis value.

Parameters

offset Value in pixels that all drawing should be offset on the X axis

Returns: 0 on success

◆ gfxDrawSetGlobalYOffset()

int gfxDrawSetGlobalYOffset ( int offset )

Sets the global draw position offset's Y axis value.

Parameters

offset Value in pixels that all drawing should be offset on the X axis

Returns: 0 on success

◆ gfxDrawSetLoadedImageScale()

int gfxDrawSetLoadedImageScale	(	gfx_image_handle_t	img,
		float	scale
	)

Scales a loaded image, the scale is a value where, for example, 1.0 represents the original image's size. The scaling factor scales the image relative to the image file's dimensions on disk.

Parameters

img	Handle to the image to be scaled
scale	Scaling factor to be applied to the image file

Returns: 0 on success

◆ gfxDrawSprite()

int gfxDrawSprite	(	gfx_spritesheet_handle_t	spritesheet,
		char	column,
		char	row,
		signed short	x,
		signed short	y
	)

Draws a sprite from a spritesheet.

Parameters

spritesheet	Spritesheet to be drawn from
column	Column on the sprite sheet where the target sprite is located
row	Row on the sprite sheet where the target sprite is located
x	X coordinate where the sprite should be drawn on the screen
y	Y coordinate where the sprite should be drawn on the screen

Returns: 0 on success

◆ gfxDrawText()

int gfxDrawText	(	char *	str,
		signed short	x,
		signed short	y,
		unsigned int	colour
	)

Prints a string to the screen.

The given string is printed in the given colour at the location x,y. The location is referenced from the top left corner of the strings bounding box.

Parameters

str	String to print
x	X coordinate of the top left point of the text's bounding box
y	Y coordinate of the top left point of the text's bounding box
colour	RGB colour of the text

Returns: 0 on success

◆ gfxDrawTriangle()

int gfxDrawTriangle	(	coord_t *	points,
		unsigned int	colour
	)

Draws a triangle on the screen.

Parameters

points	Points array giving the three corner points of the triangle
colour	RGB colour of the ellipse

Returns: 0 on success

◆ gfxDrawUpdateScreen()

int gfxDrawUpdateScreen ( void )

Executes the queued draw jobs.

The gfx_draw primative draw functions are designed to be callable from any thread, as such each function queues a draw job into a queue. Once gfxDrawUpdateScreen is called, the queued draw jobs are executed by the background SDL thread.

While primitive drawing functions, such as gfxDrawCircle(), are thread-safe calls to gfxDrawUpdateScreen() must come from the thread that holds the GL (graphics layer) context. A thread can obtain the GL context by calling gfxDrawBindThread(). Please be wary that gfxDrawBindThread() has a large overhead and should be avoided when possible. Having a centeralized screen updating thread is a good solution to this problem. Calls to GL context dependent calls, such as gfxDrawUpdateScreen() will fail if the calling thread does not hold the GL context.

Returns: 0 on success

◆ gfxGetErrorMessage()

char* gfxGetErrorMessage ( void )

Returns a string error message from the gfx_draw back end.

Returns: String holding the most recent gfx_draw error message

◆ gfxGetImageSize()

int gfxGetImageSize	(	char *	filename,
		int *	w,
		int *	h
	)

Gets the width and height of an image.

Parameters

filename	Image filename to be tested
w	Integer where the width shall be stored
h	Integer where the height shall be stored

Returns: 0 on sucess

◆ gfxGetTextSize()

int gfxGetTextSize	(	char *	str,
		int *	width,
		int *	height
	)

Finds the width and height of a strings bounding box.

Parameters

str	String who's bounding box size is required
width	Integer where the width shall be stored
height	Integer where the height shall be stored

Returns: 0 on success

Classes

Macros

Typedefs

Enumerations

Functions

Hex RGB colours

Detailed Description

Macro Definition Documentation

◆ Aqua

◆ Black

◆ Blue

◆ Cyan

◆ Fuchsia

◆ Gray

◆ Green

◆ Grey

◆ Lime

◆ Magenta

◆ Maroon

◆ Navy

◆ Olive

◆ Orange

◆ Pink

◆ Purple

◆ Red

◆ SCREEN_HEIGHT

◆ SCREEN_WIDTH

◆ Silver

◆ Skyblue

◆ Teal

◆ TUMBlue

◆ White

◆ WINDOW_TITLE

◆ Yellow

Typedef Documentation

◆ coord_t

◆ gfx_animation_handle_t

◆ gfx_image_handle_t

◆ gfx_sequence_handle_t

◆ gfx_spritesheet_handle_t

Enumeration Type Documentation

◆ sprite_sequence_direction

Function Documentation

◆ gfxDrawAnimationAddSequence()

◆ gfxDrawAnimationCreate()

◆ gfxDrawAnimationDrawFrame()

◆ gfxDrawAnimationReset()

◆ gfxDrawAnimationSequenceInstantiate()

◆ gfxDrawArc()

◆ gfxDrawArrow()

◆ gfxDrawBindThread()

◆ gfxDrawBox()

◆ gfxDrawCenteredText()

◆ gfxDrawCircle()

◆ gfxDrawClear()

◆ gfxDrawDuplicateBuffer()

◆ gfxDrawEllipse()

◆ gfxDrawExit()

◆ gfxDrawFilledBox()

◆ gfxDrawFreeLoadedImage()

◆ gfxDrawGetGlobalXOffset()

◆ gfxDrawGetGlobalYOffset()

◆ gfxDrawGetLoadedImageHeight()

◆ gfxDrawGetLoadedImageScale()

◆ gfxDrawGetLoadedImageSize()

◆ gfxDrawGetLoadedImageWidth()

◆ gfxDrawImage()

◆ gfxDrawInit()

◆ gfxDrawLine()

◆ gfxDrawLoadedImage()

◆ gfxDrawLoadImage()

◆ gfxDrawLoadScaledImage()

◆ gfxDrawLoadSpritesheetFromEntireImagePadded()

◆ gfxDrawLoadSpritesheetFromEntireImagePaddedSpacing()

◆ gfxDrawLoadSpritesheetFromEntireImageUnpadded()

◆ gfxDrawLoadSpritesheetFromPortionOfImagePadded()

◆ gfxDrawLoadSpritesheetFromPortionOfImagePaddedSpacing()

◆ gfxDrawLoadSpritesheetFromPortionOfImageUnpadded()

◆ gfxDrawPoly()

◆ gfxDrawScaledImage()