- supply C<imager> parameter to filters so we can register filters
authorTony Cook <tony@develop=help.com>
Mon, 30 Jan 2006 01:13:04 +0000 (01:13 +0000)
committerTony Cook <tony@develop=help.com>
Mon, 30 Jan 2006 01:13:04 +0000 (01:13 +0000)
  implemented in perl.
- document register_filter() and add test for it
- add example to SYNOPSIS of samples/inline_replace_color.pl

Changes
Imager.pm
lib/Imager/Filters.pod
lib/Imager/Inline.pod
samples/inline_replace_color.pl
t/t61filters.t

diff --git a/Changes b/Changes
index 8d27eb3..0d30f4c 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1315,6 +1315,10 @@ Revision history for Perl extension Imager.
 - make skip when Inline::C not available less verbose
 - convert t/t07iolayer.t to Test::More
 - handle the possibility of strerror() returning NULL.
+- supply C<imager> parameter to filters so we can register filters
+  implemented in perl.
+- document register_filter() and add test for it
+- add example to SYNOPSIS of samples/inline_replace_color.pl
 
 =================================================================
 
index 0102445..e3aa364 100644 (file)
--- a/Imager.pm
+++ b/Imager.pm
@@ -1680,9 +1680,14 @@ sub filter {
     }
   }
   if (defined($filters{$input{'type'}}{defaults})) {
-    %hsh=('image',$self->{IMG},%{$filters{$input{'type'}}{defaults}},%input);
+    %hsh=( image => $self->{IMG},
+           imager => $self,
+           %{$filters{$input{'type'}}{defaults}},
+           %input );
   } else {
-    %hsh=('image',$self->{IMG},%input);
+    %hsh=( image => $self->{IMG},
+           imager => $self,
+           %input );
   }
 
   my @cs=@{$filters{$input{'type'}}{callseq}};
index f17b2ed..ec4922d 100644 (file)
@@ -481,11 +481,62 @@ A demonstration of most of the filters can be found at:
 
   http://www.develop-help.com/imager/filters.html
 
-(This is a slow link.)
+=head2 External Filters
 
+As of Imager 0.48 you can create perl or XS based filters and hook
+them into Imager's filter() method:
+
+=over
+
+=item register_filter
+
+Registers a filter so it is visible via Imager's filter() method.
+
+  Imager->register_filter(type => 'your_filter',
+                          defaults => { parm1 => 'default1' },
+                          callseq => [ qw/image parm1/ ],
+                          callsub => \&your_filter);
+  $img->filter(type=>'your_filter', parm1 => 'something');
+
+The following parameters are needed:
+
+=over
+
+=item *
+
+type - the type value that will be supplied to filter() to use your
+filter.
+
+=item *
+
+defaults - a hash of defaults for the filter's parameters
+
+=item *
+
+callseq - a reference to an array of required parameter names.
+
+=item *
+
+callsub - a code reference called to execute your filter.  The
+parameters passed to filter() are supplied as a list of parameter
+name, value ... which can be assigned to a hash.
+
+The special parameters C<image> and C<imager> are supplied as the low
+level image object from $self and $self itself respectively.
+
+The function you supply must modify the image in place.
+
+=back
+
+See Imager::Filter::Mandelbrot for an example.
+
+=back
 
 =head2 Plugins
 
+The plugin interface is deprecated.  Please use the Imager API, see
+L</Imager::API> for details.
+
 It is possible to add filters to the module without recompiling the
 module itself.  This is done by using DSOs (Dynamic shared object)
 avaliable on most systems.  This way you can maintain our own filters
index a4d329a..8afc51e 100644 (file)
@@ -68,6 +68,7 @@ $Revision$
 
 =head1 SEE ALSO
 
-Imager, Imager::ExtUtils, Imager::API, Imager::APIRef
+Imager, Imager::ExtUtils, Imager::API, Imager::APIRef,
+samples/inline_replace_color.pl
 
 =cut
index 655a4e7..b973acf 100644 (file)
@@ -4,11 +4,13 @@ use Imager;
 
 =head1 NAME
 
-inline_replace_color - replace one color with another in an image, using Inline
+inline_replace_color.pl - replace one color with another in an image, using Inline
 
 =head1 SYNOPSIS
 
-  perl inline_replace_color fromcolor tocolor inimage outimage
+  perl inline_replace_color.pl fromcolor tocolor inimage outimage
+
+  perl inline_replace_color.pl white 808080 foo.jpg bar.png
 
 =head1 DESCRIPTION
 
index 52678c9..ae1ce1c 100644 (file)
@@ -2,7 +2,7 @@
 use strict;
 use Imager qw(:handy);
 use lib 't';
-use Test::More tests => 64;
+use Test::More tests => 66;
 Imager::init_log("testout/t61filters.log", 1);
 # meant for testing the filters themselves
 my $imbase = Imager->new;
@@ -205,6 +205,32 @@ is($name, "test gradient", "check the name matches");
   ok($radial, "radial fountain sample");
 }
 
+{
+  # try a simple custom filter that uses the Perl image interface
+  sub perl_filt {
+    my %args = @_;
+
+    my $im = $args{imager};
+
+    my $channels = $args{channels};
+    unless (@$channels) {
+      $channels = [ reverse(0 .. $im->getchannels-1) ];
+    }
+    my @chans = @$channels;
+    push @chans, 0 while @chans < 4;
+
+    for my $y (0 .. $im->getheight-1) {
+      my $row = $im->getsamples(y => $y, channels => \@chans);
+      $im->setscanline(y => $y, pixels => $row);
+    }
+  }
+  Imager->register_filter(type => 'perl_test',
+                          callsub => \&perl_filt,
+                          defaults => { channels => [] },
+                          callseq => [ qw/imager channels/ ]);
+  test($imbase, { type => 'perl_test' }, 'testout/t61perl.ppm');
+}
+
 sub test {
   my ($in, $params, $out) = @_;