added a brief tutorial

diff --git a/Changes b/Changes
index e62f889d53abb8a1e352b11987d2e4ce042f60c1..86a23bc76d52ddc98f290ba67752893f60f3c520 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1141,6 +1141,7 @@ Revision history for Perl extension Imager.
 - move include t1lib out of image.h to font.c, since nothing it 
   provides is needed elsewhere.
 - minor POD fixes
+- added a brief tutorial
 
 =================================================================
 

diff --git a/Imager.pm b/Imager.pm
index a659ffa7337887d8f4cf8032d8b5b1fec43a17f1..d6995912931ba13a124605656e60675e8225eada 100644 (file)
--- a/Imager.pm
+++ b/Imager.pm
@@ -2948,6 +2948,10 @@ Overview.
 
 =item *
 
+L<Imager::Tutorial> - a brief introduction to Imager.
+
+=item *
+
 L<Imager::Cookbook> - how to do various things with Imager.
 
 =item *
@@ -3197,7 +3201,7 @@ drawing boxes - L<Imager::Draw/box>
 
 drawing lines - L<Imager::Draw/line>
 
-drawing text - L<Imager::Font/string>
+drawing text - L<Imager::Font/string>, L<Imager::Font/align>
 
 error message - L<Imager/"Basic Overview">
 

diff --git a/MANIFEST b/MANIFEST
index 7a7fbd69b6fa22bd77e00989c0c7d5eade657872..149cb07f840049feb4e9590ae324b09409abd32a 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -84,6 +84,7 @@ lib/Imager/Matrix2d.pm
 lib/Imager/Regops.pm
 lib/Imager/Transform.pm
 lib/Imager/Transformations.pod
+lib/Imager/Tutorial.pod
 lib/Imager/interface.pod
 lib/Imager/regmach.pod
 log.c

diff --git a/TODO b/TODO
index 47fb51583f64574ad1601fd9c2900132489bb175..351b179a91eebd2419486c99570acf66585adad8 100644 (file)
--- a/TODO
+++ b/TODO
@@ -30,7 +30,7 @@ not commitments.
    - test (done)
    - document (done)
 
-- add Imager::Tutorial (see Tk::UserGuide for a structure)
+- add Imager::Tutorial (see Tk::UserGuide for a structure) (done)
   don't cover installation - belongs in README or INSTALL
   it doesn't need to cover everything - read/write/create/simple drawing
   and simple text - other stuff belongs in the cookbook or in sample code

diff --git a/lib/Imager/Tutorial.pod b/lib/Imager/Tutorial.pod
new file mode 100644 (file)
index 0000000..b4eb597
--- /dev/null
+++ b/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$
+
+=cut