lib/Imager/Fill.pm

   1 package Imager::Fill;
   2 use strict;
   3 use vars qw($VERSION);
   4
   5 $VERSION = "1.010";
   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   else {
 129     $Imager::ERRSTR = "No fill type specified";
 130     warn "No fill type!";
 131     return undef;
 132   }
 133
 134   $self;
 135 }
 136
 137 sub hatches {
 138   return @hatch_types;
 139 }
 140
 141 sub combines {
 142   return Imager->combines;
 143 }
 144
 145 1;
 146
 147 =head1 NAME
 148
 149   Imager::Fill - general fill types
 150
 151 =head1 SYNOPSIS
 152
 153   my $fill1 = Imager::Fill->new(solid=>$color, combine=>$combine);
 154   my $fill2 = Imager::Fill->new(hatch=>'vline2', fg=>$color1, bg=>$color2,
 155                                 dx=>$dx, dy=>$dy);
 156   my $fill3 = Imager::Fill->new(fountain=>$type, ...);
 157   my $fill4 = Imager::Fill->new(image=>$img, ...);
 158
 159 =head1 DESCRIPTION
 160
 161 Creates fill objects for use by most filled area drawing functions.
 162
 163 All fills are created with the new method.
 164
 165 =over
 166
 167 =item new
 168
 169   my $fill = Imager::Fill->new(...);
 170
 171 The parameters depend on the type of fill being created.  See below
 172 for details.
 173
 174 =back
 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 See L<Imager::Draw/"Combine Types">.
 202
 203 =back
 204
 205 In general colors can be specified as Imager::Color or
 206 Imager::Color::Float objects.  The fill object will typically store
 207 both types and convert from one to the other.  If a fill takes 2 color
 208 objects they should have the same type.
 209
 210 =head2 Solid fills
 211
 212   my $fill = Imager::Fill->new(solid=>$color, $combine =>$combine)
 213
 214 Creates a solid fill, the only required parameter is C<solid> which
 215 should be the color to fill with.
 216
 217 =head2 Hatched fills
 218
 219   my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
 220                                dx=>$dx, $dy=>$dy);
 221
 222 Creates a hatched fill.  You can specify the following keywords:
 223
 224 =over
 225
 226 =item hatch
 227
 228 The type of hatch to perform, this can either be the numeric index of
 229 the hatch (not recommended), the symbolic name of the hatch, or an
 230 array of 8 integers which specify the pattern of the hatch.
 231
 232 Hatches are represented as cells 8x8 arrays of bits, which limits their
 233 complexity.
 234
 235 Current hatch names are:
 236
 237 =over
 238
 239 =item check1x1, check2x2, check4x4
 240
 241 checkerboards at varios sizes
 242
 243 =item vline1, vline2, vline4
 244
 245 1, 2, or 4 vertical lines per cell
 246
 247 =item hline1, hline2, hline4
 248
 249 1, 2, or 4 horizontal lines per cell
 250
 251 =item slash1,  slash2
 252
 253 1 or 2 / lines per cell.
 254
 255 =item slosh1,  slosh2
 256
 257 1 or 2 \ lines per cell
 258
 259 =item grid1,  grid2,  grid4
 260
 261 1, 2, or 4 vertical and horizontal lines per cell
 262
 263 =item dots1, dots4, dots16
 264
 265 1, 4 or 16 dots per cell
 266
 267 =item stipple, stipple2
 268
 269 see the samples
 270
 271 =item weave
 272
 273 I hope this one is obvious.
 274
 275 =item cross1,  cross2
 276
 277 2 densities of crosshatch
 278
 279 =item vlozenge,  hlozenge
 280
 281 something like lozenge tiles
 282
 283 =item scalesdown,  scalesup,  scalesleft,  scalesright
 284
 285 Vaguely like fish scales in each direction.
 286
 287 =item tile_L
 288
 289 L-shaped tiles
 290
 291 =back
 292
 293 =item fg
 294
 295 =item bg
 296
 297 The fg color is rendered where bits are set in the hatch, and the bg
 298 where they are clear.  If you use a transparent fg or bg, and set
 299 combine, you can overlay the hatch onto an existing image.
 300
 301 fg defaults to black, bg to white.
 302
 303 =item dx
 304
 305 =item dy
 306
 307 An offset into the hatch cell.  Both default to zero.
 308
 309 =back
 310
 311 You can call Imager::Fill->hatches for a list of hatch names.
 312
 313 =head2 Fountain fills
 314
 315   my $fill = Imager::Fill->new(fountain=>$ftype,
 316        xa=>$xa, ya=>$ya, xb=>$xb, yb=>$yb,
 317        segments=>$segments, repeat=>$repeat, combine=>$combine,
 318        super_sample=>$super_sample, ssample_param=>$ssample_param);
 319
 320 This fills the given region with a fountain fill.  This is exactly the
 321 same fill as the C<fountain> filter, but is restricted to the shape
 322 you are drawing, and the fountain parameter supplies the fill type,
 323 and is required.
 324
 325 =head2 Image Fills
 326
 327   my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
 328                                matrix=>$matrix, $combine);
 329
 330 Fills the given image with a tiled version of the given image.  The
 331 first non-zero value of xoff or yoff will provide an offset along the
 332 given axis between rows or columns of tiles respectively.
 333
 334 The matrix parameter performs a co-ordinate transformation from the
 335 co-ordinates in the target image to the fill image co-ordinates.
 336 Linear interpolation is used to determine the fill pixel.  You can use
 337 the L<Imager::Matrix2d> class to create transformation matrices.
 338
 339 The matrix parameter will significantly slow down the fill.
 340
 341 =head1 OTHER METHODS
 342
 343 =over
 344
 345 =item Imager::Fill->hatches
 346
 347 A list of all defined hatch names.
 348
 349 =item Imager::Fill->combines
 350
 351 A list of all combine types.
 352
 353 =back
 354
 355 =head1 FUTURE PLANS
 356
 357 I'm planning on adding the following types of fills:
 358
 359 =over
 360
 361 =item checkerboard
 362
 363 combines 2 other fills in a checkerboard
 364
 365 =item combine
 366
 367 combines 2 other fills using the levels of an image
 368
 369 =item regmach
 370
 371 uses the transform2() register machine to create fills
 372
 373 =back
 374
 375 =head1 AUTHOR
 376
 377 Tony Cook <tony@develop-help.com>
 378
 379 =head1 SEE ALSO
 380
 381 Imager(3)
 382
 383 =cut