fill out documentation

[imager.git] / lib / Imager / Fill.pm

diff --git a/lib/Imager/Fill.pm b/lib/Imager/Fill.pm
index aca9c56d89502772a572ac111e148df97e4c680f..2997853df8f8565eb7675b985694d210ac938e6c 100644 (file)
--- a/lib/Imager/Fill.pm
+++ b/lib/Imager/Fill.pm
@@ -2,7 +2,7 @@ package Imager::Fill;
 use strict;
 use vars qw($VERSION);
 
 use strict;
 use vars qw($VERSION);
 

-$VERSION = "1.010";
+$VERSION = "1.011";

 
 # this needs to be kept in sync with the array of hatches in fills.c
 my @hatch_types =
 
 # 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) {
   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 &&
       return;
     }
     unless (ref $other_fill &&


@@ -142,7 +142,7 @@ sub new {
        undef $other_fill;
       }
       unless ($other_fill) {
        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;
       }
     }
        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, ...);
                                 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 
 
 
 =head1 DESCRIPTION 
 


@@ -222,6 +223,14 @@ hatch
 
 fountain (similar to gradients in paint software)
 
 
 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
 =back
 
 =head1 Common options


@@ -235,18 +244,22 @@ See L<Imager::Draw/"Combine Types">.
 
 =back
 
 
 =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
 
 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.
 
 
 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,
 =head2 Hatched fills
 
   my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,


@@ -269,77 +282,80 @@ Current hatch names are:
 
 =over
 
 
 =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
 
 
 =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 patten:

 
 

-=back
+  my $fill = Imager::Fill->new(hatch => "check2x2", fg => "blue");

 
 You can call Imager::Fill->hatches for a list of hatch names.
 
 
 You can call Imager::Fill->hatches for a list of hatch names.
 


@@ -355,14 +371,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.
 
 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,
 =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
 
 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.
 
 The matrix parameter performs a co-ordinate transformation from the
 co-ordinates in the target image to the fill image co-ordinates.


@@ -371,12 +398,29 @@ the L<Imager::Matrix2d> class to create transformation matrices.
 
 The matrix parameter will significantly slow down the fill.
 
 
 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);
 
 =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.
 
 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 +443,10 @@ opacity - multiplier for the source fill opacity.  Default: 0.5.
 
 =back
 
 
 =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
 
 
 =head1 OTHER METHODS
 


@@ -421,17 +468,17 @@ I'm planning on adding the following types of fills:
 
 =over
 
 
 =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
 
 
 =back