FreeRTOS Tetris
|
A simple interface to draw graphical primitives and images in a multi-threaded application. More...
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... | |
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.
#define SCREEN_HEIGHT 480 |
#include <TUM_Draw.h>
Sets the height (in pixels) of the screen
#define SCREEN_WIDTH 640 |
#include <TUM_Draw.h>
Sets the width (in pixels) of the screen
#define WINDOW_TITLE "FreeRTOS Emulator" |
#include <TUM_Draw.h>
The string that is shown on the window's status bar
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.
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.
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.
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 |
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.
spritesheet | The loaded image that contains the spritesheet |
sprite_cols | The number of colums in the sprite sheet |
sprite_rows | The number of rows in the sprite sheet |
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.
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 |
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.
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 |
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.
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 |
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.
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 |
int tumDrawBindThread | ( | void | ) |
#include <TUM_Draw.h>
Transfers the drawing ability to the calling thread/taskd.
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.
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 |
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.
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 |
int tumDrawClear | ( | unsigned int | colour | ) |
#include <TUM_Draw.h>
Sets the screen to a solid colour.
colour | RGB colour to fill the screen with |
INIT_JOB(job, DRAW_CLEAR);
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.
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 |
void tumDrawExit | ( | void | ) |
#include <TUM_Draw.h>
Exits the TUM Draw backend.
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.
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 |
int tumDrawFreeLoadedImage | ( | image_handle_t * | img | ) |
#include <TUM_Draw.h>
Closes a loaded image and frees all memory used by the image structure.
img | Handle to the loaded image |
int tumDrawGetGlobalXOffset | ( | int * | offset | ) |
#include <TUM_Draw.h>
Retrieves a copy of the current global X axis drawing offset.
offset | Refernce to the int where the value should be stored |
int tumDrawGetGlobalYOffset | ( | int * | offset | ) |
#include <TUM_Draw.h>
Retrieves a copy of the current global X axis drawing offset.
offset | Refernce to the int where the value should be stored |
int tumDrawGetLoadedImageHeight | ( | image_handle_t | img | ) |
#include <TUM_Draw.h>
Retrieves the image's height when drawn to screen, ie. after scaling.
img | Handle to the image for which the height is to be retrieved |
float tumDrawGetLoadedImageScale | ( | image_handle_t | img | ) |
#include <TUM_Draw.h>
Retrieves the current scaling factor of an image.
img | Handle to the image for which the scaling factor is to be retrieved |
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.
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 |
int tumDrawGetLoadedImageWidth | ( | image_handle_t | img | ) |
#include <TUM_Draw.h>
Retrieves the image's width when drawn to screen, ie. after scaling.
img | Handle to the image for which the width is to be retrieved |
int tumDrawImage | ( | char * | filename, |
signed short | x, | ||
signed short | y | ||
) |
#include <TUM_Draw.h>
Draws an image on the screen.
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 |
int tumDrawInit | ( | char * | path | ) |
#include <TUM_Draw.h>
Initializes the TUM Draw backend.
path | Path to the folder's location where the program's binary is located |
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.
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 |
int tumDrawLoadedImage | ( | image_handle_t | img, |
signed short | x, | ||
signed short | y | ||
) |
#include <TUM_Draw.h>
Draws a loaded image to the screen.
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 |
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
filename | Name of the image file to be loaded |
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.
filename | Name of the image file to be loaded |
scale | Scaling factor with which the image should be drawn |
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.
points | Points array specifying each point in the polygon |
n | Number of points in the points array |
colour | RGB colour of the ellipse |
int tumDrawScaledImage | ( | char * | filename, |
signed short | x, | ||
signed short | y, | ||
float | scale | ||
) |
#include <TUM_Draw.h>
Draws a scaled image on the screen.
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 |
int tumDrawSetGlobalXOffset | ( | int | offset | ) |
#include <TUM_Draw.h>
Sets the global draw position offset's X axis value.
offset | Value in pixels that all drawing should be offset on the X axis |
int tumDrawSetGlobalYOffset | ( | int | offset | ) |
#include <TUM_Draw.h>
Sets the global draw position offset's Y axis value.
offset | Value in pixels that all drawing should be offset on the X axis |
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.
img | Handle to the image to be scaled |
scale | Scaling factor to be applied to the image file |
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.
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 |
int tumDrawTriangle | ( | coord_t * | points, |
unsigned int | colour | ||
) |
#include <TUM_Draw.h>
Draws a triangle on the screen.
points | Points array giving the three corner points of the triangle |
colour | RGB colour of the ellipse |
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.
char* tumGetErrorMessage | ( | void | ) |
#include <TUM_Draw.h>
Returns a string error message from the TUM Draw back end.
int tumGetImageSize | ( | char * | filename, |
int * | w, | ||
int * | h | ||
) |
#include <TUM_Draw.h>
Gets the width and height of an image.
filename | Image filename to be tested |
w | Integer where the width shall be stored |
h | Integer where the height shall be stored |
int tumGetTextSize | ( | char * | str, |
int * | width, | ||
int * | height | ||
) |
#include <TUM_Draw.h>
Finds the width and height of a strings bounding box.
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 |