lib/Imager/Fill.pm

   1 package Imager::Fill;
   2 use strict;
   3 use vars qw($VERSION);
   4
   5 $VERSION = "1.011";
   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 =back
 227
 228 =head1 Common options
 229
 230 =over
 231
 232 =item combine
 233
 234 The way in which the fill data is combined with the underlying image.
 235 See L<Imager::Draw/"Combine Types">.
 236
 237 =back
 238
 239 In general colors can be specified as Imager::Color or
 240 Imager::Color::Float objects.  The fill object will typically store
 241 both types and convert from one to the other.  If a fill takes 2 color
 242 objects they should have the same type.
 243
 244 =head2 Solid fills
 245
 246   my $fill = Imager::Fill->new(solid=>$color, $combine =>$combine)
 247
 248 Creates a solid fill, the only required parameter is C<solid> which
 249 should be the color to fill with.
 250
 251 =head2 Hatched fills
 252
 253   my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
 254                                dx=>$dx, $dy=>$dy);
 255
 256 Creates a hatched fill.  You can specify the following keywords:
 257
 258 =over
 259
 260 =item hatch
 261
 262 The type of hatch to perform, this can either be the numeric index of
 263 the hatch (not recommended), the symbolic name of the hatch, or an
 264 array of 8 integers which specify the pattern of the hatch.
 265
 266 Hatches are represented as cells 8x8 arrays of bits, which limits their
 267 complexity.
 268
 269 Current hatch names are:
 270
 271 =over
 272
 273 =item *
 274
 275 C<check1x1>, C<check2x2>, C<check4x4> - checkerboards at various sizes
 276
 277 =item *
 278
 279 C<vline1>, C<vline2>, C<vline4> - 1, 2, or 4 vertical lines per cell
 280
 281 =item *
 282
 283 C<hline1>, C<hline2>, C<hline4> - 1, 2, or 4 horizontal lines per cell
 284
 285 =item *
 286
 287 C<slash1>, C<slash2> - 1 or 2 / lines per cell.
 288
 289 =item *
 290
 291 C<slosh1>, C<slosh2> - 1 or 2 \ lines per cell
 292
 293 =item *
 294
 295 C<grid1>, C<grid2>, C<grid4> - 1, 2, or 4 vertical and horizontal
 296 lines per cell
 297
 298 =item *
 299
 300 C<dots1>, C<dots4>, C<dots16> - 1, 4 or 16 dots per cell
 301
 302 =item *
 303
 304 C<stipple>, C<stipple2> - see the samples
 305
 306 =item *
 307
 308 C<weave> - I hope this one is obvious.
 309
 310 =item *
 311
 312 C<cross1>, C<cross2> - 2 densities of crosshatch
 313
 314 =item *
 315
 316 C<vlozenge>, C<hlozenge> - something like lozenge tiles
 317
 318 =item *
 319
 320 C<scalesdown>, C<scalesup>, C<scalesleft>, C<scalesright> - Vaguely
 321 like fish scales in each direction.
 322
 323 =item *
 324
 325 C<tile_L> - L-shaped tiles
 326
 327 =back
 328
 329 =item *
 330
 331 C<fg>, C<bg> - The C<fg> color is rendered where bits are set in the
 332 hatch, and the C<bg> where they are clear.  If you use a transparent
 333 C<fg> or C<bg>, and set combine, you can overlay the hatch onto an
 334 existing image.
 335
 336 C<fg> defaults to black, C<bg> to white.
 337
 338 =item *
 339
 340 C<dx>, C<dy> - An offset into the hatch cell.  Both default to zero.
 341
 342 =back
 343
 344 You can call Imager::Fill->hatches for a list of hatch names.
 345
 346 =head2 Fountain fills
 347
 348   my $fill = Imager::Fill->new(fountain=>$ftype,
 349        xa=>$xa, ya=>$ya, xb=>$xb, yb=>$yb,
 350        segments=>$segments, repeat=>$repeat, combine=>$combine,
 351        super_sample=>$super_sample, ssample_param=>$ssample_param);
 352
 353 This fills the given region with a fountain fill.  This is exactly the
 354 same fill as the C<fountain> filter, but is restricted to the shape
 355 you are drawing, and the fountain parameter supplies the fill type,
 356 and is required.
 357
 358 =head2 Image Fills
 359
 360   my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
 361                                matrix=>$matrix, $combine);
 362
 363 Fills the given image with a tiled version of the given image.  The
 364 first non-zero value of C<xoff> or C<yoff> will provide an offset
 365 along the given axis between rows or columns of tiles respectively.
 366
 367 The matrix parameter performs a co-ordinate transformation from the
 368 co-ordinates in the target image to the fill image co-ordinates.
 369 Linear interpolation is used to determine the fill pixel.  You can use
 370 the L<Imager::Matrix2d> class to create transformation matrices.
 371
 372 The matrix parameter will significantly slow down the fill.
 373
 374 =head2 Opacity modification fill
 375
 376   my $fill = Imager::Fill->new(type => "opacity",
 377       other => $fill, opacity => 0.25);
 378
 379 This can be used to make a fill that is a more translucent or opaque
 380 version of an existing fill.  This is intended for use where you
 381 receive a fill object as a parameter and need to change the opacity.
 382
 383 Parameters:
 384
 385 =over
 386
 387 =item *
 388
 389 type => "opacity" - Required
 390
 391 =item *
 392
 393 other - the fill to produce a modified version of.  This must be an
 394 Imager::Fill object.  Required.
 395
 396 =item *
 397
 398 opacity - multiplier for the source fill opacity.  Default: 0.5.
 399
 400 =back
 401
 402 The source fills combine mode is used.
 403
 404 =head1 OTHER METHODS
 405
 406 =over
 407
 408 =item Imager::Fill->hatches
 409
 410 A list of all defined hatch names.
 411
 412 =item Imager::Fill->combines
 413
 414 A list of all combine types.
 415
 416 =back
 417
 418 =head1 FUTURE PLANS
 419
 420 I'm planning on adding the following types of fills:
 421
 422 =over
 423
 424 =item *
 425
 426 C<checkerboard> - combines 2 other fills in a checkerboard
 427
 428 =item *
 429
 430 C<combine> - combines 2 other fills using the levels of an image
 431
 432 =item *
 433
 434 C<regmach> - uses the transform2() register machine to create fills
 435
 436 =back
 437
 438 =head1 AUTHOR
 439
 440 Tony Cook <tony@develop-help.com>
 441
 442 =head1 SEE ALSO
 443
 444 Imager(3)
 445
 446 =cut