- 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

diff --git a/Changes b/Changes
index 8d27eb37058d2ec8a132999e02e339d482ece1a7..0d30f4c55c70da4ae4e32c9b455a336ae92aadae 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
 
 =================================================================
 

diff --git a/Imager.pm b/Imager.pm
index 010244527071eb812f23d8d75cdc782aacb2746c..e3aa3643d549c6a7468a0bf2b507cdf5e9071c0a 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}};

diff --git a/lib/Imager/Filters.pod b/lib/Imager/Filters.pod
index f17b2ed5bc7f9a7e49158b96bd2e58c8d31e26ee..ec4922d712e7e58954c2b222cace2cf621b03eb5 100644 (file)
--- a/lib/Imager/Filters.pod
+++ b/lib/Imager/Filters.pod
@@ -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

diff --git a/lib/Imager/Inline.pod b/lib/Imager/Inline.pod
index a4d329a43577815207edfc27f92e58b6255e5636..8afc51e5e0ec496fa6f1e442ce419922c27ba82d 100644 (file)
--- a/lib/Imager/Inline.pod
+++ b/lib/Imager/Inline.pod
@@ -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

diff --git a/samples/inline_replace_color.pl b/samples/inline_replace_color.pl
index 655a4e751a0a78db7104421f28c5e71149df08f8..b973acfe0a9138aadb3845811e0b8a31276a3b38 100644 (file)
--- a/samples/inline_replace_color.pl
+++ b/samples/inline_replace_color.pl
@@ -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
 

diff --git a/t/t61filters.t b/t/t61filters.t
index 52678c91b304ed4a707f94d94fc5e95d76cba12f..ae1ce1cc89edbcbdbc7e6c696b2f17a4c0893034 100644 (file)
--- a/t/t61filters.t
+++ b/t/t61filters.t
@@ -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) = @_;