use strict;
use vars qw($VERSION);
-$VERSION = "1.009";
+$VERSION = "1.012";
# this needs to be kept in sync with the array of hatches in fills.c
my @hatch_types =
my %hatch_types;
@hatch_types{@hatch_types} = 0..$#hatch_types;
-my @combine_types =
- qw/none normal multiply dissolve add subtract diff lighten darken
- hue saturation value color/;
-my %combine_types;
-@combine_types{@combine_types} = 0 .. $#combine_types;
-$combine_types{mult} = $combine_types{multiply};
-$combine_types{'sub'} = $combine_types{subtract};
-$combine_types{sat} = $combine_types{saturation};
-
*_color = \&Imager::_color;
sub new {
my ($class, %hsh) = @_;
my $self = bless { }, $class;
- $hsh{combine} ||= 0;
- if (exists $combine_types{$hsh{combine}}) {
- $hsh{combine} = $combine_types{$hsh{combine}};
- }
+ $hsh{combine} = Imager->_combine($hsh{combine}, 0);
if ($hsh{solid}) {
my $solid = _color($hsh{solid});
if (UNIVERSAL::isa($solid, 'Imager::Color')) {
$hsh{yoff}, $hsh{combine});
$self->{DEPS} = [ $hsh{image}{IMG} ];
}
+ elsif (defined $hsh{type} && $hsh{type} eq "opacity") {
+ my $other_fill = delete $hsh{other};
+ unless (defined $other_fill) {
+ Imager->_set_error("'other' parameter required to create opacity fill");
+ return;
+ }
+ unless (ref $other_fill &&
+ eval { $other_fill->isa("Imager::Fill") }) {
+ # try to auto convert to a fill object
+ if (ref $other_fill && $other_fill =~ /HASH/) {
+ $other_fill = Imager::Fill->new(%$other_fill)
+ or return;
+ }
+ else {
+ undef $other_fill;
+ }
+ unless ($other_fill) {
+ Imager->_set_error("'other' parameter must be an Imager::Fill object to create an opacity fill");
+ return;
+ }
+ }
+
+ my $raw_fill = $other_fill->{fill};
+ my $opacity = delete $hsh{opacity};
+ defined $opacity or $opacity = 0.5; # some sort of default
+ $self->{fill} =
+ Imager::i_new_fill_opacity($raw_fill, $opacity);
+ $self->{DEPS} = [ $other_fill ]; # keep reference to old fill and its deps
+ }
else {
$Imager::ERRSTR = "No fill type specified";
warn "No fill type!";
}
sub combines {
- return @combine_types;
+ return Imager->combines;
}
1;
=head1 SYNOPSIS
+ use Imager;
+ use Imager::Fill;
+
my $fill1 = Imager::Fill->new(solid=>$color, combine=>$combine);
my $fill2 = Imager::Fill->new(hatch=>'vline2', fg=>$color1, bg=>$color2,
dx=>$dx, dy=>$dy);
my $fill3 = Imager::Fill->new(fountain=>$type, ...);
my $fill4 = Imager::Fill->new(image=>$img, ...);
+ my $fill5 = Imager::Fill->new(type => "opacity", other => $fill,
+ opacity => ...);
=head1 DESCRIPTION
-Creates fill objects for use by some drawing functions, currently just
-the Imager box() method.
+Creates fill objects for use by most filled area drawing functions.
-The currently available fills are:
+All fills are created with the new method.
=over
-=item *
+=item new
-solid
+ my $fill = Imager::Fill->new(...);
-=item *
-
-hatch
-
-=item *
-
-fountain (similar to gradients in paint software)
+The parameters depend on the type of fill being created. See below
+for details.
=back
-=head1 Common options
-
-=over
-
-=item combine
-
-The way in which the fill data is combined with the underlying image,
-possible values include:
+The currently available fills are:
=over
-=item none
-
-The fill pixel replaces the target pixel.
-
-=item normal
-
-The fill pixels alpha value is used to combine it with the target pixel.
-
-=item multiply
-
-=item mult
-
-Each channel of fill and target is multiplied, and the result is
-combined using the alpha channel of the fill pixel.
-
-=item dissolve
-
-If the alpha of the fill pixel is greater than a random number, the
-fill pixel is alpha combined with the target pixel.
-
-=item add
-
-The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
-
-=item subtract
-
-The channels of the fill are subtracted from the target, clamped to be
->= 0, and alpha combined with the target.
+=item *
-=item diff
+solid
-The channels of the fill are subtracted from the target and the
-absolute value taken this is alpha combined with the target.
+=item *
-=item lighten
+hatch
-The higher value is taken from each channel of the fill and target
-pixels, which is then alpha combined with the target.
+=item *
-=item darken
+fountain (similar to gradients in paint software)
-The higher value is taken from each channel of the fill and target
-pixels, which is then alpha combined with the target.
+=item *
-=item hue
+image - fill with an image, possibly transformed
-The combination of the saturation and value of the target is combined
-with the hue of the fill pixel, and is then alpha combined with the
-target.
+=item *
-=item sat
+opacity - a lower opacity version of some other fill
-The combination of the hue and value of the target is combined
-with the saturation of the fill pixel, and is then alpha combined with the
-target.
+=back
-=item value
+=head1 Common options
-The combination of the hue and value of the target is combined
-with the value of the fill pixel, and is then alpha combined with the
-target.
+=over
-=item color
+=item combine
-The combination of the value of the target is combined with the hue
-and saturation of the fill pixel, and is then alpha combined with the
-target.
+The way in which the fill data is combined with the underlying image.
+See L<Imager::Draw/"Combine Types">.
=back
-=back
-
-In general colors can be specified as Imager::Color or
-Imager::Color::Float objects. The fill object will typically store
+In general colors can be specified as L<Imager::Color> or
+L<Imager::Color::Float> objects. The fill object will typically store
both types and convert from one to the other. If a fill takes 2 color
objects they should have the same type.
=head2 Solid fills
- my $fill = Imager::Fill->new(solid=>$color, $combine =>$combine)
+ my $fill = Imager::Fill->new(solid=>$color, combine =>$combine)
Creates a solid fill, the only required parameter is C<solid> which
should be the color to fill with.
+A translucent red fill:
+
+ my $red = Imager::Fill->new(solid => "FF000080", combine => "normal");
+
=head2 Hatched fills
my $fill = Imager::Fill->new(hatch=>$type, fg=>$fgcolor, bg=>$bgcolor,
=over
-=item hatch
+=item *
-The type of hatch to perform, this can either be the numeric index of
-the hatch (not recommended), the symbolic name of the hatch, or an
-array of 8 integers which specify the pattern of the hatch.
+C<hatch> - The type of hatch to perform, this can either be the
+numeric index of the hatch (not recommended), the symbolic name of the
+hatch, or an array of 8 integers which specify the pattern of the
+hatch.
Hatches are represented as cells 8x8 arrays of bits, which limits their
complexity.
=over
-=item check1x1, check2x2, check4x4
+=item *
-checkerboards at varios sizes
+C<check1x1>, C<check2x2>, C<check4x4> - checkerboards at various sizes
-=item vline1, vline2, vline4
+=item *
-1, 2, or 4 vertical lines per cell
+C<vline1>, C<vline2>, C<vline4> - 1, 2, or 4 vertical lines per cell
-=item hline1, hline2, hline4
+=item *
-1, 2, or 4 horizontal lines per cell
+C<hline1>, C<hline2>, C<hline4> - 1, 2, or 4 horizontal lines per cell
-=item slash1, slash2
+=item *
-1 or 2 / lines per cell.
+C<slash1>, C<slash2> - 1 or 2 / lines per cell.
-=item slosh1, slosh2
+=item *
-1 or 2 \ lines per cell
+C<slosh1>, C<slosh2> - 1 or 2 \ lines per cell
-=item grid1, grid2, grid4
+=item *
-1, 2, or 4 vertical and horizontal lines per cell
+C<grid1>, C<grid2>, C<grid4> - 1, 2, or 4 vertical and horizontal
+lines per cell
-=item dots1, dots4, dots16
+=item *
-1, 4 or 16 dots per cell
+C<dots1>, C<dots4>, C<dots16> - 1, 4 or 16 dots per cell
-=item stipple, stipple2
+=item *
-see the samples
+C<stipple>, C<stipple2> - see the samples
-=item weave
+=item *
-I hope this one is obvious.
+C<weave> - I hope this one is obvious.
-=item cross1, cross2
+=item *
-2 densities of crosshatch
+C<cross1>, C<cross2> - 2 densities of crosshatch
-=item vlozenge, hlozenge
+=item *
-something like lozenge tiles
+C<vlozenge>, C<hlozenge> - something like lozenge tiles
-=item scalesdown, scalesup, scalesleft, scalesright
+=item *
-Vaguely like fish scales in each direction.
+C<scalesdown>, C<scalesup>, C<scalesleft>, C<scalesright> - Vaguely
+like fish scales in each direction.
-=item tile_L
+=item *
-L-shaped tiles
+C<tile_L> - L-shaped tiles
=back
-=item fg
+=item *
-=item bg
+C<fg>, C<bg> - The C<fg> color is rendered where bits are set in the
+hatch, and the C<bg> where they are clear. If you use a transparent
+C<fg> or C<bg>, and set combine, you can overlay the hatch onto an
+existing image.
-The fg color is rendered where bits are set in the hatch, and the bg
-where they are clear. If you use a transparent fg or bg, and set
-combine, you can overlay the hatch onto an existing image.
+C<fg> defaults to black, C<bg> to white.
-fg defaults to black, bg to white.
+=item *
-=item dx
+C<dx>, C<dy> - An offset into the hatch cell. Both default to zero.
-=item dy
+=back
-An offset into the hatch cell. Both default to zero.
+A blue and white 4-pixel check pattern:
-=back
+ my $fill = Imager::Fill->new(hatch => "check2x2", fg => "blue");
You can call Imager::Fill->hatches for a list of hatch names.
my $fill = Imager::Fill->new(fountain=>$ftype,
xa=>$xa, ya=>$ya, xb=>$xb, yb=>$yb,
- segment=>$segments, repeat=>$repeat, combine=>$combine,
+ segments=>$segments, repeat=>$repeat, combine=>$combine,
super_sample=>$super_sample, ssample_param=>$ssample_param);
This fills the given region with a fountain fill. This is exactly the
you are drawing, and the fountain parameter supplies the fill type,
and is required.
+A radial fill from white to transparent centered on (50, 50) with a 50
+pixel radius:
+
+ use Imager::Fountain;
+ my $segs = Imager::Fountain->simple(colors => [ "FFFFFF", "FFFFFF00" ],
+ positions => [ 0, 1 ]);
+ my $fill = Imager::Fill->new(fountain => "radial", segments => $segs,
+ xa => 50, ya => 50, xb => 0, yb => 50,
+ combine => "normal");
+
+
=head2 Image Fills
my $fill = Imager::Fill->new(image=>$src, xoff=>$xoff, yoff=>$yoff,
- matrix=>$matrix, $combine);
+ matrix=>$matrix, combine => $combine);
Fills the given image with a tiled version of the given image. The
-first non-zero value of xoff or yoff will provide an offset along the
-given axis between rows or columns of tiles respectively.
+first non-zero value of C<xoff> or C<yoff> will provide an offset
+along the given axis between rows or columns of tiles respectively.
The matrix parameter performs a co-ordinate transformation from the
co-ordinates in the target image to the fill image co-ordinates.
The matrix parameter will significantly slow down the fill.
+ # some image to act as a texture
+ my $txim = Imager->new(...);
+
+ # simple tiling
+ my $fill = Imager::Fill->new(image => $txim);
+
+ # tile with a vertical offset
+ my $fill = Imager::Fill->new(image => $txim, yoff => 10);
+
+ # tile with a horizontal offset
+ my $fill = Imager::Fill->new(image => $txim, xoff => 10);
+
+ # rotated
+ use Imager::Matrix2d;
+ my $fill = Imager::Fill->new(image => $txim,
+ matrix => Imager::Matrix2d->rotate(degrees => 20));
+
+=head2 Opacity modification fill
+
+ my $fill = Imager::Fill->new(type => "opacity",
+ other => $fill, opacity => 0.25);
+
+This can be used to make a fill that is a more translucent or opaque
+version of an existing fill. This is intended for use where you
+receive a fill object as a parameter and need to change the opacity.
+
+Parameters:
+
+=over
+
+=item *
+
+type => "opacity" - Required
+
+=item *
+
+other - the fill to produce a modified version of. This must be an
+Imager::Fill object. Required.
+
+=item *
+
+opacity - multiplier for the source fill opacity. Default: 0.5.
+
+=back
+
+The source fills combine mode is used.
+
+ my $hatch = Imager::Fill->new(hatch => "check4x4", combine => "normal");
+ my $fill = Imager::Fill->new(type => "opacity", other => $hatch);
+
=head1 OTHER METHODS
=over
=over
-=item checkerboard
+=item *
-combines 2 other fills in a checkerboard
+C<checkerboard> - combines 2 other fills in a checkerboard
-=item combine
+=item *
-combines 2 other fills using the levels of an image
+C<combine> - combines 2 other fills using the levels of an image
-=item regmach
+=item *
-uses the transform2() register machine to create fills
+C<regmach> - uses the transform2() register machine to create fills
=back
projects / imager.git / blobdiff