Lua Binding Guide

Overview

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

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

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

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

  imlua_open(L);

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

The imlua_open function registers all IM functions and constants your Lua program will need. The use of the ImLua 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 other secondary libraries also have their initialization functions declared in imlua.h and each one have a separate library to be linked with the application. See IM Lua 5 Binding reference.

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

local imlua_open = package.loadlib("imlua51.dll", "imlua_open")
imlua_open()

Lua 5.1 "require" can be used for all the ImLua libraries, but the full library name must be used. For example: require"imlua51", require"imlua_process51", and so on.

Function Names and Definitions

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

imXxx  -> im.Xxx
IM_XXX -> im.XXX
imFileXXX(ifile,... -> ifile:XXX(...
imImageXXX(image,... -> image:XXX(...

Garbage Collection

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

Integration with CDLUA

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 IM Lua 5 Binding reference.

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