GD
view release on metacpan or search on metacpan
The following class methods allow you to create new GD::Image objects.
=over 4
=item B<$image = GD::Image-E<gt>new([$width,$height],[$truecolor])>
=item B<$image = GD::Image-E<gt>new(*FILEHANDLE)>
=item B<$image = GD::Image-E<gt>new($filename)>
=item B<$image = GD::Image-E<gt>new($data)>
The new() method is the main constructor for the GD::Image class.
Called with two integer arguments, it creates a new blank image of the
specified width and height. For example:
$myImage = GD::Image->new(100,100) || die;
This will create an image that is 100 x 100 pixels wide. If you don't
specify the dimensions, a default of 64 x 64 will be chosen.
The optional third argument, $truecolor, tells new() to create a
truecolor GD::Image object. Truecolor images have 24 bits of color
data (eight bits each in the red, green and blue channels
respectively), allowing for precise photograph-quality color usage.
If not specified, the image will use an 8-bit palette for
compatibility with older versions of libgd.
Alternatively, you may create a GD::Image object based on an existing
image by providing an open filehandle, a filename, or the image data
itself. The image formats automatically recognized and accepted are:
GIF, PNG, JPEG, XBM, XPM, BMP, GD2, TIFF, WEBP, HEIF or AVIF. Other formats,
including WBMP, and GD version 1, cannot be recognized automatically
at this time, only by filename.
If something goes wrong (e.g. insufficient memory), this call will
return undef.
=item B<$image = GD::Image-E<gt>trueColor([0,1])>
For backwards compatibility with scripts previous versions of GD,
new images created from scratch (width, height) are palette based
by default. To change this default to create true color images use:
GD::Image->trueColor(1);
before creating new images. To switch back to palette
based by default, use:
GD::Image->trueColor(0);
=item B<$image = GD::Image-E<gt>newPalette([$width,$height])>
=item B<$image = GD::Image-E<gt>newTrueColor([$width,$height])>
The newPalette() and newTrueColor() methods can be used to explicitly
create an palette based or true color image regardless of the
current setting of trueColor().
=item B<$image = GD::Image-E<gt>newFromPng($file, [$truecolor])>
=item B<$image = GD::Image-E<gt>newFromPngData($data, [$truecolor])>
The newFromPng() method will create an image from a PNG file read in
through the provided filehandle or file path. The filehandle must
previously have been opened on a valid PNG file or pipe. If
successful, this call will return an initialized image which you can
then manipulate as you please. If it fails, which usually happens if
the thing at the other end of the filehandle is not a valid PNG file,
the call returns undef. Notice that the call doesn't automatically
close the filehandle for you. But it does call C<binmode(FILEHANDLE)>
for you, on platforms where this matters.
You may use any of the following as the argument:
1) a simple filehandle, such as STDIN
2) a filehandle glob, such as *PNG
3) a reference to a glob, such as \*PNG
4) an IO::Handle object
5) the pathname of a file
In the latter case, newFromPng() will attempt to open the file for you
and read the PNG information from it.
Example1:
open (PNG,"barnswallow.png") || die;
$myImage = GD::Image->newFromPng(\*PNG) || die;
close PNG;
Example2:
$myImage = GD::Image->newFromPng('barnswallow.png');
To get information about the size and color usage of the information,
you can call the image query methods described below. Images created
by reading PNG images will be truecolor if the image file itself is
truecolor. To force the image to be palette-based, pass a value of 0
in the optional $truecolor argument.
The newFromPngData() method will create a new GD::Image initialized
with the PNG format B<data> contained in C<$data>.
=item B<$image = GD::Image-E<gt>newFromJpeg($file, [$truecolor])>
=item B<$image = GD::Image-E<gt>newFromJpegData($data, [$truecolor])>
These methods will create an image from a JPEG file. They work just
like newFromPng() and newFromPngData(), and will accept the same
filehandle and pathname arguments.
Images created by reading JPEG images will always be truecolor. To
force the image to be palette-based, pass a value of 0 in the optional
$truecolor argument.
=item B<$image = GD::Image-E<gt>newFromGif($file, [$truecolor])>
=item B<$image = GD::Image-E<gt>newFromGifData($data)>
These methods will create an image from a GIF file. They work just
like newFromPng() and newFromPngData(), and will accept the same
filehandle and pathname arguments.
Images created from GIFs are always 8-bit palette images. To convert
to truecolor, you must create a truecolor image and then perform a
copy.
=item B<$image = GD::Image-E<gt>newFromXbm($file, [$truecolor])>
This works in exactly the same way as C<newFromPng>, but reads the
contents of an X Bitmap (black & white) file:
open (XBM,"coredump.xbm") || die;
$myImage = GD::Image->newFromXbm(\*XBM) || die;
close XBM;
There is no newFromXbmData() function, because there is no
corresponding function in the gd library.
=item B<$image = GD::Image-E<gt>newFromWBMP($file)>
This works in exactly the same way as C<newFromPng>, but reads the
contents of a Wireless Application Protocol Bitmap (WBMP) file:
open (WBMP,"coredump.wbmp") || die;
$myImage = GD::Image->newFromWBMP(\*WBMP) || die;
close WBMP;
There is no newFromWBMPData() function, because there is no
corresponding function in the gd library.
=item B<$image = GD::Image-E<gt>newFromBmp($file)>
This works in exactly the same way as C<newFromPng>, but reads the
contents of a Windows Bitmap (BMP) file:
open (BMP,"coredump.bmp") || die;
$myImage = GD::Image->newFromBmp(\*BMP) || die;
close BMP;
There is no newFromBmpData() function, because there is no
corresponding function in the gd library.
=item B<$image = GD::Image-E<gt>newFromGd($file)>
=item B<$image = GD::Image-E<gt>newFromGdData($data)>
NOTE: GD and GD2 support was dropped witn libgd 2.3.2.
These methods initialize a GD::Image from a Gd file, filehandle, or
data. Gd is Tom Boutell's disk-based storage format, intended for the
rare case when you need to read and write the image to disk quickly.
It's not intended for regular use, because, unlike PNG or JPEG, no
image compression is performed and these files can become B<BIG>.
$myImage = GD::Image->newFromGd("godzilla.gd") || die;
close GDF;
=item B<$image = GD::Image-E<gt>newFromGd2($file)>
=item B<$image = GD::Image-E<gt>newFromGd2Data($data)>
NOTE: GD and GD2 support was dropped witn libgd 2.3.2.
This works in exactly the same way as C<newFromGd()> and
newFromGdData, but use the new compressed GD2 image format.
=item B<$image = GD::Image-E<gt>newFromGd2Part($file,srcX,srcY,width,height)>
This class method allows you to read in just a portion of a GD2 image
file. In addition to a filehandle, it accepts the top-left corner and
dimensions (width,height) of the region of the image to read. For
example:
open (GDF,"godzilla.gd2") || die;
$myImage = GD::Image->newFromGd2Part(\*GDF,10,20,100,100) || die;
close GDF;
This reads a 100x100 square portion of the image starting from
position (10,20).
=item B<$image = GD::Image-E<gt>newFromXpm($filename)>
This creates a new GD::Image object starting from a B<filename>. This
is unlike the other newFrom() functions because it does not take a
filehandle. This difference comes from an inconsistency in the
underlying gd library.
$myImage = GD::Image->newFromXpm('earth.xpm') || die;
This function is only available if libgd was compiled with XPM
support.
NOTE: The libgd library is unable to read certain XPM files, returning
red green blue and alpha components. If such a color is not in the color
table and there is room, then this method allocates the color in the
color table and returns its index.
$rosey = $myImage->colorResolveAlpha(255,100,80,0);
warn "Everything's coming up roses.\n" if $rosey >= 0;
=item B<$colorsTotal = $image-E<gt>colorsTotal> I<object method>
This returns the total number of colors allocated in the object.
$maxColors = $myImage->colorsTotal;
In the case of a TrueColor image, this call will return undef.
=item B<$index = $image-E<gt>getPixel(x,y)> I<object method>
This returns the color table index underneath the specified
point. It can be combined with rgb()
to obtain the rgb color underneath the pixel.
Example:
$index = $myImage->getPixel(20,100);
($r,$g,$b) = $myImage->rgb($index);
=item B<($red,$green,$blue) = $image-E<gt>rgb($index)>
This returns a list containing the red, green and blue components of
the specified color index.
Example:
@RGB = $myImage->rgb($peachy);
=item B<($alpha) = $image-E<gt>alpha($index)>
This returns an item containing the alpha component of the specified
color index.
Example:
@RGB = $myImage->rgb($peachy);
=item B<$image-E<gt>transparent($colorIndex)>
This marks the color at the specified index as being transparent.
Portions of the image drawn in this color will be invisible. This is
useful for creating paintbrushes of odd shapes, as well as for
making PNG backgrounds transparent for displaying on the Web. Only
one color can be transparent at any time. To disable transparency,
specify -1 for the index.
If you call this method without any parameters, it will return the
current index of the transparent color, or -1 if none.
Example:
open(PNG,"test.png");
$im = GD::Image->newFromPng(PNG);
$white = $im->colorClosest(255,255,255); # find white
$im->transparent($white);
binmode STDOUT;
print $im->png;
=back
=head2 Special Colors
GD implements a number of special colors that can be used to achieve
special effects. They are constants defined in the GD::
namespace, but automatically exported into your namespace when the GD
module is loaded.
=over 4
=item B<$image-E<gt>setBrush($image)>
You can draw lines and shapes using a brush pattern. Brushes are just
palette, not TrueColor, images that you can create and manipulate in
the usual way. When you draw with them, their contents are used for
the color and shape of the lines.
To make a brushed line, you must create or load the brush first, then
assign it to the image using setBrush(). You can then draw in that
with that brush using the B<gdBrushed> special color. It's often
useful to set the background of the brush to transparent so that the
non-colored parts don't overwrite other parts of your image.
Example:
# Create a brush at an angle
$diagonal_brush = GD::Image->new(5,5);
$white = $diagonal_brush->colorAllocate(255,255,255);
$black = $diagonal_brush->colorAllocate(0,0,0);
$diagonal_brush->transparent($white);
$diagonal_brush->line(0,4,4,0,$black); # NE diagonal
# Set the brush
$myImage->setBrush($diagonal_brush);
# Draw a circle using the brush
$myImage->arc(50,50,25,25,0,360,gdBrushed);
=item B<$image-E<gt>setThickness($thickness)>
Lines drawn with line(), rectangle(), arc(), and so forth are 1 pixel
thick by default. Call setThickness() to change the line drawing
width.
=item B<$image-E<gt>setStyle(@colors)>
Styled lines consist of an arbitrary series of repeated colors and are
useful for generating dotted and dashed lines. To create a styled
line, use setStyle() to specify a repeating series of colors. It
accepts an array consisting of one or more color indexes. Then draw
using the B<gdStyled> special color. Another special color,
B<gdTransparent> can be used to introduce holes in the line, as the
example shows.
This sets the pixel at (x,y) to the specified color index. No value
is returned from this method. The coordinate system starts at the
upper left at (0,0) and gets larger as you go down and to the right.
You can use a real color, or one of the special colors gdBrushed,
gdStyled and gdStyledBrushed can be specified.
Example:
# This assumes $peach already allocated
$myImage->setPixel(50,50,$peach);
=item B<$image-E<gt>line($x1,$y1,$x2,$y2,$color)>
This draws a line from (x1,y1) to (x2,y2) of the specified color. You
can use a real color, or one of the special colors gdBrushed,
gdStyled and gdStyledBrushed.
Example:
# Draw a diagonal line using the currently defined
# paintbrush pattern.
$myImage->line(0,0,150,150,gdBrushed);
=item B<$image-E<gt>dashedLine($x1,$y1,$x2,$y2,$color)>
DEPRECATED: The libgd library provides this method solely for backward
compatibility with libgd version 1.0, and there have been reports that
it no longer works as expected. Please use the setStyle() and gdStyled
methods as described below.
This draws a dashed line from (x1,y1) to (x2,y2) in the specified
color. A more powerful way to generate arbitrary dashed and dotted
lines is to use the setStyle() method described below and to draw with
the special color gdStyled.
Example:
$myImage->dashedLine(0,0,150,150,$blue);
=item B<$image-E<gt>rectangle($x1,$y1,$x2,$y2,$color)>
This draws a rectangle with the specified color. (x1,y1) and (x2,y2)
are the upper left and lower right corners respectively. Both real
color indexes and the special colors gdBrushed, gdStyled and
gdStyledBrushed are accepted.
Example:
$myImage->rectangle(10,10,100,100,$rose);
=item B<$image-E<gt>filledRectangle($x1,$y1,$x2,$y2,$color)>
=item B<$image-E<gt>setTile($otherimage)>
This draws a rectangle filled with the specified color. You can use a
real color, or the special fill color gdTiled to fill the polygon
with a pattern.
Example:
# read in a fill pattern and set it
$tile = GD::Image->newFromPng('happyface.png');
$myImage->setTile($tile);
# draw the rectangle, filling it with the pattern
$myImage->filledRectangle(10,10,150,200,gdTiled);
=item B<$image-E<gt>openPolygon($polygon,$color)>
This draws a polygon with the specified color. The polygon must be
created first (see below). The polygon must have at least three
vertices. If the last vertex doesn't close the polygon, the method
will close it for you. Both real color indexes and the special
colors gdBrushed, gdStyled and gdStyledBrushed can be specified.
Example:
$poly = GD::Polygon->new;
$poly->addPt(50,0);
$poly->addPt(99,99);
$poly->addPt(0,99);
$myImage->openPolygon($poly,$blue);
=item B<$image-E<gt>unclosedPolygon($polygon,$color)>
This draws a sequence of connected lines with the specified color,
without connecting the first and last point to a closed polygon. The
polygon must be created first (see below). The polygon must have at
least three vertices. Both real color indexes and the special colors
gdBrushed, gdStyled and gdStyledBrushed can be specified.
You need libgd 2.0.33 or higher to use this feature.
Example:
$poly = GD::Polygon->new;
$poly->addPt(50,0);
$poly->addPt(99,99);
$poly->addPt(0,99);
$myImage->unclosedPolygon($poly,$blue);
=item B<$image-E<gt>filledPolygon($poly,$color)>
This draws a polygon filled with the specified color. You can use a
real color, or the special fill color gdTiled to fill the polygon
with a pattern.
Example:
# make a polygon
$poly = GD::Polygon->new;
$poly->addPt(50,0);
$poly->addPt(99,99);
$poly->addPt(0,99);
# draw the polygon, filling it with a color
$myImage->filledPolygon($poly,$peachpuff);
=item B<$image-E<gt>ellipse($cx,$cy,$width,$height,$color)>
=item B<$image-E<gt>filledEllipse($cx,$cy,$width,$height,$color)>
( run in 1.250 second using v1.01-cache-2.11-cpan-39bf76dae61 )