Ruby extension library for using Thomas Boutell's gd library(http://www.boutell.com/gd/).
Originally written by Yukihiro Matsumoto (matz@ruby-lang.org)
Current maintainer: Ryuichi Tamura (tam@kais.kyoto-u.ac.jp)
GD -+
|
+- GD::Image
|
+- GD::Polygon
|
+- GD::Font
Module that defines some constants refered by GD::Image or GD::Polygon instances.
GD::Brushed
If this constant is used as the color when invoking a line-drawing method such as GD::Image#line or GD::Image#rectangle, the line to be drawn is the brush image that has been set with GD::Image#setBrush.
GD::Styled
If this constant is used as the color when invoking a line-drawing method such as GD::Image#line or GD::Image#rectangle, the colors of the pixels are drawn successively from the style that has been set with GD::Image#setStyle. If the color of a pixel is equal to GD::Transparent, that pixel is not altered.
GD::StyledBrushed
If this constant is used as the color when invoking a line-drawing method such as GD::Image#line or GD::Image#rectangle, the brush set with GD::Image#setBrush is drawn wherever the color specified in GD::Image#setStyle is neither zero nor GD::Transparent.
GD::Tiled
If this constant is used as the color when invoking a filling method such as GD::Image#filledRectangle, GD::Image#filledPolygon, GD::Image#fill, and GD::Image#fillToBorder. The area is filled with a tile image set with GD::Image#setTile.
GD::Transparent
Used in place of a normal color in a style to be set with GD::Image#setStyle. This constant is not the transparent color index of the image; for that functionality, see GD::Image#transparent.
GD::Image.new(width, height)
creates a new image instance with specified width and height.
GD::Image.newFromGd(file)
creates a new image instance from Gd file.
GD::Image.newFromGd2(file)
creates a new image instance from Gd2 file.
GD::Image.newFromGd2Part(file, srcX, srcY, width, height)
creates a new image instance from part of gd2 file.
GD::Image.newFromJpeg(file)
(gd-1.8 or later)
Creates a new image instance from JPEG file.
GD::Image.newFromPng(file)
creates a new image instance from PNG file.
GD::Image.newFromXbm(file)
creates a new image instance from Xbm file.
GD::Image.newFromXpm(file)
(gd-1.7 or later)
creates a new image instance from Xpm file.
GD::Image.stringTTF(fg_color, fnt_name, pt, angle, x, y, str)
(gd-1.6.1 or later)
Tries to find the bounding rectangle of str with size (pt) and the name of the TrueType font(fnt_name), and returns the array consists of the error message string and the array of each vertex of the rectangle(brect[8], see the figure in the section of GD::Image#stringTTF). If successful, the error message is nil. See also GD::Image#stringTTF.
GD::Image#destroy
Free the memory associated with the image instance.
GD::Image#interlace= val
If val is true, the image is interlaced. Otherwise and by default, the image is not interlaced.
GD::Image#colorAllocate(r, g, b)
GD::Image#colorAllocate(str)
Finds the first available color index in the image instance, and sets its RGB values to r, g, b, respectively and returns the index of the new color table entry. r, g, b take a value between 0 and 255. Also, you can specify a color as strings like "#FF00FF".
Note that the first time you invoke this method after creating a new image by GD::Image.new, the background color of the image is set.
You can allocate upto 256 colors to one image. If there is no space to allocate the requested color, this returns -1.
If you use gd-1.6.2 or later, you can use GD::Image#colorResolve, more robust way of color allocation.
GD::Image#colorClosest(r, g, b)
GD::Image#colorClosest(str)
Searches the colors which have been defined thus far in the image instance and returns the index of the color with RGB values closest to r, g, b, respectively. Also, you can specify a color as strings like "#FF00FF". If no color have been yet allocated to that image, this returns -1
This method is useful when a image instance which you want to allocate a new color is created from the image scanned from a photograph in which many colors will be used.
GD::Image#colorDeallocate(color)
This marks the color at the specified index as being ripe for reallocation. The next time GD::Image#colorAllocate is used, this entry will be replaced. You can call this method several times to deallocate multiple colors.
GD::Image#colorExact(r, g, b)
GD::Image#colorExact(str)
Searches the colors which have been defined thus far in the image instance and returns the index of the first color with RGB values which exactly match (r, g, b). If no allocated color matches the request precisely, this returns -1. Also, you can specify a color as strings like "#FF00FF".
GD::Image#colorResolve(r, g, b)
GD::Image#colorResolve(str)
(gd-1.6.2 or later)
Searches the colors which have been defined thus far in the image specified and returns the index of the first color with RGB values which exactly match those of the request. If no allocated color matches the request precisely, then this method tries to allocate the exact color. If there is no space left in the color table then this method returns the closest color (as in GD::Image#colorClosest).
Unlike GD::Image#colorAllocate, this method always returns an index of a color.
GD::Image#transparent(idx)
Sets the transparent color index for the specified image to the specified color index idx. To indicate that there should be no transparent color, set idx to -1.
Note that JPEG images do not support transparency, so this setting has no effect when writing JPEG images.
GD::Image#arc(cx, cy, width, height, start, end, color)
Draw a partial ellipse centered at the given point (cx,cy) with specified width width and height height in pixel with specified color. The arc begins at the position in degrees specified by start and ends at the position specified by end.
GD::Image#dashedLine(x1, y1, x2, y2, color)
This method is provided solely for backwards compatibility of the Boutell's gd library. When drawing a dashed line, new programs should use GD::Image#line with GD::Image#setStyle.
GD::Image#fill(x, y, color)
Flood a portion of the image with the specified color, beginning at the specified point (x,y) and flooding the surrounding region of the same color as the starting point. See also GD::Image#fillToBorder.
GD::Image#filledPolygon(points, color)
Draw a filled polygon with the verticies specified, using the color index specified. see also GD::Image#polygon.
GD::Image#filledRectangle(x1, y1, x2, y2, color)
Draw a filled rectangle. See also GD::Image#rectangle.
GD::Image#fillToBorder(x, y, border_color, color)
floods a portion of the image with the specified color, beginning at the specified point (x,y) and stopping at the specified border_color.
The border_color cannot be a special color such as GD::Tiled. It must be a proper solid color. However the fill color can be a special color.
GD::Image#line(x1, y1, x2, y2, color)
Draw a line between two endpoints (x1,y1) and (x2,y2). color is the color allocated by GD::Image#colorAllocate, or one of GD::Styled, GD::Brushed, GD::StyledBrushed.
GD::Image#polygon(points, color)
Draw a polygon with the verticies (at least 3) specified, using the color index. points is GD::Polygon instance. After you created the GD::Polygon instances and did some operation on the vertices, the poligon is drawn with this method.
GD::Image#rectangle(x1, y1, x2, y2, color)
Draw a rectangle with two corners(upper left is (x1,y1), lower right (x2, y2)) with the specified color index.
GD::Image#setBrush(image)
Set a "brush"(an image used to draw wide, shaped strokes) to image. image can be any of GD::Image instance.By setting the transparent color index of the brush image with GD::Image#transparent, a brush of any shape can be created. All line-drawing methods, such as GD::Image#line and GD::Image#polygon, will use the current brush if the special "color" GD::Brushed or GD::StyledBrushed is used when invoking them.
As for any image instance, brush image must be destroyed by GD::Image#destroy.
GD::Image#setPixel(x, y, color)
Set the color of a pixel at (x,y) to color index.
GD::Image#setStyle(color1, color2, ...)
Set the series of colors to be drawn repeatedly during the drawing by a method such as GD::Image#line. Each element of color is either the color index allocated by GD::Image#colorAllocate, or GD::Transparent if you want the color of the particular pixel left unchanged.
GD::Image#setTile(image)
Set the image to be tiled. image can be any GD::Image instance.
GD::Image#copy(dest_img, dest_X, dest_Y, self_X, self_Y, width, height)
Copy a portion of the image at (self_X, self_Y) with specified width and height to (dest_X, dest_Y) of dest_img.
GD::Image#copyMerge(dest_img, dest_X, dest_Y, self_X, self_Y, width, height, percent)
Copy the two images by an amount specified in the last parameter percent. Arguments except for this are identical to those of GD::Image#copy. If percent is equal to 100, then this method will function identically to GD::Image#copy i.e. the source image replaces the pixels in the destination. If the percent = 0, no action is taken.
This feature is most useful to 'highlight' sections of an image by merging a solid color with percent = 50.
GD::Image#copyMergeGray(dest_img, dest_X, dest_Y, self_X, self_Y, width, height, percent)
Identical to GD::Image#copyMerge, except that when merging images it preserves the hue of the source by converting the destination pixels to grey scale before the copy operation.
GD::Image#copyResized(dest_img, dest_X, dest_Y, self_X, self_Y, self_width, self_height, dest_X, dest_Y)
Copy a portion of the image at (self_X, self_Y) with specified self_width and self_height to dest_img at (dest_X, dest_Y) with specified dest_width and dest_height.
GD::Image#paletteCopy(dest)
Copies a palette to dest image, attempting to match the colors in the target image to the colors in the palette of the self.
GD::Image#char(font, x, y, char, color)
Draws a single character char at (x, y) with specified color. font is specified by one of GD::Font::TinyFont, GD::Font::SmallFont, GD::Font::MediumFont, GD::Font::LargeFont, GD::Font::GiantFont.
GD::Image#charUp(font, x, y, char, color)
Draws a single chracter char at (x, y) with specified color. char is drawn in a vertical direction, i.e. drawn with rotated in 90 degree. See also GD::Image#char.
GD::Image#string(font, x, y, str, color)
Draws multiple characters str on the image with the specified color. font is specified by one of GD::Font::TinyFont, GD::Font::SmallFont, GD::Font::MediumFont, GD::Font::LargeFont, GD::Font::GiantFont, or GD::Font instance created by GD::Font.new.
GD::Image#stringUp(font, x, y, str, color)
Draw multiple characters str on the image with the specified color. str is drawn in a vertical direction, i.e. drawn with rotated in 90 degree. See also GD::Image#string.
GD::Image#stringTTF(fg_color, fnt_name, pt, angle, x, y, str)
(gd-1.6.1 or later)
Draws a string str at (x, y) on the image using user-supplied TrueType fonts with specified fg_color. The location of TrueType font fnt_name is specified by full path. The string may be arbitrarily scaled at pt and rotated (angle in radians).
This method returns an array of 2 elements. the first element is the error message string, the 2nd is brect of the bounding rectangle with 8 elements. Each element of brect is illustrated as below:
(brect[6],brect[7]) (brect[4],brect[5])
+--------------------+
|( S t r i n g )|
+--------------------+
(brect[0],brect[1]) (brect[2],brect[3])
When the string is successfully drawn, error message is nil.
If you only want to know the brect of the bounding rectangle, you can use GD::Image.stringTTF.
GD::Image#bounds
Returns the width and height of the image as Array instance.
GD::Image#boundsSafe(x, y)
Returns true if specified point (x,y) is within the bounds of the image. Otherwise return false.
GD::Image#blue(idx)
Returns the blue component of the specified color index idx.
GD::Image#colorsTotal
Returns the number of colors currently allocated in the image.
GD::Image#getTransparent
Returns the current transparent color index of the image. Returns -1 if there is no transparent color.
GD::Image#getPixel(x, y)
Returns the color index of a pixel at (x,y)).
GD::Image#green(idx)
Returns the green component of the specified color index idx.
GD::Image#height
Returns the height of the image.
GD::Image#interlace
Returns true if the image is interlaced, and returns false otherwise.
GD::Image#red(idx)
Returns the red component of the specified color index idx.
GD::Image#rgb(idx)
Returns array of the RGB values for the specified index idx of the image.
GD::Image#width
Returns the width of the image.
GD::Image#gd(file)
Outputs the image to the specified file in Gd format.
GD::Image#gd2(file)
Outputs the image to the specified file in Gd2 format.
GD::Image#jpeg(file, quality)
(gd-1.8 or later)
Outputs the image to the specified file with quality in Jpeg format. If quality is set to nagative, the default IJG JPEG quality value (which should yield a good general quality size trade-off for most situations) is used. For practical purposes, quality should be a value in the range 0-95.
GD::Image#png(file)
Outputs the image to the specified file in PNG format.
GD::Image#wbmp(fg_color, file)
(gd-1.8 or later)
Outputs the specified image to the specified file in WBMP format.
WBMP file support is black and white only. The color index specified by the fg_color argument is the "foreground," and only pixels of this color will be set in the WBMP file. All other pixels will be considered "background."
GD::Polygon.new
Creates a new polygon instance. After some operations provided below, the polygon is drawn on the image by GD::Image#polygon method.
GD::Polygon#addPt(x, y)
Adds a new point(vertex) from which the polygon is formed.
GD::Polygon#deletePt(idx)
Deletes the the specified idx-th elements of the vertices.
GD::Polygon#getPt(idx)
Returns the value of the specified idx-th elements of the vertices.
GD::Polygon#map(dest_L, dest_T, dest_R, dest_B)
GD::Polygon#map([src_L, src_T, src_R, src_B,] dest_L, dest_T, dest_R, dest_B)
Maps the polygon from a source rectangle to an equivalent position in a destination rectangle, moving it and resizing it as necessary. Both the source and destination rectangles are given in (left,top,right,bottom) coordinates. See figure below.
This method takes 4 or 8 arguments. Note that if 4 arguments are given, source rectangle are automatically computed as the bounding box of the poligon, and maps it to the destination rectangle specified in the arguments.
<source rectangle> <destination rectangle>
(src_L, src_T) (dest_L, dest_T)
+--------------+ +----------+
| | | |
| | => | |
| | | |
+--------------+ | |
(src_R, src_B) +----------+
(dest_R, dest_B)
GD::Polygon#offset(dx, dy)
Offsets all the vertices of the polygon by dx pixels horizontally and dy pixels vertically.
GD::Polygon#setPt(idx, new_x, new_y)
Changes the value of the specified idx-th elements of the vertices to (new_x, new_y).
GD::Polygon#toPt(dx, dy)
Draw from current vertex to a new vertex, using relative (dx, dy) coordinates. If this is the first point, act like GD::Image#addPt.
GD::Polygon#scale(sx, sy)
Scales each vertex of the polygon by the X and Y factors indicated by sx and sy. For best results, move the center of the polygon to position (0,0) before you scale, then move it back to its previous position.
GD::Polygon#transform(sx,rx,sy,ry,tx,ty)
Runs each vertex of the polygon through a transformation matrix, where sx and sy are the X and Y scaling factors, rx and ry are the X and Y rotation factors, and tx and ty are X and Y offsets.
GD::Polygon#bounds
Returns the smallest rectangle that completely encloses the polygon. The return value is an array containing the [left,top,right,bottom] of the rectangle.
GD::Polygon#length
Returns the number of the vertices.
GD::Polygon#vertices
Returns all of the coodinates of the vertices as Array instance.
GD::Font.new(name)
Creates a new font instance. The font is specified by its name, which is one of "Tiny", "Small", "Medium", "Large", "Giant". These strings correspond to GD::Font::TinyFont, GD::Font::SmallFont, GD::Font::MediumFont, GD::Font::LargeFont, GD::Font::GiantFont, respectively.
The instance becomes the arguments in the charcter/string drawing method such as GD::Image#char, GD::Image#string.
GD::Font#height
Returns the height of each character of the font.
GD::Font#nchars
Returns the number of characeters in the font.
GD::Font#offset
Returns the offset of the first character in the font.
GD::Font#width
Returns the width of each character of the font.
These constants also becomes the arguments in the charcter/string drawing method such as GD::Image#char, GD::Image#string.
GD::Font::GiantFont
This stands for 9x15 bold font:
-Misc-Fixed-Bold-R-Normal-Sans-15-140-75-75-C-90-ISO8859-2
GD::Font::LargeFont
This stands for the public domain 8x16 font:
-misc-fixed-medium-r-normal--16-140-75-75-c-80-iso8859-2
GD::Font::MediumFont
This stands for the a public domain 7x13 font:
-misc-fixed-bold-r-normal-sans-13-94-100-100-c-70-iso8859-2
GD::Font::SmallFont
This stands for a well known public domain 6x12 font:
-misc-fixed-medium-r-semicondensed-sans-12-116-75-75-c-60-iso8859-2
GD::Font::TinyFont
This stands for almost unreadable font, 5x8 pixels wide:
-Misc-Fixed-Medium-R-Normal--8-80-75-75-C-50-ISO8859-2