/ 
Imager-0.40
River stage three • 111 direct dependents • 127 total dependents
/ Imager::Fill

NAME

Imager::Fill - general fill types

SYNOPSIS

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, ...);

DESCRIPTION

Creates fill objects for use by some drawing functions, currently just the Imager box() method.

The currently available fills are:

  • solid

  • hatch

  • fountain (similar to gradients in paint software)

Common options

combine

The way in which the fill data is combined with the underlying image, possible values include:

none

The fill pixel replaces the target pixel.

normal

The fill pixels alpha value is used to combine it with the target pixel.

multiply
mult

Each channel of fill and target is multiplied, and the result is combined using the alpha channel of the fill pixel.

dissolve

If the alpha of the fill pixel is greater than a random number, the fill pixel is alpha combined with the target pixel.

add

The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.

subtract

The channels of the fill are subtracted from the target, clamped to be >= 0, and alpha combined with the target.

diff

The channels of the fill are subtracted from the target and the absolute value taken this is alpha combined with the target.

lighten

The higher value is taken from each channel of the fill and target pixels, which is then alpha combined with the target.

darken

The higher value is taken from each channel of the fill and target pixels, which is then alpha combined with the target.

hue

The combination of the saturation and value of the target is combined with the hue of the fill pixel, and is then alpha combined with the target.

sat

The combination of the hue and value of the target is combined with the saturation of the fill pixel, and is then alpha combined with the target.

value

The combination of the hue and value of the target is combined with the value of the fill pixel, and is then alpha combined with the target.

color

The combination of the value of the target is combined with the hue and saturation of the fill pixel, and is then alpha combined with the target.

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.

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 varios 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.

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, 
     segment=>$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.

Image Fills

my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
                             matrix=>$matrix, $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.

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 <tony@develop-help.com>

SEE ALSO

Imager(3)