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