1 /*
2 * Copyright 2000 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.imageio.event;
27
28 import java.awt.image.BufferedImage;
29 import java.util.EventListener;
30 import javax.imageio.ImageReader;
31
32 /**
33 * An interface used by <code>ImageReader</code> implementations to
34 * notify callers of their image and thumbnail reading methods of
35 * pixel updates.
36 *
37 * @see javax.imageio.ImageReader#addIIOReadUpdateListener
38 * @see javax.imageio.ImageReader#removeIIOReadUpdateListener
39 *
40 */
41 public interface IIOReadUpdateListener extends EventListener {
42
43 /**
44 * Reports that the current read operation is about to begin a
45 * progressive pass. Readers of formats that support progressive
46 * encoding should use this to notify clients when each pass is
47 * completed when reading a progressively encoded image.
48 *
49 * <p> An estimate of the area that will be updated by the pass is
50 * indicated by the <code>minX</code>, <code>minY</code>,
51 * <code>width</code>, and <code>height</code> parameters. If the
52 * pass is interlaced, that is, it only updates selected rows or
53 * columns, the <code>periodX</code> and <code>periodY</code>
54 * parameters will indicate the degree of subsampling. The set of
55 * bands that may be affected is indicated by the value of
56 * <code>bands</code>.
57 *
58 * @param source the <code>ImageReader</code> object calling this
59 * method.
60 * @param theImage the <code>BufferedImage</code> being updated.
61 * @param pass the numer of the pass that is about to begin,
62 * starting with 0.
63 * @param minPass the index of the first pass that will be decoded.
64 * @param maxPass the index of the last pass that will be decoded.
65 * @param minX the X coordinate of the leftmost updated column
66 * of pixels.
67 * @param minY the Y coordinate of the uppermost updated row
68 * of pixels.
69 * @param periodX the horizontal spacing between updated pixels;
70 * a value of 1 means no gaps.
71 * @param periodY the vertical spacing between updated pixels;
72 * a value of 1 means no gaps.
73 * @param bands an array of <code>int</code>s indicating the the
74 * set bands that may be updated.
75 */
76 void passStarted(ImageReader source,
77 BufferedImage theImage,
78 int pass,
79 int minPass, int maxPass,
80 int minX, int minY,
81 int periodX, int periodY,
82 int[] bands);
83
84 /**
85 * Reports that a given region of the image has been updated.
86 * The application might choose to redisplay the specified area,
87 * for example, in order to provide a progressive display effect,
88 * or perform other incremental processing.
89 *
90 * <p> Note that different image format readers may produce
91 * decoded pixels in a variety of different orders. Many readers
92 * will produce pixels in a simple top-to-bottom,
93 * left-to-right-order, but others may use multiple passes of
94 * interlacing, tiling, etc. The sequence of updates may even
95 * differ from call to call depending on network speeds, for
96 * example. A call to this method does not guarantee that all the
97 * specified pixels have actually been updated, only that some
98 * activity has taken place within some subregion of the one
99 * specified.
100 *
101 * <p> The particular <code>ImageReader</code> implementation may
102 * choose how often to provide updates. Each update specifies
103 * that a given region of the image has been updated since the
104 * last update. A region is described by its spatial bounding box
105 * (<code>minX</code>, <code>minY</code>, <code>width</code>, and
106 * <code>height</code>); X and Y subsampling factors
107 * (<code>periodX</code> and <code>periodY</code>); and a set of
108 * updated bands (<code>bands</code>). For example, the update:
109 *
110 * <pre>
111 * minX = 10
112 * minY = 20
113 * width = 3
114 * height = 4
115 * periodX = 2
116 * periodY = 3
117 * bands = { 1, 3 }
118 * </pre>
119 *
120 * would indicate that bands 1 and 3 of the following pixels were
121 * updated:
122 *
123 * <pre>
124 * (10, 20) (12, 20) (14, 20)
125 * (10, 23) (12, 23) (14, 23)
126 * (10, 26) (12, 26) (14, 26)
127 * (10, 29) (12, 29) (14, 29)
128 * </pre>
129 *
130 * @param source the <code>ImageReader</code> object calling this method.
131 * @param theImage the <code>BufferedImage</code> being updated.
132 * @param minX the X coordinate of the leftmost updated column
133 * of pixels.
134 * @param minY the Y coordinate of the uppermost updated row
135 * of pixels.
136 * @param width the number of updated pixels horizontally.
137 * @param height the number of updated pixels vertically.
138 * @param periodX the horizontal spacing between updated pixels;
139 * a value of 1 means no gaps.
140 * @param periodY the vertical spacing between updated pixels;
141 * a value of 1 means no gaps.
142 * @param bands an array of <code>int</code>s indicating which
143 * bands are being updated.
144 */
145 void imageUpdate(ImageReader source,
146 BufferedImage theImage,
147 int minX, int minY,
148 int width, int height,
149 int periodX, int periodY,
150 int[] bands);
151
152 /**
153 * Reports that the current read operation has completed a
154 * progressive pass. Readers of formats that support
155 * progressive encoding should use this to notify clients when
156 * each pass is completed when reading a progressively
157 * encoded image.
158 *
159 * @param source the <code>ImageReader</code> object calling this
160 * method.
161 * @param theImage the <code>BufferedImage</code> being updated.
162 *
163 * @see javax.imageio.ImageReadParam#setSourceProgressivePasses(int, int)
164 */
165 void passComplete(ImageReader source, BufferedImage theImage);
166
167 /**
168 * Reports that the current thumbnail read operation is about to
169 * begin a progressive pass. Readers of formats that support
170 * progressive encoding should use this to notify clients when
171 * each pass is completed when reading a progressively encoded
172 * thumbnail image.
173 *
174 * @param source the <code>ImageReader</code> object calling this
175 * method.
176 * @param theThumbnail the <code>BufferedImage</code> thumbnail
177 * being updated.
178 * @param pass the numer of the pass that is about to begin,
179 * starting with 0.
180 * @param minPass the index of the first pass that will be decoded.
181 * @param maxPass the index of the last pass that will be decoded.
182 * @param minX the X coordinate of the leftmost updated column
183 * of pixels.
184 * @param minY the Y coordinate of the uppermost updated row
185 * of pixels.
186 * @param periodX the horizontal spacing between updated pixels;
187 * a value of 1 means no gaps.
188 * @param periodY the vertical spacing between updated pixels;
189 * a value of 1 means no gaps.
190 * @param bands an array of <code>int</code>s indicating the the
191 * set bands that may be updated.
192 *
193 * @see #passStarted
194 */
195 void thumbnailPassStarted(ImageReader source,
196 BufferedImage theThumbnail,
197 int pass,
198 int minPass, int maxPass,
199 int minX, int minY,
200 int periodX, int periodY,
201 int[] bands);
202
203 /**
204 * Reports that a given region of a thumbnail image has been updated.
205 * The application might choose to redisplay the specified area,
206 * for example, in order to provide a progressive display effect,
207 * or perform other incremental processing.
208 *
209 * @param source the <code>ImageReader</code> object calling this method.
210 * @param theThumbnail the <code>BufferedImage</code> thumbnail
211 * being updated.
212 * @param minX the X coordinate of the leftmost updated column
213 * of pixels.
214 * @param minY the Y coordinate of the uppermost updated row
215 * of pixels.
216 * @param width the number of updated pixels horizontally.
217 * @param height the number of updated pixels vertically.
218 * @param periodX the horizontal spacing between updated pixels;
219 * a value of 1 means no gaps.
220 * @param periodY the vertical spacing between updated pixels;
221 * a value of 1 means no gaps.
222 * @param bands an array of <code>int</code>s indicating which
223 * bands are being updated.
224 *
225 * @see #imageUpdate
226 */
227 void thumbnailUpdate(ImageReader source,
228 BufferedImage theThumbnail,
229 int minX, int minY,
230 int width, int height,
231 int periodX, int periodY,
232 int[] bands);
233
234 /**
235 * Reports that the current thumbnail read operation has completed
236 * a progressive pass. Readers of formats that support
237 * progressive encoding should use this to notify clients when
238 * each pass is completed when reading a progressively encoded
239 * thumbnail image.
240 *
241 * @param source the <code>ImageReader</code> object calling this
242 * method.
243 * @param theThumbnail the <code>BufferedImage</code> thumbnail
244 * being updated.
245 *
246 * @see #passComplete
247 */
248 void thumbnailPassComplete(ImageReader source, BufferedImage theThumbnail);
249 }
Save This Page