lib/Imager/Fill.pm

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