< prev index next >

src/java.desktop/share/classes/javax/imageio/event/IIOReadUpdateListener.java

Print this page




  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
  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
 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 }


  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} 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 minY},
  51      * {@code width}, and {@code height} parameters.  If the
  52      * pass is interlaced, that is, it only updates selected rows or
  53      * columns, the {@code periodX} and {@code periodY}
  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}.
  57      *
  58      * @param source the {@code ImageReader} object calling this
  59      * method.
  60      * @param theImage the {@code BufferedImage} 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}s indicating 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} 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 minY}, {@code width}, and
 106      * {@code height}); X and Y subsampling factors
 107      * ({@code periodX} and {@code periodY}); and a set of
 108      * updated bands ({@code bands}).  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} object calling this method.
 131      * @param theImage the {@code BufferedImage} 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}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} object calling this
 160      * method.
 161      * @param theImage the {@code BufferedImage} 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} object calling this
 175      * method.
 176      * @param theThumbnail the {@code BufferedImage} 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}s indicating 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} object calling this method.
 210      * @param theThumbnail the {@code BufferedImage} 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}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} object calling this
 242      * method.
 243      * @param theThumbnail the {@code BufferedImage} thumbnail
 244      * being updated.
 245      *
 246      * @see #passComplete
 247      */
 248     void thumbnailPassComplete(ImageReader source, BufferedImage theThumbnail);
 249 }
< prev index next >