update FT2 Changes

[imager.git] / lib / Imager / Cookbook.pod

diff --git a/lib/Imager/Cookbook.pod b/lib/Imager/Cookbook.pod
index 21bc3d521bcfeccf92a67c0aebd227f6b1fff8bb..52fd9f2b0dde097e6dbb862e63a3217fb3b40175 100644 (file)
--- a/lib/Imager/Cookbook.pod
+++ b/lib/Imager/Cookbook.pod
@@ -16,6 +16,11 @@ This is described in detail in L<Imager::Files>.
 
   $image->read(file=>$filename) or die $image->errstr;
 
+Or:
+
+  my $image = Imager->new(file => $filename)
+    or die Imager->errstr;
+
 See L<Imager::Files>.
 
 =head2 Writing an image to a file
@@ -66,19 +71,13 @@ transparency and the output file format doesn't support that.  This
 can be a problem when converting from GIF files to JPEG files for
 example.
 
-To work around that you can compose the source image onto a background
-color:
+By default, if the output format doesn't support transparency, Imager
+will compose the image onto a black background.  You can override that
+by supplying an C<i_background> option to C<write()> or
+C<write_multi()>:
 
-  if ($image->getchannels == 4 or $image->getchannels == 2) {
-    my $back = Imager->new(xsize => $image->getwidth, 
-                           ysize => $image->getheight);
-    # grey background for grayscale images, red for color
-    my $back_color = $image->getchannels == 2 ? [ 128 ] : 'red';
-    $back->box(filled => 1, color => $back_color);
-    $back->rubthrough(src => $image);
-    $image = $back;
-  }
-  # now we can write safely to jpeg or pnm
+  $image->write(file => "foo.jpg", i_background => "#808080")
+    or die $image->errstr;
 
 Some formats support multiple files, so if you want to convert from
 say TIFF to JPEG, you'll need multiple output files:
@@ -178,7 +177,7 @@ For example, if you allow the caller to set the size of an output
 image you should limit the size to prevent the client from specifying
 an image size that will consume all available memory.
 
-This is beside any any other controls you need over access to data.
+This is beside any other controls you need over access to data.
 
 See L<CGI> for a module useful for processing CGI submitted data.
 
@@ -438,6 +437,106 @@ in pixels per centimeter, you would do:
 
 Keywords: DPI
 
+=head1 IMAGE MANIPULATION
+
+=head2 Replacing a color with transparency
+X<replacing colors>
+
+To replace a color with transparency you can use the
+L<Imager::Filters/difference()> method.
+
+  # make a work image the same size as our input
+  my $work = Imager->new(xsize => $in->getwidth, ysize => $in->getheight,
+                         channels => $in->getchannels);
+  # and fill it with the color we want transparent
+  $work->box(filled => 1, color => $color);
+
+  # get an image with that color replaced with transparent black
+  my $out = $work->difference(other => $in);
+
+=head1 SPECIAL EFFECTS
+
+=head2 Drop Shadows
+X<drop shadow>X<effects, drop shadow>
+
+This can be used for a glow effect as well.
+
+First create a new image, either with an alpha channel (if you want
+transparency behind the shadow) or without, if you want a background
+color:
+
+  my $out = Imager->new
+     (
+     xsize => $shadow_size * 2 + $src->getwidth,
+     ysize => $shadow_size * 2 + $src->getheight,
+     channels => 4,
+     );
+  # fill it with your background color, if you want one
+  # $out->box(filled => 1, color => $back_color);
+
+Make a work image to render the shadow on:
+
+  my $shadow_work = Imager->new
+    (
+    xsize => $back->getwidth,
+    ysize => $back->getheight,
+    channels => 1,
+    );
+
+Extract the alpha channel from the source image, first the alpha version:
+
+  my $alpha = $src->convert(preset => "alpha");
+
+and draw that on the work shadow:
+
+  $shadow_work->paste
+    (
+    src => $slpha,
+    left => $shadow_size,
+    top => $shadow_size,
+    );
+
+otherwise just draw a box for the non-alpha source:
+
+  $shadow_work->box
+    (
+    filled => 1,
+    color => [ 255 ],
+    xmin => $shadow_size,
+    ymin => $shadow_size,
+    xmax => $shadow_size + $src->getwidth() - 1,
+    ymax => $shadow_size + $src->getheight() - 1,
+    );
+
+Blur the work shadow:
+
+  $shadow_work->filter(type => "gaussian", stddev => $shadow_size);
+
+Convert it to an RGB image with alpha:
+
+  $shadow_work = $shadow_work->convert
+     (
+      matrix => [ [ 0, $red / 255 ],
+                   [ 0, $green / 255 ],
+                   [ 0, $blue / 255 ],
+                   [ 1 ] ]
+     );
+
+Draw that on the output image:
+
+  $out->rubthrough(src => $shadow_work);
+
+Draw our original image on the output image, perhaps with an offset:
+
+  $out->rubthrough
+    (
+    src => $src,
+    tx => $shadow_size + $x_offset,
+    ty => $shadow_size + $y_offset,
+    );
+
+See F<samples/drop_shadow.pl> for an example of this recipe.
+
 =head1 AUTHOR
 
 Tony Cook <tony@develop-help.com>