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 iw, int ih); [in C] void wdCanvasGetImageRGB(cdCanvas* canvas, unsigned char *r, unsigned char *g, unsigned char *b, double x, double y, int iw, int ih); (WC) [in C] canvas:GetImageRGB(imagergb: cdImageRGB; x, y: number) [in Lua] canvas:wGetImageRGB(imagergb: cdImageRGB; x, y: number) (WC) [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 cdfCanvasPutImageRectRGB(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); [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:fPutImageRectRGB(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 cdfCanvasPutImageRectRGBA(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); [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:fPutImageRectRGBA(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 cdfCanvasPutImageRectMap(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); [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:fPutImageRectMap(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 cdCanvasGetImImage(cdCanvas* canvas, const imImage* image, int x, int y); [in C] void wdCanvasGetImImage(cdCanvas* canvas, const imImage* image, double x, double y); (WC) [in C] canvas:GetImImage(image: imImage, x,y: number) [in Lua] canvas:wGetImImage(image: imImage, x,y: number) (WC) [in Lua]
The same as the cdCanvasGetImageRGB functions except for the fact that use an imImage structure. Image must be a display RGB image (color_space=IM_RGB and data_type=IM_BYTE). See the CD_IMIMAGE. (since 5.9)
void cdCanvasPutImImage(cdCanvas* canvas, const imImage* image, int x, int y, int w, int h); [in C] void cdfCanvasPutImImage(cdCanvas* canvas, const imImage* image, double x, double y, double w, double h); [in C] void wdCanvasPutImImage(cdCanvas* canvas, const imImage* image, double x, double y, double w, double h); (WC) [in C] canvas:PutImImage(image: imImage, x,y,w,h: number) [in Lua] canvas:fPutImImage(image: imImage, x,y,w,h: number) [in Lua] canvas:wPutImImage(image: imImage, x,y,w,h: number) (WC) [in Lua]
The same as the above functions except for the fact that use an imImage structure. Image must be a displayable image (imImageIsBitmap), and it can has an alpha channel. See the CD_IMIMAGE. (since 5.9)
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 height) 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.
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 bitmap:Width() -> w: number [in Lua] int h -image heigth bitmap:Height() -> h: number [in Lua] int type -image type: CD_RGBA, CD_RGB or CD_MAP bitmap:Type() -> type: number [in Lua]
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.
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 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.