eliminate use vars
[imager.git] / lib / Imager / Fill.pm
CommitLineData
f1ac5027 1package Imager::Fill;
ee64a81f 2use 5.006;
efdc2568 3use strict;
f17b46d8 4
ee64a81f 5our $VERSION = "1.013";
f17b46d8 6
f1ac5027
TC
7# this needs to be kept in sync with the array of hatches in fills.c
8my @hatch_types =
9 qw/check1x1 check2x2 check4x4 vline1 vline2 vline4
10 hline1 hline2 hline4 slash1 slosh1 slash2 slosh2
11 grid1 grid2 grid4 dots1 dots4 dots16 stipple weave cross1 cross2
12 vlozenge hlozenge scalesdown scalesup scalesleft scalesright stipple2
cc6483e0 13 tile_L stipple3/;
f1ac5027
TC
14my %hatch_types;
15@hatch_types{@hatch_types} = 0..$#hatch_types;
16
3a9a4241 17*_color = \&Imager::_color;
efdc2568 18
f1ac5027
TC
19sub new {
20 my ($class, %hsh) = @_;
21
22 my $self = bless { }, $class;
9b1ec2b8 23 $hsh{combine} = Imager->_combine($hsh{combine}, 0);
f1ac5027 24 if ($hsh{solid}) {
efdc2568
TC
25 my $solid = _color($hsh{solid});
26 if (UNIVERSAL::isa($solid, 'Imager::Color')) {
27 $self->{fill} =
28 Imager::i_new_fill_solid($solid, $hsh{combine});
f1ac5027 29 }
efdc2568
TC
30 elsif (UNIVERSAL::isa($solid, 'Imager::Color::Float')) {
31 $self->{fill} =
32 Imager::i_new_fill_solidf($solid, $hsh{combine});
f1ac5027
TC
33 }
34 else {
35 $Imager::ERRSTR = "solid isn't a color";
36 return undef;
37 }
38 }
39 elsif (defined $hsh{hatch}) {
40 $hsh{dx} ||= 0;
41 $hsh{dy} ||= 0;
42 $hsh{fg} ||= Imager::Color->new(0, 0, 0);
43 if (ref $hsh{hatch}) {
44 $hsh{cust_hatch} = pack("C8", @{$hsh{hatch}});
45 $hsh{hatch} = 0;
46 }
47 elsif ($hsh{hatch} =~ /\D/) {
48 unless (exists($hatch_types{$hsh{hatch}})) {
49 $Imager::ERRSTR = "Unknown hatch type $hsh{hatch}";
50 return undef;
51 }
52 $hsh{hatch} = $hatch_types{$hsh{hatch}};
53 }
efdc2568
TC
54 my $fg = _color($hsh{fg});
55 if (UNIVERSAL::isa($fg, 'Imager::Color')) {
56 my $bg = _color($hsh{bg} || Imager::Color->new(255, 255, 255));
f1ac5027 57 $self->{fill} =
efdc2568 58 Imager::i_new_fill_hatch($fg, $bg, $hsh{combine},
f1ac5027
TC
59 $hsh{hatch}, $hsh{cust_hatch},
60 $hsh{dx}, $hsh{dy});
61 }
efdc2568
TC
62 elsif (UNIVERSAL::isa($fg, 'Imager::Color::Float')) {
63 my $bg = _color($hsh{bg} || Imager::Color::Float->new(1, 1, 1));
f1ac5027 64 $self->{fill} =
efdc2568 65 Imager::i_new_fill_hatchf($fg, $bg, $hsh{combine},
f1ac5027
TC
66 $hsh{hatch}, $hsh{cust_hatch},
67 $hsh{dx}, $hsh{dy});
68 }
69 else {
70 $Imager::ERRSTR = "fg isn't a color";
71 return undef;
72 }
73 }
74 elsif (defined $hsh{fountain}) {
75 # make sure we track the filter's defaults
76 my $fount = $Imager::filters{fountain};
77 my $def = $fount->{defaults};
78 my $names = $fount->{names};
79
80 $hsh{ftype} = $hsh{fountain};
81 # process names of values
82 for my $name (keys %$names) {
83 if (defined $hsh{$name} && exists $names->{$name}{$hsh{$name}}) {
84 $hsh{$name} = $names->{$name}{$hsh{$name}};
85 }
86 }
87 # process defaults
88 %hsh = (%$def, %hsh);
89 my @parms = @{$fount->{callseq}};
90 shift @parms;
91 for my $name (@parms) {
92 unless (defined $hsh{$name}) {
93 $Imager::ERRSTR =
94 "required parameter '$name' not set for fountain fill";
95 return undef;
96 }
97 }
98
109bec2d
TC
99 # check that the segments supplied is an array ref
100 unless (ref $hsh{segments} && $hsh{segments} =~ /ARRAY/) {
101 $Imager::ERRSTR =
102 "segments must be an array reference or Imager::Fountain object";
103 return;
104 }
105
106 # make sure the segments are specified with colors
107 my @segments;
108 for my $segment (@{$hsh{segments}}) {
109 my @new_segment = @$segment;
110
111 $_ = _color($_) or return for @new_segment[3,4];
112 push @segments, \@new_segment;
113 }
114
f1ac5027
TC
115 $self->{fill} =
116 Imager::i_new_fill_fount($hsh{xa}, $hsh{ya}, $hsh{xb}, $hsh{yb},
117 $hsh{ftype}, $hsh{repeat}, $hsh{combine}, $hsh{super_sample},
109bec2d 118 $hsh{ssample_param}, \@segments);
f1ac5027 119 }
f576ce7e
TC
120 elsif (defined $hsh{image}) {
121 $hsh{xoff} ||= 0;
122 $hsh{yoff} ||= 0;
123 $self->{fill} =
124 Imager::i_new_fill_image($hsh{image}{IMG}, $hsh{matrix}, $hsh{xoff},
125 $hsh{yoff}, $hsh{combine});
126 $self->{DEPS} = [ $hsh{image}{IMG} ];
127 }
52f2b10a
TC
128 elsif (defined $hsh{type} && $hsh{type} eq "opacity") {
129 my $other_fill = delete $hsh{other};
130 unless (defined $other_fill) {
a16bae72 131 Imager->_set_error("'other' parameter required to create opacity fill");
52f2b10a
TC
132 return;
133 }
6f1e1621
TC
134 unless (ref $other_fill &&
135 eval { $other_fill->isa("Imager::Fill") }) {
136 # try to auto convert to a fill object
137 if (ref $other_fill && $other_fill =~ /HASH/) {
138 $other_fill = Imager::Fill->new(%$other_fill)
139 or return;
140 }
141 else {
142 undef $other_fill;
143 }
144 unless ($other_fill) {
a16bae72 145 Imager->_set_error("'other' parameter must be an Imager::Fill object to create an opacity fill");
6f1e1621
TC
146 return;
147 }
52f2b10a
TC
148 }
149
150 my $raw_fill = $other_fill->{fill};
151 my $opacity = delete $hsh{opacity};
152 defined $opacity or $opacity = 0.5; # some sort of default
153 $self->{fill} =
154 Imager::i_new_fill_opacity($raw_fill, $opacity);
155 $self->{DEPS} = [ $other_fill ]; # keep reference to old fill and its deps
156 }
f1ac5027
TC
157 else {
158 $Imager::ERRSTR = "No fill type specified";
159 warn "No fill type!";
160 return undef;
161 }
162
163 $self;
164}
165
166sub hatches {
167 return @hatch_types;
168}
169
efdc2568 170sub combines {
9b1ec2b8 171 return Imager->combines;
efdc2568
TC
172}
173
f1ac5027
TC
1741;
175
176=head1 NAME
177
178 Imager::Fill - general fill types
179
180=head1 SYNOPSIS
181
668c4f62
TC
182 use Imager;
183 use Imager::Fill;
184
f1ac5027
TC
185 my $fill1 = Imager::Fill->new(solid=>$color, combine=>$combine);
186 my $fill2 = Imager::Fill->new(hatch=>'vline2', fg=>$color1, bg=>$color2,
187 dx=>$dx, dy=>$dy);
f576ce7e
TC
188 my $fill3 = Imager::Fill->new(fountain=>$type, ...);
189 my $fill4 = Imager::Fill->new(image=>$img, ...);
a16bae72
TC
190 my $fill5 = Imager::Fill->new(type => "opacity", other => $fill,
191 opacity => ...);
f1ac5027
TC
192
193=head1 DESCRIPTION
194
d5556805
TC
195Creates fill objects for use by most filled area drawing functions.
196
197All fills are created with the new method.
198
199=over
200
201=item new
202
88a360c1 203 my $fill = Imager::Fill->new(...);
d5556805
TC
204
205The parameters depend on the type of fill being created. See below
206for details.
207
208=back
f1ac5027
TC
209
210The currently available fills are:
211
212=over
213
214=item *
215
216solid
217
218=item *
219
220hatch
221
65814e8e 222=item *
f1ac5027
TC
223
224fountain (similar to gradients in paint software)
225
07d3b409
TC
226=item *
227
228image - fill with an image, possibly transformed
229
230=item *
231
232opacity - a lower opacity version of some other fill
233
f1ac5027
TC
234=back
235
236=head1 Common options
237
238=over
239
240=item combine
241
9b1ec2b8
TC
242The way in which the fill data is combined with the underlying image.
243See L<Imager::Draw/"Combine Types">.
f1ac5027
TC
244
245=back
246
07d3b409
TC
247In general colors can be specified as L<Imager::Color> or
248L<Imager::Color::Float> objects. The fill object will typically store
f1ac5027
TC
249both types and convert from one to the other. If a fill takes 2 color
250objects they should have the same type.
251
252=head2 Solid fills
253
07d3b409 254 my $fill = Imager::Fill->new(solid=>$color, combine =>$combine)
f1ac5027
TC
255
256Creates a solid fill, the only required parameter is C<solid> which
257should be the color to fill with.
258
e7fad746
TC
259A translucent red fill:
260
261 my $red = Imager::Fill->new(solid => "FF000080", combine => "normal");
262
f1ac5027
TC
263=head2 Hatched fills
264
265 my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
266 dx=>$dx, $dy=>$dy);
267
268Creates a hatched fill. You can specify the following keywords:
269
270=over
271
183e3e00 272=item *
f1ac5027 273
183e3e00
TC
274C<hatch> - The type of hatch to perform, this can either be the
275numeric index of the hatch (not recommended), the symbolic name of the
276hatch, or an array of 8 integers which specify the pattern of the
277hatch.
f1ac5027
TC
278
279Hatches are represented as cells 8x8 arrays of bits, which limits their
280complexity.
281
282Current hatch names are:
283
284=over
285
5715f7c3 286=item *
f1ac5027 287
5715f7c3 288C<check1x1>, C<check2x2>, C<check4x4> - checkerboards at various sizes
f1ac5027 289
5715f7c3 290=item *
f1ac5027 291
5715f7c3 292C<vline1>, C<vline2>, C<vline4> - 1, 2, or 4 vertical lines per cell
f1ac5027 293
5715f7c3 294=item *
f1ac5027 295
5715f7c3 296C<hline1>, C<hline2>, C<hline4> - 1, 2, or 4 horizontal lines per cell
f1ac5027 297
5715f7c3 298=item *
f1ac5027 299
5715f7c3 300C<slash1>, C<slash2> - 1 or 2 / lines per cell.
f1ac5027 301
5715f7c3 302=item *
f1ac5027 303
5715f7c3 304C<slosh1>, C<slosh2> - 1 or 2 \ lines per cell
f1ac5027 305
5715f7c3 306=item *
f1ac5027 307
5715f7c3
TC
308C<grid1>, C<grid2>, C<grid4> - 1, 2, or 4 vertical and horizontal
309lines per cell
f1ac5027 310
5715f7c3 311=item *
f1ac5027 312
5715f7c3 313C<dots1>, C<dots4>, C<dots16> - 1, 4 or 16 dots per cell
f1ac5027 314
5715f7c3 315=item *
f1ac5027 316
5715f7c3 317C<stipple>, C<stipple2> - see the samples
f1ac5027 318
5715f7c3 319=item *
f1ac5027 320
5715f7c3 321C<weave> - I hope this one is obvious.
f1ac5027 322
5715f7c3 323=item *
f1ac5027 324
5715f7c3 325C<cross1>, C<cross2> - 2 densities of crosshatch
f1ac5027 326
5715f7c3 327=item *
f1ac5027 328
5715f7c3 329C<vlozenge>, C<hlozenge> - something like lozenge tiles
f1ac5027 330
5715f7c3 331=item *
f1ac5027 332
5715f7c3
TC
333C<scalesdown>, C<scalesup>, C<scalesleft>, C<scalesright> - Vaguely
334like fish scales in each direction.
f1ac5027 335
5715f7c3 336=item *
f1ac5027 337
5715f7c3 338C<tile_L> - L-shaped tiles
f1ac5027
TC
339
340=back
341
5715f7c3 342=item *
f1ac5027 343
5715f7c3
TC
344C<fg>, C<bg> - The C<fg> color is rendered where bits are set in the
345hatch, and the C<bg> where they are clear. If you use a transparent
346C<fg> or C<bg>, and set combine, you can overlay the hatch onto an
347existing image.
f1ac5027 348
5715f7c3 349C<fg> defaults to black, C<bg> to white.
f1ac5027 350
5715f7c3 351=item *
f1ac5027 352
5715f7c3 353C<dx>, C<dy> - An offset into the hatch cell. Both default to zero.
f1ac5027
TC
354
355=back
356
94995883 357A blue and white 4-pixel check pattern:
e7fad746
TC
358
359 my $fill = Imager::Fill->new(hatch => "check2x2", fg => "blue");
360
f1ac5027
TC
361You can call Imager::Fill->hatches for a list of hatch names.
362
363=head2 Fountain fills
364
365 my $fill = Imager::Fill->new(fountain=>$ftype,
366 xa=>$xa, ya=>$ya, xb=>$xb, yb=>$yb,
12e92882 367 segments=>$segments, repeat=>$repeat, combine=>$combine,
f1ac5027
TC
368 super_sample=>$super_sample, ssample_param=>$ssample_param);
369
370This fills the given region with a fountain fill. This is exactly the
371same fill as the C<fountain> filter, but is restricted to the shape
372you are drawing, and the fountain parameter supplies the fill type,
373and is required.
374
e7fad746
TC
375A radial fill from white to transparent centered on (50, 50) with a 50
376pixel radius:
377
378 use Imager::Fountain;
379 my $segs = Imager::Fountain->simple(colors => [ "FFFFFF", "FFFFFF00" ],
380 positions => [ 0, 1 ]);
381 my $fill = Imager::Fill->new(fountain => "radial", segments => $segs,
382 xa => 50, ya => 50, xb => 0, yb => 50,
383 combine => "normal");
384
385
f576ce7e
TC
386=head2 Image Fills
387
388 my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
07d3b409 389 matrix=>$matrix, combine => $combine);
f576ce7e
TC
390
391Fills the given image with a tiled version of the given image. The
5715f7c3
TC
392first non-zero value of C<xoff> or C<yoff> will provide an offset
393along the given axis between rows or columns of tiles respectively.
f576ce7e
TC
394
395The matrix parameter performs a co-ordinate transformation from the
396co-ordinates in the target image to the fill image co-ordinates.
397Linear interpolation is used to determine the fill pixel. You can use
398the L<Imager::Matrix2d> class to create transformation matrices.
399
400The matrix parameter will significantly slow down the fill.
401
e7fad746
TC
402 # some image to act as a texture
403 my $txim = Imager->new(...);
404
405 # simple tiling
406 my $fill = Imager::Fill->new(image => $txim);
407
408 # tile with a vertical offset
409 my $fill = Imager::Fill->new(image => $txim, yoff => 10);
410
411 # tile with a horizontal offset
412 my $fill = Imager::Fill->new(image => $txim, xoff => 10);
413
414 # rotated
415 use Imager::Matrix2d;
416 my $fill = Imager::Fill->new(image => $txim,
417 matrix => Imager::Matrix2d->rotate(degrees => 20));
418
52f2b10a
TC
419=head2 Opacity modification fill
420
a3ccfb4a
TC
421 my $fill = Imager::Fill->new(type => "opacity",
422 other => $fill, opacity => 0.25);
52f2b10a 423
a16bae72 424This can be used to make a fill that is a more translucent or opaque
52f2b10a
TC
425version of an existing fill. This is intended for use where you
426receive a fill object as a parameter and need to change the opacity.
427
428Parameters:
429
430=over
431
432=item *
433
a3ccfb4a 434type => "opacity" - Required
52f2b10a
TC
435
436=item *
437
438other - the fill to produce a modified version of. This must be an
439Imager::Fill object. Required.
440
441=item *
442
443opacity - multiplier for the source fill opacity. Default: 0.5.
444
445=back
446
5715f7c3 447The source fills combine mode is used.
52f2b10a 448
e7fad746
TC
449 my $hatch = Imager::Fill->new(hatch => "check4x4", combine => "normal");
450 my $fill = Imager::Fill->new(type => "opacity", other => $hatch);
451
efdc2568
TC
452=head1 OTHER METHODS
453
454=over
455
456=item Imager::Fill->hatches
457
458A list of all defined hatch names.
459
460=item Imager::Fill->combines
461
462A list of all combine types.
463
464=back
465
f1ac5027
TC
466=head1 FUTURE PLANS
467
468I'm planning on adding the following types of fills:
469
470=over
471
5715f7c3 472=item *
f1ac5027 473
5715f7c3 474C<checkerboard> - combines 2 other fills in a checkerboard
f1ac5027 475
5715f7c3 476=item *
f1ac5027 477
5715f7c3 478C<combine> - combines 2 other fills using the levels of an image
f1ac5027 479
5715f7c3 480=item *
f1ac5027 481
5715f7c3 482C<regmach> - uses the transform2() register machine to create fills
f1ac5027
TC
483
484=back
485
486=head1 AUTHOR
487
488Tony Cook <tony@develop-help.com>
489
490=head1 SEE ALSO
491
492Imager(3)
493
494=cut