Client Images

void cdGetImageRGB(unsigned char *r, unsigned char *g, unsigned char *b, int x, int y, int w, int h); [in C]
cdGetImageRGB(imagergb: imagergb_tag; 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 cdPutImageRectRGB(int iw, int ih, unsigned char *r, unsigned char *g, unsigned char *b, int x, int y, int w, int h, int xmin, int xmax, int ymin, int ymax); [in C]
void wdPutImageRectRGB(int iw, int ih, unsigned char *r, unsigned char *g, unsigned char *b, double x, double y, double w, double h, int xmin, int xmax, int ymin, int ymax); (WC) [in C]
cdPutImageRectRGB(imagergb: imagergb_tag; x, y, w, h, xmin, xmax, ymin, ymax: number) [in Lua]
wdPutImageRectRGB(imagergb: imagergb_tag; 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). As occurs with all primitives from the Canvas Draw library, 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. It allows specifying a rectangle in the image to be drawn. If xmin, xmax, ymin and ymax are 0, then the whole image is assumed. If w and h are 0, the size of the image is assumed (iw and ih). 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 cdPutImageRectRGBA(int iw, int ih, unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a, int x, int y, int w, int h, int xmin, int xmax, int ymin, int ymax); [in C]
void wdPutImageRectRGBA(int iw, int ih, unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a, double x, double y, double w, double h, int xmin, int xmax, int ymin, int ymax); (WC) [in C]
cdPutImageRectRGBA(imagergba: imagergba_tag; x, y, w, h, xmin, xmax, ymin, ymax: number) [in Lua]
wdPutImageRectRGBA(imagergba: imagergba_tag; 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 + destine * (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 cdPutImageRGB is used, as long as it is defined.

void cdPutImageRectMap(int iw, int ih, unsigned char *index, long int *colors, int x, int y, int w, int h, int xmin, int xmax, int ymin, int ymax); [in C]
void wdPutImageRectMap(int iw, int ih, unsigned char *index, long int *colors, double x, double y, double w, double h, int xmin, int xmax, int ymin, int ymax); (WC) [in C]
cdPutImageRectMap(imagemap: imagemap_tag; palette: palette_tag; x, y, w, h, xmin, xmax, ymin, ymax: number) [in Lua]
wdPutImageRectMap(imagemap: imagemap_tag; palette: palette_tag; 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 width, int height, unsigned char *red, unsigned char *green, unsigned char *blue, unsigned char *map, int pal_size, long *color); [in C]
cdRGB2Map(imagergb: imagergb_tag, imagemap: imagemap_tag) [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.

Server Images

void* cdCreateImage(int w, int h); [in C]
cdCreateImage(w, h: number) -> (image: image_tag) [in Lua]

Creates a compatible image in the server's memory with  wxh pixels. A compatible image has the same color representation (number of bits per pixel) as the server's canvas. The server image can only be used with an active canvas of the same type as the canvas that was active when the image was created. The default background is the same as the canvas, CD_WHITE. Server image functions are usually more efficient than those of client images.

void cdKillImage(void *image); [in C]
cdKillImage(image: image_tag) [in Lua]

Liberates memory allocated for the image. It is not necessary to have an active canvas to call this function.

void cdGetImage(void *image, int x, int y); [in C]
cdGetImage(image: image_tag; x, y: number) [in Lua]

Copies a rectangular region from the current rectangular context to the memory (image). (x,y) is the coordinate of the bottom left corner of the rectangular region. The width and length of the rectangular region are defined in the image structure (when the image is created).

void cdPutImageRect(void *image, int x, int y, int xmin, int xmax, int ymin, int ymax); [in C]
void wdPutImageRect(void* image, double x, double y, int xmin, int xmax, int ymin, int ymax); (WC) [in C]
cdPutImageRect(image: image_tag; x, y, xmin, xmax, ymin, ymax: number) [in Lua]
wdPutImageRect(image: image_tag; x, y, xmin, xmax, ymin, ymax: number) (WC) [in Lua]

Copies an image in a rectangular region of the canvas with the bottom left corner in (x,y). Allows specifying a rectangle in the image to be drawn. If xmin, xmax, ymin and ymax are 0, then the whole image is assumed.

void cdScrollArea(int xmin, int xmax, int ymin, int ymax, int dx, int dy); [in C]
cdScrollArea(xmin, xmax, ymin, ymax, dx, dy: number) [in Lua]

Copies the rectangle defined by the coordinates (xmin,ymin) and (xmax,ymax) to the rectangle defined by (xmin+dx,ymin+dy) and (xmax+dx,ymax+dy). It has the same effect as cdGetImage followed by cdPutImage, but it should be faster and does not require the explicit creation of an image to be executed. Note that the region belonging to the first rectangle, but not to the second, remains unchanged (the function does not clean this region).

Auxiliary Image Functions

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

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

cdImageEx
  int w;      /* image width */
  int h;      /* image heigth */
  int type;   /* image type: CD_SERVER, CD_RGBA, CD_RGB or CD_MAP(256) */

cdImageEx* cdCreateImageEx(int w, int h, int type); [in C]
cdCreateImageEx(w, h, type: number) -> (image: imageex_tag) [in Lua]

Creates an image with width w, and height h and of type type. The type can be CD_SERVER, 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. It also encapsulates cdCreateImage.

cdImageEx* cdCreateImageDataEx(int w, int h, int type, ...); [in C]
[There is no equivalent in Lua]

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

CD_SERVER - (void* image)
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 cdKillImageEx(cdImageEx* image); [in C]
cdKillImageEx(image: imageex_tag) [in Lua]

Liberates the memory allocated for the image. It is not necessary to have an active canvas to call this function. It also encapsulates cdKillImage.

unsigned char* cdImageDataEx(cdImageEx* image, int dataptr); [in C]
cdImageDataEx(image: imageex_tag; dataptr: number) [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.
CD_IGREEN - green component of an RGB image.
CD_IBLUE - blue component of an RGB image.
CD_IALPHA - alpha component of an RGBA image.
CD_INDEX - indices of a MAP image.
CD_COLORS - color table of a MAP image. In this case, a type conversion must be made to (long int*).
CD_ISERVER - server image.

void cdImageRectEx(cdImageEx* image, int xmin, int xmax, int ymin, int ymax); [in C]
cdImageRectEx(image: imageex_tag; xmin, xmax, ymin, ymax: number) [in Lua]

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

void cdPutImageEx(cdImageEx* image, int x, int y, int w, int h); [in C]
void wdPutImageEx(cdImageEx* image, double x, double y, double w, double h); (WC) [in C]
cdPutImageEx(image: imageex_tag; x, y, w, h: number) [in Lua]
wdPutImageEx(image: imageex_tag; x, y, w, h: number) (WC) [in Lua]

Draws the  image in the position (x,y), changing the scale. It encapsulates cdPutImageRect, cdPutImageRectRGB, cdPutImageRectRGBA and cdPutImageRectMap. For server images, w and h are ignored. The region of the image drawn depends on the rectangle defined by cdImageRectEx. If no rectangle was defined, then the whole image is used.

The parameters w and h allow distorting the image, increasing or decreasing its dimensions when drawn. If  w and/or h are 0, then no scale change is assumed. These parameters are ignored for server images.

void cdGetImageEx(cdImageEx* image, int x, int y); [in C]
cdGetImageEx(image: imageex_tag; x, y: number) [in Lua]

Encapsulates cdGetImageRGB and cdGetImage. Nothing happens if the image is MAP.

void cdRGB2MapEx(cdImageEx* image_rgb, cdImageEx* image_map); [in C]
cdRGB2MapEx(image_rgb: imageex_tag, image_map: imageex_tag) [in Lua]

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