.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::Fill 3pm"
.TH Imager::Fill 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
.Vb 1
\&  Imager::Fill \- general fill types
.Ve
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use Imager;
\&  use Imager::Fill;
\&
\&  my $fill1 = Imager::Fill\->new(solid=>$color, combine=>$combine);
\&  my $fill2 = Imager::Fill\->new(hatch=>\*(Aqvline2\*(Aq, fg=>$color1, bg=>$color2,
\&                                dx=>$dx, dy=>$dy);
\&  my $fill3 = Imager::Fill\->new(fountain=>$type, ...);
\&  my $fill4 = Imager::Fill\->new(image=>$img, ...);
\&  my $fill5 = Imager::Fill\->new(type => "opacity", other => $fill,
\&                                opacity => ...);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Creates fill objects for use by most filled area drawing functions.
.PP
All fills are created with the new method.
.IP new 4
.IX Item "new"
.Vb 1
\&  my $fill = Imager::Fill\->new(...);
.Ve
.Sp
The parameters depend on the type of fill being created.  See below
for details.
.PP
The currently available fills are:
.IP \(bu 4
solid
.IP \(bu 4
hatch
.IP \(bu 4
fountain (similar to gradients in paint software)
.IP \(bu 4
image \- fill with an image, possibly transformed
.IP \(bu 4
opacity \- a lower opacity version of some other fill
.SH "Common options"
.IX Header "Common options"
.IP combine 4
.IX Item "combine"
The way in which the fill data is combined with the underlying image.
See "Combine Types" in Imager::Draw.
.PP
In general colors can be specified as Imager::Color or
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.
.SS "Solid fills"
.IX Subsection "Solid fills"
.Vb 1
\&  my $fill = Imager::Fill\->new(solid=>$color, combine =>$combine)
.Ve
.PP
Creates a solid fill, the only required parameter is \f(CW\*(C`solid\*(C'\fR which
should be the color to fill with.
.PP
A translucent red fill:
.PP
.Vb 1
\&  my $red = Imager::Fill\->new(solid => "FF000080", combine => "normal");
.Ve
.SS "Hatched fills"
.IX Subsection "Hatched fills"
.Vb 2
\&  my $fill = Imager::Fill\->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
\&                               dx=>$dx, $dy=>$dy);
.Ve
.PP
Creates a hatched fill.  You can specify the following keywords:
.IP \(bu 4
\&\f(CW\*(C`hatch\*(C'\fR \- 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.
.Sp
Hatches are represented as cells 8x8 arrays of bits, which limits their
complexity.
.Sp
Current hatch names are:
.RS 4
.IP \(bu 4
\&\f(CW\*(C`check1x1\*(C'\fR, \f(CW\*(C`check2x2\*(C'\fR, \f(CW\*(C`check4x4\*(C'\fR \- checkerboards at various sizes
.IP \(bu 4
\&\f(CW\*(C`vline1\*(C'\fR, \f(CW\*(C`vline2\*(C'\fR, \f(CW\*(C`vline4\*(C'\fR \- 1, 2, or 4 vertical lines per cell
.IP \(bu 4
\&\f(CW\*(C`hline1\*(C'\fR, \f(CW\*(C`hline2\*(C'\fR, \f(CW\*(C`hline4\*(C'\fR \- 1, 2, or 4 horizontal lines per cell
.IP \(bu 4
\&\f(CW\*(C`slash1\*(C'\fR, \f(CW\*(C`slash2\*(C'\fR \- 1 or 2 / lines per cell.
.IP \(bu 4
\&\f(CW\*(C`slosh1\*(C'\fR, \f(CW\*(C`slosh2\*(C'\fR \- 1 or 2 \e lines per cell
.IP \(bu 4
\&\f(CW\*(C`grid1\*(C'\fR, \f(CW\*(C`grid2\*(C'\fR, \f(CW\*(C`grid4\*(C'\fR \- 1, 2, or 4 vertical and horizontal
lines per cell
.IP \(bu 4
\&\f(CW\*(C`dots1\*(C'\fR, \f(CW\*(C`dots4\*(C'\fR, \f(CW\*(C`dots16\*(C'\fR \- 1, 4 or 16 dots per cell
.IP \(bu 4
\&\f(CW\*(C`stipple\*(C'\fR, \f(CW\*(C`stipple2\*(C'\fR \- see the samples
.IP \(bu 4
\&\f(CW\*(C`weave\*(C'\fR \- I hope this one is obvious.
.IP \(bu 4
\&\f(CW\*(C`cross1\*(C'\fR, \f(CW\*(C`cross2\*(C'\fR \- 2 densities of crosshatch
.IP \(bu 4
\&\f(CW\*(C`vlozenge\*(C'\fR, \f(CW\*(C`hlozenge\*(C'\fR \- something like lozenge tiles
.IP \(bu 4
\&\f(CW\*(C`scalesdown\*(C'\fR, \f(CW\*(C`scalesup\*(C'\fR, \f(CW\*(C`scalesleft\*(C'\fR, \f(CW\*(C`scalesright\*(C'\fR \- Vaguely
like fish scales in each direction.
.IP \(bu 4
\&\f(CW\*(C`tile_L\*(C'\fR \- L\-shaped tiles
.RE
.RS 4
.RE
.IP \(bu 4
\&\f(CW\*(C`fg\*(C'\fR, \f(CW\*(C`bg\*(C'\fR \- The \f(CW\*(C`fg\*(C'\fR color is rendered where bits are set in the
hatch, and the \f(CW\*(C`bg\*(C'\fR where they are clear.  If you use a transparent
\&\f(CW\*(C`fg\*(C'\fR or \f(CW\*(C`bg\*(C'\fR, and set combine, you can overlay the hatch onto an
existing image.
.Sp
\&\f(CW\*(C`fg\*(C'\fR defaults to black, \f(CW\*(C`bg\*(C'\fR to white.
.IP \(bu 4
\&\f(CW\*(C`dx\*(C'\fR, \f(CW\*(C`dy\*(C'\fR \- An offset into the hatch cell.  Both default to zero.
.PP
A blue and white 4\-pixel check pattern:
.PP
.Vb 1
\&  my $fill = Imager::Fill\->new(hatch => "check2x2", fg => "blue");
.Ve
.PP
You can call Imager::Fill\->hatches for a list of hatch names.
.SS "Fountain fills"
.IX Subsection "Fountain fills"
.Vb 4
\&  my $fill = Imager::Fill\->new(fountain=>$ftype, 
\&       xa=>$xa, ya=>$ya, xb=>$xb, yb=>$yb, 
\&       segments=>$segments, repeat=>$repeat, combine=>$combine, 
\&       super_sample=>$super_sample, ssample_param=>$ssample_param);
.Ve
.PP
This fills the given region with a fountain fill.  This is exactly the
same fill as the \f(CW\*(C`fountain\*(C'\fR filter, but is restricted to the shape
you are drawing, and the fountain parameter supplies the fill type,
and is required.
.PP
A radial fill from white to transparent centered on (50, 50) with a 50
pixel radius:
.PP
.Vb 6
\&  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");
.Ve
.SS "Image Fills"
.IX Subsection "Image Fills"
.Vb 2
\&  my $fill = Imager::Fill\->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
\&                               matrix=>$matrix, combine => $combine);
.Ve
.PP
Fills the given image with a tiled version of the given image.  The
first non-zero value of \f(CW\*(C`xoff\*(C'\fR or \f(CW\*(C`yoff\*(C'\fR will provide an offset
along the given axis between rows or columns of tiles respectively.
.PP
The matrix parameter performs a co-ordinate transformation from the
co-ordinates in the target image to the fill image co-ordinates.
Linear interpolation is used to determine the fill pixel.  You can use
the Imager::Matrix2d class to create transformation matrices.
.PP
The matrix parameter will significantly slow down the fill.
.PP
.Vb 2
\&  # 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));
.Ve
.SS "Opacity modification fill"
.IX Subsection "Opacity modification fill"
.Vb 2
\&  my $fill = Imager::Fill\->new(type => "opacity",
\&      other => $fill, opacity => 0.25);
.Ve
.PP
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.
.PP
Parameters:
.IP \(bu 4
type => "opacity" \- Required
.IP \(bu 4
other \- the fill to produce a modified version of.  This must be an
Imager::Fill object.  Required.
.IP \(bu 4
opacity \- multiplier for the source fill opacity.  Default: 0.5.
.PP
The source fills combine mode is used.
.PP
.Vb 2
\&  my $hatch = Imager::Fill\->new(hatch => "check4x4", combine => "normal");
\&  my $fill = Imager::Fill\->new(type => "opacity", other => $hatch);
.Ve
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.IP Imager::Fill\->hatches 4
.IX Item "Imager::Fill->hatches"
A list of all defined hatch names.
.IP Imager::Fill\->combines 4
.IX Item "Imager::Fill->combines"
A list of all combine types.
.SH "FUTURE PLANS"
.IX Header "FUTURE PLANS"
I'm planning on adding the following types of fills:
.IP \(bu 4
\&\f(CW\*(C`checkerboard\*(C'\fR \- combines 2 other fills in a checkerboard
.IP \(bu 4
\&\f(CW\*(C`combine\*(C'\fR \- combines 2 other fills using the levels of an image
.IP \(bu 4
\&\f(CW\*(C`regmach\*(C'\fR \- uses the \fBtransform2()\fR register machine to create fills
.SH AUTHOR
.IX Header "AUTHOR"
Tony Cook <tony@develop\-help.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBImager\fR\|(3)