Line Drawing Toolkit

Iterator-based line drawing

#include <libtcod.h>

void main() {
  TCOD_bresenham_data_t bresenham_data;
  int x=5, y=8;
  TCOD_line_init_mt(x, y, 13, 14, &bresenham_data);
  do {
    printf("%d %d\n", x, y);
  } while (!TCOD_line_step_mt(&x, &y, &bresenham_data));
}
struct TCOD_bresenham_data_t

A struct used for computing a bresenham line.

void TCOD_line_init_mt(int xFrom, int yFrom, int xTo, int yTo, TCOD_bresenham_data_t *data)

Initialize a TCOD_bresenham_data_t struct.

After calling this function you use TCOD_line_step_mt to iterate over the individual points on the line.

Parameters
  • xFrom – The starting x position.

  • yFrom – The starting y position.

  • xTo – The ending x position.

  • yTo – The ending y position.

  • data – Pointer to a TCOD_bresenham_data_t struct.

bool TCOD_line_step_mt(int *xCur, int *yCur, TCOD_bresenham_data_t *data)

Get the next point on a line, returns true once the line has ended.

The starting point is excluded by this function. After the ending point is reached, the next call will return true.

Parameters
  • xCur – An int pointer to fill with the next x position.

  • yCur – An int pointer to fill with the next y position.

  • data – Pointer to a initialized TCOD_bresenham_data_t struct.

Returns

true after the ending point has been reached.

Callback-based line drawing

#include <libtcod.h>

void main() {
  bool my_listener(int x,int y) {
    printf("%d %d\n", x, y);
    return true;
  }
  TCOD_line(5, 8, 13, 4, my_listener);
}
typedef bool (*TCOD_line_listener_t)(int x, int y)

A callback to be passed to TCOD_line.

The points given to the callback include both the starting and ending positions.

Parameters
  • x

  • y

Returns

As long as this callback returns true it will be called with the next x,y point on the line.

bool TCOD_line(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener)

Iterate over a line using a callback.

Changed in version 1.6.6: This function is now reentrant.

Parameters
  • xo – The origin x position.

  • yo – The origin y position.

  • xd – The destination x position.

  • yd – The destination y position.

  • listener – A TCOD_line_listener_t callback.

Returns

true if the line was completely exhausted by the callback.

class tcod::BresenhamLine

Encapsulates a Bresenham line drawing algorithm.

This class is provisional.

Public Functions

inline BresenhamLine(int xFrom, int yFrom, int xTo, int yTo)

Initializes the object to draw a line from xFrom, yFrom to xTo, yTo.

inline bool step(int &x, int &y)

Steps through each cell from the start to the end coordinates.

The input variables x, y are passed in by reference and updated at each step of the line.

inline bool tcod::bresenham_line(int xFrom, int yFrom, int xTo, int yTo, const std::function<bool(int, int)> &callback)

Draw a Bresenham line, passing the indexes of the line to callback.

This function is provisional.

Deprecated functions

bool TCOD_line_mt(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener, TCOD_bresenham_data_t *data)

Iterate over a line using a callback.

Deprecated since version 1.6.6: The data parameter for this call is redundant, you should call TCOD_line() instead.

Parameters
  • xo – The origin x position.

  • yo – The origin y position.

  • xd – The destination x position.

  • yd – The destination y position.

  • listener – A TCOD_line_listener_t callback.

  • data – Pointer to a TCOD_bresenham_data_t struct.

Returns

true if the line was completely exhausted by the callback.

void TCOD_line_init(int xFrom, int yFrom, int xTo, int yTo)

Initialize a line using a global state.

Deprecated since version 1.6.6: This function is not reentrant and will fail if a new line is started before the last is finished processing.

Use TCOD_line_init_mt() instead.

Parameters
  • xFrom – The starting x position.

  • yFrom – The starting y position.

  • xTo – The ending x position.

  • yTo – The ending y position.

bool TCOD_line_step(int *xCur, int *yCur)

advance one step.

returns true if we reach destination

advance one step.

The starting point is excluded by this function. After the ending point is reached, the next call will return true.

Deprecated since version 1.6.6: This function is not reentrant and will fail if a new line is started before the last is finished processing.

Use TCOD_line_step_mt() instead.

Parameters
  • xCur – An int pointer to fill with the next x position.

  • yCur – An int pointer to fill with the next y position.

Returns

true once the ending point has been reached.