Implement custom filter callback in Java

git-svn-id: svn+ssh://svn.code.sf.net/p/libjpeg-turbo/code/trunk@707 632fc199-4ca6-4c93-a231-07263d6284db

java/org/libjpegturbo/turbojpeg/TJCustomFilter.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright (C)2011 D. R. Commander.  All Rights Reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * - Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * - Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ * - Neither the name of the libjpeg-turbo Project nor the names of its
+ *   contributors may be used to endorse or promote products derived from this
+ *   software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS",
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package org.libjpegturbo.turbojpeg;
+
+import java.awt.*;
+import java.nio.*;
+
+/**
+ * Custom filter callback interface
+ */
+public interface TJCustomFilter {
+
+  /**
+   * A callback function that can be used to modify the DCT coefficients after
+   * they are losslessly transformed but before they are transcoded to a new
+   * JPEG file.  This allows for custom filters or other transformations to be
+   * applied in the frequency domain.
+   *
+   * @param coeffBuffer a buffer containing transformed DCT coefficients.
+   * (NOTE: this buffer is not guaranteed to be valid once the callback
+   * returns, so applications wishing to hand off the DCT coefficients to
+   * another function or library should make a copy of them within the body of
+   * the callback.)
+   *
+   * @param bufferRegion rectangle containing the width and height of
+   * <code>coeffBuffer</code> as well as its offset relative to the component
+   * plane.  TurboJPEG implementations may choose to split each component plane
+   * into multiple DCT coefficient buffers and call the callback function once
+   * for each buffer.
+   *
+   * @param planeRegion rectangle containing the width and height of the
+   * component plane to which <code>coeffBuffer</code> belongs
+   *
+   * @param componentID ID number of the component plane to which
+   * <code>coeffBuffer</code>belongs (Y, Cb, and Cr have, respectively, ID's of
+   * 0, 1, and 2 in typical JPEG images.)
+   *
+   * @param transformID ID number of the transformed image to which
+   * <code>coeffBuffer</code> belongs.  This is the same as the index of the
+   * transform in the transforms array that was passed to {@link
+   * TJTransformer#transform TJTransformer.transform()}.
+   *
+   * @param transform a {@link TJTransform} instance that specifies the
+   * parameters and/or cropping region for this transform
+   */
+  public void customFilter(ShortBuffer coeffBuffer, Rectangle bufferRegion,
+    Rectangle planeRegion, int componentID, int transformID,
+    TJTransform transform)
+    throws Exception;
+}

java/org/libjpegturbo/turbojpeg/TJTransform.java

@@ -37,7 +37,6 @@ public class TJTransform extends Rectangle {
 
   private static final long serialVersionUID = -127367705761430371L;
 
-
   /**
    * The number of lossless transform operations
    */
@@ -104,21 +103,29 @@ public class TJTransform extends Rectangle {
    * partial MCU blocks that cannot be transformed will be left in place, which
    * will create odd-looking strips on the right or bottom edge of the image.
    */
-  final public static int OPT_PERFECT = 1;
+  final public static int OPT_PERFECT  = 1;
   /**
    * This option will discard any partial MCU blocks that cannot be
    * transformed.
    */
-  final public static int OPT_TRIM    = 2;
+  final public static int OPT_TRIM     = 2;
   /**
    * This option will enable lossless cropping.
    */
-  final public static int OPT_CROP    = 4;
+  final public static int OPT_CROP     = 4;
   /**
    * This option will discard the color data in the input image and produce
    * a grayscale output image.
    */
-  final public static int OPT_GRAY    = 8;
+  final public static int OPT_GRAY     = 8;
+  /**
+   * This option will prevent {@link TJTransformer#transform
+   * TJTransformer.transform()} from outputting a JPEG image for this
+   * particular transform.  This can be used in conjunction with a custom
+   * filter to capture the transformed DCT coefficients without transcoding
+   * them.
+   */
+  final public static int OPT_NOOUTPUT = 16;
 
   
   /**
@@ -146,28 +153,36 @@ public class TJTransform extends Rectangle {
    *
    * @param options the bitwise OR of one or more of the transform options
    * (<code>OPT_*</code>)
+   *
+   * @param cf an instance of an object that implements the {@link
+   * TJCustomFilter} interface, or null if no custom filter is needed
    */
-  public TJTransform(int x, int y, int w, int h, int op, int options)
-    throws Exception {
+  public TJTransform(int x, int y, int w, int h, int op, int options,
+    TJCustomFilter cf) throws Exception {
     super(x, y, w, h);
-    this.op = op;  this.options = options;
+    this.op = op;  this.options = options;  this.cf = cf;
   }
 
   /**
    * Create a new lossless transform instance with the given parameters.
    *
    * @param r a <code>Rectangle</code> instance which specifies the cropping
-   * region.  See {@link #TJTransform(int, int, int, int, int, int)} for more
+   * region.  See {@link
+   * #TJTransform(int, int, int, int, int, int, TJCustomFilter)} for more
    * detail.
    *
    * @param op one of the transform operations (<code>OP_*</code>)
    *
    * @param options the bitwise OR of one or more of the transform options
    * (<code>OPT_*</code>)
+   *
+   * @param cf an instance of an object that implements the {@link
+   * TJCustomFilter} interface, or null if no custom filter is needed
    */
-  public TJTransform(Rectangle r, int op, int options) throws Exception {
+  public TJTransform(Rectangle r, int op, int options,
+    TJCustomFilter cf) throws Exception {
     super(r);
-    this.op = op;  this.options = options;
+    this.op = op;  this.options = options;  this.cf = cf;
   }
 
   /**
@@ -179,4 +194,9 @@ public class TJTransform extends Rectangle {
    * Transform options (bitwise OR of one or more of <code>OPT_*</code>)
    */
   public int options = 0;
+
+  /**
+   * Custom filter instance
+   */
+  public TJCustomFilter cf = null;
 }