Imager::Fountain - a class for building fountain fills suitable for use by

       Tony Cook <tony@develop-help.com>

       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) ]);

   ImplementationFunctions
       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.

       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.

         Imager::Fountain - a class for building fountain fills suitable for use by
        the fountain filter.

Imager(3)

perl v5.40.1                                       2025-03-16                              Imager::Fountain(3pm)

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