1 /*
2 * Copyright (c) 1995, 2013, 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.util.Hashtable;
29
30
31 /**
32 * The interface for objects expressing interest in image data through
33 * the ImageProducer interfaces. When a consumer is added to an image
34 * producer, the producer delivers all of the data about the image
35 * using the method calls defined in this interface.
36 *
37 * @see ImageProducer
38 *
39 * @author Jim Graham
40 */
41 public interface ImageConsumer {
42 /**
43 * The dimensions of the source image are reported using the
44 * setDimensions method call.
45 * @param width the width of the source image
46 * @param height the height of the source image
47 */
48 void setDimensions(int width, int height);
49
50 /**
51 * Sets the extensible list of properties associated with this image.
52 * @param props the list of properties to be associated with this
53 * image
54 */
55 void setProperties(Hashtable<?,?> props);
56
57 /**
58 * Sets the ColorModel object used for the majority of
59 * the pixels reported using the setPixels method
60 * calls. Note that each set of pixels delivered using setPixels
61 * contains its own ColorModel object, so no assumption should
62 * be made that this model will be the only one used in delivering
63 * pixel values. A notable case where multiple ColorModel objects
64 * may be seen is a filtered image when for each set of pixels
65 * that it filters, the filter
66 * determines whether the
67 * pixels can be sent on untouched, using the original ColorModel,
68 * or whether the pixels should be modified (filtered) and passed
69 * on using a ColorModel more convenient for the filtering process.
70 * @param model the specified <code>ColorModel</code>
71 * @see ColorModel
72 */
73 void setColorModel(ColorModel model);
74
75 /**
76 * Sets the hints that the ImageConsumer uses to process the
77 * pixels delivered by the ImageProducer.
78 * The ImageProducer can deliver the pixels in any order, but
79 * the ImageConsumer may be able to scale or convert the pixels
80 * to the destination ColorModel more efficiently or with higher
81 * quality if it knows some information about how the pixels will
82 * be delivered up front. The setHints method should be called
83 * before any calls to any of the setPixels methods with a bit mask
84 * of hints about the manner in which the pixels will be delivered.
85 * If the ImageProducer does not follow the guidelines for the
86 * indicated hint, the results are undefined.
87 * @param hintflags a set of hints that the ImageConsumer uses to
88 * process the pixels
89 */
90 void setHints(int hintflags);
91
92 /**
93 * The pixels will be delivered in a random order. This tells the
94 * ImageConsumer not to use any optimizations that depend on the
95 * order of pixel delivery, which should be the default assumption
96 * in the absence of any call to the setHints method.
97 * @see #setHints
98 */
99 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,
161 ColorModel model, 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,
187 ColorModel model, 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 }