From 7b52cc13af4e85f1ca2deb6b6c77de9c95ea0dcf Mon Sep 17 00:00:00 2001 From: scuri Date: Fri, 17 Oct 2008 06:10:33 +0000 Subject: First commit - moving from LuaForge to SourceForge --- html/en/cdlua.html | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 html/en/cdlua.html (limited to 'html/en/cdlua.html') diff --git a/html/en/cdlua.html b/html/en/cdlua.html new file mode 100644 index 0000000..9cfb965 --- /dev/null +++ b/html/en/cdlua.html @@ -0,0 +1,117 @@ + + + + +Lua Binding + + + + + +

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:

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

in Lua5

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

+ +

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);
+ + + + + \ No newline at end of file -- cgit v1.2.3