1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
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>
|
