view release on metacpan or  search on metacpan

lib/Image/Base/GD.pm  view on Meta::CPAN

 $image->line (50,50, 70,70, '#0000AAAA9999');
 $image->save ('/some/filename.png');

=head1 CLASS HIERARCHY

C<Image::Base::GD> is a subclass of C<Image::Base>,

    Image::Base
      Image::Base::GD

=head1 DESCRIPTION

C<Image::Base::GD> extends C<Image::Base> to create or update image files in
various formats using the C<GD> module and library (libgd version 2 or
higher).

Native GD drawing has many more features but this module is an easy way to
point C<Image::Base> style code at a GD and is a good way to get PNG and
other formats out of C<Image::Base> code.

=head2 Colour Names

Colour names for drawing are

    GD::Simple->color_names()
    "#RGB"           hex upper or lower case
    "#RRGGBB"
    "#RRRGGGBBB"
    "#RRRRGGGGBBBB"
    "None"           transparent

See L<GD::Simple> for its C<color_names()> list.  Special "None" means
transparent.  Colours are allocated when first used.  GD works in 8-bit
components so 3 and 4-digit hex forms are truncated to the high 2 hex
digits, and 1-digit hex "#123" expands to "#112233".

=head2 File Formats

C<GD> can read and write

    png      with libpng
    jpeg     with libjpeg
    gif      unless disabled in GD.pm
    wbmp     wireless app bitmap

And prior to libgd version 2.32 (now gone),

    gd       GD's own format, raw
    gd2      GD's own format, compressed

And read-only,

    xpm      with libXpm
    xbm

PNG, JPEG and XPM are available if libgd is compiled with the respective
support libraries.  GIF will be unavailable if the Perl C<GD> interface was
built with its option to disable GIF.

C<load()> auto-detects the file format and calls the corresponding
C<newFromPng()> etc.  "gd" file format differs between libgd 1.x and 2.x.
libgd 2.x could load the 1.x format, but always wrote 2.x so that's what
C<save()> here gives.  Both "gd" formats were a byte dump mainly intended
for temporary files but are unsupported in current libgd.

WBMP is a bitmap format and is treated by GD as colours black "#000000" for
0 and white "#FFFFFF" for 1.  On save, any non-black is treated as white 1
too, but not sure that's a documented feature.

=head2 Other GD Modules

Some other modules implement a GD-like interface with other output types or
features.  To the extent they're GD-compatible they should work passed in as
a C<-gd> object here.

C<GD::SVG::Image> (see L<GD::SVG>) can be saved with C<-file_format> set to
"svg".  (Or see C<Image::Base::SVG> to go directly to an C<SVG> module
object if that's desired.)

C<Image::WMF> (see L<Image::WMF>) can be saved by setting C<-file_format>
to "wmf".

C<GD::Window> (see L<GD::Window>) as of its version 0.02 almost works in
C<passThrough> mode, but look for a bug fix post 0.02.

=head1 FUNCTIONS

See L<Image::Base/FUNCTIONS> for the behaviour common to all Image-Base
classes.

=over 4

=item C<$image = Image::Base::GD-E<gt>new (key=E<gt>value,...)>

Create and return a new image object.  A new image can be started with
C<-width> and C<-height>,

    $image = Image::Base::GD->new (-width => 200, -height => 100);

Or an existing file can be read,

    $image = Image::Base::GD->new (-file => '/some/filename.png');

Or a C<GD::Image> object can be given,

    $image = Image::Base::GD->new (-gd => $gdimageobject);

=item C<$new_image = $image-E<gt>new (key=E<gt>value,...)>

Create and return a copy of C<$image>.  The GD within C<$image> is cloned
(per C<$gd-E<gt>clone()>).  The optional parameters are applied to the new
image as per C<set()>.

    # copy image, new compression level
    my $new_image = $image->new (-zlib_compression => 9);

=item C<$colour = $image-E<gt>xy ($x, $y)>

=item C<$image-E<gt>xy ($x, $y, $colour)>

Get or set an individual pixel.