<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Imager/Fill.md. Do not edit. -->

```{index} single: Imager::Fill
```

# Imager::Fill

```text
Imager::Fill - general fill types
```

## SYNOPSIS

```perl
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

    ```perl
    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](https://metacpan.org/pod/Imager::Draw#Combine-Types).

In general colors can be specified as [Imager::Color](Color.md) or
[Imager::Color::Float](Color/Float.md) 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

```perl
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:

```perl
my $red = Imager::Fill->new(solid => "FF000080", combine => "normal");
```

### Hatched fills

```perl
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:

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

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

### Fountain fills

```perl
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:

```perl
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

```perl
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](Matrix2d.md) class to create transformation matrices.

The matrix parameter will significantly slow down the fill.

```perl
## 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

```perl
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.

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

## SEE ALSO

Imager(3)