lib/Imager/Fill.pm

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