lib/Imager/Fill.pm

   1 package Imager::Fill;
   2
   3 # this needs to be kept in sync with the array of hatches in fills.c
   4 my @hatch_types =
   5   qw/check1x1 check2x2 check4x4 vline1 vline2 vline4
   6      hline1 hline2 hline4 slash1 slosh1 slash2 slosh2
   7      grid1 grid2 grid4 dots1 dots4 dots16 stipple weave cross1 cross2
   8      vlozenge hlozenge scalesdown scalesup scalesleft scalesright stipple2
   9      tile_L stipple3/;
  10 my %hatch_types;
  11 @hatch_types{@hatch_types} = 0..$#hatch_types;
  12
  13 sub new {
  14   my ($class, %hsh) = @_;
  15
  16   my $self = bless { }, $class;
  17   $hsh{combine} ||= 0;
  18   if ($hsh{solid}) {
  19     if (UNIVERSAL::isa($hsh{solid}, 'Imager::Color')) {
  20       $self->{fill} = Imager::i_new_fill_solid($hsh{solid}, $hsh{combine});
  21     }
  22     elsif (UNIVERSAL::isa($hsh{colid}, 'Imager::Color::Float')) {
  23       $self->{fill} = Imager::i_new_fill_solidf($hsh{solid}, $hsh{combine});
  24     }
  25     else {
  26       $Imager::ERRSTR = "solid isn't a color";
  27       return undef;
  28     }
  29   }
  30   elsif (defined $hsh{hatch}) {
  31     $hsh{dx} ||= 0;
  32     $hsh{dy} ||= 0;
  33     $hsh{fg} ||= Imager::Color->new(0, 0, 0);
  34     if (ref $hsh{hatch}) {
  35       $hsh{cust_hatch} = pack("C8", @{$hsh{hatch}});
  36       $hsh{hatch} = 0;
  37     }
  38     elsif ($hsh{hatch} =~ /\D/) {
  39       unless (exists($hatch_types{$hsh{hatch}})) {
  40         $Imager::ERRSTR = "Unknown hatch type $hsh{hatch}";
  41         return undef;
  42       }
  43       $hsh{hatch} = $hatch_types{$hsh{hatch}};
  44     }
  45     if (UNIVERSAL::isa($hsh{fg}, 'Imager::Color')) {
  46       $hsh{bg} ||= Imager::Color->new(255, 255, 255);
  47       $self->{fill} =
  48         Imager::i_new_fill_hatch($hsh{fg}, $hsh{bg}, $hsh{combine},
  49                                  $hsh{hatch}, $hsh{cust_hatch},
  50                                  $hsh{dx}, $hsh{dy});
  51     }
  52     elsif (UNIVERSAL::isa($hsh{bg}, 'Imager::Color::Float')) {
  53       $hsh{bg} ||= Imager::Color::Float->new(1, 1, 1);
  54       $self->{fill} =
  55         Imager::i_new_fill_hatchf($hsh{fg}, $hsh{bg}, $hsh{combine},
  56                                   $hsh{hatch}, $hsh{cust_hatch},
  57                                   $hsh{dx}, $hsh{dy});
  58     }
  59     else {
  60       $Imager::ERRSTR = "fg isn't a color";
  61       return undef;
  62     }
  63   }
  64   elsif (defined $hsh{fountain}) {
  65     # make sure we track the filter's defaults
  66     my $fount = $Imager::filters{fountain};
  67     my $def = $fount->{defaults};
  68     my $names = $fount->{names};
  69
  70     $hsh{ftype} = $hsh{fountain};
  71     # process names of values
  72     for my $name (keys %$names) {
  73       if (defined $hsh{$name} && exists $names->{$name}{$hsh{$name}}) {
  74         $hsh{$name} = $names->{$name}{$hsh{$name}};
  75       }
  76     }
  77     # process defaults
  78     %hsh = (%$def, %hsh);
  79     my @parms = @{$fount->{callseq}};
  80     shift @parms;
  81     for my $name (@parms) {
  82       unless (defined $hsh{$name}) {
  83         $Imager::ERRSTR =
  84           "required parameter '$name' not set for fountain fill";
  85         return undef;
  86       }
  87     }
  88
  89     $self->{fill} =
  90       Imager::i_new_fill_fount($hsh{xa}, $hsh{ya}, $hsh{xb}, $hsh{yb},
  91                   $hsh{ftype}, $hsh{repeat}, $hsh{combine}, $hsh{super_sample},
  92                   $hsh{ssample_param}, $hsh{segments});
  93   }
  94   else {
  95     $Imager::ERRSTR = "No fill type specified";
  96     warn "No fill type!";
  97     return undef;
  98   }
  99
 100   $self;
 101 }
 102
 103 sub hatches {
 104   return @hatch_types;
 105 }
 106
 107 1;
 108
 109 =head1 NAME
 110
 111   Imager::Fill - general fill types
 112
 113 =head1 SYNOPSIS
 114
 115   my $fill1 = Imager::Fill->new(solid=>$color, combine=>$combine);
 116   my $fill2 = Imager::Fill->new(hatch=>'vline2', fg=>$color1, bg=>$color2,
 117                                 dx=>$dx, dy=>$dy);
 118
 119 =head1 DESCRIPTION
 120
 121 Creates fill objects for use by some drawing functions, currently just
 122 the Imager box() method.
 123
 124 The currently available fills are:
 125
 126 =over
 127
 128 =item *
 129
 130 solid
 131
 132 =item *
 133
 134 hatch
 135
 136 =item
 137
 138 fountain (similar to gradients in paint software)
 139
 140 =back
 141
 142 =head1 Common options
 143
 144 =over
 145
 146 =item combine
 147
 148 If this is non-zero the fill combines the given colors or samples (if
 149 the fill is an image) with the underlying image.
 150
 151 This this is missing or zero then the target image pixels are simply
 152 overwritten.
 153
 154 =back
 155
 156 In general colors can be specified as Imager::Color or
 157 Imager::Color::Float objects.  The fill object will typically store
 158 both types and convert from one to the other.  If a fill takes 2 color
 159 objects they should have the same type.
 160
 161 =head2 Solid fills
 162
 163   my $fill = Imager::Fill->new(solid=>$color, $combine =>$combine)
 164
 165 Creates a solid fill, the only required parameter is C<solid> which
 166 should be the color to fill with.
 167
 168 =head2 Hatched fills
 169
 170   my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
 171                                dx=>$dx, $dy=>$dy);
 172
 173 Creates a hatched fill.  You can specify the following keywords:
 174
 175 =over
 176
 177 =item hatch
 178
 179 The type of hatch to perform, this can either be the numeric index of
 180 the hatch (not recommended), the symbolic name of the hatch, or an
 181 array of 8 integers which specify the pattern of the hatch.
 182
 183 Hatches are represented as cells 8x8 arrays of bits, which limits their
 184 complexity.
 185
 186 Current hatch names are:
 187
 188 =over
 189
 190 =item check1x1, check2x2, check4x4
 191
 192 checkerboards at varios sizes
 193
 194 =item vline1, vline2, vline4
 195
 196 1, 2, or 4 vertical lines per cell
 197
 198 =item hline1, hline2, hline4
 199
 200 1, 2, or 4 horizontal lines per cell
 201
 202 =item slash1,  slash2
 203
 204 1 or 2 / lines per cell.
 205
 206 =item slosh1,  slosh2
 207
 208 1 or 2 \ lines per cell
 209
 210 =item grid1,  grid2,  grid4
 211
 212 1, 2, or 4 vertical and horizontal lines per cell
 213
 214 =item dots1, dots4, dots16
 215
 216 1, 4 or 16 dots per cell
 217
 218 =item stipple, stipple2
 219
 220 see the samples
 221
 222 =item weave
 223
 224 I hope this one is obvious.
 225
 226 =item cross1,  cross2
 227
 228 2 densities of crosshatch
 229
 230 =item vlozenge,  hlozenge
 231
 232 something like lozenge tiles
 233
 234 =item scalesdown,  scalesup,  scalesleft,  scalesright
 235
 236 Vaguely like fish scales in each direction.
 237
 238 =item tile_L
 239
 240 L-shaped tiles
 241
 242 =back
 243
 244 =item fg
 245
 246 =item bg
 247
 248 The fg color is rendered where bits are set in the hatch, and the bg
 249 where they are clear.  If you use a transparent fg or bg, and set
 250 combine, you can overlay the hatch onto an existing image.
 251
 252 fg defaults to black, bg to white.
 253
 254 =item dx
 255
 256 =item dy
 257
 258 An offset into the hatch cell.  Both default to zero.
 259
 260 =back
 261
 262 You can call Imager::Fill->hatches for a list of hatch names.
 263
 264 =head2 Fountain fills
 265
 266   my $fill = Imager::Fill->new(fountain=>$ftype,
 267        xa=>$xa, ya=>$ya, xb=>$xb, yb=>$yb,
 268        segment=>$segments, repeat=>$repeat, combine=>$combine,
 269        super_sample=>$super_sample, ssample_param=>$ssample_param);
 270
 271 This fills the given region with a fountain fill.  This is exactly the
 272 same fill as the C<fountain> filter, but is restricted to the shape
 273 you are drawing, and the fountain parameter supplies the fill type,
 274 and is required.
 275
 276 =head1 FUTURE PLANS
 277
 278 I'm planning on adding the following types of fills:
 279
 280 =over
 281
 282 =item image
 283
 284 tiled image fill
 285
 286 =item checkerboard
 287
 288 combines 2 other fills in a checkerboard
 289
 290 =item combine
 291
 292 combines 2 other fills using the levels of an image
 293
 294 =item regmach
 295
 296 uses the transform2() register machine to create fills
 297
 298 =back
 299
 300 =head1 AUTHOR
 301
 302 Tony Cook <tony@develop-help.com>
 303
 304 =head1 SEE ALSO
 305
 306 Imager(3)
 307
 308 =cut