Note on this version

This is a working temporary(?) fork of cl-tcod, residing officially
on Bitbucket. I am working with the
official maintainer on these changes, so expect them to be merged back upstream at some
point. For now though, this provides a version of cl-tcod that works with the latest
version (and development) of libtcod, 1.6.2. This is also that version that works with
my Common Lisp port, cl-tcod-tutorial, of the
"Complete Roguelike Tutorial, using python+libtcod".

cl-tcod

The cl-tcod library provides an interface (wrapper) between Common Lisp and
the Doryen Library (libtcod). Libtcod is described on its website as
follows:

libtcod, a.k.a. "The Doryen Library", is a free, fast, portable and
uncomplicated API for roguelike developpers providing an advanced true
color console, input, and lots of other utilities frequently used in
roguelikes.

Files

cl-tcod consists of the following files:

• tcod.lisp, a lisp file which creates lisp bindings for C functions in the
  compiled libtcod library, using the CFFI lisp foreign function interface.
• tcod.asd, which allows TCOD to be easily loaded and used as a library by
  other common lisp programs, via the ASDF library-loading facility.
• tcod-colours.lisp, a lisp file containing definitions for all the colours
  named in /etc/X11/rgb.txt; autogenerated using 'parse-rgb' (see below)
• parse-rgb.lisp, a lisp file containing code for parsing /etc/X11/rgb.txt
  and generating tcod-colours.lisp
• parse-rgb.asd, ASDF system definition file for parse-rgb.lisp

cl-tcod has been tested with SBCL 1.1.0 on Linux, Mac OSX Mountain Lion
and Windows, Clozure Common Lisp 1.5 on Linux and Windows, and
Clisp on Windows.

License

The cl-tcod package is placed in the Public Domain by its author.

Dependencies

cl-tcod depends on the following libraries:

• ASDF: http://common-lisp.net/project/asdf/
• defstar: http://bitbucket.org/eeeickythump/defstar/
• CFFI: http://common-lisp.net/project/cffi/

Installation

You need to know your way around your chosen common lisp and how to install and
load lisp libraries before proceeding. You also need to have a version of
libtcod newer than 1.4.1rc2, which is the first version that includes the
wrappers.c and wrappers.h source files that allow cl-tcod to interface
with libtcod.

1. Ensure you have a working common lisp installation.

2. Ensure either Quicklisp or the ASDF lisp
   library is installed.

3. If CFFI or defstar are not installed, download and install them
   somewhere ASDF can find them. CFFI requires several third-party lisp
   libraries -- see the CFFI documentation for more details. Note that if you
   have Quicklisp installed, you can install CFFI and its dependencies easily
   using the command (ql:quickload "cffi") at the Lisp prompt.

4. Put the cl-tcod files in a directory where ASDF can find them.

5. Make sure libtcod is installed and compiled. Make sure the libtcod
   dynamically linked library (.dll, .so or .dylib file) is somewhere your lisp
   system can find it. It probably is, but if CFFI complains about being unable
   to find the library, you can either copy it to an appropriate directory or
   add its directory to the list variable cffi:*foreign-library-directories*
   e.g. by typing the following in the lisp interpreter:

   :::cl
   (push #P"/my/libtcod/directory/" cffi:*foreign-library-directories*)
   

   On windows, .dll files should be put in one of the directories listed in the
   PATH environment variable. You will need to put SDL.dll in the same place
   if you don't already have SDL installed.

   On Linux, you can usually put .so files in /usr/local/lib/.
   Use your package installer to install libSDL.
   Try running the libtcod demo programs to check everything works.

6. Start lisp, then load cl-tcod. Using Quicklisp:

   :::cl
   (ql:quickload :tcod)
   

   Using ASDF:

   :::cl
   (load "/path/to/asdf/asdf.lisp")
   (asdf:oos 'asdf:load-op :tcod)
   

7. Type something like the following commands at the lisp prompt to start using
   libtcod from within Lisp. Alternatively you can type (tcod:hello-world),
   which is a function containing the code below.

   :::cl
   (tcod:console-set-custom-font "terminal.png" '(:font-layout-ascii-in-row) 16 16)
   (tcod:console-init-root 80 25 "Test" nil :renderer-sdl)
   (tcod:console-clear tcod:*root*)
   (tcod:console-print tcod:*root* 1 1 "Hello, world!~%")
   (tcod:console-wait-for-keypress t)
   

Differences between CL-TCOD and libtcod

Naming conventions

The C function TCOD_foo_bar corresponds to the lisp function foo-bar, which
is in the tcod package (and so requires a prefix of tcod: to access in most
situations). Underscores become hyphens. So:

:::cl
(tcod:foobar-function a b)    ; = TCOD_foobar_function(a, b)

Predicate functions' are functions whose main job is to return a boolean value, true (non nil) or false (nil`), that answers a question. These have a
terminal '?' added to their name:

:::cl
(tcod:console-is-fullscreen?)    ; TCOD_console_is_fullscreen()

C enums have generally more succinct names. As they are lisp keywords, their
names all begin with a colon :. THey are named according to the following
pattern:

:::cl
:backspace         ;  TCODK_BACKSPACE (etc)
:char-hline        ;  TCOD_CHAR_HLINE  (etc)
:colctrl-1         ;  TCOD_COLCTRL_1  (etc)
:set               ;  TCOD_BKGND_SET (etc)
:font-layout-ascii-in-col   ;  TCOD_FONT_LAYOUT_ASCII_INCOL
:fov-shadow        ;  FOV_SHADOW
:key-pressed       ;  TCOD_KEY_PRESSED
:center, :centre   ;  CENTER

In general, most functions exist in both U.S. and non-U.S. spellings, This is
mainly relevant to those functions with colour/color or centre/center in their
names.

Colournums

In libtcod, colours are represented as structures containing three integer
values: red, green and blue (each 0-255). The name of the structure type is
TCOD_color_t.

In cl-tcod, these colour structs are converted into 3-byte integers using the C
functions int_to_color(int) and color_to_int(TCOD_color_t), both defined in
wrappers.c. The 3 bytes are red, green and blue in order (blue is 1's). ie:

:::C
struct TCOD_color_t {r, g, b}    /* becomes #x00RRGGBB */

So, for example, one way to use the function TCOD_color_multiply_scalar()
from lisp is:

:::cl
(tcod:color-multiply-scalar (tcod:compose-colour 218 165 32) 0.5)

All C functions that take or return TCOD_color_t structs, are wrapped by lisp
functions that take or return integers as described above.

Colours by keyword

A lisp keyword is any symbol beginning with a colon :. In lisp, keywords
(like all symbols) are first-class values and can be passed around just like
any other value. cl-tcod uses keywords to refer to particular colours, for
example the keyword :cyan refers to the colour #x0056A3CD (or 5678029 in
decimal notation).

You can use keywords instead of colournums as arguments to lisp functions, by
using the function colour to return the colournum associated with a keyword:

:::cl
(tcod:colour :cyan)    ; returns 5678029

You can also define your own colour names, like so:

:::cl
(tcod:make-colour :my-goldenrod 218 165 32)
(tcod:color-multiply-scalar (tcod:colour :my-goldenrod) 0.5)

cl-tcod knows all the colour names defined in the "rgb.txt" file under
Xwindows -- :navajo-white, :honeydew, :mint-cream, and so on. There is
nothing special about the fact that rgb.txt comes from Xwindows -- the colours
are just named R,G,B values and can be used anywhere that cl-tcod can be
used. Look in the source file tcod-colours.lisp to see the available colour
names. If you are using [[http://www.gnu.org/software/emacs/][GNU Emacs]], do
M-x list-colors-display to see a list of all colours.

Lisp format versus C printf

The TCOD functions that accept printf-like string-formatting arguments, have
been modified to instead accept arguments to Common Lisp's much more capable
format function. For example:

:::C
TCOD_console_print (con, x, y, "Printing at %d, %dn", x, y);

becomes:

:::cl
(tcod:console-print con x y "Printing at ~D, ~D~%" x y)

Miscellaneous extra functions

console-print-double-frame is like console-print-frame, but draws using
`double-line' characters:

:::cl
(tcod:console-print-double-frame CONSOLE X Y W H EMPTY? STRING...)

Coverage

Does not provide wrappers for:

• File parser. Using this from lisp would be a very cumbersome way to read
  values from a file, as the resulting values are not lisp objects. You would
  be better to either consider using the lisp
  read function, or looking into lisp libraries for parser generation.
• namegen-get-sets -- I haven't yet implemented this as it will have to
  involve converting from libtcod's bespoke 'linked list' to a lisp list.
  You may be better to write your random name generator in lisp (fairly trivial).
• sys-get-directory-content, sys-file-exists, sys-is-directory,
  sys-delete-file: Common Lisp already has functions that do the same thing.