summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl0/lib/Imager/Tutorial.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Imager/Tutorial.pod')
-rwxr-xr-xMaster/tlpkg/tlperl0/lib/Imager/Tutorial.pod180
1 files changed, 180 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Imager/Tutorial.pod b/Master/tlpkg/tlperl0/lib/Imager/Tutorial.pod
new file mode 100755
index 00000000000..a26d8d9bdc0
--- /dev/null
+++ b/Master/tlpkg/tlperl0/lib/Imager/Tutorial.pod
@@ -0,0 +1,180 @@
+=head1 NAME
+
+Imager::Tutorial - an introduction to Imager.
+
+=head1 DESCRIPTION
+
+=head2 Before you start
+
+If you have the necessary knowledge, install the image format
+libraries you want Imager image file support for, and Imager itself,
+otherwise arrange to have it done.
+
+You will also want some sort of image viewer tool, whether an image
+editor like Photoshop or the GIMP, or a web browser.
+
+=head2 Hello Boxes! - A Simple Start
+
+As with any perl program it's useful to start with a #! line, and to
+enable strict mode:
+
+ #!/usr/bin/perl -w
+ # you might to 'use warnings;' instead of the -w above
+ use strict;
+
+These lines will be omitted in further examples.
+
+As with any module, you need to load it:
+
+ use Imager;
+
+Now create a image to draw on:
+
+ my $image = Imager->new(xsize => 100, ysize => 100);
+
+and draw a couple of filled rectangles on it:
+
+ $image->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
+ filled => 1, color => 'blue');
+ $image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
+ filled => 1, color => 'green');
+
+Since the first box fills the whole image, it can be simplified to:
+
+ $image->box(filled => 1, color => 'blue');
+
+and save it to a file:
+
+ $image->write(file=>'tutorial1.ppm')
+ or die 'Cannot save tutorial1.ppm: ', $image->errstr;
+
+So our completed program is:
+
+ use Imager;
+
+ my $image = Imager->new(xsize => 100, ysize => 100);
+
+ $image->box(filled => 1, color => 'blue');
+ $image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
+ filled => 1, color => 'green');
+
+ $image->write(file=>'tutorial1.ppm')
+ or die 'Cannot save tutorial1.ppm: ', $image->errstr;
+
+=head2 Adding some text
+
+The first thing you need to draw text is a font object:
+
+ # use a different file, depending on the font support you have in
+ # your installed Imager.
+ my $font_filename = 'fontfiles/ImUgly.ttf';
+ my $font = Imager::Font->new(file=>$font_filename)
+ or die "Cannot load $font_filename: ", Imager->errstr;
+
+If you're on Windows, you can supply a face name instead:
+
+ my $font = Imager::Font->new(face=>'Arial Bold')
+ or die "Cannot load 'Arial Bold: ", Imager->errstr;
+
+and draw the text:
+
+ my $text = "Hello Boxes!";
+ my $text_size = 12;
+
+ $font->align(string => $text,
+ size => $text_size,
+ color => 'red',
+ x => $image->getwidth/2,
+ y => $image->getheight/2,
+ halign => 'center',
+ valign => 'center',
+ image => $image);
+
+So inserting this into our existing code we have:
+
+ use Imager;
+
+ my $image = Imager->new(xsize => 100, ysize => 100);
+
+ $image->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
+ filled => 1, color => 'blue');
+ $image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
+ filled => 1, color => 'green');
+
+ # use a different file, depending on the font support you have in
+ # your installed Imager.
+ my $font_filename = 'fontfiles/ImUgly.ttf';
+ my $font = Imager::Font->new(file=>$font_filename)
+ or die "Cannot load $font_filename: ", Imager->errstr;
+
+ my $text = "Hello Boxes!";
+ my $text_size = 12;
+
+ $font->align(string => $text,
+ size => $text_size,
+ color => 'red',
+ x => $image->getwidth/2,
+ y => $image->getheight/2,
+ halign => 'center',
+ valign => 'center',
+ image => $image);
+
+ $image->write(file=>'tutorial2.ppm')
+ or die 'Cannot save tutorial2.ppm: ', $image->errstr;
+
+=head2 Using an existing image as a base
+
+To load an image from a file, first create an empty image object:
+
+ my $read_image = Imager->new;
+
+then call the read method:
+
+ my $image_source = shift; # from the command-line
+ $read_image->read(file=>$image_source)
+ or die "Cannot load $image_source: ", $image->errstr;
+
+To keep to our working size, we'll scale the image:
+
+ # the scale() method always does a proportional scale, we don't want
+ # that here
+ my $scaled_image = $read_image->scaleX(pixels=>100)->scaleY(pixels=>100);
+
+draw our inner box on that, and save the result:
+
+ $scaled_image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
+ filled => 1, color => 'green');
+
+ $scaled_image->write(file=>'tutorial3.ppm')
+ or die 'Cannot save tutorial3.ppm: ', $image->errstr;
+
+so the complete program is:
+
+ use Imager;
+
+ my $read_image = Imager->new;
+
+ my $image_source = shift; # from the command-line
+ $read_image->read(file=>$image_source)
+ or die "Cannot load $image_source: ", $image->errstr;
+
+ # the scale() method always does a proportional scale, we don't want
+ # that here
+ my $scaled_image = $read_image->scaleX(pixels=>100)->scaleY(pixels=>100);
+
+ $scaled_image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
+ filled => 1, color => 'green');
+
+ $scaled_image->write(file=>'tutorial3.ppm')
+ or die 'Cannot save tutorial3.ppm: ', $image->errstr;
+
+
+=head1 AUTHOR
+
+Tony Cook <tony@imager.perl.org>
+
+=head1 REVISION
+
+$Revision: 811 $
+
+=cut