Implementation Functions

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)

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

write(gimp=>$filename)

Save the gradient to a GIMP gradient file.

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.
hsvup: The color is converted to a HSV value and the scaling is done such that the hue increases as the fill parameter increases.
hsvdown: 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 arrayrefs 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 occasinally 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