X-Git-Url: http://git.imager.perl.org/imager.git/blobdiff_plain/6f1e1621066f30edb42f9cee3b5df0366960e6fc..306618c39cda46d702ce8784bec425c2caf6cded:/lib/Imager/Fill.pm

diff --git a/lib/Imager/Fill.pm b/lib/Imager/Fill.pm
index aca9c56d..f964c097 100644
--- a/lib/Imager/Fill.pm
+++ b/lib/Imager/Fill.pm
@@ -2,7 +2,7 @@ package Imager::Fill;
 use strict;
 use vars qw($VERSION);
 
-$VERSION = "1.010";
+$VERSION = "1.012";
 
 # this needs to be kept in sync with the array of hatches in fills.c
 my @hatch_types =
@@ -128,7 +128,7 @@ sub new {
   elsif (defined $hsh{type} && $hsh{type} eq "opacity") {
     my $other_fill = delete $hsh{other};
     unless (defined $other_fill) {
-      Imager->_set_error("'other' parameter required to create alpha fill");
+      Imager->_set_error("'other' parameter required to create opacity fill");
       return;
     }
     unless (ref $other_fill &&
@@ -142,7 +142,7 @@ sub new {
 	undef $other_fill;
       }
       unless ($other_fill) {
-	Imager->_set_error("'other' parameter must be an Imager::Fill object to create an alpha fill");
+	Imager->_set_error("'other' parameter must be an Imager::Fill object to create an opacity fill");
 	return;
       }
     }
@@ -187,7 +187,8 @@ sub combines {
                                 dx=>$dx, dy=>$dy);
   my $fill3 = Imager::Fill->new(fountain=>$type, ...);
   my $fill4 = Imager::Fill->new(image=>$img, ...);
-  my $fill5 = Imager::Fill->new(type => "alpha", other => $fill, alpha => ...);
+  my $fill5 = Imager::Fill->new(type => "opacity", other => $fill,
+                                opacity => ...);
 
 =head1 DESCRIPTION 
 
@@ -222,6 +223,14 @@ hatch
 
 fountain (similar to gradients in paint software)
 
+=item *
+
+image - fill with an image, possibly transformed
+
+=item *
+
+opacity - a lower opacity version of some other fill
+
 =back
 
 =head1 Common options
@@ -235,18 +244,22 @@ See L<Imager::Draw/"Combine Types">.
 
 =back
 
-In general colors can be specified as Imager::Color or
-Imager::Color::Float objects.  The fill object will typically store
+In general colors can be specified as L<Imager::Color> or
+L<Imager::Color::Float> objects.  The fill object will typically store
 both types and convert from one to the other.  If a fill takes 2 color
 objects they should have the same type.
 
 =head2 Solid fills
 
-  my $fill = Imager::Fill->new(solid=>$color, $combine =>$combine)
+  my $fill = Imager::Fill->new(solid=>$color, combine =>$combine)
 
 Creates a solid fill, the only required parameter is C<solid> which
 should be the color to fill with.
 
+A translucent red fill:
+
+  my $red = Imager::Fill->new(solid => "FF000080", combine => "normal");
+
 =head2 Hatched fills
 
   my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
@@ -256,11 +269,12 @@ Creates a hatched fill.  You can specify the following keywords:
 
 =over
 
-=item hatch
+=item *
 
-The type of hatch to perform, this can either be the numeric index of
-the hatch (not recommended), the symbolic name of the hatch, or an
-array of 8 integers which specify the pattern of the hatch.
+C<hatch> - The type of hatch to perform, this can either be the
+numeric index of the hatch (not recommended), the symbolic name of the
+hatch, or an array of 8 integers which specify the pattern of the
+hatch.
 
 Hatches are represented as cells 8x8 arrays of bits, which limits their
 complexity.
@@ -269,77 +283,80 @@ Current hatch names are:
 
 =over
 
-=item check1x1, check2x2, check4x4
+=item *
 
-checkerboards at varios sizes
+C<check1x1>, C<check2x2>, C<check4x4> - checkerboards at various sizes
 
-=item vline1, vline2, vline4
+=item *
 
-1, 2, or 4 vertical lines per cell
+C<vline1>, C<vline2>, C<vline4> - 1, 2, or 4 vertical lines per cell
 
-=item hline1, hline2, hline4
+=item *
 
-1, 2, or 4 horizontal lines per cell
+C<hline1>, C<hline2>, C<hline4> - 1, 2, or 4 horizontal lines per cell
 
-=item slash1,  slash2
+=item *
 
-1 or 2 / lines per cell.
+C<slash1>, C<slash2> - 1 or 2 / lines per cell.
 
-=item slosh1,  slosh2
+=item *
 
-1 or 2 \ lines per cell
+C<slosh1>, C<slosh2> - 1 or 2 \ lines per cell
 
-=item grid1,  grid2,  grid4
+=item *
 
-1, 2, or 4 vertical and horizontal lines per cell
+C<grid1>, C<grid2>, C<grid4> - 1, 2, or 4 vertical and horizontal
+lines per cell
 
-=item dots1, dots4, dots16
+=item *
 
-1, 4 or 16 dots per cell
+C<dots1>, C<dots4>, C<dots16> - 1, 4 or 16 dots per cell
 
-=item stipple, stipple2
+=item *
 
-see the samples
+C<stipple>, C<stipple2> - see the samples
 
-=item weave
+=item *
 
-I hope this one is obvious.
+C<weave> - I hope this one is obvious.
 
-=item cross1,  cross2
+=item *
 
-2 densities of crosshatch
+C<cross1>, C<cross2> - 2 densities of crosshatch
 
-=item vlozenge,  hlozenge
+=item *
 
-something like lozenge tiles
+C<vlozenge>, C<hlozenge> - something like lozenge tiles
 
-=item scalesdown,  scalesup,  scalesleft,  scalesright
+=item *
 
-Vaguely like fish scales in each direction.
+C<scalesdown>, C<scalesup>, C<scalesleft>, C<scalesright> - Vaguely
+like fish scales in each direction.
 
-=item tile_L
+=item *
 
-L-shaped tiles
+C<tile_L> - L-shaped tiles
 
 =back
 
-=item fg
+=item *
 
-=item bg
+C<fg>, C<bg> - The C<fg> color is rendered where bits are set in the
+hatch, and the C<bg> where they are clear.  If you use a transparent
+C<fg> or C<bg>, and set combine, you can overlay the hatch onto an
+existing image.
 
-The fg color is rendered where bits are set in the hatch, and the bg
-where they are clear.  If you use a transparent fg or bg, and set
-combine, you can overlay the hatch onto an existing image.
+C<fg> defaults to black, C<bg> to white.
 
-fg defaults to black, bg to white.
+=item *
 
-=item dx
+C<dx>, C<dy> - An offset into the hatch cell.  Both default to zero.
 
-=item dy
+=back
 
-An offset into the hatch cell.  Both default to zero.
+A blue and white 4-pixel check pattern:
 
-=back
+  my $fill = Imager::Fill->new(hatch => "check2x2", fg => "blue");
 
 You can call Imager::Fill->hatches for a list of hatch names.
 
@@ -355,14 +372,25 @@ same fill as the C<fountain> filter, but is restricted to the shape
 you are drawing, and the fountain parameter supplies the fill type,
 and is required.
 
+A radial fill from white to transparent centered on (50, 50) with a 50
+pixel radius:
+
+  use Imager::Fountain;
+  my $segs = Imager::Fountain->simple(colors => [ "FFFFFF", "FFFFFF00" ],
+                                      positions => [ 0, 1 ]);
+  my $fill = Imager::Fill->new(fountain => "radial", segments => $segs,
+                               xa => 50, ya => 50, xb => 0, yb => 50,
+                               combine => "normal");
+
+
 =head2 Image Fills
 
   my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
-                               matrix=>$matrix, $combine);
+                               matrix=>$matrix, combine => $combine);
 
 Fills the given image with a tiled version of the given image.  The
-first non-zero value of xoff or yoff will provide an offset along the
-given axis between rows or columns of tiles respectively.
+first non-zero value of C<xoff> or C<yoff> will provide an offset
+along the given axis between rows or columns of tiles respectively.
 
 The matrix parameter performs a co-ordinate transformation from the
 co-ordinates in the target image to the fill image co-ordinates.
@@ -371,12 +399,29 @@ the L<Imager::Matrix2d> class to create transformation matrices.
 
 The matrix parameter will significantly slow down the fill.
 
+  # some image to act as a texture
+  my $txim = Imager->new(...);
+
+  # simple tiling
+  my $fill = Imager::Fill->new(image => $txim);
+
+  # tile with a vertical offset
+  my $fill = Imager::Fill->new(image => $txim, yoff => 10);
+
+  # tile with a horizontal offset
+  my $fill = Imager::Fill->new(image => $txim, xoff => 10);
+
+  # rotated
+  use Imager::Matrix2d;
+  my $fill = Imager::Fill->new(image => $txim,
+                matrix => Imager::Matrix2d->rotate(degrees => 20));
+
 =head2 Opacity modification fill
 
   my $fill = Imager::Fill->new(type => "opacity",
       other => $fill, opacity => 0.25);
 
-This can be used to make a fill that is a more translucent of opaque
+This can be used to make a fill that is a more translucent or opaque
 version of an existing fill.  This is intended for use where you
 receive a fill object as a parameter and need to change the opacity.
 
@@ -399,7 +444,10 @@ opacity - multiplier for the source fill opacity.  Default: 0.5.
 
 =back
 
-The source fill's combine mode is used.
+The source fills combine mode is used.
+
+  my $hatch = Imager::Fill->new(hatch => "check4x4", combine => "normal");
+  my $fill = Imager::Fill->new(type => "opacity", other => $hatch);
 
 =head1 OTHER METHODS
 
@@ -421,17 +469,17 @@ I'm planning on adding the following types of fills:
 
 =over
 
-=item checkerboard
+=item *
 
-combines 2 other fills in a checkerboard
+C<checkerboard> - combines 2 other fills in a checkerboard
 
-=item combine
+=item *
 
-combines 2 other fills using the levels of an image
+C<combine> - combines 2 other fills using the levels of an image
 
-=item regmach
+=item *
 
-uses the transform2() register machine to create fills
+C<regmach> - uses the transform2() register machine to create fills
 
 =back