Lua Binding

Overview

CDLua was developed to make all functionalities of the CD library available to Lua programmers. To use the CDLua bindings, your executable must be linked with the CDLua library, and you must call the initialization function cdlua_open declared in the header file cdlua.h, as seen in the example below:

#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
#include <cdlua.h>

void main(void)
{
  lua_State *L = lua_open();

  luaopen_string(L);
  luaopen_math(L);
  luaopen_io(L);  

  cdlua_open(L);

  lua_dofile("myprog.lua");
  
  cdlua_close(L);
  lua_close(L);
}

The cdlua_open() function registers all CD functions and constants your Lua program will need. The use of the CDLua functions in Lua is generally identical to their equivalents in C. Nevertheless, there are several exceptions due to differences between the two languages. Notice that, as opposed to C, in which the flags are combined with the bitwise operator OR, in Lua the flags are added arithmetically.

The CDLua dynamic libraries are also compatible with the Lua 5 "loadlib" function. Here is an example on how to dynamically load CD in Lua 5.1:

local cdlua_open = package.loadlib("cdlua51.dll", "cdlua_open")
cdlua_open()

Lua 5.1 "require" can be used for all the CDLua libraries, but the full library name should be used. For example: require"cdlua51", require"cdluapdf51", and so on. Additionally the LUA_CPATH in UNIX must add the prefix "lib" to the search path, for example:

LUA_CPATH = ./\?.so\;./lib\?.so\;$LIBPATH_ARCH/\?.so\;$LIBPATH_ARCH/lib\?.so

You can also use require"cdlua" and so on, but the LUA_CPATH must contains the "51" pattern. For example:

LUA_CPATH = ./\?.so\;./lib\?51.so\;$LIBPATH_ARCH/\?.so\;$LIBPATH_ARCH/lib\?51.so

The simplest form require"cd" and so on, can not be used because there are CD dynamic libraries with names that will conflict with the names used by require during search.

Function Names and Definitions

In Lua, because of the name space "cd" all the functions and definitions have their names prefix changed. The general rule is quite simple:

cdXxx  -> cd.Xxx
wdXxx  -> cd.wXxx
CD_XXX -> cd.XXX

Modifications to the API

New functions (without equivalents in C) were implemented to create and destroy objects that do not exist in C. For instance functions were developed to create and destroy images, pattern, stipple and palette.  All the metatables have the "tostring" method implemented to help debuging.

Some functions were modified to receive those objects as parameters.

Also the functions which receive values by reference in C were modified. Generally, the values of parameters that would have their values modified are now returned by the function in the same order.

Garbage Collection

All the objects are garbage collected by the Lua garbage collector.

Exchanging Values between C and Lua

Because of some applications that interchange the use of CD canvases in Lua and C, we build a few C functions that are available in "cdlua.h":

cdCanvas* cdlua_checkcanvas(lua_State* L, int pos);
void cdlua_pushcanvas(lua_State* L, cdCanvas* canvas);

Integration with ImLua

In ImLua there is an additional library providing simple functions to map the imImage structure to the cdBitmap structure. And some facilities to draw an image in a CD canvas. See the IM documentation.

Color values and palettes can be created and used transparently in both libraries. Palettes and color values are 100% compatible between CD and IM.