< index < 3. System layer | ===================================== 4. Line drawing toolkit ===================================== | > 5. Image toolkit

This toolkit is a very simple and lightweight implementation of the bresenham line drawing algorithm.
It allows you to follow straight paths on your map very easily.
First, you have to initialize the toolkit with your starting and ending coordinates :

    C++ : static void TCODLine::init(int xFrom, int yFrom, int xTo, int yTo)
    C   : void TCOD_line_init(int xFrom, int yFrom, int xTo, int yTo)
    Py  : line_init(xFrom, yFrom, xTo, yTo)

Parameter | Description
--- | ---
xFrom,yFrom | Coordinates of the line's starting point.
xTo, yTo | Coordinates of the line's ending point.

You can then step through each cell with this function. It returns true when you reach the line's ending point.

    C++ : static bool TCODLine::step(int *xCur, int *yCur)
    C   : bool TCOD_line_step(int *xCur, int *yCur)
    Py  : line_step() # returns x,y or None,None if finished

Parameter | Description
--- | ---
xCur,yCur | Coordinates of the next cell on the line.

Example :
Going from point 5,8 to point 13,4 :

    C++ : int x=5,y=8;
          TCODLine::init(x,y,13,4);
          do {
    	     .. update cell x,y
          } while (! TCODLine::step(&x,&y) );
    C   : int x=5,y=8;
          TCOD_line_init(x,y,13,4);
          do {
    	     .. update cell x,y
          } while (! TCOD_line_step(&x,&y) );
    Py  : libtcod.line_init(5,8,13,4)
          .. update cell 5,8
          x,y=libtcod.line_step()
          while (not x is None ) :
    	     .. update cell x,y
             x,y=libtcod.line_step()

You can also use a callback-based atomic function.

    C++ : class TCODLIB_API TCODLineListener {
              virtual bool putPoint(int x,int y) = 0;
          };
          static bool TCODLine::line(int xFrom, int yFrom, int xTo, int yTo, TCODLineListener *listener)
    C   : typedef bool (*TCOD_line_listener_t) (int x, int y);
          bool TCOD_line(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener)
    Py  : def line_listener(x,y) : ...
          line(xFrom, yFrom, xTo, yTo, listener)

Parameter | Description
--- | ---
xFrom,yFrom | Coordinates of the line's starting point.
xTo, yTo | Coordinates of the line's ending point.
listener | Callback called for each line's point. The function stops if the callback returns false.

The function returns false if the line has been interrupted by the callback (it returned false before the last point).
Example :
Going from point 5,8 to point 13,4 :

    C++ : class MyLineListener : public TCODLineListener {
              public :
              bool putPoint(int x,int y) { printf ("%d %d\n",x,y); return true; }
          };
          MyLineListener myListener;
          TCODLine::line(5,8,13,4,&myListener);
    C   : bool my_listener(int x,int y) { printf ("%d %d\n",x,y); return true; }
          TCOD_line_line(5,8,13,4,my_listener);
    Py  : def my_listener(x,y) :
              print x,y
              return True
          libtcod.line_line(5,8,13,4,my_listener)