From 5a422aba704c375a307a902bafe658342e209906 Mon Sep 17 00:00:00 2001 From: scuri Date: Fri, 17 Oct 2008 06:10:15 +0000 Subject: First commit - moving from LuaForge to SourceForge --- html/en/imlua.html | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 html/en/imlua.html (limited to 'html/en/imlua.html') diff --git a/html/en/imlua.html b/html/en/imlua.html new file mode 100644 index 0000000..63ebd05 --- /dev/null +++ b/html/en/imlua.html @@ -0,0 +1,124 @@ + + + + + + +Lua Binding + + + + + +

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:

+ +
+
+ + + + + + + +
+

in Lua 5

+ 
#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. You can use require"imlua" and so on, but the LUA_CPATH +must also contains the following:

+ +
"./lib?51.so;"    [in UNIX]
+
+".\\?51.dll;"     [in Windows]
+

The LuaBinaries distribution already includes these modifications on the +default search path.

+

The simplest form require"im" +and so on, can not be used because there are IM 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 "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(...
+ + +

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, files, viceo capture 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.

+

In C there is no parameter checking in the processing functions, but in Lua +all parameters are checked and a Lua error is emitted when check fails.

+ + +

Garbage Collection

+ +

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

+ +

Integration with CDLua

+ +

In CDLua 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 also the CD documentation and + the 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.

+ + + + + \ No newline at end of file -- cgit v1.2.3