From 260844b45c6eedf8e3a1471354074be9ce59e693 Mon Sep 17 00:00:00 2001 From: scuri Date: Wed, 7 Oct 2009 17:42:02 +0000 Subject: *** empty log message *** --- html/en/imlua.html | 142 ++++++++++++++++++++++++++--------------------------- 1 file changed, 69 insertions(+), 73 deletions(-) (limited to 'html/en') diff --git a/html/en/imlua.html b/html/en/imlua.html index c7cfc43..651d472 100644 --- a/html/en/imlua.html +++ b/html/en/imlua.html @@ -13,20 +13,66 @@

Lua Binding

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:

- +

+ All the IM functions are available in Lua, with a few exceptions. We call it + ImLua. To use them the general application will do require"imlua", + and require"imluaxxxx" to all other secondary libraries that are needed. The functions + and definitions will be available under the table "im" using the following name + rules:

+ 
imXxx  -> im.Xxx    (for functions)
IM_XXX -> im.XXX    (for definitions)
imFileXXX(ifile,... -> ifile:XXX(...     (for methods)
+imImageXXX(image,... -> image:XXX(...    (for methods)
+

+ 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 palettes. + All the metatables have the "tostring" + metamethod implemented to help debuging. The imImage metatable has the "index" metamethod + so you can address its data directly in Lua. 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.

+

+ Notice that, as opposed to C, in which enumeration flags are combined with + the bitwise operator OR, in Lua the flags are added arithmetically.

+

+ In Lua +all parameters are checked and a Lua error is emitted when the check fails.

+

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

+

+ + +

+

+ Initialization

+

+ 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.

+

+ Additionally you can statically link the ImLua libraries, but you + must call the initialization functions manually. The + imlua_open function is declared in the header file imlua.h, + see the example below:

+
- - - @@ -52,71 +98,21 @@
-

in Lua 5

#include <lua.h>
@@ -39,12 +85,12 @@
 
   luaopen_string(L);
   luaopen_math(L);
-  luaopen_io(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

+

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 +

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 +

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

+

+ Reference

+

+ See also the ImLua 5 Binding Reference.

-- cgit v1.2.3