View Javadoc
1   /*
2    * Copyright (c) 2000, 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 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 number 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 number 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 }