diff options
Diffstat (limited to 'html/en/func/client.html')
| -rw-r--r-- | html/en/func/client.html | 255 |
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 <=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 <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 <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 <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. </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) -> (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) -> (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>. + </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 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 <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) -> (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) -> (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) -> (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 |