Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Imager::Fountain(3)   User Contributed Perl Documentation  Imager::Fountain(3)

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:

	   o   "start" - the start position in the gradient where this segment
	       takes effect between 0 and 1.  Default: 0.

	   o   "middle"	- the mid-point	of the transition between the 2
	       colors, between 0 and 1.	 Default: average of "start" and
	       "end".

	   o   "end" - the end of the gradient,	from 0 to 1.  Default: 1.

	   o   "c0" - the color	of the fountain	fill where the fill parameter
	       is equal	to start.  Default: opaque black.

	   o   "c1" - the color	of the fountain	fill where the fill parameter
	       is equal	to end.	 Default: opaque black.

	   o   "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:

	       o   "linear"

	       o   "curved" - unimplemented so far.

	       o   "sine"

	       o   "sphereup"

	       o   "spheredown"

	   o   "color" - the way in which the color transitions	between	"c0"
	       and "c1".  Default: direct.

	       This can	take any of the	following values:

	       o   "direct" - each channel is simple scaled between c0 and c1.

	       o   "hueup" - the color is converted to a HSV value and the
		   scaling is done such	that the hue increases as the fill
		   parameter increases.

	       o   "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)

perl v5.24.1			  2012-09-28		   Imager::Fountain(3)

NAME | SYNOPSIS | DESCRIPTION | FILL PARAMETER | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Imager::Fountain&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help