From 7f789588c40e5837b2d8bb49c34102ac97e81bed Mon Sep 17 00:00:00 2001 From: scuri Date: Wed, 7 Oct 2009 17:41:53 +0000 Subject: *** empty log message *** --- html/en/cdlua.html | 110 +++++++++++++++++++++++------------------------------ 1 file changed, 48 insertions(+), 62 deletions(-) (limited to 'html') diff --git a/html/en/cdlua.html b/html/en/cdlua.html index 60b95d0..750081b 100644 --- a/html/en/cdlua.html +++ b/html/en/cdlua.html @@ -11,18 +11,58 @@

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:

+

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

+ 
cdXxx  -> cd.Xxx    (for functions)
wdXxx  -> cd.wXxx   (for WD functions)
CD_XXX -> cd.XXX    (for definitions)
cdCanvasXXX(canvas,... => canvas: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 images, pattern, stipple and palette. All the + metatables have the "tostring" metamethod 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.

+

+ 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, except + the canvas because there can be different Lua canvases pointing to the same + C canvas. The "tostring" + metamethod of the Lua canvas will print both values, Lua + and C. The equal method will compare the C canvas value.

+

+ Initialization

+

+ Lua 5.1 "require" can be used for all the +CDLua +libraries. You can use require"cdlua" 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"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.

+

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

- - - @@ -49,59 +88,6 @@
-

in Lua5

#include <lua.h>
@@ -41,7 +81,6 @@
 
   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. You can use require"cdlua" 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"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, except - the canvas because there can be different Lua canvases pointing to the same - C canvas. The tostring method of the Lua canvas will print both values, Lua - and C. The equal method will compare the C canvas value.

Exchanging Values between C and Lua

-- cgit v1.2.3