First commit - moving from LuaForge to SourceForge

author: scuri <scuri> 2008-10-17 06:10:33 +0000
committer: scuri <scuri> 2008-10-17 06:10:33 +0000
commit: 7b52cc13af4e85f1ca2deb6b6c77de9c95ea0dcf (patch)
tree: d0857278bde2eff784227c57dcaf930346ceb7ac /html/en/func/client.html
1 files changed, 255 insertions, 0 deletions
diff --git a/html/en/func/client.html b/html/en/func/client.html
new file mode 100644
index 0000000..20a6c4e
--- /dev/null
+++ b/html/en/func/client.html
@@ -0,0 +1,255 @@
+<!doctype HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+  <head>
+    <title>Client Images</title>
+    <meta http-equiv="Content-Language" content="en-us">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../../style.css">
+  </head>
+  <body>
+    <h2 align="center">Client Images</h2>
+    <p>There are 2 kinds of client images: RGB and Indexed RGB (or MAP). The RGB 
+      image is composed by 3 buffers: red, green and blue (more colors, more memory). 
+      The MAP image is composed by 1 buffer of indices for a table and one table of 
+      encoded RGB values (less colors, less memory).
+    </p>
+    <p>The image buffer is described by its width and height in pixels. The starting 
+      point of the buffer is the origin of the image, which is located at its bottom 
+      left corner. To retrieve a pixel in the image, use the formula <font>pixel(x,y)=buffer[y*width 
+        + x]</font>.
+    </p>
+    <p>The Put functions may do zoom in or out; zero order interpolation is used to 
+      scale the image. It is not possible to specify a part of the image to be drawn.</p>
+    <hr>
+    <pre class="function"><span class="mainFunction">void <a name="cdGetImageRGB">cdCanvasGetImageRGB</a>(cdCanvas* canvas, unsigned char *r, 
+                   unsigned char *g, 
+                   unsigned char *b, 
+                   int x, int y, int w, int h); [in C]</span>
+
+canvas:GetImageRGB(imagergb: cdImageRGB; x, y: number) [in Lua]</pre>
+    <p>Returns the red, green and blue components of each pixel in a server image. 
+      The RGB components are provided in three matrices stored as byte arrays. The <strong>
+        <tt>(i,j)</tt></strong> component of these matrices is at the address <strong><tt>
+          (j*w+i)</tt></strong>. As occurs with all primitives from the Canvas Draw 
+      library, the pixel <strong><tt>(0,0)</tt></strong> is at the bottom left 
+      corner, and the pixel <strong><tt>(w-1,h-1)</tt></strong> is that the upper 
+      right corner of the image rectangle.</p>
+    <pre class="function"><span class="mainFunction">void <a name="cdPutImageRectRGB">cdCanvasPutImageRectRGB</a>(cdCanvas* canvas, int iw, int ih, 
+                       const unsigned char *r, 
+                       const unsigned char *g, 
+                       const unsigned char *b, 
+                       int x, int y, int w, int h, 
+                       int xmin, int xmax, int ymin, int ymax); [in C]</span>
+void wdCanvasPutImageRectRGB(cdCanvas* canvas, int iw, int ih, 
+                       const unsigned char *r, 
+                       const unsigned char *g, 
+                       const unsigned char *b, 
+                       double x, double y, double w, double h, 
+                       int xmin, int xmax, int ymin, int ymax); (WC) [in C]
+
+canvas:PutImageRectRGB(imagergb: cdImageRGB; x, y, w, h, xmin, xmax, ymin, ymax: number) [in Lua]
+canvas:wPutImageRectRGB(imagergb: cdImageRGB; x, y, w, h, xmin, xmax, ymin, ymax: number) (WC) [in Lua]</pre>
+    <p>Puts, in a specified area of the canvas, an image with its red, green and blue 
+      components defined in the three matrices stored in byte arrays. The <strong><tt>(i,j)</tt></strong>
+      component of these matrices is at the address <strong><tt>(j*iw+i)</tt></strong>. 
+      The pixel <strong><tt>(0,0)</tt></strong> is at the bottom left corner, and the 
+      pixel <strong><tt>(iw-1,ih-1)</tt></strong> is that the upper right corner of 
+      the image rectangle.
+    </p>
+    <p>Parameters <strong><font>w</font></strong> and <font><strong>h</strong></font> 
+      refer to the target rectangle of the canvas, so that it is possible to reduce 
+      or expand the image drawn. If <strong><font>w</font></strong> and <strong><font>h</font></strong>
+      are 0, the size of the image is assumed (<strong><font>iw</font></strong> and <strong>
+        <font>ih</font></strong>).
+    </p>
+    <p>It also allows specifying a rectangle inside the image to be drawn, if <strong><font>
+          xmin</font>, <font>xmax</font>, <font>ymin</font> </strong>and <strong><font>ymax</font></strong>
+      are 0 then the whole image is assumed.
+    </p>
+    <p>If the driver has bpp &lt;=8 or only 256 colors or less, then the image is 
+      converted to 256 optimal colors using the function <strong><font>cdRGB2Map</font></strong>
+      and is drawn using <strong><font>cdPutImageRectMap</font></strong>.</p>
+    <pre class="function"><span class="mainFunction">void <a name="cdPutImageRectRGBA">cdCanvasPutImageRectRGBA</a>(cdCanvas* canvas, int iw, int ih, 
+                        const unsigned char *r, 
+                        const unsigned char *g, 
+                        const unsigned char *b, 
+                        const unsigned char *a, 
+                        int x, int y, int w, int h, 
+                        int xmin, int xmax, int ymin, int ymax); [in C]</span>
+void wdCanvasPutImageRectRGBA(cdCanvas* canvas, int iw, int ih, 
+                        const unsigned char *r, 
+                        const unsigned char *g, 
+                        const unsigned char *b, 
+                        const unsigned char *a, 
+                        double x, double y, double w, double h, 
+                        int xmin, int xmax, int ymin, int ymax); (WC) [in C]
+
+canvas:PutImageRectRGBA(imagergba: cdImageRGBA; x, y, w, h, xmin, xmax, ymin, ymax: number) [in Lua]
+canvas:wPutImageRectRGBA(imagergba: cdImageRGBA; x, y, w, h, xmin, xmax, ymin, ymax: number) (WC) [in Lua]</pre>
+    <p>The same as function&nbsp; <font><strong>cdPutImageRectRGB</strong></font>, 
+      except for the fact that it is possible to specify an alpha channel. The 
+      resulting color is the image color weighted by the alpha value, using the 
+      formula <strong><tt>result=(source * alpha + destiny * (255 - alpha))/255</tt></strong>. 
+      This means that, if alpha is 0, the resulting color is the target color 
+      (completely transparent), and, if alpha is 255, the resulting color is the 
+      original image color (completely opaque).</p>
+    <p>If this function is not defined for a given driver or if alpha is <font>NULL</font>, 
+      then the function <strong><font>cdPutImageRectRGB</font></strong> is used, as 
+      long as it is defined.</p>
+    <pre class="function"><span class="mainFunction">void <a name="cdPutImageRectMap">cdCanvasPutImageRectMap</a>(cdCanvas* canvas, int iw, int ih, 
+                       const unsigned char *index, 
+                       const long int *colors, 
+                       int x, int y, int w, int h, 
+                       int xmin, int xmax, int ymin, int ymax); [in C]</span>
+void wdCanvasPutImageRectMap(cdCanvas* canvas, int iw, int ih, 
+                       const unsigned char *index, 
+                       const long int *colors, 
+                       double x, double y, double w, double h, 
+                       int xmin, int xmax, int ymin, int ymax); (WC) [in C]
+
+canvas:PutImageRectMap(imagemap: cdImageMap; palette: cdPalette; x, y, w, h, xmin, xmax, ymin, ymax: number) [in Lua]
+canvas:wPutImageRectMap(imagemap: cdImageMap; palette: cdPalette; x, y, w, h, xmin, xmax, ymin, ymax: number) (WC) [in Lua]</pre>
+    <p>The same as function&nbsp; <font><strong>cdPutImageRectRGB</strong></font>, 
+      except for the fact that the colors are provided by means of an index matrix 
+      (map). The color corresponding to a given index is given in&nbsp; <font><b>colors[index]</b></font>. 
+      The map is also a matrix stored as a byte vector. If the color vector is null, 
+      then a vector with 256 gray tones is assumed.</p>
+    <pre class="function"><span class="mainFunction">void <a name="cdRGB2Map">cdRGB2Map</a>(int iw, int ih, 
+               const unsigned char *r, 
+               const unsigned char *g, 
+               const unsigned char *b, 
+               unsigned char *index, 
+               int pal_size, long *color); [in C]</span>
+
+cd.RGB2Map(imagergb: cdImageRGB, imagemap: cdImageMap, palette: cdPalette) [in Lua]</pre>
+    <p>Converts an RGB image into an image with 256 indexed colors. The resulting 
+      image must have the same size (width x length) as the RGB image. It is 
+      necessary to allocate memory for the arrays <strong><font>map</font></strong> and
+      <strong><font>colors</font></strong>. This is the same algorithm used in the IM 
+      library - in fact, the same code.</p>
+    <h3>Extras</h3>
+    <p>The following functions are used only for encapsulating the several types of 
+      client images from the library in a single structure, simplifying their 
+      treatment.&nbsp;</p>
+    <p>For such, a public structure was created, called <font><b>cdBitmap</b></font>, 
+      which will store the image. From this structure, the following fields are 
+      officially defined:</p>
+    <pre>cdBitmap:
+  int w      /* image width */
+  int h      /* image heigth */
+  int type   /* image type: CD_RGBA, CD_RGB or CD_MAP */</pre>
+    <pre class="function"><span class="mainFunction">cdBitmap* <a name="cdCreateBitmap">cdCreateBitmap</a>(int w, int h, int type); [in C]</span>
+
+cd.CreateBitmap(w, h, type: number) -&gt; (bitmap: cdBitmap) [in Lua]</pre>
+    <p>Creates an image with width <strong>w</strong>, and height <strong>h</strong> and 
+      of type <strong>type</strong>. The type can be <font>CD_RGBA, CD_RGB or CD_MAP</font>. 
+      However, <font>CD_MAP</font> only means that the image will have 256 colors if <strong>
+        type</strong> is greater than 0. It is assumed that the image will be MAP 
+      with the same number of colors in the palette as <strong>type</strong>. 
+      Internally, the color palette is always allocated with 256 entries, which may 
+      or may not be totally fulfilled. In this case, the value of <strong>type</strong> 
+    can be changed as wished.</p>
+    <pre class="function"><span class="mainFunction">cdBitmap* <a name="cdInitBitmap">cdInitBitmap</a>(int w, int h, int type, ...); [in C]</span>
+
+[There is no equivalent in Lua]</pre>
+    <p>Similar to <strong><font>cdCreateBitmap</font></strong>, but it accepts the 
+      data area already allocated by the user. The parameters vary according to the 
+      image type.</p>
+    <pre><font>CD_RGBA - (unsigned char* red, unsigned char* green, unsigned char* blue, unsigned char* alpha)
+CD_RGB - (unsigned char* red, unsigned char* green, unsigned char* blue)
+CD_MAP - (unsigned char* index, lont int* colors)</font></pre>
+    <pre class="function"><span class="mainFunction">void <a name="cdKillBitmap">cdKillBitmap</a>(cdBitmap* image); [in C]</span>
+
+cd.KillBitmap(bitmap: cdBitmap) [in Lua]</pre>
+    <p>Liberates the memory allocated for the image. If this function is not 
+    called in Lua, the garbage collector will call it.</p>
+    <pre class="function"><span class="mainFunction">unsigned char* <a name="cdBitmapGetData">cdBitmapGetData</a>(cdBitmap* image, int dataptr); [in C]</span>
+
+cd.BitmapGetData(bitmap: cdBitmap; dataptr: number) -&gt; (data: cdImageChannel) [in Lua]</pre>
+    <p>Returns a pointer to the image's data area according to <font><strong>dataptr</strong></font>. 
+      The following values are defined for <font><strong>dataptr</strong>:</font></p>
+    <pre><strong>CD_IRED</strong> - red component of an RGB image. cdImageChannel in Lua.
+<strong>CD_IGREEN</strong> - green component of an RGB image. cdImageChannel in Lua.
+<strong>CD_IBLUE</strong> - blue component of an RGB image. cdImageChannel in Lua.
+<strong>CD_IALPHA</strong> - alpha component of an RGBA image. cdImageChannel in Lua.
+<strong>CD_INDEX</strong> - indices of a MAP image. cdImageChannel in Lua.
+<strong>CD_COLORS</strong> - color table of a MAP image. In this case, a type conversion must be made to <strong>(long int*)</strong>.  cdPalette in Lua.</pre>
+    <p>In Lua, channels are also available as tables, see <a href="#DataAccess">Data 
+        Access</a>.&nbsp;
+    </p>
+    <pre class="function"><span class="mainFunction">void <a name="cdBitmapSetRect">cdBitmapSetRect</a>(cdBitmap* image, int xmin, int xmax, int ymin, int ymax); [in C]</span>
+
+cd.BitmapSetRect(bitmap: cdBitmap; xmin, xmax, ymin, ymax: number) [in Lua]</pre>
+    <p>Allows specifying a region of interest inside the image to be used by the 
+      function <b><font>cdPutBitmap</font></b>. If no region was defined, the whole 
+      image is used, that is, (0, w-1, 0, h-1).</p>
+    <pre class="function"><span class="mainFunction">void <a name="cdPutBitmap">cdCanvasPutBitmap</a>(cdCanvas* canvas, cdBitmap* image, int x, int y, int w, int h); [in C]</span>
+void wdCanvasPutBitmap(cdCanvas* canvas, cdBitmap* image, double x, double y, double w, double h); (WC) [in C]
+
+canvas:PutBitmap(image: cdBitmap; x, y, w, h: number) [in Lua]
+canvas:wPutBitmap(bitmap: cdBitmap; x, y, w, h: number) (WC) [in Lua]</pre>
+    <p>Draws the&nbsp; image in the position (x,y), changing the scale. It 
+      encapsulates <font><strong>cdPutImageRectRGB</strong>, <strong>cdPutImageRectRGBA</strong></font>
+      and <strong><font>cdPutImageRectMap</font></strong>. The region of the image 
+      drawn depends on the rectangle defined by <strong><font>cdBitmapSetRect</font></strong>. 
+      If no rectangle was defined, then the whole image is used.</p>
+    <p>The parameters <strong>w</strong> and <strong>h</strong> allow scaling the 
+      image, increasing or decreasing its dimensions when drawn. If&nbsp; <strong>w</strong>
+      and/or <strong>h</strong> are 0, then no scale change is assumed.
+    </p>
+    <pre class="function"><span class="mainFunction">void <a name="cdGetBitmap">cdCanvasGetBitmap</a>(cdCanvas* canvas, cdBitmap* image, int x, int y); [in C]</span>
+
+canvas:GetBitmap(bitmap: cdBitmap; x, y: number) [in Lua]</pre>
+    <p>Encapsulates <strong><font>cdGetImageRGB</font></strong>. Nothing happens if 
+      the image is MAP.</p>
+    <pre class="function"><span class="mainFunction">void <a name="cdBitmapRGB2Map">cdBitmapRGB2Map</a>(cdBitmap* image_rgb, cdBitmap* image_map); [in C]</span>
+
+cd.BitmapRGB2Map(bitmap_rgb: cdBitmap, bitmap_map: cdBitmap) [in Lua]</pre>
+    <p>Encapsulates <strong><font>cdRGB2Map</font></strong>. The images must be of 
+      types <font>RGB(A)</font> and <font>MAP</font>, respectively.</p>
+    <h3>Extras in Lua (Deprecated)</h3>
+    <pre class="function"><a name="cdCreateImageRGB">cd.CreateImageRGB</a>(width, height: number) -&gt; (imagergb: cdImageRGB)</pre>
+    <p>Creates an RGB image in Lua. Deprecated use <strong>cd.CreateBitmap</strong>.</p>
+    <pre class="function"><a name="cdKillImageRGB">cd.KillImageRGB</a>(imagergb: cdImageRGB)</pre>
+    <p>Destroys the created RGB image and liberates allocated memory. If this 
+    function is not called in Lua, the garbage collector will call it. Deprecated use <strong>
+        cd.KillBitmap</strong>.</p>
+    <pre class="function"><a name="cdCreateImageRGBA">cd.CreateImageRGBA</a>(width, height: number) -&gt; (imagergba: cdImageRGBA)</pre>
+    <p>Creates an RGBA image in Lua. Deprecated use <strong>cd.CreateBitmap</strong>.</p>
+    <pre class="function"><a name="cdKillImageRGBA">cd.KillImageRGBA</a>(imagergba: cdImageRGBA)</pre>
+    <p>Destroys the created RGBA image and liberates allocated memory. If this 
+    function is not called in Lua, the garbage collector will call it. Deprecated use <strong>
+        cd.KillBitmap</strong>.</p>
+    <pre class="function"><a name="cdCreateImageMap">cd.CreateImageMap</a>(width, height: number) -&gt; (imagemap: cdImageMap)</pre>
+    <p>Creates a Map image in Lua. Deprecated use <strong>cd.CreateBitmap</strong>.</p>
+    <pre class="function"><a name="cdKillImageMap">cd.KillImageMap</a>(imagemap: cdImageMap)</pre>
+    <p>Destroys the created Map image and liberates allocated memory. If this 
+    function is not called in Lua, the garbage collector will call it. Deprecated use <strong>
+        cd.KillBitmap</strong>.</p>
+    <h3><a name="DataAccess">Data Access</a></h3>
+    <p>Data access in Lua is done directly using the operator "<font>[y*width + x]</font>" 
+      in image channels. Each channel works as a value table which should be 
+      consulted or modified in the following way:</p>
+    <pre><font>image = cd.CreateBitmap(100, 200)
+...
+image.r[y*100 + x] = 255
+image.g[y*100 + x] = 128
+image.b[y*100 + x] = 0
+...
+green = image.g[y*100 + x] -- it will return 128</font></pre>
+    <p>The order of the tables <em>is</em> important, so that <font size="3">image[n].r</font>
+      has no meaning to CDLua and the expression will cause an error. Finally, 
+      the user could expect the value of <font size="3">image[n]</font> to be of type <font>
+        lightuserdata</font>. Unfortunately, this is not the case, and such expression 
+      will cause the same  error.</p>
+    <p>In the old <font>cdImageMap </font>images, the channel must be not 
+      specified: <font size="3">imagemap[y*100+x]</font>.</p>
+    <p>Known channel names are:</p>
+    <pre>r - red channel of RGB or RGBA images.
+g - gree channel of RGB or RGBA images.
+b - blue channel of RGB or RGBA images.
+a - alpha channel of RGBA images.
+m - indices channel of MAP images (valid only for cdBitmap objects).
+p - colors table of MAP images (valid only for cdBitmap objects). It is a cdPalette object.</pre>
+  </body>
+</html>
+\ No newline at end of file
author	scuri <scuri>	2008-10-17 06:10:33 +0000
committer	scuri <scuri>	2008-10-17 06:10:33 +0000
commit	7b52cc13af4e85f1ca2deb6b6c77de9c95ea0dcf (patch)
tree	d0857278bde2eff784227c57dcaf930346ceb7ac /html/en/func/client.html