001 /*
002 * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.image;
027
028 import java.util.Hashtable;
029
030 /**
031 * The interface for objects expressing interest in image data through
032 * the ImageProducer interfaces. When a consumer is added to an image
033 * producer, the producer delivers all of the data about the image
034 * using the method calls defined in this interface.
035 *
036 * @see ImageProducer
037 *
038 * @version 1.31 05/05/07
039 * @author Jim Graham
040 */
041 public interface ImageConsumer {
042 /**
043 * The dimensions of the source image are reported using the
044 * setDimensions method call.
045 * @param width the width of the source image
046 * @param height the height of the source image
047 */
048 void setDimensions(int width, int height);
049
050 /**
051 * Sets the extensible list of properties associated with this image.
052 * @param props the list of properties to be associated with this
053 * image
054 */
055 void setProperties(Hashtable<?, ?> props);
056
057 /**
058 * Sets the ColorModel object used for the majority of
059 * the pixels reported using the setPixels method
060 * calls. Note that each set of pixels delivered using setPixels
061 * contains its own ColorModel object, so no assumption should
062 * be made that this model will be the only one used in delivering
063 * pixel values. A notable case where multiple ColorModel objects
064 * may be seen is a filtered image when for each set of pixels
065 * that it filters, the filter
066 * determines whether the
067 * pixels can be sent on untouched, using the original ColorModel,
068 * or whether the pixels should be modified (filtered) and passed
069 * on using a ColorModel more convenient for the filtering process.
070 * @param model the specified <code>ColorModel</code>
071 * @see ColorModel
072 */
073 void setColorModel(ColorModel model);
074
075 /**
076 * Sets the hints that the ImageConsumer uses to process the
077 * pixels delivered by the ImageProducer.
078 * The ImageProducer can deliver the pixels in any order, but
079 * the ImageConsumer may be able to scale or convert the pixels
080 * to the destination ColorModel more efficiently or with higher
081 * quality if it knows some information about how the pixels will
082 * be delivered up front. The setHints method should be called
083 * before any calls to any of the setPixels methods with a bit mask
084 * of hints about the manner in which the pixels will be delivered.
085 * If the ImageProducer does not follow the guidelines for the
086 * indicated hint, the results are undefined.
087 * @param hintflags a set of hints that the ImageConsumer uses to
088 * process the pixels
089 */
090 void setHints(int hintflags);
091
092 /**
093 * The pixels will be delivered in a random order. This tells the
094 * ImageConsumer not to use any optimizations that depend on the
095 * order of pixel delivery, which should be the default assumption
096 * in the absence of any call to the setHints method.
097 * @see #setHints
098 */
099 int RANDOMPIXELORDER = 1;
100
101 /**
102 * The pixels will be delivered in top-down, left-to-right order.
103 * @see #setHints
104 */
105 int TOPDOWNLEFTRIGHT = 2;
106
107 /**
108 * The pixels will be delivered in (multiples of) complete scanlines
109 * at a time.
110 * @see #setHints
111 */
112 int COMPLETESCANLINES = 4;
113
114 /**
115 * The pixels will be delivered in a single pass. Each pixel will
116 * appear in only one call to any of the setPixels methods. An
117 * example of an image format which does not meet this criterion
118 * is a progressive JPEG image which defines pixels in multiple
119 * passes, each more refined than the previous.
120 * @see #setHints
121 */
122 int SINGLEPASS = 8;
123
124 /**
125 * The image contain a single static image. The pixels will be defined
126 * in calls to the setPixels methods and then the imageComplete method
127 * will be called with the STATICIMAGEDONE flag after which no more
128 * image data will be delivered. An example of an image type which
129 * would not meet these criteria would be the output of a video feed,
130 * or the representation of a 3D rendering being manipulated
131 * by the user. The end of each frame in those types of images will
132 * be indicated by calling imageComplete with the SINGLEFRAMEDONE flag.
133 * @see #setHints
134 * @see #imageComplete
135 */
136 int SINGLEFRAME = 16;
137
138 /**
139 * Delivers the pixels of the image with one or more calls
140 * to this method. Each call specifies the location and
141 * size of the rectangle of source pixels that are contained in
142 * the array of pixels. The specified ColorModel object should
143 * be used to convert the pixels into their corresponding color
144 * and alpha components. Pixel (m,n) is stored in the pixels array
145 * at index (n * scansize + m + off). The pixels delivered using
146 * this method are all stored as bytes.
147 * @param x the X coordinate of the upper-left corner of the
148 * area of pixels to be set
149 * @param y the Y coordinate of the upper-left corner of the
150 * area of pixels to be set
151 * @param w the width of the area of pixels
152 * @param h the height of the area of pixels
153 * @param model the specified <code>ColorModel</code>
154 * @param pixels the array of pixels
155 * @param off the offset into the <code>pixels</code> array
156 * @param scansize the distance from one row of pixels to the next in
157 * the <code>pixels</code> array
158 * @see ColorModel
159 */
160 void setPixels(int x, int y, int w, int h, ColorModel model,
161 byte pixels[], int off, int scansize);
162
163 /**
164 * The pixels of the image are delivered using one or more calls
165 * to the setPixels method. Each call specifies the location and
166 * size of the rectangle of source pixels that are contained in
167 * the array of pixels. The specified ColorModel object should
168 * be used to convert the pixels into their corresponding color
169 * and alpha components. Pixel (m,n) is stored in the pixels array
170 * at index (n * scansize + m + off). The pixels delivered using
171 * this method are all stored as ints.
172 * this method are all stored as ints.
173 * @param x the X coordinate of the upper-left corner of the
174 * area of pixels to be set
175 * @param y the Y coordinate of the upper-left corner of the
176 * area of pixels to be set
177 * @param w the width of the area of pixels
178 * @param h the height of the area of pixels
179 * @param model the specified <code>ColorModel</code>
180 * @param pixels the array of pixels
181 * @param off the offset into the <code>pixels</code> array
182 * @param scansize the distance from one row of pixels to the next in
183 * the <code>pixels</code> array
184 * @see ColorModel
185 */
186 void setPixels(int x, int y, int w, int h, ColorModel model,
187 int pixels[], int off, int scansize);
188
189 /**
190 * The imageComplete method is called when the ImageProducer is
191 * finished delivering all of the pixels that the source image
192 * contains, or when a single frame of a multi-frame animation has
193 * been completed, or when an error in loading or producing the
194 * image has occured. The ImageConsumer should remove itself from the
195 * list of consumers registered with the ImageProducer at this time,
196 * unless it is interested in successive frames.
197 * @param status the status of image loading
198 * @see ImageProducer#removeConsumer
199 */
200 void imageComplete(int status);
201
202 /**
203 * An error was encountered while producing the image.
204 * @see #imageComplete
205 */
206 int IMAGEERROR = 1;
207
208 /**
209 * One frame of the image is complete but there are more frames
210 * to be delivered.
211 * @see #imageComplete
212 */
213 int SINGLEFRAMEDONE = 2;
214
215 /**
216 * The image is complete and there are no more pixels or frames
217 * to be delivered.
218 * @see #imageComplete
219 */
220 int STATICIMAGEDONE = 3;
221
222 /**
223 * The image creation process was deliberately aborted.
224 * @see #imageComplete
225 */
226 int IMAGEABORTED = 4;
227 }
|