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 26package javax.imageio.event; 27 28import java.awt.image.BufferedImage; 29import java.util.EventListener; 30import 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 */ 41public 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} 250