1Imager::Fountain(3) User Contributed Perl Documentation Imager::Fountain(3)
2
6 Imager::Fountain - a class for building fountain fills suitable for use by
7 the fountain filter.
8
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
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 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 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 my $gradient = Imager::Fountain->read(gimp=>'foo.ggr');
33 my $name;
34 my $gradient2 = Imager::Fountain->read(gimp=>'bar.ggr', name=>\$name);
35 write(gimp=>$filename)
37 write(gimp=>$filename, name=>$name)
38 Save the gradient to a GIMP gradient file.
39 The second variant allows the gradient name to be set (for newer
41 versions of the GIMP).
42 $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 new Create an empty fountain fill description.
49 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 • "start" - the start position in the gradient where this segment
55 takes effect between 0 and 1. Default: 0.
56 • "middle" - the mid-point of the transition between the 2
58 colors, between 0 and 1. Default: average of "start" and
59 "end".
60 • "end" - the end of the gradient, from 0 to 1. Default: 1.
62 • "c0" - the color of the fountain fill where the fill parameter
64 is equal to start. Default: opaque black.
65 • "c1" - the color of the fountain fill where the fill parameter
67 is equal to end. Default: opaque black.
68 • "type" - the type of segment, controls the way in which the
70 fill parameter moves from 0 to 1. Default: linear.
71 This can take any of the following values:
73 • "linear"
75 • "curved" - unimplemented so far.
77 • "sine"
79 • "sphereup"
81 • "spheredown"
83 • "color" - the way in which the color transitions between "c0"
85 and "c1". Default: direct.
86 This can take any of the following values:
88 • "direct" - each channel is simple scaled between c0 and c1.
90 • "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 • "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 In most cases you can ignore some of the arguments, eg.
100 # 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 simple(positions=>[ ... ], colors=>[...])
110 Creates a simple fountain fill object consisting of linear
111 segments.
112 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 colors must contain Imager::Color or Imager::Color::Float objects.
117 eg.
119 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 Implementation Functions
125 Documented for internal use.
126 _load_gimp_gradient($class, $fh, $name)
128 Does the work of loading a GIMP gradient file.
129 _save_gimp_gradient($self, $fh, $name)
131 Does the work of saving to a GIMP gradient file.
132
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 The process of deciding the color produced by the gradient works
138 through the following steps:
139 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 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 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 4. the fill parameter is scaled from 0 to 1 depending on the segment
154 type.
155 5. the color produced, depending on the segment color type.
157
159 Tony Cook <tony@develop-help.com>
160
162 Imager(3)
163perl v5.36.0 2022-07-22 Imager::Fountain(3)