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.