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)
If gd-2.0.x is installed in your system, and Ruby/GD is compiled
with --enable-gd2_0 option, you can use those constants or
methods described in the subsection "gd-2.0.0 or higher"
GD -+
|
+- GD::Image
|
+- GD::Polygon
|
+- GD::Font
Module that defines some constants refered by GD::Image or GD::Polygon instances.
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.
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.
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.
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.
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.
specifies Gd2 image to be compressed. This constant is used in GD::Image#gd2.
specifies Gd2 image to be uncompressed. This constant is used in GD::Image#gd2.
These constants are used in GD::Image.trueColorAlpha, and each defines the upper(127) and lower(0) bounds of alpha channel value, respectively. Full transparency corresponds to GD::AlphaTransparent.
These constants become options that specify how an arc is drawn with using GD::Image#filledArc. See also GD::Image#filledArc.
creates a new palette image instance with specified width and height.
creates a new image instance from Gd file. file is a File object.
creates a new Gd image instance from filename. filename is a String object which specifies the localtion of the image file.
creates a new image instance from Gd2 file. file is a File object.
creates a new Gd2 image instance from filename. filename is a String object which specifies the location of the image file.
creates a new image instance from part of Gd2 file. file is a File object.
creates a new Gd2 image instance from filename. filename is a String object which specifies the location of the image file.
(gd-1.8 or later)
Creates a new image instance from JPEG file. file is a File object.
creates a new Jpeg image instance from filename. filename is a String object which specifies the location of the image file.
creates a new image instance from PNG file. file is a File object.
creates a new PNG image instance from filename. filename is a String object which specifies the location of the image file.
creates a new image instance from Xbm file. file is a File object.
creates a new XBitmap image instance from filename. filename is a String object which specifies the location of the image file.
(gd-1.7 or later)
creates a new image instance from Xpm file. file is a File object.
creates a new XPixmaps image instance from filename. filename is a String object which specifies the location of the image file.
(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-1.8.4)
This method provides the same functionarity as GD::Image.stringTTF does, but uses FreeType2 library when redering the string. See also GD::Image#stringFT
Creates a new truecolor image instance with specified width and height.
returns the RGBA color value for drawing on a truecolor image, or an image created by GD::Image.newTrueColor. r, g, b values are in the range between 0 and 255. Or, you can specify it by rgbstr which is in the range between "#000000" and "#FFFFFF".
returns the RGBA color value for drawing on a truecolor image, or an image created by GD::Image.newTrueColor with alpha channel transparency. Because gd has 7-bit alpha channel, the alpha value takes between 0(opaque) and 127(transparent).
These class methods are used for truecolor images. If you want to specify alpha value for palette images, use GD::Image#colorAllocateAlpha, GD::Image#colorExactAlpha, GD::Image#colorClosestAlpha, or GD::Image#colorResolveAlpha instead.
Free the memory associated with the image instance.
If val is true, the image is interlaced. Otherwise and by default, the image is not interlaced.
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, if you use Ruby-1.6.0 or later, 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.
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, if you use Ruby-1.6.0 or later, 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.
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.
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, if you use Ruby-1.6.0 or later, you can specify a color as strings like "#FF00FF".
(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. Also, if you use Ruby-1.6.0 or later, you can specify a color as strings like "#FF00FF".
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.
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.
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.
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.
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.
Draw a filled polygon with the verticies specified, using the color index specified. see also GD::Image#polygon.
Draw a filled rectangle. See also GD::Image#rectangle.
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.
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.
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.
Draw a rectangle with two corners(upper left is (x1,y1), lower right (x2, y2)) with the specified color index.
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.
Set the color of a pixel at (x,y) to color index.
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.
Set the image to be tiled. image can be any GD::Image instance.
Copy a portion of the image at (self_X, self_Y) with specified width and height to (dest_X, dest_Y) of dest_img.
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.
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.
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.
Copies a palette to dest image, attempting to match the colors in the target image to the colors in the palette of the self.
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.
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.
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.
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-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-1.8.4)
This method provides the same functionarity as GD::Image#stringTTF does, but uses FreeType2 library when redering the string.
Returns the width and height of the image as Array instance.
Returns true if specified point (x,y) is within the bounds of the image. Otherwise return false.
Returns the blue component of the specified color index idx.
Returns the number of colors currently allocated in the image.
Returns the current transparent color index of the image. Returns -1 if there is no transparent color.
Returns the color index of a pixel at (x,y)).
Returns the green component of the specified color index idx.
Returns the height of the image.
Returns true if the image is interlaced, and returns false otherwise.
Returns the red component of the specified color index idx.
Returns array of the RGB values for the specified index idx of the image.
Returns the width of the image.
Outputs the image to the specified file in Gd format.
Outputs the image to the specified file in Gd2 format with specified chunk_size and fmt. A gd2 Image are stored as a series of compressed/uncompressed subimages. You can specify chunk_size which determines the size of the subimages. If chunk_size is set zero, the default size is used. Whether the image is compressed or uncompressed is determined by fmt being GD::GD2_FMT_COMPRESSED or GD::GD2_FMT_RAW, respectively.
(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-1.8 or later)
Outputs the Jpeg image as String object with specified quality. This method will be especially useful when you want to transmit an image directly to an user(i.e, without first writing it to a file).
This method is provided by Colin Steele(colin@webg2.com).
Outputs the image to the specified file in PNG format.
Outputs the image in PNG format as String object. This method will be especially useful when you want to transmit an image directly to an user(i.e, without first writing it to a 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."
Finds the first available color index in the image specified, sets its RGBA values to those requested and returns the index of the new color table entry, or an RGBA value in the case of a truecolor image; in either case you can then use the returned value as a parameter to drawing functions. The alpha value takes between 0(opaque) and 127(transparent).
See also GD::Image#colorAllocate.
Searches the colors which have been defined thus far in the image specified and returns the index of the first color entry which exactly match those of the request, or an RGBA value in the case of a truecolor image; in either case you can then use the returned value as a parameter to drawing functions.The alpha value takes between 0(opaque) and 127(transparent).
See also GD::Image#colorExact.
Searches the colors which have been defined thus far in the palette image specified and returns the index of the color with RGBA values closest to those of the request. The alpha value takes between 0(opaque) and 127(transparent).
Closeness is determined by Euclidian distance, which is used to determine the distance in four-dimensional color/alpha space between colors.
When applied to a truecolor image, this method always succeeds in returning the desired color.
See also GD::Image#colorClosest.
Searches the colors which have been defined thus far in the palette image specified and returns the index of the first color with RGBA values which exactly match those of the request. The alpha value takes between 0(opaque) and 127(transparent).
If no allocated color matches the request precisely, then it tries to allocate the exact color. If there is no space left in the color table then it returns the closest color (as in GD::Image#closestAlpha).
This method always returns an index of a color. When applied to a truecolor image, this function always succeeds in returning the desired color.
See also GD::Image#colorResolve.
Specifies the different modes for drawing on truecolor images. When bool sets true("blending mode"), how much of the underlying color should be allowed to shine through is determined by the alpha channel value of the color.
This blending mode is effective for the following drawing operations, and in this mode, the existing color at the drawing point is blended with drawing color with its alpha value.
When bool sets false("non-blending mode"), the existing color at the drawing point is replaced by the drawing color with its own alpha value.
Note that this blending mode is not available when drawing on palette images.
Returns the alpha channel component (between 0 and 127) of the specified color index.
Copies a rectangular portion of one image to another image, smoothly interpolating pixel values so that, in particular, reducing the size of an image still retains a great deal of clarity.
Pixel values are interpolated only if the destination image is a truecolor image. Otherwise, for a palette image, the same functionality as GD::Image#copyResized will be invoked.
See also GD::Image#copyResized, for a version which does not interpolate pixel values.
draws an ellipse centered at the given point (cx, cy), with the specified width and height in pixels.
The ellipse is filled in the color and is drawn by beginning from start degrees and ending at end degrees. end must be greater than start. Values greater than 360 are interpreted modulo 360.
draws an partial ellipse(arc) centered at the given point (cx, cy), with the specified width and height in pixels, and filled in the color. The arc begins at start degrees and ends at end degrees.
The last argument is bitwise OR of the following possibilities.
GD::Arcdraws the rounded edge between start and end.
GD::Chorddraws the line connecting start and end.
GD::Pie synonym for GD::Arc
GD::NoFillindicates Pie and Chord should be outlined, not filled.
GD::Edgedused together with GD::NoFill, indicates that the beginning and
ending angles should be connected to the center; this is a good way to
outline (rather than fill) a 'pie slice'.
transforms the truecolor image to palette image. If dither_flag is true, the image will be dithered to approximate colors better, at the expense of some obvious "speckling." colors may be anything up to 256, but if the image includes the photographic information, or is a JPEG image, 256 is strongly recommended.
returns true if the image is a truecolor image.
returns true if the image is a palette image.
specifies the line thickness (defaults to 1) that affects methods drawing lines or curves.
Creates a new polygon instance. After some operations provided below, the polygon is drawn on the image by GD::Image#polygon method.
Adds a new point(vertex) from which the polygon is formed.
Deletes the the specified idx-th elements of the vertices.
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)
Offsets all the vertices of the polygon by dx pixels horizontally and dy pixels vertically.
Changes the value of the specified idx-th elements of the vertices to (new_x, new_y).
Draw from current vertex to a new vertex, using relative (dx, dy) coordinates. If this is the first point, act like GD::Image#addPt.
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.
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.
Returns the smallest rectangle that completely encloses the polygon. The return value is an array containing the [left,top,right,bottom] of the rectangle.
Returns the number of the vertices.
Returns all of the coodinates of the vertices as Array instance.
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.
Returns the height of each character of the font.
Returns the number of characeters in the font.
Returns the offset of the first character in the font.
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.
This stands for 9x15 bold font:
-Misc-Fixed-Bold-R-Normal-Sans-15-140-75-75-C-90-ISO8859-2
This stands for the public domain 8x16 font:
-misc-fixed-medium-r-normal--16-140-75-75-c-80-iso8859-2
This stands for the a public domain 7x13 font:
-misc-fixed-bold-r-normal-sans-13-94-100-100-c-70-iso8859-2
This stands for a well known public domain 6x12 font:
-misc-fixed-medium-r-semicondensed-sans-12-116-75-75-c-60-iso8859-2
This stands for almost unreadable font, 5x8 pixels wide:
-Misc-Fixed-Medium-R-Normal--8-80-75-75-C-50-ISO8859-2