FreeRTOS Tetris
Data Structures | Macros | Typedefs | Enumerations | Functions
TUM Drawing API

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

Collaboration diagram for TUM Drawing API:

Data Structures

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.
 
typedef void * image_handle_t
 Handle used to reference loaded images, an invalid image will have a NULL handle.
 
typedef void * animation_handle_t
 Handle used to reference a loaded animation spritesheet, an invalid spritesheet will have a NULL handle. More...
 
typedef void * sequence_handle_t
 Returns an instance of an animation;. More...
 

Enumerations

enum  sprite_sequence_direction { SPRITE_SEQUENCE_HORIZONTAL_POS, SPRITE_SEQUENCE_HORIZONTAL_NEG, SPRITE_SEQUENCY_VERTICAL_POS, SPRITE_SEQUENCY_VERTICAL_NEG }
 Defines the direction that the animation appears on the spritesheet.
 

Functions

char * tumGetErrorMessage (void)
 Returns a string error message from the TUM Draw back end. More...
 
int tumDrawInit (char *path)
 Initializes the TUM Draw backend. More...
 
int tumDrawBindThread (void)
 Transfers the drawing ability to the calling thread/taskd. More...
 
void tumDrawExit (void)
 Exits the TUM Draw backend. More...
 
int tumDrawUpdateScreen (void)
 Executes the queued draw jobs. More...
 
int tumDrawClear (unsigned int colour)
 Sets the screen to a solid colour. More...
 
void tumDrawDuplicateBuffer (void)
 
int tumDrawEllipse (signed short x, signed short y, signed short rx, signed short ry, unsigned int colour)
 Draws an ellipse on the screen. More...
 
int tumDrawArc (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 tumDrawText (char *str, signed short x, signed short y, unsigned int colour)
 Prints a string to the screen. More...
 
int tumGetTextSize (char *str, int *width, int *height)
 Finds the width and height of a strings bounding box. More...
 
int tumDrawBox (signed short x, signed short y, signed short w, signed short h, unsigned int colour)
 Draws a filled box on the screen. More...
 
int tumDrawFilledBox (signed short x, signed short y, signed short w, signed short h, unsigned int colour)
 Draws an unfilled box on the screen. More...
 
int tumDrawCircle (signed short x, signed short y, signed short radius, unsigned int colour)
 Draws a filled circle on the screen. More...
 
int tumDrawLine (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 tumDrawPoly (coord_t *points, int n, unsigned int colour)
 Draws a polygon on the screen. More...
 
int tumDrawTriangle (coord_t *points, unsigned int colour)
 Draws a triangle on the screen. More...
 
image_handle_t tumDrawLoadImage (char *filename)
 Loads an image file from disk, loaded image file can be closed using tumDrawFreeLoadedImage() More...
 
image_handle_t tumDrawLoadScaledImage (char *filename, float scale)
 Loads an image from disk and scales the image, loaded image file can be closed using tumDrawFreeLoadedImage(). Note that scaled images have large overheads compared to manually scaled images (changing image file's dimensions) More...
 
int tumDrawFreeLoadedImage (image_handle_t *img)
 Closes a loaded image and frees all memory used by the image structure. More...
 
int tumDrawSetLoadedImageScale (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 tumDrawGetLoadedImageScale (image_handle_t img)
 Retrieves the current scaling factor of an image. More...
 
int tumDrawGetLoadedImageWidth (image_handle_t img)
 Retrieves the image's width when drawn to screen, ie. after scaling. More...
 
int tumDrawGetLoadedImageHeight (image_handle_t img)
 Retrieves the image's height when drawn to screen, ie. after scaling. More...
 
int tumDrawGetLoadedImageSize (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 tumDrawLoadedImage (image_handle_t img, signed short x, signed short y)
 Draws a loaded image to the screen. More...
 
int tumDrawImage (char *filename, signed short x, signed short y)
 Draws an image on the screen. More...
 
int tumGetImageSize (char *filename, int *w, int *h)
 Gets the width and height of an image. More...
 
int tumDrawScaledImage (char *filename, signed short x, signed short y, float scale)
 Draws a scaled image on the screen. More...
 
int tumDrawArrow (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...
 
animation_handle_t tumDrawAnimationCreate (image_handle_t spritesheet, unsigned sprite_cols, unsigned sprite_rows)
 Creates an animation object with an attached spritesheet that must be loaded prior as an image. More...
 
int tumDrawAnimationAddSequence (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...
 
sequence_handle_t tumDrawAnimationSequenceInstantiate (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...
 
int tumDrawAnimationDrawFrame (sequence_handle_t sequence, unsigned ms_timestep, int x, int y)
 Draws the target intantiated animation sequence at a given location. More...
 
int tumDrawSetGlobalXOffset (int offset)
 Sets the global draw position offset's X axis value. More...
 
int tumDrawSetGlobalYOffset (int offset)
 Sets the global draw position offset's Y axis value. More...
 
int tumDrawGetGlobalXOffset (int *offset)
 Retrieves a copy of the current global X axis drawing offset. More...
 
int tumDrawGetGlobalYOffset (int *offset)
 Retrieves a copy of the current global X axis drawing offset. More...
 

Hex RGB colours

RRGGBB colours used by TUM 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

◆ SCREEN_HEIGHT

#define SCREEN_HEIGHT   480

#include <TUM_Draw.h>

Sets the height (in pixels) of the screen

◆ SCREEN_WIDTH

#define SCREEN_WIDTH   640

#include <TUM_Draw.h>

Sets the width (in pixels) of the screen

◆ WINDOW_TITLE

#define WINDOW_TITLE   "FreeRTOS Emulator"

#include <TUM_Draw.h>

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

Typedef Documentation

◆ animation_handle_t

typedef void* animation_handle_t

#include <TUM_Draw.h>

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 tumDrawAnimationAddSequence() and this must be added to an animation that has been created by passing in a loaded sprite sheet.

◆ sequence_handle_t

typedef void* sequence_handle_t

#include <TUM_Draw.h>

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.

Function Documentation

◆ tumDrawAnimationAddSequence()

int tumDrawAnimationAddSequence ( animation_handle_t  animation,
char *  name,
unsigned  start_row,
unsigned  start_col,
enum sprite_sequence_direction  sprite_step_direction,
unsigned  frames 
)

#include <TUM_Draw.h>

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
animationHandle to the prviously created animation object
nameAscii name to be given to the sequence. Used to reference the sequence
start_rowThe row at which the start sprite can be found (0 indexed)
start_colThe col at which the start sprite can be found (0 indexed)
sprite_step_directionDefines the direction with which the sprite frames can be found on the spritesheet
framesThe number of sprite frames that make up the animation
Returns
0 on success

◆ tumDrawAnimationCreate()

animation_handle_t tumDrawAnimationCreate ( image_handle_t  spritesheet,
unsigned  sprite_cols,
unsigned  sprite_rows 
)

#include <TUM_Draw.h>

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

Parameters
spritesheetThe loaded image that contains the spritesheet
sprite_colsThe number of colums in the sprite sheet
sprite_rowsThe number of rows in the sprite sheet
Returns
A handle to the created animation object

◆ tumDrawAnimationDrawFrame()

int tumDrawAnimationDrawFrame ( sequence_handle_t  sequence,
unsigned  ms_timestep,
int  x,
int  y 
)

#include <TUM_Draw.h>

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 tumDrawAnimationDrawFrame() so that the sprite frame can be selected appropriately.

Parameters
sequenceSequence instance that is to be rendered
ms_timestepThe number of milliseconds that have transpired since the last call to this function for the given animation sequence
xThe X axis location, in pixels, refernced from the top left of the sprite frame
yThe Y axis location, in pixels, refernced from the top left of the sprite frame
Returns
0 on success

◆ tumDrawAnimationSequenceInstantiate()

sequence_handle_t tumDrawAnimationSequenceInstantiate ( animation_handle_t  animation,
char *  sequence_name,
unsigned  frame_period_ms 
)

#include <TUM_Draw.h>

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
animationThe animation object countaining the target spritesheet and animation sequence
sequence_nameAscii string name of the sequence to be instantiated
frame_period_msThe number of milliseconds that should transpire between sprite frames
Returns
A handle to the instantiated animation sequence, NULL otherwise

◆ tumDrawArc()

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

#include <TUM_Draw.h>

Draws an arc on the screen.

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

Parameters
xX coordinate of the center of the arc
yY coordinate of the cente of the arc
radiusRadius of the arc in pixels
startStarting radius of the arc, 0 degrees is down
endEnding radius of the arc, 0 degrees is down
colourRGB colour of the arc
Returns
0 on success

◆ tumDrawArrow()

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

#include <TUM_Draw.h>

Draws an arrow on the screen.

Parameters
x1X coordinate of the tail of the arrow
y1Y coordinate of the tail of the arrow
x2X coordinate of the head of the arrow
y2Y coordinate of the head of the arrow
head_lengthLength in pixels of the arrow's head
thicknessThickness in pixels of the arrow's lines
colourRGB colour of the ellipse
Returns
0 on success

◆ tumDrawBindThread()

int tumDrawBindThread ( void  )

#include <TUM_Draw.h>

Transfers the drawing ability to the calling thread/taskd.

Returns
0 on success

◆ tumDrawBox()

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

#include <TUM_Draw.h>

Draws a filled box on the screen.

Parameters
xX coordinate of the top left point of the box
yY coordinate of the top left point of the box
wWidth of the box
hHeight of the box
colourRGB colour of the box
Returns
0 on success

◆ tumDrawCircle()

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

#include <TUM_Draw.h>

Draws a filled circle on the screen.

Parameters
xX coordinate of the center of the circle
yY coordinate of the center of the circle
radiusRadius of the circle in pixels
colourRGB colour of the ellipse
Returns
0 on success

◆ tumDrawClear()

int tumDrawClear ( unsigned int  colour)

#include <TUM_Draw.h>

Sets the screen to a solid colour.

Parameters
colourRGB colour to fill the screen with
Returns
0 on success

INIT_JOB(job, DRAW_CLEAR);

◆ tumDrawEllipse()

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

#include <TUM_Draw.h>

Draws an ellipse on the screen.

Parameters
xX coordinate of the center of the ellipse
yY coordinate of the cente of the ellipse
rxHorizontal radius in pixels
ryVertical radius in pixels
colourRGB colour of the ellipse
Returns
0 on success

◆ tumDrawExit()

void tumDrawExit ( void  )

#include <TUM_Draw.h>

Exits the TUM Draw backend.

Returns
NULL always returns NULL

◆ tumDrawFilledBox()

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

#include <TUM_Draw.h>

Draws an unfilled box on the screen.

Parameters
xX coordinate of the top left point of the box
yY coordinate of the top left point of the box
wWidth of the box
hHeight of the box
colourRGB colour of the filled box
Returns
0 on success

◆ tumDrawFreeLoadedImage()

int tumDrawFreeLoadedImage ( image_handle_t img)

#include <TUM_Draw.h>

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

Parameters
imgHandle to the loaded image
Returns
0 on success

◆ tumDrawGetGlobalXOffset()

int tumDrawGetGlobalXOffset ( int *  offset)

#include <TUM_Draw.h>

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

Parameters
offsetRefernce to the int where the value should be stored
Returns
0 on success

◆ tumDrawGetGlobalYOffset()

int tumDrawGetGlobalYOffset ( int *  offset)

#include <TUM_Draw.h>

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

Parameters
offsetRefernce to the int where the value should be stored
Returns
0 on success

◆ tumDrawGetLoadedImageHeight()

int tumDrawGetLoadedImageHeight ( image_handle_t  img)

#include <TUM_Draw.h>

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

Parameters
imgHandle to the image for which the height is to be retrieved
Returns
Height of the image in pixels

◆ tumDrawGetLoadedImageScale()

float tumDrawGetLoadedImageScale ( image_handle_t  img)

#include <TUM_Draw.h>

Retrieves the current scaling factor of an image.

Parameters
imgHandle to the image for which the scaling factor is to be retrieved
Returns
Current scaling factor

◆ tumDrawGetLoadedImageSize()

int tumDrawGetLoadedImageSize ( image_handle_t  img,
int *  w,
int *  h 
)

#include <TUM_Draw.h>

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

Parameters
imgHandle to the image of interest
wReference to the variable to store the retrieved width
hReference to the variable to store the retrieved height
Returns
0 on success

◆ tumDrawGetLoadedImageWidth()

int tumDrawGetLoadedImageWidth ( image_handle_t  img)

#include <TUM_Draw.h>

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

Parameters
imgHandle to the image for which the width is to be retrieved
Returns
Width of the image in pixels

◆ tumDrawImage()

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

#include <TUM_Draw.h>

Draws an image on the screen.

Parameters
filenameFilename of the image to be drawn
xX coordinate of the top left corner of the image
yY coordinate of the top left corner of the image
Returns
0 on success

◆ tumDrawInit()

int tumDrawInit ( char *  path)

#include <TUM_Draw.h>

Initializes the TUM Draw backend.

Parameters
pathPath to the folder's location where the program's binary is located
Returns
0 on success

◆ tumDrawLine()

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

#include <TUM_Draw.h>

Draws a line on the screen.

Parameters
x1X coordinate of the starting point of the line
y1Y coordinate of the starting point of the line
x2X coordinate of the starting point of the line
y2x coordinate of the starting point of the line
thicknessThe thickness of the line in pixels
colourRGB colour of the ellipse
Returns
0 on success

◆ tumDrawLoadedImage()

int tumDrawLoadedImage ( image_handle_t  img,
signed short  x,
signed short  y 
)

#include <TUM_Draw.h>

Draws a loaded image to the screen.

Parameters
imgHandle to the image to be drawn to the screen
xX coordinate of the top left corner of the image
yY coordinate of the top left corner of the image
Returns
0 on success

◆ tumDrawLoadImage()

image_handle_t tumDrawLoadImage ( char *  filename)

#include <TUM_Draw.h>

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

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
filenameName of the image file to be loaded
Returns
Returns a image_handle_t handle to the image

◆ tumDrawLoadScaledImage()

image_handle_t tumDrawLoadScaledImage ( char *  filename,
float  scale 
)

#include <TUM_Draw.h>

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

See tumDrawLoadImage() for information on filenames.

Parameters
filenameName of the image file to be loaded
scaleScaling factor with which the image should be drawn
Returns
Returns a image_handle_t handle to the image

◆ tumDrawPoly()

int tumDrawPoly ( coord_t points,
int  n,
unsigned int  colour 
)

#include <TUM_Draw.h>

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
pointsPoints array specifying each point in the polygon
nNumber of points in the points array
colourRGB colour of the ellipse
Returns
0 on success

◆ tumDrawScaledImage()

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

#include <TUM_Draw.h>

Draws a scaled image on the screen.

Parameters
filenameFilename of the image to be drawn
xX coordinate of the top left corner of the image
yY coordinate of the top left corner of the image
scaleThe scale factor of the image
Returns
0 on success

◆ tumDrawSetGlobalXOffset()

int tumDrawSetGlobalXOffset ( int  offset)

#include <TUM_Draw.h>

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

Parameters
offsetValue in pixels that all drawing should be offset on the X axis
Returns
0 on success

◆ tumDrawSetGlobalYOffset()

int tumDrawSetGlobalYOffset ( int  offset)

#include <TUM_Draw.h>

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

Parameters
offsetValue in pixels that all drawing should be offset on the X axis
Returns
0 on success

◆ tumDrawSetLoadedImageScale()

int tumDrawSetLoadedImageScale ( image_handle_t  img,
float  scale 
)

#include <TUM_Draw.h>

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
imgHandle to the image to be scaled
scaleScaling factor to be applied to the image file
Returns
0 on success

◆ tumDrawText()

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

#include <TUM_Draw.h>

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
strString to print
xX coordinate of the top left point of the text's bounding box
yY coordinate of the top left point of the text's bounding box
colourRGB colour of the text
Returns
0 on success

◆ tumDrawTriangle()

int tumDrawTriangle ( coord_t points,
unsigned int  colour 
)

#include <TUM_Draw.h>

Draws a triangle on the screen.

Parameters
pointsPoints array giving the three corner points of the triangle
colourRGB colour of the ellipse
Returns
0 on success

◆ tumDrawUpdateScreen()

int tumDrawUpdateScreen ( void  )

#include <TUM_Draw.h>

Executes the queued draw jobs.

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

While primitive drawing functions, such as tumDrawCircle(), are thread-safe calls to tumDrawUpdateScreen() must come from the thread that holds the GL (graphics layer) context. A thread can obtain the GL context by calling tumDrawBindThread(). Please be wary that tumDrawBindThread() 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 tumDrawUpdateScreen() will fail if the calling thread does not hold the GL context.

Returns
0 on success

◆ tumGetErrorMessage()

char* tumGetErrorMessage ( void  )

#include <TUM_Draw.h>

Returns a string error message from the TUM Draw back end.

Returns
String holding the most recent TUM Draw error message

◆ tumGetImageSize()

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

#include <TUM_Draw.h>

Gets the width and height of an image.

Parameters
filenameImage filename to be tested
wInteger where the width shall be stored
hInteger where the height shall be stored
Returns
0 on sucess

◆ tumGetTextSize()

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

#include <TUM_Draw.h>

Finds the width and height of a strings bounding box.

Parameters
strString who's bounding box size is required
widthInteger where the width shall be stored
heightInteger where the height shall be stored
Returns
0 on success