--- name: "Imager::Fill" section: "3pm" platform: "linux" package: "libimager-perl" version: "1.027+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Imager::Fill" --- # Imager::Fill(3pm) ## NAME ``` Imager::Fill - general fill types ``` ## SYNOPSIS ``` use Imager; use Imager::Fill; my $fill1 = Imager::Fill->new(solid=>$color, combine=>$combine); my $fill2 = Imager::Fill->new(hatch=>'vline2', 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 => ...); ``` ## DESCRIPTION Creates fill objects for use by most filled area drawing functions. All fills are created with the new method. - new ``` my $fill = Imager::Fill->new(...); ``` The parameters depend on the type of fill being created. See below for details. The currently available fills are: - • solid - • hatch - • fountain (similar to gradients in paint software) - • image - fill with an image, possibly transformed - • opacity - a lower opacity version of some other fill ## Common options - combine The way in which the fill data is combined with the underlying image. See "Combine Types" in Imager::Draw. 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. ### Solid fills ``` my $fill = Imager::Fill->new(solid=>$color, combine =>$combine) ``` Creates a solid fill, the only required parameter is `"solid"` which should be the color to fill with. A translucent red fill: ``` my $red = Imager::Fill->new(solid => "FF000080", combine => "normal"); ``` ### Hatched fills ``` my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor, dx=>$dx, $dy=>$dy); ``` Creates a hatched fill. You can specify the following keywords: - • `"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. Current hatch names are: - • `"check1x1"`, `"check2x2"`, `"check4x4"` - checkerboards at various sizes - • `"vline1"`, `"vline2"`, `"vline4"` - 1, 2, or 4 vertical lines per cell - • `"hline1"`, `"hline2"`, `"hline4"` - 1, 2, or 4 horizontal lines per cell - • `"slash1"`, `"slash2"` - 1 or 2 / lines per cell. - • `"slosh1"`, `"slosh2"` - 1 or 2 \\ lines per cell - • `"grid1"`, `"grid2"`, `"grid4"` - 1, 2, or 4 vertical and horizontal lines per cell - • `"dots1"`, `"dots4"`, `"dots16"` - 1, 4 or 16 dots per cell - • `"stipple"`, `"stipple2"` - see the samples - • `"weave"` - I hope this one is obvious. - • `"cross1"`, `"cross2"` - 2 densities of crosshatch - • `"vlozenge"`, `"hlozenge"` - something like lozenge tiles - • `"scalesdown"`, `"scalesup"`, `"scalesleft"`, `"scalesright"` - Vaguely like fish scales in each direction. - • `"tile_L"` - L-shaped tiles - • `"fg"`, `"bg"` - 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. `"fg"` defaults to black, `"bg"` to white. - • `"dx"`, `"dy"` - An offset into the hatch cell. Both default to zero. A blue and white 4-pixel check pattern: ``` my $fill = Imager::Fill->new(hatch => "check2x2", fg => "blue"); ``` You can call Imager::Fill-\>hatches for a list of hatch names. ### Fountain fills ``` 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); ``` This fills the given region with a fountain fill. This is exactly the same fill as the `"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"); ``` ### Image Fills ``` my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff, 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. 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. 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)); ``` ### 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 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. Parameters: - • type =\> "opacity" - Required - • other - the fill to produce a modified version of. This must be an Imager::Fill object. Required. - • opacity - multiplier for the source fill opacity. Default: 0.5. 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); ``` ## OTHER METHODS - Imager::Fill-\>hatches A list of all defined hatch names. - Imager::Fill-\>combines A list of all combine types. ## FUTURE PLANS I'm planning on adding the following types of fills: - • `"checkerboard"` - combines 2 other fills in a checkerboard - • `"combine"` - combines 2 other fills using the levels of an image - • `"regmach"` - uses the **transform2()** register machine to create fills ## AUTHOR Tony Cook \ ## SEE ALSO **Imager**(3)