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
26package java.awt.image;
27
28import java.awt.geom.Rectangle2D;
29import java.awt.geom.Point2D;
30import java.awt.RenderingHints;
31
32/**
33 * This interface describes single-input/single-output
34 * operations performed on {@code BufferedImage} objects.
35 * It is implemented by {@code AffineTransformOp},
36 * {@code ConvolveOp}, {@code ColorConvertOp}, {@code RescaleOp},
37 * and {@code LookupOp}.  These objects can be passed into
38 * a {@code BufferedImageFilter} to operate on a
39 * {@code BufferedImage} 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 */
61public interface BufferedImageOp {
62    /**
63     * Performs a single-input/single-output operation on a
64     * {@code BufferedImage}.
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} with an appropriate {@code ColorModel}
69     * is created.
70     * <p>
71     * An {@code IllegalArgumentException} 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} to be filtered
76     * @param dest The {@code BufferedImage} in which to store the results$
77     *
78     * @return The filtered {@code BufferedImage}.
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} 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} to be filtered
93     *
94     * @return The {@code Rectangle2D} 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} 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} to be filtered
107     * @param destCM {@code ColorModel} of the destination.  If null,
108     * the {@code ColorModel} 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} is specified, it
118     * is used to hold the return value.
119     * @param srcPt the {@code Point2D} that represents the point in
120     * the source image
121     * @param dstPt The {@code Point2D} in which to store the result
122     *
123     * @return The {@code Point2D} 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} object for this
132     * {@code BufferedImageOp}.  Returns
133     * null if no hints have been set.
134     */
135    public RenderingHints getRenderingHints();
136}
137