ruby-gd 0.7.4

Sign up to get free protection for your applications and to get access to all the features.
data/doc/manual.rd ADDED
@@ -0,0 +1,969 @@
1
+ =begin
2
+
3
+ = Ruby/GD Version 0.7.4
4
+
5
+ Ruby extension library for using Thomas Boutell's gd
6
+ library(http://www.boutell.com/gd/).
7
+
8
+ Originally written by Yukihiro Matsumoto (matz@ruby-lang.org)
9
+
10
+ Current maintainer: Ryuichi Tamura (tam@kais.kyoto-u.ac.jp)
11
+
12
+ ((* If gd-2.0.x is installed in your system, and Ruby/GD is compiled
13
+ with (({--enable-gd2_0})) option, you can use those constants or
14
+ methods described in the subsection "gd-2.0.0 or higher"*))
15
+
16
+ == Module/Class Hierarchy
17
+
18
+ GD -+
19
+ |
20
+ +- GD::Image
21
+ |
22
+ +- GD::Polygon
23
+ |
24
+ +- GD::Font
25
+
26
+ = Module GD
27
+
28
+ Module that defines some constants refered by GD::Image or GD::Polygon
29
+ instances.
30
+
31
+ == Constants
32
+
33
+ --- GD::Brushed
34
+
35
+ If this constant is used as the color when invoking a line-drawing
36
+ method such as ((<GD::Image#line>)) or ((<GD::Image#rectangle>)), the
37
+ line to be drawn is the brush image that has been set with
38
+ ((<GD::Image#setBrush>)).
39
+
40
+ --- GD::Styled
41
+
42
+ If this constant is used as the color when invoking a line-drawing
43
+ method such as ((<GD::Image#line>)) or ((<GD::Image#rectangle>)), the
44
+ colors of the pixels are drawn successively from the style that has
45
+ been set with ((<GD::Image#setStyle>)). If the color of a pixel is
46
+ equal to ((<GD::Transparent>)), that pixel is not altered.
47
+
48
+ --- GD::StyledBrushed
49
+
50
+ If this constant is used as the color when invoking a line-drawing
51
+ method such as ((<GD::Image#line>)) or ((<GD::Image#rectangle>)), the
52
+ brush set with ((<GD::Image#setBrush>)) is drawn wherever the color
53
+ specified in ((<GD::Image#setStyle>)) is neither zero nor
54
+ ((<GD::Transparent>)).
55
+
56
+ --- GD::Tiled
57
+
58
+ If this constant is used as the color when invoking a filling method
59
+ such as ((<GD::Image#filledRectangle>)),
60
+ ((<GD::Image#filledPolygon>)), ((<GD::Image#fill>)), and
61
+ ((<GD::Image#fillToBorder>)). The area is filled with a tile image set
62
+ with ((<GD::Image#setTile>)).
63
+
64
+ --- GD::Transparent
65
+
66
+ Used in place of a normal color in a style to be set with
67
+ ((<GD::Image#setStyle>)). This constant is not the transparent color
68
+ index of the image; for that functionality, see
69
+ ((<GD::Image#transparent>)).
70
+
71
+ --- GD::GD2_FMT_COMPRESSED
72
+
73
+ specifies Gd2 image to be compressed. This constant is used in
74
+ ((<GD::Image#gd2>)).
75
+
76
+ --- GD::GD2_FMT_RAW
77
+
78
+ specifies Gd2 image to be uncompressed. This constant is used in
79
+ ((<GD::Image#gd2>)).
80
+
81
+
82
+ === gd-2.0.0 or higher
83
+
84
+ --- GD::AlphaTransparent
85
+
86
+ --- GD::AlphaOpaque
87
+
88
+ These constants are used in ((<GD::Image.trueColorAlpha>)), and each
89
+ defines the upper(127) and lower(0) bounds of alpha channel value,
90
+ respectively. Full transparency corresponds to GD::AlphaTransparent.
91
+
92
+ --- GD::Arc
93
+
94
+ --- GD::Chord
95
+
96
+ --- GD::Pie
97
+
98
+ --- GD::NoFill
99
+
100
+ --- GD::Edged
101
+
102
+ These constants become options that specify how an arc is drawn with
103
+ using ((<GD::Image#filledArc>)). See also ((<GD::Image#filledArc>)).
104
+
105
+
106
+ = Class GD::Image
107
+
108
+ == Class Methods
109
+
110
+ + Instance Creation
111
+
112
+ --- GD::Image.new(width, height)
113
+
114
+ creates a new palette image instance with specified ((|width|)) and
115
+ ((|height|)).
116
+
117
+ --- GD::Image.newFromGd(file)
118
+
119
+ creates a new image instance from Gd file. ((|file|)) is a File
120
+ object.
121
+
122
+ --- GD::Image.new_from_gd(filename)
123
+
124
+ creates a new Gd image instance from ((|filename|)). ((|filename|))
125
+ is a String object which specifies the localtion of the image file.
126
+
127
+ --- GD::Image.newFromGd2(file)
128
+
129
+ creates a new image instance from Gd2 file. ((|file|)) is a File
130
+ object.
131
+
132
+ --- GD::Image.new_from_gd2(filename)
133
+
134
+ creates a new Gd2 image instance from ((|filename|)). ((|filename|))
135
+ is a String object which specifies the location of the image file.
136
+
137
+ --- GD::Image.newFromGd2Part(file, srcX, srcY, width, height)
138
+
139
+ creates a new image instance from part of Gd2 file. ((|file|)) is a
140
+ File object.
141
+
142
+ --- GD::Image.new_from_gd2_part(filename)
143
+
144
+ creates a new Gd2 image instance from ((|filename|)). ((|filename|))
145
+ is a String object which specifies the location of the image file.
146
+
147
+ --- GD::Image.newFromJpeg(file)
148
+ (gd-1.8 or later)
149
+
150
+ Creates a new image instance from JPEG file. ((|file|)) is a File
151
+ object.
152
+
153
+ --- GD::Image.new_from_jpeg(filename)
154
+
155
+ creates a new Jpeg image instance from ((|filename|)). ((|filename|))
156
+ is a String object which specifies the location of the image file.
157
+
158
+ --- GD::Image.newFromPng(file)
159
+
160
+ creates a new image instance from PNG file. ((|file|)) is a File
161
+ object.
162
+
163
+ --- GD::Image.new_from_png(filename)
164
+
165
+ creates a new PNG image instance from ((|filename|)). ((|filename|))
166
+ is a String object which specifies the location of the image file.
167
+
168
+ --- GD::Image.newFromXbm(file)
169
+
170
+ creates a new image instance from Xbm file. ((|file|)) is a File
171
+ object.
172
+
173
+ --- GD::Image.new_from_xbm(filename)
174
+
175
+ creates a new XBitmap image instance from
176
+ ((|filename|)). ((|filename|)) is a String object which specifies the
177
+ location of the image file.
178
+
179
+
180
+ --- GD::Image.newFromXpm(file)
181
+ (gd-1.7 or later)
182
+
183
+ creates a new image instance from Xpm file. ((|file|)) is a File
184
+ object.
185
+
186
+ --- GD::Image.new_from_xpm(filename)
187
+
188
+ creates a new XPixmaps image instance from
189
+ ((|filename|)). ((|filename|)) is a String object which specifies the
190
+ location of the image file.
191
+
192
+ + Query
193
+
194
+ --- GD::Image.stringTTF(fg_color, fnt_name, pt, angle, x, y, str)
195
+ (gd-1.6.1 or later)
196
+
197
+ Tries to find the bounding rectangle of ((|str|)) with size (((|pt|)))
198
+ and the name of the TrueType font(((|fnt_name|))), and returns the
199
+ array consists of the error message string and the array of each
200
+ vertex of the rectangle(brect[8], see the figure in the section of
201
+ ((<GD::Image#stringTTF>))). If successful, the error message is
202
+ ((:nil:)). See also ((<GD::Image#stringTTF>)).
203
+
204
+ --- GD::Image.stringFT(fg_color, fnt_name, pt, angle, x, y, str)
205
+ (gd-1.8.4)
206
+
207
+ This method provides the same functionarity as
208
+ ((<GD::Image.stringTTF>)) does, but uses FreeType2 library when
209
+ redering the string. See also ((<GD::Image#stringFT>))
210
+
211
+ === gd-2.0.0 or higher
212
+
213
+ --- GD::Image.newTrueColor(width, height)
214
+
215
+ Creates a new truecolor image instance with specified ((|width|)) and
216
+ ((|height|)).
217
+
218
+ --- GD::Image.trueColor(r, g, b)
219
+ --- GD::Image.trueColor(rgbstr)
220
+
221
+ returns the RGBA color value for drawing on a truecolor image, or an
222
+ image created by ((<GD::Image.newTrueColor>)). ((|r|)), ((|g|)),
223
+ ((|b|)) values are in the range between 0 and 255. Or, you can
224
+ specify it by ((|rgbstr|)) which is in the range between "#000000" and
225
+ "#FFFFFF".
226
+
227
+ --- GD::Image.trueColor(r, g, b, alpha)
228
+ --- GD::Image.trueColorAlpha(rgbstr, alpha)
229
+
230
+ returns the RGBA color value for drawing on a truecolor image, or an
231
+ image created by ((<GD::Image.newTrueColor>)) with alpha channel
232
+ transparency. Because gd has 7-bit alpha channel, the ((|alpha|))
233
+ value takes between 0(opaque) and 127(transparent).
234
+
235
+ These class methods are used for ((*truecolor*)) images. If you want
236
+ to specify alpha value for ((*palette*)) images, use
237
+ ((<GD::Image#colorAllocateAlpha>)), ((<GD::Image#colorExactAlpha>)),
238
+ ((<GD::Image#colorClosestAlpha>)), or
239
+ ((<GD::Image#colorResolveAlpha>)) instead.
240
+
241
+
242
+ == Methods
243
+
244
+ --- GD::Image#destroy
245
+
246
+ Free the memory associated with the image instance.
247
+
248
+ --- GD::Image#interlace=(val)
249
+
250
+ If ((|val|)) is ((:true:)), the image is interlaced. Otherwise and by
251
+ default, the image is not interlaced.
252
+
253
+ === Color Handling
254
+
255
+ --- GD::Image#colorAllocate(r, g, b)
256
+ --- GD::Image#colorAllocate(str)
257
+
258
+ Finds the first available color index in the image instance, and sets
259
+ its RGB values to ((|r|)), ((|g|)), ((|b|)), respectively and returns
260
+ the index of the new color table entry. ((|r|)), ((|g|)), ((|b|)) take
261
+ a value between 0 and 255. Also, if you use Ruby-1.6.0 or later, you
262
+ can specify a color as strings like "#FF00FF".
263
+
264
+ Note that the first time you invoke this method after creating a new
265
+ image by ((<GD::Image.new>)), ((*the background color*)) of the image
266
+ is set.
267
+
268
+ You can allocate upto 256 colors to one image. If there is no space to
269
+ allocate the requested color, this returns -1.
270
+
271
+ If you use gd-1.6.2 or later, you can use
272
+ ((<GD::Image#colorResolve>)), more robust way of color allocation.
273
+
274
+ --- GD::Image#colorClosest(r, g, b)
275
+ --- GD::Image#colorClosest(str)
276
+
277
+ Searches the colors which have been defined thus far in the image
278
+ instance and returns the index of the color with RGB values closest to
279
+ ((|r|)), ((|g|)), ((|b|)), respectively. Also, if you use Ruby-1.6.0
280
+ or later, you can specify a color as strings like "#FF00FF".If no
281
+ color have been yet allocated to that image, this returns -1
282
+
283
+ This method is useful when a image instance which you want to allocate
284
+ a new color is created from the image scanned from a photograph in
285
+ which many colors will be used.
286
+
287
+ --- GD::Image#colorDeallocate(color)
288
+
289
+ This marks the ((|color|)) at the specified index as being ripe for
290
+ reallocation. The next time ((<GD::Image#colorAllocate>)) is used,
291
+ this entry will be replaced. You can call this method several times
292
+ to deallocate multiple colors.
293
+
294
+ --- GD::Image#colorExact(r, g, b)
295
+ --- GD::Image#colorExact(str)
296
+
297
+ Searches the colors which have been defined thus far in the image
298
+ instance and returns the index of the first color with RGB values
299
+ which exactly match (((|r|)), ((|g|)), ((|b|))). If no allocated color
300
+ matches the request precisely, this returns -1. Also, if you use
301
+ Ruby-1.6.0 or later, you can specify a color as strings like
302
+ "#FF00FF".
303
+
304
+ --- GD::Image#colorResolve(r, g, b)
305
+ --- GD::Image#colorResolve(str)
306
+ (gd-1.6.2 or later)
307
+
308
+ Searches the colors which have been defined thus far in the image
309
+ specified and returns the index of the first color with RGB values
310
+ which exactly match those of the request. Also, if you use Ruby-1.6.0
311
+ or later, you can specify a color as strings like "#FF00FF".
312
+
313
+ If no allocated color matches the request precisely, then this method
314
+ tries to allocate the exact color.If there is no space left in the
315
+ color table then this method returns the closest color (as in
316
+ ((<GD::Image#colorClosest>))).
317
+
318
+ Unlike ((<GD::Image#colorAllocate>)), this method always returns an
319
+ index of a color.
320
+
321
+ --- GD::Image#transparent(idx)
322
+
323
+ Sets the transparent color index for the specified image to the
324
+ specified color index ((|idx|)). To indicate that there should be no
325
+ transparent color, set ((|idx|)) to -1.
326
+
327
+ Note that JPEG images ((*do not support*)) transparency, so this
328
+ setting has no effect when writing JPEG images.
329
+
330
+ + Drawing and Filling
331
+
332
+ --- GD::Image#arc(cx, cy, width, height, start, end, color)
333
+
334
+ Draw a partial ellipse centered at the given point (((|cx|)),((|cy|)))
335
+ with specified width ((|width|)) and height ((|height|)) in pixel with
336
+ specified ((|color|)). The arc begins at the position in degrees
337
+ specified by ((|start|)) and ends at the position specified by
338
+ ((|end|)).
339
+
340
+ --- GD::Image#dashedLine(x1, y1, x2, y2, color)
341
+
342
+ This method is provided solely for backwards compatibility of the
343
+ Boutell's gd library. When drawing a dashed line, new programs should
344
+ use ((<GD::Image#line>)) with ((<GD::Image#setStyle>)).
345
+
346
+ --- GD::Image#fill(x, y, color)
347
+
348
+ Flood a portion of the image with the specified ((|color|)), beginning
349
+ at the specified point (((|x|)),((|y|))) and flooding the surrounding
350
+ region of the same color as the starting point. See also
351
+ ((<GD::Image#fillToBorder>)).
352
+
353
+ --- GD::Image#filledPolygon(points, color)
354
+
355
+ Draw a filled polygon with the verticies specified, using the
356
+ ((|color|)) index specified. see also ((<GD::Image#polygon>)).
357
+
358
+ --- GD::Image#filledRectangle(x1, y1, x2, y2, color)
359
+
360
+ Draw a filled rectangle. See also ((<GD::Image#rectangle>)).
361
+
362
+ --- GD::Image#fillToBorder(x, y, border_color, color)
363
+
364
+ floods a portion of the image with the specified ((|color|)),
365
+ beginning at the specified point (((|x|)),((|y|))) and stopping at the
366
+ specified ((|border_color|)).
367
+
368
+ The ((|border_color|)) cannot be a special color such as
369
+ ((<GD::Tiled>)). It must be a proper solid color. However the fill
370
+ ((|color|)) can be a special color.
371
+
372
+ --- GD::Image#line(x1, y1, x2, y2, color)
373
+
374
+ Draw a line between two endpoints (((|x1|)),((|y1|))) and
375
+ (((|x2|)),((|y2|))). ((|color|)) is the color allocated by
376
+ ((<GD::Image#colorAllocate>)), or one of ((<GD::Styled>)),
377
+ ((<GD::Brushed>)), ((<GD::StyledBrushed>)).
378
+
379
+ --- GD::Image#polygon(points, color)
380
+
381
+ Draw a polygon with the verticies (at least 3) specified, using the
382
+ ((|color|)) index. ((|points|)) is ((:GD::Polygon:)) instance. After
383
+ you created the ((:GD::Polygon:)) instances and did some operation on
384
+ the vertices, the poligon is drawn with this method.
385
+
386
+ --- GD::Image#rectangle(x1, y1, x2, y2, color)
387
+
388
+ Draw a rectangle with two corners(upper left is (((|x1|)),((|y1|))),
389
+ lower right (((|x2|)), ((|y2|)))) with the specified ((|color|))
390
+ index.
391
+
392
+ --- GD::Image#setBrush(image)
393
+
394
+ Set a "brush"(an image used to draw wide, shaped strokes) to
395
+ ((|image|)). ((|image|)) can be any of ((:GD::Image:)) instance.By
396
+ setting the transparent color index of the brush image with
397
+ ((<GD::Image#transparent>)), a brush of any shape can be created. All
398
+ line-drawing methods, such as ((<GD::Image#line>)) and
399
+ ((<GD::Image#polygon>)), will use the current brush if the special
400
+ "color" ((<GD::Brushed>)) or ((<GD::StyledBrushed>)) is used when
401
+ invoking them.
402
+
403
+ As for any image instance, brush image must be destroyed by
404
+ ((<GD::Image#destroy>)).
405
+
406
+ --- GD::Image#setPixel(x, y, color)
407
+
408
+ Set the color of a pixel at (((|x|)),((|y|))) to ((|color|)) index.
409
+
410
+ --- GD::Image#setStyle(color1, color2, ...)
411
+
412
+ Set the series of colors to be drawn repeatedly during the drawing by
413
+ a method such as ((<GD::Image#line>)). Each element of ((|color|)) is
414
+ either the color index allocated by ((<GD::Image#colorAllocate>)), or
415
+ ((<GD::Transparent>)) if you want the color of the particular pixel
416
+ left unchanged.
417
+
418
+ --- GD::Image#setTile(image)
419
+
420
+ Set the image to be tiled. ((|image|)) can be any ((:GD::Image:)) instance.
421
+
422
+ + Copy and Merge
423
+
424
+ --- GD::Image#copy(dest_img, dest_X, dest_Y, self_X, self_Y, width, height)
425
+
426
+ Copy a portion of the image at (((|self_X, self_Y|))) with specified
427
+ ((|width|)) and ((|height|)) to (((|dest_X|)), ((|dest_Y|))) of
428
+ ((|dest_img|)).
429
+
430
+ --- GD::Image#copyMerge(dest_img, dest_X, dest_Y, self_X, self_Y, width, height, percent)
431
+
432
+ Copy the two images by an amount specified in the last parameter
433
+ ((|percent|)). Arguments except for this are identical to those of
434
+ ((<GD::Image#copy>)). If ((|percent|)) is equal to 100, then this
435
+ method will function identically to ((<GD::Image#copy>)) i.e. the
436
+ source image replaces the pixels in the destination. If the
437
+ ((|percent|)) = 0, no action is taken.
438
+
439
+ This feature is most useful to 'highlight' sections of an image by
440
+ merging a solid color with ((|percent|)) = 50.
441
+
442
+ --- GD::Image#copyMergeGray(dest_img, dest_X, dest_Y, self_X, self_Y, width, height, percent)
443
+
444
+ Identical to ((<GD::Image#copyMerge>)), except that when merging
445
+ images it preserves the hue of the source by converting the
446
+ destination pixels to grey scale before the copy operation.
447
+
448
+ --- GD::Image#copyResized(dest_img, dest_X, dest_Y, self_X, self_Y, self_width, self_height, dest_X, dest_Y)
449
+
450
+ Copy a portion of the image at (((|self_X, self_Y|))) with specified
451
+ ((|self_width|)) and ((|self_height|)) to ((|dest_img|)) at
452
+ (((|dest_X|)), ((|dest_Y|))) with specified ((|dest_width|)) and
453
+ ((|dest_height|)).
454
+
455
+ --- GD::Image#paletteCopy(dest)
456
+
457
+ Copies a palette to ((|dest|)) image, attempting to match the colors
458
+ in the target image to the colors in the palette of the self.
459
+
460
+ + Font and text handling
461
+
462
+ --- GD::Image#char(font, x, y, char, color)
463
+
464
+ Draws a single character ((|char|)) at (((|x|)), ((|y|))) with
465
+ specified ((|color|)). ((|font|)) is specified by one of
466
+ ((<GD::Font::TinyFont>)), ((<GD::Font::SmallFont>)),
467
+ ((<GD::Font::MediumFont>)), ((<GD::Font::LargeFont>)),
468
+ ((<GD::Font::GiantFont>)).
469
+
470
+ --- GD::Image#charUp(font, x, y, char, color)
471
+
472
+ Draws a single chracter ((|char|)) at (((|x|)), ((|y|))) with
473
+ specified ((|color|)). ((|char|)) is drawn in a vertical direction,
474
+ i.e. drawn with rotated in 90 degree. See also ((<GD::Image#char>)).
475
+
476
+ --- GD::Image#string(font, x, y, str, color)
477
+
478
+ Draws multiple characters ((|str|)) on the image with the specified
479
+ ((|color|)). ((|font|)) is specified by one of
480
+ ((<GD::Font::TinyFont>)), ((<GD::Font::SmallFont>)),
481
+ ((<GD::Font::MediumFont>)), ((<GD::Font::LargeFont>)),
482
+ ((<GD::Font::GiantFont>)), or ((:GD::Font:)) instance created by
483
+ ((<GD::Font.new>)).
484
+
485
+ --- GD::Image#stringUp(font, x, y, str, color)
486
+
487
+ Draw multiple characters ((|str|)) on the image with the specified
488
+ ((|color|)). ((|str|)) is drawn in a vertical direction, i.e. drawn
489
+ with rotated in 90 degree. See also ((<GD::Image#string>)).
490
+
491
+ --- GD::Image#stringTTF(fg_color, fnt_name, pt, angle, x, y, str)
492
+
493
+ (gd-1.6.1 or later)
494
+
495
+ Draws a string ((|str|)) at (((|x|)), ((|y|))) on the image using
496
+ user-supplied TrueType fonts with specified ((|fg_color|)). The
497
+ location of TrueType font ((|fnt_name|)) is specified by full path.
498
+ The string may be arbitrarily scaled at ((|pt|)) and rotated
499
+ (((|angle|)) in radians).
500
+
501
+ This method returns an array of 2 elements. the first element is the
502
+ error message string, the 2nd is ((*brect*)) of the bounding rectangle
503
+ with 8 elements. Each element of ((*brect*)) is illustrated as below:
504
+
505
+ (brect[6],brect[7]) (brect[4],brect[5])
506
+ +--------------------+
507
+ |( S t r i n g )|
508
+ +--------------------+
509
+ (brect[0],brect[1]) (brect[2],brect[3])
510
+
511
+ When the string is successfully drawn, error message is ((:nil:)).
512
+
513
+ If you only want to know the brect of the bounding rectangle, you can
514
+ use ((<GD::Image.stringTTF>)).
515
+
516
+ --- GD::Image#stringFT(fg_color, fnt_name, pt, angle, x, y, str)
517
+ (gd-1.8.4)
518
+
519
+ This method provides the same functionarity as
520
+ ((<GD::Image#stringTTF>)) does, but uses FreeType2 library when
521
+ redering the string.
522
+
523
+ + Query
524
+
525
+ --- GD::Image#bounds
526
+
527
+ Returns the width and height of the image as Array instance.
528
+
529
+ --- GD::Image#boundsSafe(x, y)
530
+
531
+ Returns ((:true:)) if specified point (((|x|)),((|y|))) is within the
532
+ bounds of the image. Otherwise return ((:false:)).
533
+
534
+ --- GD::Image#blue(idx)
535
+
536
+ Returns the blue component of the specified color index ((|idx|)).
537
+
538
+ --- GD::Image#colorsTotal
539
+
540
+ Returns the number of colors currently allocated in the image.
541
+
542
+ --- GD::Image#getTransparent
543
+
544
+ Returns the current transparent color index of the image. Returns -1
545
+ if there is no transparent color.
546
+
547
+ --- GD::Image#getPixel(x, y)
548
+
549
+ Returns the color index of a pixel at (((|x|)),((|y|)))).
550
+
551
+ --- GD::Image#green(idx)
552
+
553
+ Returns the green component of the specified color index ((|idx|)).
554
+
555
+ --- GD::Image#height
556
+
557
+ Returns the height of the image.
558
+
559
+ --- GD::Image#interlace
560
+
561
+ Returns ((:true:)) if the image is interlaced, and returns ((:false:)) otherwise.
562
+
563
+ --- GD::Image#red(idx)
564
+
565
+ Returns the red component of the specified color index ((|idx|)).
566
+
567
+ --- GD::Image#rgb(idx)
568
+
569
+ Returns array of the RGB values for the specified index ((|idx|)) of
570
+ the image.
571
+
572
+ --- GD::Image#width
573
+
574
+ Returns the width of the image.
575
+
576
+ + Output
577
+
578
+ --- GD::Image#gd(file)
579
+
580
+ Outputs the image to the specified ((|file|)) in Gd format.
581
+
582
+ --- GD::Image#gd2(file, chunk_size, fmt)
583
+
584
+ Outputs the image to the specified ((|file|)) in Gd2 format with
585
+ specified ((|chunk_size|)) and ((|fmt|)). A gd2 Image are stored as a
586
+ series of compressed/uncompressed subimages. You can specify
587
+ ((|chunk_size|)) which determines the size of the subimages. If
588
+ ((|chunk_size|)) is set zero, the default size is used. Whether the image
589
+ is compressed or uncompressed is determined by ((|fmt|)) being
590
+ ((<GD::GD2_FMT_COMPRESSED>)) or
591
+ ((<GD::GD2_FMT_RAW>)), respectively.
592
+
593
+ --- GD::Image#jpeg(file, quality)
594
+ (gd-1.8 or later)
595
+
596
+ Outputs the image to the specified ((|file|)) with ((|quality|)) in
597
+ Jpeg format. If ((|quality|)) is set to nagative, the default IJG JPEG
598
+ quality value (which should yield a good general quality size
599
+ trade-off for most situations) is used. For practical purposes,
600
+ quality should be a value in the range 0-95.
601
+
602
+ --- GD::Image#jpegStr(quality)
603
+ (gd-1.8 or later)
604
+
605
+ Outputs the Jpeg image as String object with specified ((|quality|)).
606
+ This method will be especially useful when you want to transmit an
607
+ image ((*directly*)) to an user(i.e, without first writing it to a
608
+ file).
609
+
610
+ This method is provided by Colin Steele(colin@webg2.com).
611
+
612
+ --- GD::Image#png(file)
613
+
614
+ Outputs the image to the specified ((|file|)) in PNG format.
615
+
616
+ --- GD::Image#pngStr(file)
617
+
618
+ Outputs the image in PNG format as String object. This method will be
619
+ especially useful when you want to transmit an image ((*directly*)) to
620
+ an user(i.e, without first writing it to a file).
621
+
622
+ --- GD::Image#wbmp(fg_color, file)
623
+ (gd-1.8 or later)
624
+
625
+ Outputs the specified image to the specified file in WBMP format.
626
+
627
+ WBMP file support is ((*black*)) and ((*white*)) only. The color index
628
+ specified by the ((|fg_color|)) argument is the "foreground," and only
629
+ pixels of this color will be set in the WBMP file. All other pixels
630
+ will be considered "background."
631
+
632
+
633
+ === gd-2.0.0 or higher
634
+
635
+ + Color handling
636
+
637
+ --- GD::Image#colorAllocateAlpha(r, g, b, alpha)
638
+ --- GD::Image#colorAllocateAlpha(rgbstr, alpha)
639
+
640
+ Finds the first available color index in the image specified, sets its
641
+ RGBA values to those requested and returns the index of the new color
642
+ table entry, or an RGBA value in the case of a truecolor image; in
643
+ either case you can then use the returned value as a parameter to
644
+ drawing functions. The ((|alpha|)) value takes between 0(opaque) and
645
+ 127(transparent).
646
+
647
+ See also ((<GD::Image#colorAllocate>)).
648
+
649
+ --- GD::Image#colorExactAlpha(r, g, b, alpha)
650
+ --- GD::Image#colorExactAlpha(rgbstr, alpha)
651
+
652
+ Searches the colors which have been defined thus far in the image
653
+ specified and returns the index of the first color entry which exactly
654
+ match those of the request, or an RGBA value in the case of a
655
+ truecolor image; in either case you can then use the returned value as
656
+ a parameter to drawing functions.The ((|alpha|)) value takes between
657
+ 0(opaque) and 127(transparent).
658
+
659
+ See also ((<GD::Image#colorExact>)).
660
+
661
+ --- GD::Image#colorClosestAlpha(r, g, b, alpha)
662
+ --- GD::Image#colorClosestAlpha(rgbstr, alpha)
663
+
664
+ Searches the colors which have been defined thus far in the palette
665
+ image specified and returns the index of the color with RGBA values
666
+ closest to those of the request. The ((|alpha|)) value takes between
667
+ 0(opaque) and 127(transparent).
668
+
669
+ Closeness is determined by Euclidian distance, which is used to
670
+ determine the distance in four-dimensional color/alpha space between
671
+ colors.
672
+
673
+ When applied to a truecolor image, this method always succeeds in
674
+ returning the desired color.
675
+
676
+ See also ((<GD::Image#colorClosest>)).
677
+
678
+ --- GD::Image#colorResolveAlpha(r, g, b, alpha)
679
+ --- GD::Image#colorResolveAlpha(rgbstr, alpha)
680
+
681
+ Searches the colors which have been defined thus far in the palette
682
+ image specified and returns the index of the first color with RGBA
683
+ values which exactly match those of the request. The ((|alpha|)) value
684
+ takes between 0(opaque) and 127(transparent).
685
+
686
+ If no allocated color matches the request precisely, then it tries to
687
+ allocate the exact color. If there is no space left in the color table
688
+ then it returns the closest color (as in
689
+ ((<GD::Image#closestAlpha>))).
690
+
691
+ This method always returns an index of a color. When applied to a
692
+ truecolor image, this function always succeeds in returning the
693
+ desired color.
694
+
695
+ See also ((<GD::Image#colorResolve>)).
696
+
697
+ --- GD::Image#alphaBlending=(bool)
698
+
699
+ Specifies the different modes for drawing on ((*truecolor*)) images.
700
+ When ((|bool|)) sets ((:true:))("blending mode"), how much of the
701
+ underlying color should be allowed to shine through is determined by
702
+ the alpha channel value of the color.
703
+
704
+ This blending mode is effective for the following drawing operations,
705
+ and in this mode, the existing color at the drawing point is blended
706
+ with drawing color with its alpha value.
707
+
708
+ When ((|bool|)) sets ((:false:))("non-blending mode"), the existing
709
+ color at the drawing point is replaced by the drawing color with its
710
+ own alpha value.
711
+
712
+ Note that this blending mode is not available when drawing on
713
+ ((*palette*)) images.
714
+
715
+ --- GD::Image#alpha(color)
716
+
717
+ Returns the alpha channel component (between 0 and 127) of the
718
+ specified color index.
719
+
720
+
721
+ + Image manipulation
722
+
723
+ --- GD::Image#copyResampled(dest_img, dest_X, dest_Y, self_X, self_Y, dest_width, dest_height, self_width, self_height)
724
+
725
+ Copies a rectangular portion of one image to another image, smoothly
726
+ interpolating pixel values so that, in particular, reducing the size
727
+ of an image still retains a great deal of clarity.
728
+
729
+ Pixel values are interpolated only if the destination image is a
730
+ truecolor image. Otherwise, for a palette image, the same
731
+ functionality as ((<GD::Image#copyResized>)) will be invoked.
732
+
733
+ See also ((<GD::Image#copyResized>)), for a version which does not
734
+ interpolate pixel values.
735
+
736
+ --- GD::Image#filledEllipse(cx, cy, width, height, start, end, color)
737
+
738
+ draws an ellipse centered at the given point (((|cx|)), ((|cy|))),
739
+ with the specified ((|width|)) and ((|height|)) in pixels.
740
+
741
+ The ellipse is filled in the ((|color|)) and is drawn by beginning
742
+ from ((|start|)) degrees and ending at ((|end|)) degrees. ((|end|))
743
+ must be greater than ((|start|)). Values greater than 360 are
744
+ interpreted modulo 360.
745
+
746
+ --- GD::Image#filledArc(cx, cy, width, height, start, end, color, style)
747
+
748
+ draws an partial ellipse(arc) centered at the given point (((|cx|)),
749
+ ((|cy|))), with the specified ((|width|)) and ((|height|)) in pixels,
750
+ and filled in the ((|color|)). The arc begins at ((|start|)) degrees
751
+ and ends at ((|end|)) degrees.
752
+
753
+ The last argument is bitwise (({OR})) of the following possibilities.
754
+
755
+ * (({GD::Arc}))
756
+
757
+ draws the rounded edge between ((|start|)) and ((|end|)).
758
+
759
+ * (({GD::Chord}))
760
+
761
+ draws the line connecting ((|start|)) and ((|end|)).
762
+
763
+ * (({GD::Pie}))
764
+
765
+ synonym for (({GD::Arc}))
766
+
767
+
768
+ * (({GD::NoFill}))
769
+
770
+ indicates Pie and Chord should be outlined, not filled.
771
+
772
+ * (({GD::Edged}))
773
+
774
+ used together with (({GD::NoFill})), indicates that the beginning and
775
+ ending angles should be connected to the center; this is a good way to
776
+ outline (rather than fill) a 'pie slice'.
777
+
778
+ --- GD::Image#to_paletteImage(dither_flag, colors)
779
+
780
+ transforms the truecolor image to palette image. If ((|dither_flag|))
781
+ is ((:true:)), the image will be dithered to approximate colors
782
+ better, at the expense of some obvious "speckling." ((|colors|)) may
783
+ be anything up to 256, but if the image includes the photographic
784
+ information, or is a JPEG image, 256 is strongly recommended.
785
+
786
+ + Query methods
787
+
788
+ --- GD::Image#is_trueColor?
789
+
790
+ returns ((:true:)) if the image is a truecolor image.
791
+
792
+ --- GD::Image#is_palette?
793
+
794
+ returns ((:true:)) if the image is a palette image.
795
+
796
+ --- GD::Image#thickness=(val)
797
+
798
+ specifies the line thickness (defaults to 1) that affects methods
799
+ drawing lines or curves.
800
+
801
+ = Class GD::Polygon
802
+
803
+ == Class Methods
804
+
805
+ --- GD::Polygon.new
806
+
807
+ Creates a new polygon instance. After some operations provided below,
808
+ the polygon is drawn on the image by ((<GD::Image#polygon>)) method.
809
+
810
+ == Methods
811
+
812
+ + Operation
813
+
814
+ --- GD::Polygon#addPt(x, y)
815
+
816
+ Adds a new point(vertex) from which the polygon is formed.
817
+
818
+ --- GD::Polygon#deletePt(idx)
819
+
820
+ Deletes the the specified ((|idx|))-th elements of the vertices.
821
+
822
+ --- GD::Polygon#getPt(idx)
823
+
824
+ Returns the value of the specified ((|idx|))-th elements of the
825
+ vertices.
826
+
827
+ --- GD::Polygon#map(dest_L, dest_T, dest_R, dest_B)
828
+ --- GD::Polygon#map([src_L, src_T, src_R, src_B,] dest_L, dest_T, dest_R, dest_B)
829
+
830
+ Maps the polygon from a source rectangle to an equivalent position in
831
+ a destination rectangle, moving it and resizing it as necessary. Both
832
+ the source and destination rectangles are given in
833
+ (left,top,right,bottom) coordinates. See figure below.
834
+
835
+ This method takes 4 or 8 arguments. Note that if 4 arguments are
836
+ given, source rectangle are automatically computed as the bounding box
837
+ of the poligon, and maps it to the destination rectangle specified in
838
+ the arguments.
839
+
840
+
841
+ <source rectangle> <destination rectangle>
842
+ (src_L, src_T) (dest_L, dest_T)
843
+ +--------------+ +----------+
844
+ | | | |
845
+ | | => | |
846
+ | | | |
847
+ +--------------+ | |
848
+ (src_R, src_B) +----------+
849
+ (dest_R, dest_B)
850
+
851
+ --- GD::Polygon#offset(dx, dy)
852
+
853
+ Offsets all the vertices of the polygon by ((|dx|)) pixels
854
+ horizontally and ((|dy|)) pixels vertically.
855
+
856
+ --- GD::Polygon#setPt(idx, new_x, new_y)
857
+
858
+ Changes the value of the specified ((|idx|))-th elements of the
859
+ vertices to (((|new_x|)), ((|new_y|))).
860
+
861
+ --- GD::Polygon#toPt(dx, dy)
862
+
863
+ Draw from current vertex to a new vertex, using relative (((|dx|)),
864
+ ((|dy|))) coordinates. If this is the first point, act like
865
+ ((<GD::Image#addPt>)).
866
+
867
+ --- GD::Polygon#scale(sx, sy)
868
+
869
+ Scales each vertex of the polygon by the X and Y factors indicated by
870
+ ((|sx|)) and ((|sy|)). For best results, move the center of the
871
+ polygon to position (0,0) before you scale, then move it back to its
872
+ previous position.
873
+
874
+ --- GD::Polygon#transform(sx,rx,sy,ry,tx,ty)
875
+
876
+ Runs each vertex of the polygon through a transformation matrix, where
877
+ ((|sx|)) and ((|sy|)) are the X and Y scaling factors, ((|rx|)) and
878
+ ((|ry|)) are the X and Y rotation factors, and ((|tx|)) and ((|ty|))
879
+ are X and Y offsets.
880
+
881
+ + Query
882
+
883
+ --- GD::Polygon#bounds
884
+
885
+ Returns the smallest rectangle that completely encloses the polygon.
886
+ The return value is an array containing the [left,top,right,bottom] of
887
+ the rectangle.
888
+
889
+ --- GD::Polygon#length
890
+
891
+ Returns the number of the vertices.
892
+
893
+ --- GD::Polygon#vertices
894
+
895
+ Returns all of the coodinates of the vertices as Array instance.
896
+
897
+ = Class GD::Font
898
+
899
+ == Class Methods
900
+
901
+ --- GD::Font.new(name)
902
+
903
+ Creates a new font instance. The font is specified by its
904
+ ((|name|)), which is one of "((*Tiny*))", "((*Small*))",
905
+ "((*Medium*))", "((*Large*))", "((*Giant*))". These strings correspond
906
+ to ((<GD::Font::TinyFont>)), ((<GD::Font::SmallFont>)),
907
+ ((<GD::Font::MediumFont>)), ((<GD::Font::LargeFont>)),
908
+ ((<GD::Font::GiantFont>)), respectively.
909
+
910
+ The instance becomes the arguments in the charcter/string drawing
911
+ method such as ((<GD::Image#char>)), ((<GD::Image#string>)).
912
+
913
+ == Methods
914
+
915
+ --- GD::Font#height
916
+
917
+ Returns the height of each character of the font.
918
+
919
+ --- GD::Font#nchars
920
+
921
+ Returns the number of characeters in the font.
922
+
923
+ --- GD::Font#offset
924
+
925
+ Returns the offset of the first character in the font.
926
+
927
+ --- GD::Font#width
928
+
929
+ Returns the width of each character of the font.
930
+
931
+ == Constants
932
+
933
+ These constants also becomes the arguments in the charcter/string
934
+ drawing method such as ((<GD::Image#char>)), ((<GD::Image#string>)).
935
+
936
+ --- GD::Font::GiantFont
937
+
938
+ This stands for 9x15 bold font:
939
+ -Misc-Fixed-Bold-R-Normal-Sans-15-140-75-75-C-90-ISO8859-2
940
+
941
+ --- GD::Font::LargeFont
942
+
943
+ This stands for the public domain 8x16 font:
944
+ -misc-fixed-medium-r-normal--16-140-75-75-c-80-iso8859-2
945
+
946
+ --- GD::Font::MediumFont
947
+
948
+ This stands for the a public domain 7x13 font:
949
+ -misc-fixed-bold-r-normal-sans-13-94-100-100-c-70-iso8859-2
950
+
951
+ --- GD::Font::SmallFont
952
+
953
+ This stands for a well known public domain 6x12 font:
954
+ -misc-fixed-medium-r-semicondensed-sans-12-116-75-75-c-60-iso8859-2
955
+
956
+ --- GD::Font::TinyFont
957
+
958
+ This stands for almost unreadable font, 5x8 pixels wide:
959
+ -Misc-Fixed-Medium-R-Normal--8-80-75-75-C-50-ISO8859-2
960
+
961
+
962
+ = Reference
963
+
964
+ * index.html distributed with gd-1.8.4
965
+ * index.html distributed with gd-2.0.1
966
+ * gd.h distributed with gd-2.0.1
967
+ * documents embedded in GD.pm version 1.30
968
+
969
+ =end