update Changes for FT2 thread safety

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

diff --git a/lib/Imager/Cookbook.pod b/lib/Imager/Cookbook.pod
index 0724ec02fa4e9d6bfd9c8d2390554fe042bf90ed..ad7af17e46bfaa4ee218c2c4e06f06dc2e8cfce2 100644 (file)
--- a/lib/Imager/Cookbook.pod
+++ b/lib/Imager/Cookbook.pod
@@ -66,19 +66,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:
-
-  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
+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()>:
+
+  $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:
@@ -292,7 +286,7 @@ Imager distribution for example code.
 
 You may also want to set limits on the size of the image read, using
 Imager's C<set_file_limits> method, documented in
-L<Imager::Files/set_file_limits>.  For example:
+L<Imager::Files/set_file_limits()>.  For example:
 
   # limit to 10 million bytes of memory usage
   Imager->set_file_limits(bytes => 10_000_000);
@@ -438,6 +432,23 @@ 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 colour we want transparent
+  $work->box(filled => 1, color => $color);
+
+  # get an image with that colour replaced with transparent black
+  my $out = $work->difference(other => $in);
+
 =head1 AUTHOR
 
 Tony Cook <tony@develop-help.com>