IIOReadUpdateListener


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