1Imager::Fountain(3)   User Contributed Perl Documentation  Imager::Fountain(3)
2
3
4

NAME

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

SYNOPSIS

10         use Imager::Fountain;
11         my $f1 = Imager::Fountain->read(gimp=>$filename);
12         $f->write(gimp=>$filename);
13         my $f1 = Imager::Fountain->new;
14         $f1->add(start=>0, middle=>0.5, end=>1.0,
15                  c0=>Imager::Color->new(...),
16                  c1=>Imager::Color->new(...),
17                  type=>$trans_type, color=>$color_trans_type);
18

DESCRIPTION

20       Provide an interface to build arrays suitable for use by the Imager
21       fountain filter.  These can be loaded from or saved to a GIMP gradient
22       file or you can build them from scratch.
23
24       read(gimp=>$filename)
25       read(gimp=>$filename, name=>\$name)
26           Loads a gradient from the given GIMP gradient file, and returns a
27           new Imager::Fountain object.
28
29           If the name parameter is supplied as a scalar reference then any
30           name field from newer GIMP gradient files will be returned in it.
31
32             my $gradient = Imager::Fountain->read(gimp=>'foo.ggr');
33             my $name;
34             my $gradient2 = Imager::Fountain->read(gimp=>'bar.ggr', name=>\$name);
35
36       write(gimp=>$filename)
37       write(gimp=>$filename, name=>$name)
38           Save the gradient to a GIMP gradient file.
39
40           The second variant allows the gradient name to be set (for newer
41           versions of the GIMP).
42
43             $gradient->write(gimp=>'foo.ggr')
44               or die Imager->errstr;
45             $gradient->write(gimp=>'bar.ggr', name=>'the bar gradient')
46               or die Imager->errstr;
47
48       new Create an empty fountain fill description.
49
50       add(start=>$start, middle=>$middle, end=>1.0, c0=>$start_color,
51       c1=>$end_color, type=>$trans_type, color=>$color_trans_type)
52           Adds a new segment to the fountain fill, the possible options are:
53
54           •   "start" - the start position in the gradient where this segment
55               takes effect between 0 and 1.  Default: 0.
56
57           •   "middle" - the mid-point of the transition between the 2
58               colors, between 0 and 1.  Default: average of "start" and
59               "end".
60
61           •   "end" - the end of the gradient, from 0 to 1.  Default: 1.
62
63           •   "c0" - the color of the fountain fill where the fill parameter
64               is equal to start.  Default: opaque black.
65
66           •   "c1" - the color of the fountain fill where the fill parameter
67               is equal to end.  Default: opaque black.
68
69           •   "type" - the type of segment, controls the way in which the
70               fill parameter moves from 0 to 1.  Default: linear.
71
72               This can take any of the following values:
73
74               •   "linear"
75
76               •   "curved" - unimplemented so far.
77
78               •   "sine"
79
80               •   "sphereup"
81
82               •   "spheredown"
83
84           •   "color" - the way in which the color transitions between "c0"
85               and "c1".  Default: direct.
86
87               This can take any of the following values:
88
89               •   "direct" - each channel is simple scaled between c0 and c1.
90
91               •   "hueup" - the color is converted to a HSV value and the
92                   scaling is done such that the hue increases as the fill
93                   parameter increases.
94
95               •   "huedown" - the color is converted to a HSV value and the
96                   scaling is done such that the hue decreases as the fill
97                   parameter increases.
98
99           In most cases you can ignore some of the arguments, eg.
100
101             # assuming $f is a new Imager::Fountain in each case here
102             use Imager ':handy';
103             # simple transition from red to blue
104             $f->add(c0=>NC('#FF0000'), c1=>NC('#0000FF'));
105             # simple 2 stages from red to green to blue
106             $f->add(end=>0.5, c0=>NC('#FF0000'), c1=>NC('#00FF00'))
107             $f->add(start=>0.5, c0=>NC('#00FF00'), c1=>NC('#0000FF'));
108
109       simple(positions=>[ ... ], colors=>[...])
110           Creates a simple fountain fill object consisting of linear
111           segments.
112
113           The array references passed as positions and colors must have the
114           same number of elements.  They must have at least 2 elements each.
115
116           colors must contain Imager::Color or Imager::Color::Float objects.
117
118           eg.
119
120             my $f = Imager::Fountain->simple(positions=>[0, 0.2, 1.0],
121                                              colors=>[ NC(255,0,0), NC(0,255,0),
122                                                        NC(0,0,255) ]);
123
124   Implementation Functions
125       Documented for internal use.
126
127       _load_gimp_gradient($class, $fh, $name)
128           Does the work of loading a GIMP gradient file.
129
130       _save_gimp_gradient($self, $fh, $name)
131           Does the work of saving to a GIMP gradient file.
132

FILL PARAMETER

134       The add() documentation mentions a fill parameter in a few places, this
135       is as good a place as any to discuss it.
136
137       The process of deciding the color produced by the gradient works
138       through the following steps:
139
140       1.  calculate the base value, which is typically a distance or an angle
141           of some sort.  This can be positive or occasionally negative,
142           depending on the type of fill being performed (linear, radial,
143           etc).
144
145       2.  clamp or convert the base value to the range 0 through 1, how this
146           is done depends on the repeat parameter.  I'm calling this result
147           the fill parameter.
148
149       3.  the appropriate segment is found.  This is currently done with a
150           linear search, and the first matching segment is used.  If there is
151           no matching segment the pixel is not touched.
152
153       4.  the fill parameter is scaled from 0 to 1 depending on the segment
154           type.
155
156       5.  the color produced, depending on the segment color type.
157

AUTHOR

159       Tony Cook <tony@develop-help.com>
160

SEE ALSO

162       Imager(3)
163
164
165
166perl v5.36.0                      2022-07-22               Imager::Fountain(3)
Impressum