TUM Ball API

Demo "game engine" code for basic game objects. More...

Collaboration diagram for TUM Ball API:

Data Structures
struct	ball
	Object to represent a ball that bounces off walls. More...
struct	wall
	Object to represent a wall that balls bounce off of. More...

Typedefs
typedef void(*	callback_t) (void *args)
	Callback function attached to an object. More...
typedef struct ball	ball_t
	Object to represent a ball that bounces off walls. More...
typedef struct wall	wall_t
	Object to represent a wall that balls bounce off of. More...

Functions
ball_t *	createBall (signed short initial_x, signed short initial_y, unsigned int colour, signed short radius, float max_speed, callback_t callback, void *args)
	Creates a ball object. More...
wall_t *	createWall (signed short x1, signed short y1, signed short w, signed short h, float dampening, unsigned int colour, callback_t callback, void *args)
	Creates a wall object. More...
void	setWallProperty (wall_t *wall, signed short x, signed short y, signed short width, signed short height, unsigned char flags)
	Sets one or more properties of a wall. More...
void	setBallSpeed (ball_t *ball, float dx, float dy, float max_speed, unsigned char flags)
	Sets the speed of the ball. More...
void	setBallLocation (ball_t *ball, signed short x, signed short y)
	Sets the location of the ball. More...
signed char	checkBallCollisions (ball_t *ball, callback_t callback, void *args)
	Checks if a ball is currently collided with other objects. More...
void	updateBallPosition (ball_t *ball, unsigned int milli_seconds)
	Updates the position of the ball. More...

Set wall location flags
Flags passed to setWallProperty to set the X, Y, width or height of a wall.
#define	SET_WALL_X   0b1
#define	SET_WALL_Y   0b10
#define	SET_WALL_WIDTH   0b100
#define	SET_WALL_HEIGHT   0b1000
#define	SET_WALL_AXES   SET_WALL_X | SET_WALL_Y
#define	SET_WALL_SIZE   SET_WALL_WIDTH | SET_WALL_HEIGHT
#define	SET_WALL_ALL   SET_WALL_AXES | SET_WALL_SIZE

Set ball speed flags
Flags passed to setBallSpeed to set various speed properties of a ball
#define	SET_BALL_SPEED_X   0b1
#define	SET_BALL_SPEED_Y   0b10
#define	SET_BALL_SPEED_MAX   0b100
#define	SET_BALL_SPEED_AXES   SET_BALL_SPEED_X | SET_BALL_SPEED_Y
#define	SET_BALL_SPEED_ALL   SET_BALL_SPEED_AXES | SET_BALL_SPEED_MAX

Detailed Description

Demo "game engine" code for basic game objects.

Functions to generate ball and wall object that interact each other in a 2D environment

Macro Definition Documentation

SET_BALL_SPEED_ALL

#define SET_BALL_SPEED_ALL   SET_BALL_SPEED_AXES | SET_BALL_SPEED_MAX

#include <TUM_Ball.h>

Sets both the axes (X and Y) speeds as well as the max speed that the ball can have along either axis.

SET_BALL_SPEED_AXES

#define SET_BALL_SPEED_AXES   SET_BALL_SPEED_X | SET_BALL_SPEED_Y

#include <TUM_Ball.h>

Sets both the X and Y axis speeds of the ball (dx and dy)

SET_BALL_SPEED_MAX

#define SET_BALL_SPEED_MAX   0b100

#include <TUM_Ball.h>

Sets the maximum speed either axis of the ball can have

SET_BALL_SPEED_X

#define SET_BALL_SPEED_X   0b1

#include <TUM_Ball.h>

Sets the X axis speed of the ball (dx)

SET_BALL_SPEED_Y

#define SET_BALL_SPEED_Y   0b10

#include <TUM_Ball.h>

Sets the Y axis speed of the ball (dy)

Typedef Documentation

ball_t

typedef struct ball ball_t

#include <TUM_Ball.h>

Object to represent a ball that bounces off walls.

A ball is created with a starting X and Y location (center of the ball), initial X and Y axis speeds (dx and dy respectively), as well as a limiting maximum speed, a colour and a radius. A callback function can be passed to the ball creation function createBall with the form void (*callback)(void), which is called each time the ball collides with a wall.

The absolute location of the ball is stored in the floats f_x and f_y, this is to avoid situation where the ball is moving so slowly that it cannot escape its current pixel as the rounding performed during integer mathematics is causing the ball to become trapped on a pixel.

The colour of the ball is a 24bit hex colour code of the format RRGGBB.

A ball is created with initial speeds (dx and dy) of zero. The speed of the ball must be set to a non-zero value using setBallSpeed before the ball will start to move.

callback_t

typedef void(* callback_t) (void *args)

#include <TUM_Ball.h>

Callback function attached to an object.

Parameters

args	Arguments passed into the callback function upon execution

wall_t

typedef struct wall wall_t

#include <TUM_Ball.h>

Object to represent a wall that balls bounce off of.

A wall object is created by passing the top left X and Y locations (in pixels) and the width and height of the desired wall. The wall also stores a colour that can be used to render it, allowing for the information to be stored in the object. A wall interacts with balls automatically as all walls generated are stored in a list that is iterated though by the function checkBallCollisions.

When a wall is collided with it causes a ball to loose or gain speed, the dampening is a normalized percentage value that is used to either increase or decrease the balls velocity. A dampening of -0.4 represents a 40% decrease in speed, similarly 0.4 represents a 40% increase in speed.

Please be aware that the position of a ball can be tested slower than a ball can move when the ball is moving extremely quickly, this can cause the balls to jump over objects, this is due to the extremely simple collision detection implemented.

A walls callback is a function pointer taking a function of the format void (*callback)(void *). If the function is set the that function is called when the wall is collided with. This allows for actions to be performed when a specific wall is collided with.

Function Documentation

checkBallCollisions()

signed char checkBallCollisions	(	ball_t *	ball,
		callback_t	callback,
		void *	args
	)

#include <TUM_Ball.h>

Checks if a ball is currently collided with other objects.

Parameters

ball	Reference to the ball object which is to be checked
callback	Callback function that is to be called when a collision is detected
args	Args passed to callback function

Returns

1 if a collision is detected

createBall()

ball_t* createBall	(	signed short	initial_x,
		signed short	initial_y,
		unsigned int	colour,
		signed short	radius,
		float	max_speed,
		callback_t	callback,
		void *	args
	)

#include <TUM_Ball.h>

Creates a ball object.

Example use:

ball_t *my_ball = createBall(SCREEN_WIDTH / 2, SCREEN_HEIGHT/2, Black, 20,
     1000, &playBallSound);

Parameters

initial_x	Initial X coordinate of the ball (in pixels)
initial_y	Initial Y coordinate of the ball (in pixels)
colour	The hex RGB colour of the ball
radius	The radius of the ball (in pixels)
max_speed	The maximum speed (in pixels/second) that the ball can travel
callback	The callback function called (if set) when the ball collides with a wall
args	Args passed to callback function

Returns

A pointer to the created ball, program exits if creation failed

createWall()

wall_t* createWall	(	signed short	x1,
		signed short	y1,
		signed short	w,
		signed short	h,
		float	dampening,
		unsigned int	colour,
		callback_t	callback,
		void *	args
	)

#include <TUM_Ball.h>

Creates a wall object.

Parameters

x1	Top left X coordinate of the wall (in pixels)
y1	Top left Y coordinate of the wall (in pixels)
w	X axis width of the wall (in pixels)
h	Y axis width of the wall (in pixels)
dampening	Dampening factor that is applied to a ball upon collision
colour	The hex RGB colour of the wall
callback	The callback function called (if set) when a ball collides with the wall
args	Args passed to callback function

Returns

A pointer to the created wall, program exits if creation failed

setBallLocation()

void setBallLocation	(	ball_t *	ball,
		signed short	x,
		signed short	y
	)

#include <TUM_Ball.h>

Sets the location of the ball.

Parameters

ball	Reference to the ball objects whose parameters are to be modified
x	New X axis location that is to be set
y	New Y axis location that is to be set

Returns

NULL Always returns NULL

setBallSpeed()

void setBallSpeed	(	ball_t *	ball,
		float	dx,
		float	dy,
		float	max_speed,
		unsigned char	flags
	)

#include <TUM_Ball.h>

Sets the speed of the ball.

Parameters

ball	Reference to the ball objects whos parameters are to be modified
dx	New X axis speed that is to be set
dy	New Y axis speed that is to be set
max_speed	New maximum speed limit that is to be set
flags	Flag specifying which attributes of the referenced ball are to be set.

See also

speed_flags.

Returns

NULL Always returns NULL

setWallProperty()

void setWallProperty	(	wall_t *	wall,
		signed short	x,
		signed short	y,
		signed short	width,
		signed short	height,
		unsigned char	flags
	)

#include <TUM_Ball.h>

Sets one or more properties of a wall.

Parameters

wall	Wall object whose properties are to be set
x	New X coordinate for the wall
y	New Y coordinate for the wall
width	New width of the wall
height	New height of the wall
flags	Flags specifying which attributes of the referenced wall are to be set.

See also

wall_flags.

updateBallPosition()

void updateBallPosition	(	ball_t *	ball,
		unsigned int	milli_seconds
	)

#include <TUM_Ball.h>

Updates the position of the ball.

The balls position is updated by passing in the amount of time that has passed since the ball's position was last updated. The speeds of the ball are stored in pixel/second and, as such, the position of the ball is updated by applying scalar amounts of these speeds proportionate to the seconds passed since the last update.

The formula used is as follows: New position += speed * milliseconds passed / milliseconds in a second

Parameters

ball	Reference to the ball object whose position is to be updated
milli_seconds	Milliseconds passed since balls position was last updated

Returns