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 some drawing functions, currently just
 174 the Imager box() method.
 175
 176 The currently available fills are:
 177
 178 =over
 179
 180 =item *
 181
 182 solid
 183
 184 =item *
 185
 186 hatch
 187
 188 =item *
 189
 190 fountain (similar to gradients in paint software)
 191
 192 =back
 193
 194 =head1 Common options
 195
 196 =over
 197
 198 =item combine
 199
 200 The way in which the fill data is combined with the underlying image,
 201 possible values include:
 202
 203 =over
 204
 205 =item none
 206
 207 The fill pixel replaces the target pixel.
 208
 209 =item normal
 210
 211 The fill pixels alpha value is used to combine it with the target pixel.
 212
 213 =item multiply
 214
 215 =item mult
 216
 217 Each channel of fill and target is multiplied, and the result is
 218 combined using the alpha channel of the fill pixel.
 219
 220 =item dissolve
 221
 222 If the alpha of the fill pixel is greater than a random number, the
 223 fill pixel is alpha combined with the target pixel.
 224
 225 =item add
 226
 227 The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
 228
 229 =item subtract
 230
 231 The channels of the fill are subtracted from the target, clamped to be
 232 >= 0, and alpha combined with the target.
 233
 234 =item diff
 235
 236 The channels of the fill are subtracted from the target and the
 237 absolute value taken this is alpha combined with the target.
 238
 239 =item lighten
 240
 241 The higher value is taken from each channel of the fill and target
 242 pixels, which is then alpha combined with the target.
 243
 244 =item darken
 245
 246 The higher value is taken from each channel of the fill and target
 247 pixels, which is then alpha combined with the target.
 248
 249 =item hue
 250
 251 The combination of the saturation and value of the target is combined
 252 with the hue of the fill pixel, and is then alpha combined with the
 253 target.
 254
 255 =item sat
 256
 257 The combination of the hue and value of the target is combined
 258 with the saturation of the fill pixel, and is then alpha combined with the
 259 target.
 260
 261 =item value
 262
 263 The combination of the hue and value of the target is combined
 264 with the value of the fill pixel, and is then alpha combined with the
 265 target.
 266
 267 =item color
 268
 269 The combination of the value of the target is combined with the hue
 270 and saturation of the fill pixel, and is then alpha combined with the
 271 target.
 272
 273 =back
 274
 275 =back
 276
 277 In general colors can be specified as Imager::Color or
 278 Imager::Color::Float objects.  The fill object will typically store
 279 both types and convert from one to the other.  If a fill takes 2 color
 280 objects they should have the same type.
 281
 282 =head2 Solid fills
 283
 284   my $fill = Imager::Fill->new(solid=>$color, $combine =>$combine)
 285
 286 Creates a solid fill, the only required parameter is C<solid> which
 287 should be the color to fill with.
 288
 289 =head2 Hatched fills
 290
 291   my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
 292                                dx=>$dx, $dy=>$dy);
 293
 294 Creates a hatched fill.  You can specify the following keywords:
 295
 296 =over
 297
 298 =item hatch
 299
 300 The type of hatch to perform, this can either be the numeric index of
 301 the hatch (not recommended), the symbolic name of the hatch, or an
 302 array of 8 integers which specify the pattern of the hatch.
 303
 304 Hatches are represented as cells 8x8 arrays of bits, which limits their
 305 complexity.
 306
 307 Current hatch names are:
 308
 309 =over
 310
 311 =item check1x1, check2x2, check4x4
 312
 313 checkerboards at varios sizes
 314
 315 =item vline1, vline2, vline4
 316
 317 1, 2, or 4 vertical lines per cell
 318
 319 =item hline1, hline2, hline4
 320
 321 1, 2, or 4 horizontal lines per cell
 322
 323 =item slash1,  slash2
 324
 325 1 or 2 / lines per cell.
 326
 327 =item slosh1,  slosh2
 328
 329 1 or 2 \ lines per cell
 330
 331 =item grid1,  grid2,  grid4
 332
 333 1, 2, or 4 vertical and horizontal lines per cell
 334
 335 =item dots1, dots4, dots16
 336
 337 1, 4 or 16 dots per cell
 338
 339 =item stipple, stipple2
 340
 341 see the samples
 342
 343 =item weave
 344
 345 I hope this one is obvious.
 346
 347 =item cross1,  cross2
 348
 349 2 densities of crosshatch
 350
 351 =item vlozenge,  hlozenge
 352
 353 something like lozenge tiles
 354
 355 =item scalesdown,  scalesup,  scalesleft,  scalesright
 356
 357 Vaguely like fish scales in each direction.
 358
 359 =item tile_L
 360
 361 L-shaped tiles
 362
 363 =back
 364
 365 =item fg
 366
 367 =item bg
 368
 369 The fg color is rendered where bits are set in the hatch, and the bg
 370 where they are clear.  If you use a transparent fg or bg, and set
 371 combine, you can overlay the hatch onto an existing image.
 372
 373 fg defaults to black, bg to white.
 374
 375 =item dx
 376
 377 =item dy
 378
 379 An offset into the hatch cell.  Both default to zero.
 380
 381 =back
 382
 383 You can call Imager::Fill->hatches for a list of hatch names.
 384
 385 =head2 Fountain fills
 386
 387   my $fill = Imager::Fill->new(fountain=>$ftype,
 388        xa=>$xa, ya=>$ya, xb=>$xb, yb=>$yb,
 389        segment=>$segments, repeat=>$repeat, combine=>$combine,
 390        super_sample=>$super_sample, ssample_param=>$ssample_param);
 391
 392 This fills the given region with a fountain fill.  This is exactly the
 393 same fill as the C<fountain> filter, but is restricted to the shape
 394 you are drawing, and the fountain parameter supplies the fill type,
 395 and is required.
 396
 397 =head2 Image Fills
 398
 399   my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
 400                                matrix=>$matrix, $combine);
 401
 402 Fills the given image with a tiled version of the given image.  The
 403 first non-zero value of xoff or yoff will provide an offset along the
 404 given axis between rows or columns of tiles respectively.
 405
 406 The matrix parameter performs a co-ordinate transformation from the
 407 co-ordinates in the target image to the fill image co-ordinates.
 408 Linear interpolation is used to determine the fill pixel.  You can use
 409 the L<Imager::Matrix2d> class to create transformation matrices.
 410
 411 The matrix parameter will significantly slow down the fill.
 412
 413 =head1 OTHER METHODS
 414
 415 =over
 416
 417 =item Imager::Fill->hatches
 418
 419 A list of all defined hatch names.
 420
 421 =item Imager::Fill->combines
 422
 423 A list of all combine types.
 424
 425 =back
 426
 427 =head1 FUTURE PLANS
 428
 429 I'm planning on adding the following types of fills:
 430
 431 =over
 432
 433 =item checkerboard
 434
 435 combines 2 other fills in a checkerboard
 436
 437 =item combine
 438
 439 combines 2 other fills using the levels of an image
 440
 441 =item regmach
 442
 443 uses the transform2() register machine to create fills
 444
 445 =back
 446
 447 =head1 AUTHOR
 448
 449 Tony Cook <tony@develop-help.com>
 450
 451 =head1 SEE ALSO
 452
 453 Imager(3)
 454
 455 =cut