Imager::Fountain(3pm)

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
55               The start position in the gradient where this segment takes
56               effect between 0 and 1.  Default: 0.
57
58           middle
59               The mid-point of the transition between the 2 colors, between 0
60               and 1.  Default: average of start and end.
61
62           end The end of the gradient, from 0 to 1.  Default: 1.
63
64           c0  The color of the fountain fill where the fill parameter is
65               equal to start.  Default: opaque black.
66
67           c1  The color of the fountain fill where the fill parameter is
68               equal to end.  Default: opaque black.
69
70           type
71               The type of segment, controls the way in which the fill parame‐
72               ter moves from 0 to 1.  Default: linear.
73
74               This can take any of the following values:
75
76               linear
77               curved
78                   Unimplemented so far.
79
80               sine
81               sphereup
82               spheredown
83           color
84               The way in which the color transitions between c0 and c1.
85               Default: direct.
86
87               This can take any of the following values:
88
89               direct
90                   Each channel is simple scaled between c0 and c1.
91
92               hueup
93                   The color is converted to a HSV value and the scaling is
94                   done such that the hue increases as the fill parameter
95                   increases.
96
97               huedown
98                   The color is converted to a HSV value and the scaling is
99                   done such that the hue decreases as the fill parameter
100                   increases.
101
102           In most cases you can ignore some of the arguments, eg.
103
104             # assuming $f is a new Imager::Fountain in each case here
105             use Imager ':handy';
106             # simple transition from red to blue
107             $f->add(c0=>NC('#FF0000'), c1=>NC('#0000FF'));
108             # simple 2 stages from red to green to blue
109             $f->add(end=>0.5, c0=>NC('#FF0000'), c1=>NC('#00FF00'))
110             $f->add(start=>0.5, c0=>NC('#00FF00'), c1=>NC('#0000FF'));
111
112       simple(positions=>[ ... ], colors=>[...])
113           Creates a simple fountain fill object consisting of linear seg‐
114           ments.
115
116           The arrayrefs passed as positions and colors must have the same
117           number of elements.  They must have at least 2 elements each.
118
119           colors must contain Imager::Color or Imager::Color::Float objects.
120
121           eg.
122
123             my $f = Imager::Fountain->simple(positions=>[0, 0.2, 1.0],
124                                              colors=>[ NC(255,0,0), NC(0,255,0),
125                                                        NC(0,0,255) ]);
126
127       Implementation Functions
128
129       Documented for internal use.
130
131       _load_gimp_gradient($class, $fh, $name)
132           Does the work of loading a GIMP gradient file.
133
134       _save_gimp_gradient($self, $fh, $name)
135           Does the work of saving to a GIMP gradient file.
136

FILL PARAMETER

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

AUTHOR

163       Tony Cook <tony@develop-help.com>
164

NAME

SYNOPSIS

DESCRIPTION

FILL PARAMETER

AUTHOR

SEE ALSO