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