diff options
| -rw-r--r-- | html/en/cdlua.html | 110 |
1 files changed, 48 insertions, 62 deletions
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,19 +11,59 @@ <h2>Lua Binding</h2> <h3><a name="Overview">Overview</a></h3> - <p>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 <strong> - <font face="Courier New">cdlua_open</font></strong> declared in the header file <strong><font face="Courier New">cdlua</font><font size="2" face="Courier New">.</font><font face="Courier New">h</font></strong>, - as seen in the example below:</p> + <p> + All the CD functions are available in Lua, with a few exceptions. We call it <strong> + CDLua</strong>. 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:</p> + <pre>cdXxx -> cd.Xxx (for functions)<br />wdXxx -> cd.wXxx (for WD functions)<br />CD_XXX -> cd.XXX (for definitions)<br />cdCanvasXXX(canvas,... => canvas:XXX(... (for methods)<br /></pre> + <p> + 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.</p> + <p> + 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.</p> + <p> + Notice that, as opposed to C, + in which enumeration flags are<i> </i>combined with the bitwise operator OR, in Lua the flags are added arithmetically.</p> + <p> + In Lua all parameters are checked and a Lua error is emitted when the check fails.</p> + <p> + 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.</p> + <h3> + Initialization</h3> + <p> + <strong>Lua</strong> 5.1 "require" can be used for all the <strong> +CDLua</strong> +libraries. You can use <b>require</b>"<b>cdlua</b>" and so on, but the LUA_CPATH +must also contains the following: + </p> + +<pre>"./lib?51.so;" [in UNIX] + +".\\?51.dll;" [in Windows] +</pre> +<p>The <a href="http://luabinaries.luaforge.net/">LuaBinaries</a> distribution already includes these modifications on the +default search path.</p> +<p>The simplest form <b>require</b>"<b>cd</b>" +and so on, can not be used because there are CD dynamic libraries with names +that will conflict with the names used by <b>require</b> during search.</p> + <p> + Additionally you can statically link the <strong>CDLua</strong> libraries, but you must call the initialization functions manually. The <strong> + <font face="Courier New">cdlua_open</font></strong> function is declared in the header file <strong><font face="Courier New">cdlua</font><font size="2" face="Courier New">.</font><font face="Courier New">h</font></strong>, + see the example below:</p> <div align="center"> <center> <table border="1" cellpadding="10" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" id="AutoNumber1"> <tr> - <th> - <p align="center">in Lua5</th> - </tr> - <tr> <td> <pre>#include <lua.h> #include <lualib.h> @@ -41,7 +81,6 @@ </b> lua_dofile("myprog.lua"); - <b><font color="#FF0000">cdlua_close(L);</font></b> lua_close(L); }</pre> </td> @@ -49,59 +88,6 @@ </table> </center> </div> - - <p>The <font face="Courier New"><strong>cdlua_open</strong>()</font> 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<i> </i>combined with the bitwise operator OR, in Lua the flags are added arithmetically. </p> - <p>The CDLua dynamic libraries are also compatible with the Lua 5 "loadlib" function.<span lang="en-us"> - </span>Here is an example on how to dynamically load CD - in Lua 5<span lang="en-us">.1</span>:</p> -<pre>local cdlua_open = package.loadlib("cdlua51.dll", "cdlua_open") -cdlua_open()</pre> -<p><strong>Lua</strong> 5.1 "require" can be used for all the <strong> -CDLua</strong> -libraries. You can use <b>require</b>"<b>cdlua</b>" and so on, but the LUA_CPATH -must also contains the following: </p> - -<pre>"./lib?51.so;" [in UNIX] - -".\\?51.dll;" [in Windows] -</pre> -<p>The <a href="http://luabinaries.luaforge.net/">LuaBinaries</a> distribution already includes these modifications on the -default search path.</p> -<p>The simplest form <b>require</b>"<b>cd</b>" -and so on, can not be used because there are CD dynamic libraries with names -that will conflict with the names used by <b>require</b> during search.</p> - -<h3><a name="New Functions">Function Names and Definitions</a></h3> - - <p>In Lua, because of the name space "cd" all the functions and definitions have their names prefix changed. The - general rule is quite simple:</p> - - <pre>cdXxx -> cd.Xxx -wdXxx -> cd.wXxx -CD_XXX -> cd.XXX</pre> - - -<h3>Modifications to the API</h3> - - <p>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.</p> - - <p>Some functions were modified to receive those objects as parameters.</p> - <p>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.</p> - - -<h3>Garbage Collection</h3> - - <p>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.</p> <h3>Exchanging Values between C and Lua</h3> |