1 /*
   2  * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt.image;
  27 
  28 import java.awt.geom.Rectangle2D;
  29 import java.awt.geom.Point2D;
  30 import java.awt.RenderingHints;
  31 
  32 /**
  33  * This interface describes single-input/single-output
  34  * operations performed on <CODE>BufferedImage</CODE> objects.
  35  * It is implemented by <CODE>AffineTransformOp</CODE>,
  36  * <CODE>ConvolveOp</CODE>, <CODE>ColorConvertOp</CODE>, <CODE>RescaleOp</CODE>,
  37  * and <CODE>LookupOp</CODE>.  These objects can be passed into
  38  * a <CODE>BufferedImageFilter</CODE> to operate on a
  39  * <CODE>BufferedImage</CODE> in the
  40  * ImageProducer-ImageFilter-ImageConsumer paradigm.
  41  * <p>
  42  * Classes that implement this
  43  * interface must specify whether or not they allow in-place filtering--
  44  * filter operations where the source object is equal to the destination
  45  * object.
  46  * <p>
  47  * This interface cannot be used to describe more sophisticated operations
  48  * such as those that take multiple sources. Note that this restriction also
  49  * means that the values of the destination pixels prior to the operation are
  50  * not used as input to the filter operation.
  51 
  52  * @see BufferedImage
  53  * @see BufferedImageFilter
  54  * @see AffineTransformOp
  55  * @see BandCombineOp
  56  * @see ColorConvertOp
  57  * @see ConvolveOp
  58  * @see LookupOp
  59  * @see RescaleOp
  60  */
  61 public interface BufferedImageOp {
  62     /**
  63      * Performs a single-input/single-output operation on a
  64      * <CODE>BufferedImage</CODE>.
  65      * If the color models for the two images do not match, a color
  66      * conversion into the destination color model is performed.
  67      * If the destination image is null,
  68      * a <CODE>BufferedImage</CODE> with an appropriate <CODE>ColorModel</CODE>
  69      * is created.
  70      * <p>
  71      * An <CODE>IllegalArgumentException</CODE> may be thrown if the source
  72      * and/or destination image is incompatible with the types of images       $
  73      * allowed by the class implementing this filter.
  74      *
  75      * @param src The <CODE>BufferedImage</CODE> to be filtered
  76      * @param dest The <CODE>BufferedImage</CODE> in which to store the results$
  77      *
  78      * @return The filtered <CODE>BufferedImage</CODE>.
  79      *
  80      * @throws IllegalArgumentException If the source and/or destination
  81      * image is not compatible with the types of images allowed by the class
  82      * implementing this filter.
  83      */
  84     public BufferedImage filter(BufferedImage src, BufferedImage dest);
  85 
  86     /**
  87      * Returns the bounding box of the filtered destination image.
  88      * An <CODE>IllegalArgumentException</CODE> may be thrown if the source
  89      * image is incompatible with the types of images allowed
  90      * by the class implementing this filter.
  91      *
  92      * @param src The <CODE>BufferedImage</CODE> to be filtered
  93      *
  94      * @return The <CODE>Rectangle2D</CODE> representing the destination
  95      * image's bounding box.
  96      */
  97     public Rectangle2D getBounds2D (BufferedImage src);
  98 
  99     /**
 100      * Creates a zeroed destination image with the correct size and number of
 101      * bands.
 102      * An <CODE>IllegalArgumentException</CODE> may be thrown if the source
 103      * image is incompatible with the types of images allowed
 104      * by the class implementing this filter.
 105      *
 106      * @param src The <CODE>BufferedImage</CODE> to be filtered
 107      * @param destCM <CODE>ColorModel</CODE> of the destination.  If null,
 108      * the <CODE>ColorModel</CODE> of the source is used.
 109      *
 110      * @return The zeroed destination image.
 111      */
 112     public BufferedImage createCompatibleDestImage (BufferedImage src,
 113                                                     ColorModel destCM);
 114 
 115     /**
 116      * Returns the location of the corresponding destination point given a
 117      * point in the source image.  If <CODE>dstPt</CODE> is specified, it
 118      * is used to hold the return value.
 119      * @param srcPt the <code>Point2D</code> that represents the point in
 120      * the source image
 121      * @param dstPt The <CODE>Point2D</CODE> in which to store the result
 122      *
 123      * @return The <CODE>Point2D</CODE> in the destination image that
 124      * corresponds to the specified point in the source image.
 125      */
 126     public Point2D getPoint2D (Point2D srcPt, Point2D dstPt);
 127 
 128     /**
 129      * Returns the rendering hints for this operation.
 130      *
 131      * @return The <CODE>RenderingHints</CODE> object for this
 132      * <CODE>BufferedImageOp</CODE>.  Returns
 133      * null if no hints have been set.
 134      */
 135     public RenderingHints getRenderingHints();
 136 }