diff options
| -rw-r--r-- | html/en/imlua.html | 142 | ||||
| -rw-r--r-- | include/imlua.h | 12 |
2 files changed, 70 insertions, 84 deletions
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,21 +13,67 @@ <h2>Lua Binding</h2> <h3><a name="Overview">Overview</a></h3> - <p><strong>I</strong><span lang="en-us"><strong>m</strong></span><strong>Lua</strong> was developed to make all functionalities of the - <strong>IM</strong> library available to Lua programmers. To use the <strong>I</strong><span lang="en-us"><strong>m</strong></span><strong>Lua</strong> - bindings, your executable must be linked with the "imlua" library, and you must call the initialization function - <strong><font face="Courier New">imlua_open</font></strong> declared in the header file <strong> - <font face="Courier New">imlua</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 IM functions are available in Lua, with a few exceptions. We call it <strong> + ImLua</strong>. 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:</p> + <pre>imXxx -> im.Xxx (for functions)<br />IM_XXX -> im.XXX (for definitions)<br />imFileXXX(ifile,... -> ifile:XXX(... (for methods) +imImageXXX(image,... -> image: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 palettes. + All the metatables have the "tostring" + metamethod implemented to help debuging. The <strong>imImage</strong> metatable has the "index" metamethod + so you can address its data directly in Lua. 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. </p> + <p> + <span style="color: #ff0000"> + </span> + <span style="color: #ff0000"><span style="color: #000000"> </span></span></p> + <h3> + Initialization</h3> + <p> + <strong>Lua</strong> 5.1 "require" can be used for all the <strong>ImLua</strong> + libraries. You can use <b>require</b>"<b>imlua</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>im</b>" and so on, can not be used because there + are IM 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>ImLua</strong> libraries, but you + must call the initialization functions manually. The <strong><font face="Courier New"> + imlua_open</font></strong> function is declared in the header file <strong><font + face="Courier New">imlua</font><font face="Courier New" size="2">.</font><font face="Courier New">h</font></strong>, + see the example below:</p> + <div align="center"> <center> <table cellpadding="10" cellspacing="0" style="border-width: 0; border-collapse: collapse" bordercolor="#111111" id="AutoNumber1"> <tr> - <th> - <p align="center">in Lua<span lang="en-us"> </span>5</th> - </tr> - <tr> <td> <pre>#include <lua.h> #include <lualib.h> @@ -39,12 +85,12 @@ luaopen_string(L); luaopen_math(L); - luaopen_io(L); + luaopen_io(L); <b> <font color="#FF0000">imlua_open(L);</font> </b> lua_dofile("myprog.lua"); - + lua_close(L); }</pre> </td> @@ -52,71 +98,21 @@ </table> </center> </div> - - <p>The <strong>imlua_open</strong> function registers all <strong>IM</strong> functions and constants - your Lua program will need. The use of the <strong>I</strong><span lang="en-us"><strong>m</strong></span><strong>Lua</strong> 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 other secondary libraries also have their initialization functions declared in - <strong>imlua.h</strong> - and each one have a separate library to be linked with the application. See <a href="doxygen/group__imlua.html">IM Lua - 5 Binding</a> reference.</p> - <p>The I<span lang="en-us">m</span>Lua 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 I<span lang="en-us">M</span> - in Lua 5<span lang="en-us">.1</span>:</p> -<pre>local i<span lang="en-us">m</span>lua_open = package.loadlib("i<span lang="en-us">m</span>lua51.dll", "i<span lang="en-us">m</span>lua_open") -i<span lang="en-us">m</span>lua_open()</pre> -<p><strong>Lua</strong> 5.1 "require" can be used for all the <strong> -ImLua</strong> -libraries. You can use <b>require</b>"<strong>im</strong><b>lua</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>i<span lang="en-us">m</span></b>" -and so on, can not be used because there are IM 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 "im" all the functions and definitions have their names prefix changed. The - general rule is quite simple:</p> - - <pre>imXxx -> im.Xxx -IM_XXX -> im.XXX -imFileXXX(ifile,... -> ifile:XXX(... -imImageXXX(image,... -> image: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, files, viceo capture 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> -<p>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.</p> - - -<h3>Garbage Collection</h3> - - <p>All the objects are garbage collected by the Lua garbage collector.</p> -<h3><a name="Integration with IMLua">Integration with CDLua</a></h3> +<h3><a name="Integration with ImLua">Integration with CDLua</a></h3> - <p>In <b>CDLua</b> there is an additional library providing simple functions to map the - <strong>imImage</strong> - structure to the <strong>cdBitmap</strong> structure. And some facilities to + <p>In <b>CDLua</b> there is an additional library providing simple functions to map the + <strong>imImage</strong> + structure to the <strong>cdBitmap</strong> structure. And some facilities to draw an image in a CD canvas. See also the <a target="_blank" href="http://www.tecgraf.puc-rio.br/cd">CD documentation</a> and the <a href="doxygen/group__imlua.html">IM Lua 5 Binding</a> reference.</p> - <p>Color values and palettes can be created and used transparently in both libraries. Palettes and color values are + <p>Color values and palettes can be created and used transparently in both libraries. Palettes and color values are 100% compatible between CD and IM.</p> + <h3> + Reference</h3> + <p> + See also the <a href="doxygen/group__imlua.html">ImLua 5 Binding Reference</a><span + style="color: #ff0000">.</span></p> </body> diff --git a/include/imlua.h b/include/imlua.h index 5714dff..bc07cca 100644 --- a/include/imlua.h +++ b/include/imlua.h @@ -11,23 +11,13 @@ extern "C" { #endif -/** \defgroup imlua IM Lua 5 Binding +/** \defgroup imlua ImLua 5 Binding Reference * \par * Binding for the Lua 5 scripting language. \n * Lua 5.1 Copyright (C) 1994-2005 Lua.org, PUC-Rio \n * R. Ierusalimschy, L. H. de Figueiredo & W. Celes \n * http://www.lua.org * \par - * The name of the functions were changed because of the namespace "im" and because of the object orientation. \n - * As a general rule use: -\verbatim - imXxx -> im.Xxx - IM_XXX -> im.XXX - imFileXXX(ifile,... -> ifile:XXX(... - imImageXXX(image,... -> image:XXX(... -\endverbatim - * All the objects are garbage collected by the Lua garbage collector. - * \par * See \ref imlua.h * \ingroup util */ |