lib/Imager/Fill.pm

   1 package Imager::Fill;
   2 use strict;
   3 use vars qw($VERSION);
   4
   5 $VERSION = "1.012";
   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 *_color = \&Imager::_color;
  18
  19 sub new {
  20   my ($class, %hsh) = @_;
  21
  22   my $self = bless { }, $class;
  23   $hsh{combine} = Imager->_combine($hsh{combine}, 0);
  24   if ($hsh{solid}) {
  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});
  29     }
  30     elsif (UNIVERSAL::isa($solid, 'Imager::Color::Float')) {
  31       $self->{fill} =
  32         Imager::i_new_fill_solidf($solid, $hsh{combine});
  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     }
  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));
  57       $self->{fill} =
  58         Imager::i_new_fill_hatch($fg, $bg, $hsh{combine},
  59                                  $hsh{hatch}, $hsh{cust_hatch},
  60                                  $hsh{dx}, $hsh{dy});
  61     }
  62     elsif (UNIVERSAL::isa($fg, 'Imager::Color::Float')) {
  63       my $bg  = _color($hsh{bg} || Imager::Color::Float->new(1, 1, 1));
  64       $self->{fill} =
  65         Imager::i_new_fill_hatchf($fg, $bg, $hsh{combine},
  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
  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
 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},
 118                   $hsh{ssample_param}, \@segments);
 119   }
 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   }
 128   elsif (defined $hsh{type} && $hsh{type} eq "opacity") {
 129     my $other_fill = delete $hsh{other};
 130     unless (defined $other_fill) {
 131       Imager->_set_error("'other' parameter required to create opacity fill");
 132       return;
 133     }
 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) {
 145         Imager->_set_error("'other' parameter must be an Imager::Fill object to create an opacity fill");
 146         return;
 147       }
 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   }
 157   else {
 158     $Imager::ERRSTR = "No fill type specified";
 159     warn "No fill type!";
 160     return undef;
 161   }
 162
 163   $self;
 164 }
 165
 166 sub hatches {
 167   return @hatch_types;
 168 }
 169
 170 sub combines {
 171   return Imager->combines;
 172 }
 173
 174 1;
 175
 176 =head1 NAME
 177
 178   Imager::Fill - general fill types
 179
 180 =head1 SYNOPSIS
 181
 182   use Imager;
 183   use Imager::Fill;
 184
 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);
 188   my $fill3 = Imager::Fill->new(fountain=>$type, ...);
 189   my $fill4 = Imager::Fill->new(image=>$img, ...);
 190   my $fill5 = Imager::Fill->new(type => "opacity", other => $fill,
 191                                 opacity => ...);
 192
 193 =head1 DESCRIPTION
 194
 195 Creates fill objects for use by most filled area drawing functions.
 196
 197 All fills are created with the new method.
 198
 199 =over
 200
 201 =item new
 202
 203   my $fill = Imager::Fill->new(...);
 204
 205 The parameters depend on the type of fill being created.  See below
 206 for details.
 207
 208 =back
 209
 210 The currently available fills are:
 211
 212 =over
 213
 214 =item *
 215
 216 solid
 217
 218 =item *
 219
 220 hatch
 221
 222 =item *
 223
 224 fountain (similar to gradients in paint software)
 225
 226 =item *
 227
 228 image - fill with an image, possibly transformed
 229
 230 =item *
 231
 232 opacity - a lower opacity version of some other fill
 233
 234 =back
 235
 236 =head1 Common options
 237
 238 =over
 239
 240 =item combine
 241
 242 The way in which the fill data is combined with the underlying image.
 243 See L<Imager::Draw/"Combine Types">.
 244
 245 =back
 246
 247 In general colors can be specified as L<Imager::Color> or
 248 L<Imager::Color::Float> objects.  The fill object will typically store
 249 both types and convert from one to the other.  If a fill takes 2 color
 250 objects they should have the same type.
 251
 252 =head2 Solid fills
 253
 254   my $fill = Imager::Fill->new(solid=>$color, combine =>$combine)
 255
 256 Creates a solid fill, the only required parameter is C<solid> which
 257 should be the color to fill with.
 258
 259 A translucent red fill:
 260
 261   my $red = Imager::Fill->new(solid => "FF000080", combine => "normal");
 262
 263 =head2 Hatched fills
 264
 265   my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
 266                                dx=>$dx, $dy=>$dy);
 267
 268 Creates a hatched fill.  You can specify the following keywords:
 269
 270 =over
 271
 272 =item *
 273
 274 C<hatch> - The type of hatch to perform, this can either be the
 275 numeric index of the hatch (not recommended), the symbolic name of the
 276 hatch, or an array of 8 integers which specify the pattern of the
 277 hatch.
 278
 279 Hatches are represented as cells 8x8 arrays of bits, which limits their
 280 complexity.
 281
 282 Current hatch names are:
 283
 284 =over
 285
 286 =item *
 287
 288 C<check1x1>, C<check2x2>, C<check4x4> - checkerboards at various sizes
 289
 290 =item *
 291
 292 C<vline1>, C<vline2>, C<vline4> - 1, 2, or 4 vertical lines per cell
 293
 294 =item *
 295
 296 C<hline1>, C<hline2>, C<hline4> - 1, 2, or 4 horizontal lines per cell
 297
 298 =item *
 299
 300 C<slash1>, C<slash2> - 1 or 2 / lines per cell.
 301
 302 =item *
 303
 304 C<slosh1>, C<slosh2> - 1 or 2 \ lines per cell
 305
 306 =item *
 307
 308 C<grid1>, C<grid2>, C<grid4> - 1, 2, or 4 vertical and horizontal
 309 lines per cell
 310
 311 =item *
 312
 313 C<dots1>, C<dots4>, C<dots16> - 1, 4 or 16 dots per cell
 314
 315 =item *
 316
 317 C<stipple>, C<stipple2> - see the samples
 318
 319 =item *
 320
 321 C<weave> - I hope this one is obvious.
 322
 323 =item *
 324
 325 C<cross1>, C<cross2> - 2 densities of crosshatch
 326
 327 =item *
 328
 329 C<vlozenge>, C<hlozenge> - something like lozenge tiles
 330
 331 =item *
 332
 333 C<scalesdown>, C<scalesup>, C<scalesleft>, C<scalesright> - Vaguely
 334 like fish scales in each direction.
 335
 336 =item *
 337
 338 C<tile_L> - L-shaped tiles
 339
 340 =back
 341
 342 =item *
 343
 344 C<fg>, C<bg> - The C<fg> color is rendered where bits are set in the
 345 hatch, and the C<bg> where they are clear.  If you use a transparent
 346 C<fg> or C<bg>, and set combine, you can overlay the hatch onto an
 347 existing image.
 348
 349 C<fg> defaults to black, C<bg> to white.
 350
 351 =item *
 352
 353 C<dx>, C<dy> - An offset into the hatch cell.  Both default to zero.
 354
 355 =back
 356
 357 A blue and white 4-pixel check pattern:
 358
 359   my $fill = Imager::Fill->new(hatch => "check2x2", fg => "blue");
 360
 361 You 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,
 367        segments=>$segments, repeat=>$repeat, combine=>$combine,
 368        super_sample=>$super_sample, ssample_param=>$ssample_param);
 369
 370 This fills the given region with a fountain fill.  This is exactly the
 371 same fill as the C<fountain> filter, but is restricted to the shape
 372 you are drawing, and the fountain parameter supplies the fill type,
 373 and is required.
 374
 375 A radial fill from white to transparent centered on (50, 50) with a 50
 376 pixel 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
 386 =head2 Image Fills
 387
 388   my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
 389                                matrix=>$matrix, combine => $combine);
 390
 391 Fills the given image with a tiled version of the given image.  The
 392 first non-zero value of C<xoff> or C<yoff> will provide an offset
 393 along the given axis between rows or columns of tiles respectively.
 394
 395 The matrix parameter performs a co-ordinate transformation from the
 396 co-ordinates in the target image to the fill image co-ordinates.
 397 Linear interpolation is used to determine the fill pixel.  You can use
 398 the L<Imager::Matrix2d> class to create transformation matrices.
 399
 400 The matrix parameter will significantly slow down the fill.
 401
 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
 419 =head2 Opacity modification fill
 420
 421   my $fill = Imager::Fill->new(type => "opacity",
 422       other => $fill, opacity => 0.25);
 423
 424 This can be used to make a fill that is a more translucent or opaque
 425 version of an existing fill.  This is intended for use where you
 426 receive a fill object as a parameter and need to change the opacity.
 427
 428 Parameters:
 429
 430 =over
 431
 432 =item *
 433
 434 type => "opacity" - Required
 435
 436 =item *
 437
 438 other - the fill to produce a modified version of.  This must be an
 439 Imager::Fill object.  Required.
 440
 441 =item *
 442
 443 opacity - multiplier for the source fill opacity.  Default: 0.5.
 444
 445 =back
 446
 447 The source fills combine mode is used.
 448
 449   my $hatch = Imager::Fill->new(hatch => "check4x4", combine => "normal");
 450   my $fill = Imager::Fill->new(type => "opacity", other => $hatch);
 451
 452 =head1 OTHER METHODS
 453
 454 =over
 455
 456 =item Imager::Fill->hatches
 457
 458 A list of all defined hatch names.
 459
 460 =item Imager::Fill->combines
 461
 462 A list of all combine types.
 463
 464 =back
 465
 466 =head1 FUTURE PLANS
 467
 468 I'm planning on adding the following types of fills:
 469
 470 =over
 471
 472 =item *
 473
 474 C<checkerboard> - combines 2 other fills in a checkerboard
 475
 476 =item *
 477
 478 C<combine> - combines 2 other fills using the levels of an image
 479
 480 =item *
 481
 482 C<regmach> - uses the transform2() register machine to create fills
 483
 484 =back
 485
 486 =head1 AUTHOR
 487
 488 Tony Cook <tony@develop-help.com>
 489
 490 =head1 SEE ALSO
 491
 492 Imager(3)
 493
 494 =cut