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)