Client Images

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/func/client.html | 255 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 html/en/func/client.html (limited to 'html/en/func/client.html') 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 @@ + + + + Client Images + + + + + +

Client Images

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

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 pixel(x,y)=buffer[y*width + + x]. +

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.

void cdCanvasGetImageRGB(cdCanvas* canvas, unsigned char *r, 
+                   unsigned char *g, 
+                   unsigned char *b, 
+                   int x, int y, int w, int h); [in C]
+
+canvas:GetImageRGB(imagergb: cdImageRGB; x, y: number) [in Lua]

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 + (i,j) component of these matrices is at the address + (j*w+i). As occurs with all primitives from the Canvas Draw + library, the pixel (0,0) is at the bottom left + corner, and the pixel (w-1,h-1) is that the upper + right corner of the image rectangle.

void cdCanvasPutImageRectRGB(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]
+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]

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 (i,j) + component of these matrices is at the address (j*iw+i). + The pixel (0,0) is at the bottom left corner, and the + pixel (iw-1,ih-1) is that the upper right corner of + the image rectangle. +

Parameters w and h + refer to the target rectangle of the canvas, so that it is possible to reduce + or expand the image drawn. If w and h + are 0, the size of the image is assumed (iw and + ih). +

It also allows specifying a rectangle inside the image to be drawn, if + xmin, xmax, ymin and ymax + are 0 then the whole image is assumed. +

If the driver has bpp <=8 or only 256 colors or less, then the image is + converted to 256 optimal colors using the function cdRGB2Map + and is drawn using cdPutImageRectMap.

void cdCanvasPutImageRectRGBA(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]
+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]

The same as function cdPutImageRectRGB, + 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 result=(source * alpha + destiny * (255 - alpha))/255. + 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).

If this function is not defined for a given driver or if alpha is NULL, + then the function cdPutImageRectRGB is used, as + long as it is defined.

void cdCanvasPutImageRectMap(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]
+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]

The same as function cdPutImageRectRGB, + 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 colors[index]. + 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.

void cdRGB2Map(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]
+
+cd.RGB2Map(imagergb: cdImageRGB, imagemap: cdImageMap, palette: cdPalette) [in Lua]

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 map and + colors. This is the same algorithm used in the IM + library - in fact, the same code.

Extras

The following functions are used only for encapsulating the several types of + client images from the library in a single structure, simplifying their + treatment.

For such, a public structure was created, called cdBitmap, + which will store the image. From this structure, the following fields are + officially defined:

cdBitmap:
+  int w      /* image width */
+  int h      /* image heigth */
+  int type   /* image type: CD_RGBA, CD_RGB or CD_MAP */

cdBitmap* cdCreateBitmap(int w, int h, int type); [in C]
+
+cd.CreateBitmap(w, h, type: number) -> (bitmap: cdBitmap) [in Lua]

Creates an image with width w, and height h and + of type type. The type can be CD_RGBA, CD_RGB or CD_MAP. + However, CD_MAP only means that the image will have 256 colors if + type is greater than 0. It is assumed that the image will be MAP + with the same number of colors in the palette as type. + Internally, the color palette is always allocated with 256 entries, which may + or may not be totally fulfilled. In this case, the value of type + can be changed as wished.

cdBitmap* cdInitBitmap(int w, int h, int type, ...); [in C]
+
+[There is no equivalent in Lua]

Similar to cdCreateBitmap, but it accepts the + data area already allocated by the user. The parameters vary according to the + image type.

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)

void cdKillBitmap(cdBitmap* image); [in C]
+
+cd.KillBitmap(bitmap: cdBitmap) [in Lua]

Liberates the memory allocated for the image. If this function is not + called in Lua, the garbage collector will call it.

unsigned char* cdBitmapGetData(cdBitmap* image, int dataptr); [in C]
+
+cd.BitmapGetData(bitmap: cdBitmap; dataptr: number) -> (data: cdImageChannel) [in Lua]

Returns a pointer to the image's data area according to dataptr. + The following values are defined for dataptr:

CD_IRED - red component of an RGB image. cdImageChannel in Lua.
+CD_IGREEN - green component of an RGB image. cdImageChannel in Lua.
+CD_IBLUE - blue component of an RGB image. cdImageChannel in Lua.
+CD_IALPHA - alpha component of an RGBA image. cdImageChannel in Lua.
+CD_INDEX - indices of a MAP image. cdImageChannel in Lua.
+CD_COLORS - color table of a MAP image. In this case, a type conversion must be made to (long int*).  cdPalette in Lua.

In Lua, channels are also available as tables, see Data + Access. +

void cdBitmapSetRect(cdBitmap* image, int xmin, int xmax, int ymin, int ymax); [in C]
+
+cd.BitmapSetRect(bitmap: cdBitmap; xmin, xmax, ymin, ymax: number) [in Lua]

Allows specifying a region of interest inside the image to be used by the + function cdPutBitmap. If no region was defined, the whole + image is used, that is, (0, w-1, 0, h-1).

void cdCanvasPutBitmap(cdCanvas* canvas, cdBitmap* image, int x, int y, int w, int h); [in C]
+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]

Draws the image in the position (x,y), changing the scale. It + encapsulates cdPutImageRectRGB, cdPutImageRectRGBA + and cdPutImageRectMap. The region of the image + drawn depends on the rectangle defined by cdBitmapSetRect. + If no rectangle was defined, then the whole image is used.

The parameters w and h allow scaling the + image, increasing or decreasing its dimensions when drawn. If w + and/or h are 0, then no scale change is assumed. +

void cdCanvasGetBitmap(cdCanvas* canvas, cdBitmap* image, int x, int y); [in C]
+
+canvas:GetBitmap(bitmap: cdBitmap; x, y: number) [in Lua]

Encapsulates cdGetImageRGB. Nothing happens if + the image is MAP.

void cdBitmapRGB2Map(cdBitmap* image_rgb, cdBitmap* image_map); [in C]
+
+cd.BitmapRGB2Map(bitmap_rgb: cdBitmap, bitmap_map: cdBitmap) [in Lua]

Encapsulates cdRGB2Map. The images must be of + types RGB(A) and MAP, respectively.

Extras in Lua (Deprecated)

cd.CreateImageRGB(width, height: number) -> (imagergb: cdImageRGB)

Creates an RGB image in Lua. Deprecated use cd.CreateBitmap.

cd.KillImageRGB(imagergb: cdImageRGB)

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 + cd.KillBitmap.

cd.CreateImageRGBA(width, height: number) -> (imagergba: cdImageRGBA)

Creates an RGBA image in Lua. Deprecated use cd.CreateBitmap.

cd.KillImageRGBA(imagergba: cdImageRGBA)

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 + cd.KillBitmap.

cd.CreateImageMap(width, height: number) -> (imagemap: cdImageMap)

Creates a Map image in Lua. Deprecated use cd.CreateBitmap.

cd.KillImageMap(imagemap: cdImageMap)

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 + cd.KillBitmap.

Data Access

Data access in Lua is done directly using the operator "[y*width + x]" + in image channels. Each channel works as a value table which should be + consulted or modified in the following way:

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

The order of the tables is important, so that image[n].r + has no meaning to CDLua and the expression will cause an error. Finally, + the user could expect the value of image[n] to be of type + lightuserdata. Unfortunately, this is not the case, and such expression + will cause the same error.

In the old cdImageMap images, the channel must be not + specified: imagemap[y*100+x].

Known channel names are:

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.

+ + \ No newline at end of file -- cgit v1.2.3