Imager::Fountain(3pm)

📦
version 1.035 · 9 versions
, in ubuntu stonking

💖 NAME 💖

Imager::Fountain — bestie, this is the class that builds fountain fills for the fountain filter. Think of it as your personal gradient-glow-up factory ✨

🦋 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 🌸

Okay so here's the tea: this module gives you an interface to build arrays that are suitable for the Imager fountain filter. You can load them from a GIMP gradient file, save them to one, or build the whole thing from scratch like the DIY icon you are 💅

🎀 read(gimp=>$filename) 🎀

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

Loads a gradient from the given GIMP gradient file and hands you back a brand new Imager::Fountain object. Obsessed.

If you pass the name parameter as a scalar reference, then any name field from newer GIMP gradient files gets returned in it. Free real estate, no cap.

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) 🎀

Saves the gradient to a GIMP gradient file. Slay.

The second variant lets you set the gradient name (for newer versions of the GIMP), iykyk.

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

🎀 new 🎀

Creates an empty fountain fill description. A blank canvas, a fresh start, main character energy fr fr 🫶

🎀 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, and yes I'm listing all of them because we don't skip:

  • 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: the 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 the fill parameter moves from 0 to 1. Default: linear.

This can take any of these 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 these 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 made of linear segments. Lowkey the easiest way in.

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

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. (Yes, we're documenting the internals too, we're thorough like that 💅)

  • _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() docs mention a fill parameter in a few places, so this is as good a place as any to discuss it. Grab a snack 🍓

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)

Okay that's the whole page, you ate that 💅 This was Imager::Fountain(3pm) from perl v5.42.3, dated 2026-08-19 — go forth and gradient, bestie 💖✨

📦 where this page comes from