---
name: "Imager::Fountain"
section: "3pm"
platform: "linux"
package: "libimager-perl"
version: "1.027+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Imager::Fountain"
---

# Imager::Fountain(3pm)

## NAME

```
  Imager::Fountain - a class for building fountain fills suitable for use by
 the fountain filter.
```

## SYNOPSIS

```
  use Imager::Fountain;
  my $f1 = Imager::Fountain->read(gimp=>$filename);
  $f->write(gimp=>$filename);
  my $f1 = Imager::Fountain->new;
  $f1->add(start=>0, middle=>0.5, end=>1.0,
           c0=>Imager::Color->new(...),
           c1=>Imager::Color->new(...),
           type=>$trans_type, color=>$color_trans_type);
```

## DESCRIPTION

Provide an interface to build arrays suitable for use by the Imager fountain filter.  These can be loaded from or saved to a GIMP gradient file or you can build them from scratch.

- read(gimp=\>$filename)

  - read(gimp=\>$filename, name=\>\\$name)

  Loads a gradient from the given GIMP gradient file, and returns a new Imager::Fountain object.

  If the name parameter is supplied as a scalar reference then any name field from newer GIMP gradient files will be returned in it.

  ```
    my $gradient = Imager::Fountain->read(gimp=>'foo.ggr');
    my $name;
    my $gradient2 = Imager::Fountain->read(gimp=>'bar.ggr', name=>\$name);
  ```

- write(gimp=\>$filename)

  - write(gimp=\>$filename, name=\>$name)

  Save the gradient to a GIMP gradient file.

  The second variant allows the gradient name to be set (for newer versions of the GIMP).

  ```
    $gradient->write(gimp=>'foo.ggr')
      or die Imager->errstr;
    $gradient->write(gimp=>'bar.ggr', name=>'the bar gradient')
      or die Imager->errstr;
  ```

- new

  Create an empty fountain fill description.

- add(start=\>$start, middle=\>$middle, end=\>1.0, c0=\>$start\_color, c1=\>$end\_color, type=\>$trans\_type, color=\>$color\_trans\_type)

  Adds a new segment to the fountain fill, the possible options are:

  - •

    `"start"` - the start position in the gradient where this segment takes effect between 0 and 1.  Default: 0.

  - •

    `"middle"` - the mid-point of the transition between the 2 colors, between 0 and 1.  Default: average of `"start"` and `"end"`.

  - •

    `"end"` - the end of the gradient, from 0 to 1.  Default: 1.

  - •

    `"c0"` - the color of the fountain fill where the fill parameter is equal to *start*.  Default: opaque black.

  - •

    `"c1"` - the color of the fountain fill where the fill parameter is equal to *end*.  Default: opaque black.

  - •

    `"type"` - the type of segment, controls the way in which the fill parameter moves from 0 to 1.  Default: linear.

    This can take any of the following values:

    - •

      `"linear"`

    - •

      `"curved"` - unimplemented so far.

    - •

      `"sine"`

    - •

      `"sphereup"`

    - •

      `"spheredown"`

  - •

    `"color"` - the way in which the color transitions between `"c0"` and `"c1"`. Default: direct.

    This can take any of the following values:

    - •

      `"direct"` - each channel is simple scaled between c0 and c1.

    - •

      `"hueup"` - the color is converted to a HSV value and the scaling is done such that the hue increases as the fill parameter increases.

    - •

      `"huedown"` - the color is converted to a HSV value and the scaling is done such that the hue decreases as the fill parameter increases.

  In most cases you can ignore some of the arguments, eg.

  ```
    # assuming $f is a new Imager::Fountain in each case here
    use Imager ':handy';
    # simple transition from red to blue
    $f->add(c0=>NC('#FF0000'), c1=>NC('#0000FF'));
    # simple 2 stages from red to green to blue
    $f->add(end=>0.5, c0=>NC('#FF0000'), c1=>NC('#00FF00'))
    $f->add(start=>0.5, c0=>NC('#00FF00'), c1=>NC('#0000FF'));
  ```

- simple(positions=\>\[ ... \], colors=\>\[...\])

  Creates a simple fountain fill object consisting of linear segments.

  The array references passed as positions and colors must have the same number of elements.  They must have at least 2 elements each.

  colors must contain Imager::Color or Imager::Color::Float objects.

  eg.

  ```
    my $f = Imager::Fountain->simple(positions=>[0, 0.2, 1.0],
                                     colors=>[ NC(255,0,0), NC(0,255,0),
                                               NC(0,0,255) ]);
  ```

### Implementation Functions

Documented for internal use.

- \_load\_gimp\_gradient($class, $fh, $name)

  Does the work of loading a GIMP gradient file.

- \_save\_gimp\_gradient($self, $fh, $name)

  Does the work of saving to a GIMP gradient file.

## FILL PARAMETER

The **add()** documentation mentions a fill parameter in a few places, this is as good a place as any to discuss it.

The process of deciding the color produced by the gradient works through the following steps:

- 1\.

  calculate the base value, which is typically a distance or an angle of some sort.  This can be positive or occasionally negative, depending on the type of fill being performed (linear, radial, etc).

- 2\.

  clamp or convert the base value to the range 0 through 1, how this is done depends on the repeat parameter.  I'm calling this result the fill parameter.

- 3\.

  the appropriate segment is found.  This is currently done with a linear search, and the first matching segment is used.  If there is no matching segment the pixel is not touched.

- 4\.

  the fill parameter is scaled from 0 to 1 depending on the segment type.

- 5\.

  the color produced, depending on the segment color type.

## AUTHOR

Tony Cook \<tony@develop-help.com\>

## SEE ALSO

**Imager**(3)