C API Reference

Welcome to the quick reference guide for the Brick Engine, v5.1. This document covers the C API.

void init_brick();

Initializes the brick engine and activates the hardware.

void quit_brick();

Shuts down the brick engine, closes the graphics window, and halts all sounds.

These are the functions used to open and close the graphics display.

int graphics_open(int mode, int w, int h, int fs, int zf);

Opens the graphics display. The mode value is one of the following: GRAPHICS_SDL (standard SDL display) or GRAPHICS_ACCEL (OpenGL-accelerated blit to screen). The graphics display size is given in w and h. There is a compile-time maximum width and height, defaulting to 640×480.

Full-screen mode is controlled by the boolean fs flag. In the accelerated graphics output mode, the zoom factor zf determines the amount by which the display is scaled. Note that a zoom factor of either 0 or 1 has no effect on the output display.

Returns 0 on success, or an error code on failure.

void graphics_close();

Closes the active graphics display.

int graphics_info(int *w, int *h);

Returns the active graphics mode, and stores the current display resolution in w and h.

These are the functions used to open and close the audio output.

int audio_open(int mode, char *file);

Opens the audio output. mode is one of the following: AUDIO_SPEAKER (speaker output).

void audio_close();

Closes the active audio output.

These are functions used to create and manipulate the brick-engine internal lists.

struct list *list_create();

Creates a new brick-engine list.

void list_empty(struct list *list);

Empties the given listen. Note that this does not delete any of the items in the list.

void list_delete(struct list *list);

Deletes the given brick-engine list. Note that this does not delete any of the items in the list.

void list_add(struct list *list, void *item);

Adds the given item to the end of the list.

void list_prepend(struct list *list, void *item);

Adds the given item to the start of the list.

void *list_shift(struct list *list);

Removes the first item from the head of the list and returns it.

void *list_pop(struct list *list);

Removes the last item from the list and returns it.

void list_remove(struct list *list, void *item, int direction);

Removes the given item from the list. The direction flag can be set to LIST_HEAD, LIST_TAIL, or LIST_ALL. If set to LIST_HEAD or LIST_TAIL, this routine removes the first matching entry it finds from the beginning or end of the list. If LIST_ALL is given, then all matching items are removed from the list.

int list_length(struct list *list);

Returns a count of the number of items in the given list.

int list_find(struct list *list, void *item);

Determines whether the given item is in the list.

void list_sort(struct list *list, int(*)(void *, void *));

Sorts the list using the provided comparison function.

These are the functions used to set rendering options.

void render_set_bg_fill(int fill);

Enable or disable the solid-color background fill.

void render_set_bg_color(char r, char g, char b);

Sets the background fill color to the given RGB values.

void render_set_overdraw(int w, int h);

Sets the amount of overdraw applied to the internal render canvas. This does not affect the displayed canvas size. Some sprite frame types (e.g. the pixel-repositioning frame) may depend on graphics data being drawn outside the screen borders for proper composition of the display, and the overdraw instructs the renderer to generate this extra data.

void render_display();

Renders and displays the current frame.

int render_to_disk(char *file);

Renders the current frame to the so-named file.

These are the functions used to create and adjust layers, set layer camera positions, and the like.

int layer_count();

Returns the current number of layers.

int layer_add();

Adds a new layer and returns its ID. When a layer is added, a sprite list, map, and string list are automatically created.

void layer_reorder(int first, int second);

Swaps the first layer with the second.

void layer_remove(int id);

Removes the specified layer

int layer_copy(int id);

Makes a copy of the specified layer, assigning its properties (sprite list, map, etc) to the new layer.

struct list *layer_get_sprite_list(int id);

Returns the sprite list for the given layer.

struct map *layer_get_map(int id);

Returns the map for the given layer.

struct list *layer_get_string_list(int id);

Returns the string list for the given layer.

int layer_get_visible(int id);

Returns a boolean value for the layer visibility setting.

int layer_get_sorting(int id);

Returns a boolean value for sprite z-hint sorting on the given layer.

void layer_set_sprite_list(int id, struct list *list);

Sets the sprite list for the given layer.

void layer_set_map(int id, struct map *map);

Sets the map for the given layer.

void layer_set_string_list(int id, struct list *list);

Sets the string list for the given layer.

void layer_set_visible(int id, int mode);

Sets the layer visibility setting to the boolean value specified in mode.

void layer_set_sorting(int id, int mode);

Sets the sprite z-hint sorting value setting on the given layer.

int layer_get_camera(int id, int *x, int *y);

Retrieves the camera position on the specified layer. Returns 0 on success, or ERR if the layer ID is invalid.

void layer_set_camera(int id, int x, int y);

Sets the camera position on the specified layer.

void layer_adjust_camera(int id, int x, int y);

Adjusts the camera position on the specified layer.

int layer_get_view(int id, struct box *);

Retreives the viewport on the specified layer. Returns 0 on success, or ERR if the layer ID is invalid.

void layer_set_view(int id, struct box *);

Sets the viewport on the specified layer. The layer contents will only be rendered within the viewport, so when used in conjunction with layer_copy(), a split-screen effect can be made very easily (e.g., make a copy of the playfield layer, set the layer viewports to sit side by side, and adjust the layers' camera positions to center on different players.)

These are the functions used to work with the tile-based maps.

struct map *map_create();

Creates a new map.

void map_empty(struct map *map);

Empties a map and resets all map attributes to zero.

void map_delete(struct map *map);

Deletes a map.

int map_get_size(struct map *map, int *w, int *h);

Stores the size of the map into w and h. Returns 0 on success, or ERR if the map does not exist.

int map_get_tile_size(struct map *map, int *tw, int *th);

Stores the map's tile size into tw and th. Returns 0 on success, or ERR if the map does not exist.

int map_get_tile(struct map *map, int index, struct tile **tile);

Stores the tile pointer for the given map index into tile. Returns 0 on success, or ERR if the map does not exist.

void map_set_size(struct map *map, int w, int h);

Sets the size of the given map.

void map_set_tile_size(struct map *map, int tw, int th);

Sets the tile size for the given map.

void map_set_tile(struct map *map, int index, struct tile *tile);

Loads the given tile into the tile index for the map.

void map_set_data(struct map *map, short *data);

Sets the map data for the given map. w and h are the dimensions of the map. The map data is a buffer of 16-bit (big endian) words, each word containing the index of the tile to display.

void map_set_single(struct map *map, int x, int y, short data);

Sets a single element in the map data. x and y are the tile coordinates to be set. The tile is a 16-bit (big endian) word containing the index of the tile.

void map_animate_tiles(struct map *map);

Animate all tiles on the given map.

void map_reset_tiles(struct map *map);

Reset all tile animation on the given map.

These routines are used to create and manipulate frames of graphics data.

struct frame *frame_create(int mode, int width, int height, void *data, void *auxiliary);

Creates a new graphics frame using the given frame data. mode is one of: FRAME_NONE (no display data), FRAME_RGB (RGB data with an optional chroma-key), FRAME_DISPL (pixel-displacement frame), FRAME_CONVO (convolution kernel), FRAME_BR (brightness-adjusting frame), FRAME_CT (contrast-adjusting frame), FRAME_LT (luminance-adjusting frame), FRAME_SAT (saturation-adjusting frame), FRAME_LUT (RGB lookup-table frame). The width and height are given in width and height.

A frame type of FRAME_NONE takes no display data and produces no output. The data and opts arguments are ignored. This isn't very useful, except for situations where some unusual collision detection is needed.

If the frame type is FRAME_RGB, the data is a buffer of RGB pixels. An optional chroma key can be passed in as a struct color in opts. The frame data will be drawn onto the render canvas.

If the type is FRAME_DISPL, the pixel data is an array of 16-bit (big-endian) X/Y coordinate pairs. Each coordinate pair represents an offset from the pixel in the frame to the location in the underlying image data from which to retrieve the given pixel. For example, pixel data consisting of only zeros has no effect, while pixel data containing all pairs of -1, -1 will create a frame that offsets the underlying image data up and to the left by one pixel.

If the type is FRAME_CONVO, then the data array is a pixel mask, in which each non-zero pixel applies the specified convolution kernel to the underlying image data. The convolution kernel definition is passed into opts as a struct convolution.

If the type is FRAME_BR, the data is a buffer of RGB pixels. A pixel component value of 64 is neutral and doesn't alter the image brightness. Values less than 64 darken the image, and values greater than 64 brighten the image.

If the type is FRAME_CT, the data is a buffer of unsigned char values which adjust the contrast of the underlying image. A pixel component value of 64 is neutral and leaves the image contrast unaltered. Values less than 64 decrease the image contrast to a neutral grey, and values greater than 64 increase the contrast of the image.

If the type is FRAME_LT, the data is a buffer of RGB pixels. A pixel component value of 128 is neutral and doesn't alter image lightness. Values less than 128 darken the image toward black, and values greater than 128 lighten the image toward white.

If the type is FRAME_SAT, the data is a buffer of unsigned char values which adjust the saturation of the underlying image. A pixel value of 128 leaves the image unchanged. A value of 64 desaturates the image, and values between 64 and 128 give varying degrees of desaturation. Values less than 64 invert the hue of the image data. Values greater than 128 increase the saturation.

If the type is FRAME_LUT, the data is a buffer of unsigned chars which act as a pixel mask. Each non-zero pixel causes the underlying image data to be replaced according to that pixel's value in the lookup table. The lookup table is passed into opts as a struct lut.

struct frame *frame_copy(struct frame *frame);

Makes a copy of the given frame.

void frame_delete(struct frame *frame);

Deletes the given frame.

void frame_set_mask(struct frame *frame, unsigned char *data);

Sets the pixel mask for the given frame. This can be useful if you plan to use one frame both as a tile and as a sprite.

void frame_set_mask_from(struct frame *frame, struct frame *source);

Sets the pixel mask for the given frame one of two ways, depending on the source frame. If the source frame has a color key set, then the pixel mask is generated by non-transparent pixels. If the source frame has no transparency set, then each pixel is desaturated and any pixels darker than middle gray are treated as solid. This routine only accepts RGB-type frames.

struct frame *frame_slice(struct frame *frame, int x, int y, int width, int height);

Copies out a section out of the given RGB frame and returns it as a new frame.

struct frame *frame_convert(struct frame *frame, int mode, void *auxiliary);

Converts an RGB frame to almost any other frame type. This routine modifies the frame in-place, so you should make a copy if you plan to use the original again.

struct frame *frame_from_disk(char *file, struct color *key);

Loads and decompresses the given image file into an RGB frame. This routine is only available if the brick engine has been built with SDL_image support.

struct frame *frame_from_buffer(int len, unsigned char *data, struct color *);

Loads and decompresses an RGB frame from an image file stored in the given data buffer. This routine is only available if the brick engine has been built with SDL_image support.

These are the routines used to create and prepare tiles for use with maps.

struct tile *tile_create();

Creates a new tile.

void tile_delete(struct tile *tile);

Deletes a tile and frees all of its image data.

int tile_get_collides(struct tile *tile, int *mode);

Retrieves the collision mode for the specified tile. Returns 0 on success, or ERR if the tile does not exist.

void tile_set_collides(struct tile *tile, int mode);

Sets the collision mode for the specified tile. The mode must be one of: COLLISION_OFF (sprite does not collide), COLLISION_BOX (collision testing by bounding box), or COLLISION_PIXEL (collision testing by pixel-mask).

int tile_get_anim_type(struct tile *tile, int *type);

Retrieves the animation type for the specified tile. Returns 0 on success, or ERR if the tile does not exist.

void tile_set_anim_type(struct tile *tile, int type);

Sets the animation type for the specified tile. Valid animation types are: TILE_STILL (do not animate), TILE_FWD (forward looping animation), TILE_REV (reverse looping animation), and TILE_PP (ping-pong animation).

int tile_add_frame(struct tile *tile, struct frame *frame);

Adds the given frame to the tile. Please note that this does not make a copy of the frame, so beware that you might want to make a copy of the frame before passing it to this routine (e.g. if you use the frame in other places).

int tile_add_frame_data(struct tile *tile, int mode, int width, int heigt, void *data, void *aux);

Loads the given graphics data into the tile. The documentation for frame_create() has a detailed description of the arguments, as this is essentially a wrapper for that routine.

void tile_set_pixel_mask(struct tile *tile, int index, unsigned char *data);

Sets a pixel-accurate collision mask for the specified frame of the tile. Any non-zero value in the data buffer counts as an active pixel.

void tile_set_pixel_mask_from(struct tile *tile, int index, struct frame *source);

Sets a pixel-accurate collision mask for the specified frame of the tile from a source frame. If the source frame has a color key set, then the opaque pixels represent the collidable portions of the pixel mask. If the source frame does not have a color key, then each pixel is desaturated and any pixel lighter than medium gray counts as an active pixel.

void tile_animate(struct tile *tile);

Animates the specified tile.

void tile_reset(struct tile *tile);

Resets the tile animation for the specified tile.

These are the functions used to create and work with sprites.

struct sprite *sprite_create();

Creates a new sprite.

struct sprite *sprite_copy(struct sprite *sprite);

Makes a copy of the given sprite.

void sprite_delete(struct sprite *sprite);

Deletes the given sprite and frees all of the frame data.

void sprite_set_frame(struct sprite *sprite, int frame);

Sets the currently-displayed sprite frame.

int sprite_get_frame(struct sprite *sprite, int *frame);

Stores the sprite's currently-selected frame into frame. Returns 0 on success, or ERR if given an invalid sprite.

void sprite_get_z_hint(struct sprite *sprite, int z_hint);

Sets the sprite's z-hint. When layer sorting is enabled, then sprites are sorted by z-hint before being drawn. When layer sorting is not enabled, the sprite's z-hint has no effect.

int sprite_get_z_hint(struct sprite *sprite, int *z_hint);

Stores the sprite's z-hint into z_hint. When layer sorting is enabled, then sprites are sorted by z-hint before being drawn. When layer sorting is not enabled, the sprite's z-hint has no effect. Returns 0 on success, or ERR if given an invalid sprite.

void sprite_set_collides(struct sprite *sprite, int mode);

Sets the sprite's collision mode. The mode must be one of: COLLISION_OFF (sprite does not collide), COLLISION_BOX (collision testing by bounding box), or COLLISION_PIXEL (collision testing by pixel-mask).

int sprite_get_collides(struct sprite *sprite, int *mode);

Stores the sprite's collision mode into mode. Returns 0 on success, or ERR if given an invalid sprite.

void sprite_set_bounding_box(struct sprite *sprite, int frame, struct box *box);

Sets the bounding box for the specified frame of the sprite.

void sprite_set_pixel_mask(struct sprite *sprite, int frame, unsigned char *data);

Sets the pixel-accurate collision mask for the specified frame of the sprite. Any non-zero value in the data buffer counts as an active pixel.

void sprite_set_pixel_mask_from(struct sprite *sprite, int frame, struct frame *source);

Sets the pixel-accurate collision mask for the specified frame of the sprite. If the source frame has a color key set, then the opaque pixels represent the collidable portions of the pixel mask. If the source frame does not have a color key, then each pixel is desaturated and any pixel lighter than medium gray counts as an active pixel.

void sprite_set_position(struct sprite *sprite, int x, int y);

Sets the position of the sprite.

int sprite_get_position(struct sprite *sprite, int *x, int *y);

Stores the position of the sprite into x and y. Returns 0 on success, or ERR if given an invalid sprite.

void sprite_set_velocity(struct sprite *sprite, int x, int y);

Sets the velocity of the sprite.

int sprite_get_velocity(struct sprite *sprite, int *x, int *y);

Stores the velocity of the sprite into x and y. Returns 0 on success, or ERR if given an invalid sprite.

int sprite_add_frame(struct sprite *sprite, struct frame *frame);

Adds the given frame to the sprite. Please note that this does not make a copy of the frame, so beware that you might want to make a copy of the frame before passing it to this routine (e.g. if you use the frame in other places).

int sprite_add_frame_data(struct sprite *sprite, int mode, int w, int h, void *data, void *auxiliary);

Loads a frame of data into the given sprite. The documentation for frame_create() has a detailed description of the arguments, as this is essentially a wrapper for that routine.

int sprite_add_subframe(struct sprite *sprite, int index, struct frame *frame);

Adds the frame to the sprite as a subframe on the given frame index. Subframes are rendered in reverse order, i.e. the last-added subframe is rendered first. This allows for easy compositing of sprite frames together (e.g. a shadow, a lighting effect, etc) into a single sprite. Please note that this does not make a copy of the frame, however, so it may be necessary or desirable to make a copy of the frame before passing it into this routine.

int sprite_load_program(struct sprite *sprite, char *program);

The motion control program system is a simple way to give sprites some simple autonomous movement, without interaction from the scripting level. Motion-control programs can also be used to generate simple particle systems, environmental effects, and the like. Motion-control programs aren't intended to be a full-blown replacement for sprite movement. For more information, please see the in-depth guide at the motion control programs page.

This routine loads the given motion-control program into the sprite. The program is a text string containing motion-control instructions, one per line. The following instructions are available:

set var, var/immediate  - store the right-side value in the left-side named var
add var, var/immediate  - add the right-side value to the left-side named var
stc var, var/immediate  - stochastic alter the left-side var with a range of -(var/imm)..var/imm
trk var, id             - copy over the left-side named var contents from another sprite
avg var, id             - average the left-side named var contents with those of another sprite

beq var, var/immediate  - break (immediately exit the program) if equal
bne var, var/immediate  - break if not equal
blt var, var/immediate  - break if less than
bgt var, var/immediate  - break if greater than
bmp id                  - break if there is a collision with the given map
bnm id                  - break if there is a not a collision with the given map
bst var/immediate       - stochastic break, i.e. exit if random value between 0 and imm is zero

copy id                 - make a copy of the sprite and replace the current sprite with the copy for
                          the remainder of the program
ladd id                 - add the sprite to the given list
lrem id                 - remove the sprite from the given list
del                     - delete the sprite

xchgp ptr               - exchange the sprite's motion control program with another sprite's program

sound id                - play the sound

eoc                     - end of code

The var is a named variable, one of the following: xpos, ypos, xvel, yvel, frame, tick. xpos and ypos refer to the sprite's position, and xvel and yvel refer to the sprite's velocity. Immediate values are integers, and id values specify a list, sprite, map, or sound. Argument order matches Intel-style assembly language syntax, i.e. instructions that set or change a variable have the destination given first (set xpos, 4 can be read as xpos = 4)

Every sprite also has its own internal tick counter, and this increments every time the sprite's motion-control program is run.

These routines execute the motion-control programs for a sprite or for a list of sprites.

int motion_exec_single(struct sprite *sprite);

Executes the motion-control program for the given sprite. Returns 0 on success, or an error code on failure.

int motion_exec_list(struct list *list);

Executes the motion-control program for every sprite in the given list. Returns 0 on success, or an error code if any motion-control program fails to execute.

These routines allow the programmer to load and play sounds.

struct sound *sound_load_from_disk(char *filename);

Loads a sound from a file on disk. The list of supported file formats can be found in the documentation for SDL_mixer.

struct sound *sound_load_from_buffer(int length, unsigned char *data);

Loads a sound from the data buffer. The buffer length is given in length. The list of supported file formats can be found in the documentation for SDL_mixer.

struct sound *sound_load_raw(int length, unsigned char *data);

Creates a sound from the given data buffer. The data must match the audio format set at compile time. By default, the audio format is 8-bit unsigned data.

int sound_play(struct sound *sound, int volume);

Plays the given sound. The volume may range from 0 to 128. This returns the ID of the audio channel that is playing the sound, so that the sound can be stopped or have its volume or panning values adjusted.

void sound_halt(int id);

Stops the sound playing on the given channel. If id is -1, halt all sounds.

void sound_adjust_vol(int id, int volume);

Sets the volume of the sound playing on the given channel ID. The volume may range from 0 to 128. If id is -1, sets the volume for all currently-playing sounds.

void sound_adjust_an(int id, int panning);

Sets the panning of the sound playing on the given channel ID. The panning value ranges from 0 (left speaker only) to 254 (right speaker only), and is balanced at 127. If id is -1, sets the panning for all currently-playing sounds.

These routines are used to control music playback.

void song_play_from_disk(char *filename, int fade_in_delay);

Loads and plays the named song from disk, with a fade-in delay given in milliseconds. The list of supported file formats can be found in the documentation for SDL_mixer.

void song_play_from_buffer(int length, unsigned char *buffer, int fade_in_delay);

Loads and plays the named song from a memory buffer of length length, with a fade-in delay given in milliseconds. The list of supported file formats can be found in the documentation for SDL_mixer.

void song_pause();

Pauses the currently-playing song.

void song_resume();

Resumes the currently-paused song.

void song_stop(int fade_out_delay);

Stops the currently-playing song with fade-out delay given in milliseconds.

void song_set_position(int pos);

Sets the position of the currently-playing song.

void song_adjust_vol(int volume);

Sets the music playback volume. The volume can range from 0 to 128.

These are functions used to configure and read user input from keyboard, joystick, and mouse.

int io_fetch(int input, struct input *io);

Retrieves the status of the given input into io.

There are eight inputs from which movement and actions can be requested, numbered 0 through 7. Keys can be assigned to any action (axis, hat, or button) on any input. If joysticks are plugged in, they are assigned to the inputs starting at 0.

Axes have a range from -127 to 127. Key presses will set the axis to the ends of this range, while an analog joystick input may return any value within this range. Up to eight axes are read, either from joystick or from the assigned keys.

Usually, the first two axes will represent horizontal and vertical motion, either from the keyboard or the joystick. Joysticks with more than one analog stick will use additional axes to represent the movement on the additional sticks. By default, the arrow keys are mapped onto axes 0 and 1 on input 0.

Hats represent the four-way directional inputs present on some joysticks. Hat values range from -1 to 1 and are returned as pairs of horizontal and vertical results. Note that a joypad-style controller with just one directional input probably returns its results as a pair of axes rather than a hat. By default, the keys wasd are mapped onto hat 0 of input 0.

Button presses return either 0 or 1. By default, the keys left ctrl, left alt, z, and x are assigned to button presses 0 through 3 on input 0.

There are eight axes, four hats, and twenty buttons available on each input. If a physical joystick has more axes, hats, or buttons than this, the excess will be ignored.

The keys space, tab, enter/return (as select), pause, and escape are always included in the results.

int io_mouse(int input, struct mouse *);

Reads the mouse motions on the specified mouse input.

void io_grab(int flag);

Grabs the keyboard and mouse input, preventing interference from the window manager or operating system. Be cautious that your game is thoroughly debugged before using this routine!! If your game has an infinite loop and the input grab is enabled, there will be no way for the player to exit gracefully.

int io_has_quit();

Returns whether or not a quit signal has been received by the game, e.g. clicking the close button of the game window.

int io_wait(int delay);

Waits until all input buffers are cleared, and then waits until any activity on any of the inputs is received. If the application-quit button is pressed, this immediately returns ERR. The delay value indicates how many times each second the inputs will be checked for activity, so that the processor use can be kept low.

void io_assign(int input, int type, ... );
void io_assign(int input, int type = IO_AXIS, int axis_no, int dir, int keycode);
void io_assign(int input, int type = IO_HAT, int hat_no, int dir, int keycode);
void io_assign(int input, int type = IO_BUTTON, int button_no, int keycode);

Assigns a keycode to the action on the given input. The combination of axis, hat, button number, and direction specifies which joystick action will have a keyboard-mapping assigned. The type must be one of IO_AXIS, IO_HAT, IO_BUTTON. If the action type is IO_AXIS, then only the directions IO_LEFT and IO_RIGHT are permitted. If the action type is IO_HAT, then the directions IO_LEFT, IO_UP, IO_DOWN, and IO_RIGHT are permitted. Note that if the action type is IO_BUTTON, then the direction argument is omitted.

int io_read_key()

Halts until a single keypress can be read, and a keycode returned. This is not useful for general-purpose input, but is intended only to let the programmer determine keycodes interactively, for use with io_assign().

These are routines that allow the programmer inspect the environment in various ways.

void inspect_adjacent_tiles(struct map *map, struct sprite *spr, int dir, struct map_fragment *res);

Returns a buffer of tiles adjacent to the sprite on the specified map. The direction must be one of INSPECT_NW, INSPECT_N, INSPECT_NE, INSPECT_E, INSPECT_SE, INSPECT_S, INSPECT_SW, INSPECT_W. If the sprite is using bounding box collision, the buffer of tiles is determined by the edge of the bounding box. If pixel-accurate collision is enabled, the bounding edges of the pixel mask are used.

void inspect_obscured_tiles(struct map *map, struct sprite *spr, struct map_fragment *res);

Returns a buffer of tiles obscured by the sprite on the specified map. If the sprite is using bounding box collision, the tiles are determined by the edge of the bounding box. If pixel-accurate collision is enabled, the bounding edges of the pixel mask are used.

int inspect_line_of_sight(struct map *map, struct sprite *spr, int xofs, int yofs, int dist, struct sprite *target);

Performs a line-of-sight test to determine visibility from the originating sprite to the target sprite within the given map. The xofs and yofs offsets determine the point, relative to the sprite's upper left corner, from which the visibility test is performed. These offsets can be negative, performing the visibility test from a point outside the originating sprite's frame. The dist value is the maximum range for the test.

The originating sprite does not need to have collision detection enabled, but the target sprite must have collision detection enabled. If the target sprite has bounding-box collision enabled, the four corners of the bounding box are checked for visibility from the originating sprite. If the target sprite has pixel-accurate collision enabled, the visibility test is performed on the four corners of the pixel mask's bounding edges.

struct list *inspect_in_frame(struct list *list, struct box *range);

Returns a list of sprites that fall within the given rectangle.

struct sprite *inspect_near_point(struct list *list, int x, int y, int distance);

Returns a list of sprites near the given point.

These are the routines used to detect collisions among sprites, and between sprites and maps.

void collision_with_map(struct sprite *sprite, struct map *map, int slip, struct map_collision *res);

Checks the given sprite for collision against the given map. The optional slip argument indicates that, when a collision occurs, the sprite will be adjusted by the given number of one-pixel increments to continue motion. The slip factor allows sprites to travel near the corners of maps without stopping on all single-pixel collisions.

The result is stored res. The res.mode value will be COLLISION_ATSTART to indicate that the sprite and map were colliding before motion began, COLLISION_NEVER to indicate that no collision has occurred, or COLLISION_INMOTION to indicate that collision occurred during motion. The pixel distance before the sprite hits the map is stored in res.stop and the distance that the sprite may travel after being adjusted by the given slip value is stored in res.go.

int collision_with_sprites(struct sprite *sprite, struct list *sprlist, int limit, struct sprite_collision res[]);

Tests the given sprite for collisions with all collidable members of the given sprite list. Only limit collisions will be returned, and res must be large enough to hold this number of collisions. The res.mode value will be COLLISION_ATSTART to indicate that the sprite and map were colliding before motion began, COLLISION_NEVER to indicate that no collision has occurred, or COLLISION_INMOTION to indicate that collision occurred during motion. The pixel distance before the sprite hits the target is stored in res.dist and the direction in which the collision occurred is stored in res.hit.

These are the routines used to load fonts and display text strings. One font, named default, is built into the brick engine. Additional fonts can be loaded at any time.

void font_add(char *name, int w, int h, unsigned char *data, struct color *key);

Adds a new font named name, with the bitmap data stored in data. If key is not null, it will be used as a chroma key for the font display. The data buffer is three-bytes-per-pixel RGB data, consisting of an image of all characters in the font arranged in order. The dimensions of each character are given in w and h, and the font image must be 128 characters wide.

void font_from_disk(char *name, char *file, struct color *key);

Adds a new font named name from the compressed image file named file. If key is not null, it will be used as a chroma key for the font display. The font image is assumed to be 128 characters wide. This routine is only available if the brick engine has been built with SDL_image support.

void font_from_buffer(char *name, int len, unsigned char *data, struct color *key);

Adds a new font named name from the data buffer which contain a compressed image file. If key is not null, it will be used as a chroma key for the font display. The font image is assumed to be 128 characters wide. This routine is only available if the brick engine has been built with SDL_image support.

These are the routines used to display text strings. If an unknown font name is assigned to a string, the string will not be displayed. Note that strings are positioned absolutely on the display canvas and do not move when the layer camera moves.

struct string *string_create();

Creates a new string.

void string_delete(struct string *string);

deletes the given string.

void string_set_font(struct string *string, char *font);

Sets the font for the given string.

void string_set_position(struct string *string, int x, int y);

Sets the position for the given string.

void string_set_text(struct string *string, char *text);

Sets the display text for the given string.

A useful routine to hold the game's frame rate steady.

int delay(int fps);

If the time between calls to delay() is less than necessary (i.e. the game would otherwise run too fast) to maintain the given fps rate, then the routine will delay until enough time has passed. if the game is running too slowly to maintain the requested fps rate, delay() will return the number of frames that must be skipped to maintain speed.