001 /* IIOParam.java -- 002 Copyright (C) 2004 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package javax.imageio; 040 041 import java.awt.Point; 042 import java.awt.Rectangle; 043 044 /** 045 * An IIOParam stores parameters used when encoding or decoding image 046 * streams. ImageReadParam and ImageWriteParam extend this abstract 047 * base class. 048 * 049 * IIOParams allow control over how source pixels converted into 050 * destination pixels. This conversion can take place between a 051 * stream and in-memory image data, when an image reader is doing the 052 * conversion, or a writer can be doing the conversion from an 053 * in-memory source to a stream destination. 054 * 055 * An image reader can be restricted to only read from a given region; 056 * likewise a writer can be restricted to only write output to a given 057 * region. 058 * 059 * For image readers and writers, IIOParam supports image pixelation 060 * -- where the input image is approximated by the output image using 061 * larger-sized pixel blocks. For example: FIXME 062 * 063 * IIOParams can control how pixels are combined into larger blocks 064 * using sub-sampling matrices. For example: FIXME 065 * 066 * They can also control which source bands are read and written; this 067 * example reads the RGBA (red, green, blue, transparency) data from a 068 * PNG image and outputs just the red and transparency bands: FIXME 069 * 070 * @author Thomas Fitzsimmons (fitzsim@redhat.com) 071 * @author Michael Koch (konqueror@gmx.de) 072 */ 073 public abstract class IIOParam 074 { 075 /** 076 * The controller called by this IIOParam to retrieve parameters. 077 */ 078 protected IIOParamController controller = null; 079 080 /** 081 * The default controller called by this IIOParam to retrieve 082 * parameters. 083 */ 084 protected IIOParamController defaultController = null; 085 086 /** 087 * The offset in the destination where the upper-left 088 * decoded/encoded pixel should be located. 089 */ 090 protected Point destinationOffset = new Point(0, 0); 091 092 /** 093 * Sets the output colour type when writing or the destination image 094 * type when reading. 095 */ 096 protected ImageTypeSpecifier destinationType = null; 097 098 /** 099 * An array indicating which source bands will be used or null. 100 */ 101 protected int[] sourceBands = null; 102 103 /** 104 * The source pixel region or null. 105 */ 106 protected Rectangle sourceRegion = null; 107 108 /** 109 * Sample every sourceXSubsampling'th pixel in the source image when 110 * pixelating the destination image in the horizontal direction. 111 */ 112 protected int sourceXSubsampling = 1; 113 114 /** 115 * Sample every sourceYSubsampling'th pixel in the source image when 116 * pixelating the destination image in the vertical direction. 117 */ 118 protected int sourceYSubsampling = 1; 119 120 /** 121 * Start sampling at this horizontal offset within the source region 122 * when pixelating the destination image in the horizontal 123 * direction. 124 */ 125 protected int subsamplingXOffset = 0; 126 127 /** 128 * Start sampling at this vertical offset within the source region 129 * when pixelating the destination image in the vertical direction. 130 */ 131 protected int subsamplingYOffset = 0; 132 133 /** 134 * Indicates whether or not the controller has been explicitly set 135 * to null. 136 */ 137 private boolean no_controller = false; 138 139 /** 140 * Constructs an IIOParam object. 141 */ 142 protected IIOParam() 143 { 144 } 145 146 /** 147 * Activates the parameter controller by calling its activate method 148 * and passing it this IIOParam. A true return value indicates that 149 * this IIOParam's values are ready for the next read or write 150 * operation. A return value of false means that this IIOParam's 151 * values have not been affected because the controller operations 152 * were cancelled. 153 * 154 * @return true if parameters were successfully set, false if 155 * parameters were not changed 156 */ 157 public boolean activateController() 158 { 159 if (controller == null) 160 { 161 if (defaultController == null || no_controller) 162 return false; 163 else 164 return defaultController.activate (this); 165 } 166 else 167 return controller.activate(this); 168 } 169 170 /** 171 * Retrieve the currently set controller if one has been set, or the 172 * default controller, or null if the controller has been explicitly 173 * set to null. 174 * 175 * @return the currently used controller or null 176 */ 177 public IIOParamController getController() 178 { 179 return controller == null ? 180 (no_controller ? null : defaultController) : controller; 181 } 182 183 /** 184 * Retrieve the default controller regardless of whether or not a 185 * non-default controller has been set. The default controller may 186 * be null. 187 * 188 * @return the default controller or null 189 */ 190 public IIOParamController getDefaultController() 191 { 192 return defaultController; 193 } 194 195 /** 196 * Retrieve the offset in the destination where the upper-left 197 * decoded/encoded pixel should be located. (0, 0) by default. 198 * 199 * @return the destination offset 200 */ 201 public Point getDestinationOffset() 202 { 203 return destinationOffset; 204 } 205 206 /** 207 * Retrieve the currently set image-type specifier or null if none 208 * has been set. 209 * 210 * @return the current image-type specifier or null 211 */ 212 public ImageTypeSpecifier getDestinationType() 213 { 214 return destinationType; 215 } 216 217 /** 218 * Retrieve the current source band values or null if source band 219 * values have not been set. 220 * 221 * The returned array is a copy of this IIOParam's source band 222 * array. 223 * 224 * @return the current set of source band values or null 225 */ 226 public int[] getSourceBands() 227 { 228 if (sourceBands == null) 229 return null; 230 231 int[] sourceBandsCopy = new int[sourceBands.length]; 232 System.arraycopy (sourceBands, 0, sourceBandsCopy, 0, sourceBands.length); 233 return sourceBandsCopy; 234 } 235 236 /** 237 * Retrieve the source rectangle from which pixels should be read or 238 * null if no source region has been set. 239 * 240 * @return the current source region or null 241 */ 242 public Rectangle getSourceRegion() 243 { 244 return sourceRegion; 245 } 246 247 /** 248 * Retrieve the number of pixel columns to advance before taking a 249 * pixel sample. 250 * 251 * @return the horizontal sub-sampling interval 252 */ 253 public int getSourceXSubsampling() 254 { 255 return sourceXSubsampling; 256 } 257 258 /** 259 * Retrieve the number of pixel rows to advance before taking a 260 * pixel sample. 261 * 262 * @return the vertical sub-sampling interval 263 */ 264 public int getSourceYSubsampling() 265 { 266 return sourceYSubsampling; 267 } 268 269 /** 270 * Retrieve the number of pixel columns to advance before taking any 271 * pixel samples. 272 * 273 * @return the horizontal sub-sampling offset 274 */ 275 public int getSubsamplingXOffset() 276 { 277 return subsamplingXOffset; 278 } 279 280 /** 281 * Retrieve the number of pixel rows to advance before taking any 282 * pixel samples. 283 * 284 * @return the vertical sub-sampling offset 285 */ 286 public int getSubsamplingYOffset() 287 { 288 return subsamplingYOffset; 289 } 290 291 /** 292 * Check if a non-null controller is currently available. 293 * 294 * @return true if getController returns a non-null value, false if 295 * getController returns null 296 */ 297 public boolean hasController() 298 { 299 return getController() != null; 300 } 301 302 /** 303 * Sets the controller for this IIOParam. This is the controller 304 * that will be activated when activateController is called. The 305 * argument controller overrides this IIOParam's default controller. 306 * If the argument is null then no controller will be set, not even 307 * the default one. To reset the default controller call 308 * setController(getDefaultController()). 309 * 310 * @param controller the controller to set or null 311 */ 312 public void setController(IIOParamController controller) 313 { 314 if (controller == defaultController) 315 { 316 this.controller = null; 317 no_controller = false; 318 } 319 else 320 { 321 no_controller = (controller == null); 322 this.controller = controller; 323 } 324 } 325 326 /** 327 * Set the destination image type. 328 * 329 * If this value is set on an image reader then its read method will 330 * return a new BufferedImage of the specified destination type. In 331 * this case any destination image set using setDestination() is 332 * ignored. 333 * 334 * If this is set on an image writer then the destination type 335 * affects only the colour model of the destination image. The 336 * destination type's SampleModel is ignored. The destination 337 * type's ColorModel will override the source image's colour model. 338 * 339 * @param destinationType the sample and colour models of the 340 * destination image 341 */ 342 public void setDestinationType (ImageTypeSpecifier destinationType) 343 { 344 this.destinationType = destinationType; 345 } 346 347 /** 348 * Specify the destination pixel offset. Image writers are only 349 * affected by this setting when ImageWriter.replacePixels is called 350 * in which case the offset is into the region of pixels being 351 * changed. 352 * 353 * @param destinationOffset the offset where pixel writing should 354 * begin 355 */ 356 public void setDestinationOffset(Point destinationOffset) 357 { 358 if (destinationOffset == null) 359 throw new IllegalArgumentException("destinationOffset is null"); 360 361 this.destinationOffset = destinationOffset; 362 } 363 364 /** 365 * Set the indices of the source bands to be used. Duplicate 366 * indices are not allowed. A value of null means use all source 367 * bands. The argument array is copied and stored, so subsequent 368 * updates to it will not be reflected in this IIOParam. 369 * 370 * @param sourceBands the array of source bands to use 371 */ 372 public void setSourceBands(int[] sourceBands) 373 { 374 int[] sourceBandsCopy = new int[sourceBands.length]; 375 System.arraycopy (sourceBands, 0, sourceBandsCopy, 0, sourceBands.length); 376 this.sourceBands = sourceBandsCopy; 377 } 378 379 /** 380 * Set the source region from which to read. The number of pixels 381 * sampled from the source region depends on the source sub-sampling 382 * settings. If the combination of this sourceRegion and the 383 * current sub-sampling settings would result in no pixels being 384 * sampled then an IllegalStateException will be thrown. 385 * 386 * The source region is specified in the source image coordinate 387 * system which has point (0, 0) at the top-left and increases down 388 * and to the right. The argument source region is clipped to the 389 * image boundaries at read-time. 390 * 391 * A null argument sets the source region to null meaning that the 392 * whole image should be read. 393 * 394 * @param sourceRegion the rectangular source region 395 * 396 * @exception IllegalArgumentException if sourceRegion has width or 397 * height <= 0 or x or y < 0 398 * @exception IllegalStateException if the given sourceRegion and 399 * the current sampling settings would produce zero samples 400 */ 401 public void setSourceRegion(Rectangle sourceRegion) 402 { 403 if (sourceRegion != null 404 && (sourceRegion.x < 0 405 || sourceRegion.y < 0 406 || sourceRegion.width <= 0 407 || sourceRegion.height <= 0)) 408 throw new IllegalArgumentException("illegal source region"); 409 410 if (sourceRegion != null) 411 { 412 int num_rows = 413 (sourceRegion.height - subsamplingYOffset + sourceYSubsampling - 1) 414 / sourceYSubsampling; 415 416 int num_columns = 417 (sourceRegion.width - subsamplingXOffset + sourceXSubsampling - 1) 418 / sourceXSubsampling; 419 420 if (num_rows <= 0 || num_columns <= 0) 421 throw new IllegalStateException("zero pixels in source region"); 422 } 423 424 this.sourceRegion = sourceRegion; 425 } 426 427 /** 428 * Set the source sampling intervals and offsets. Every 429 * sourceXSubsampling'th pixel horizontally and 430 * sourceYSubsampling'th pixel vertically will be sampled. Sampling 431 * will being a the subsamplingXOffset'th column and the 432 * subsamplingYOffset'th row. 433 * 434 * Horizontally, the number of sampled pixels will be: 435 * 436 * floor((width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling) 437 * 438 * Vertically: 439 * 440 * floor((height - subsamplingYOffset + sourceYSubsampling - 1) / sourceYSubsampling) 441 * 442 * If the current source region setting is such that the given 443 * sub-sampling arguments would produce zero pixel samples, an 444 * IllegalStateException is thrown. 445 * 446 * The offset parameters can be used to make source regions overlap 447 * when tiling across an image. This can eliminate seams and 448 * better-tile images whose width or height is not a multiple of the 449 * sampling interval. 450 * 451 * @param sourceXSubsampling the horizontal sampling interval 452 * @param sourceYSubsampling the vertical sampling interval 453 * @param subsamplingXOffset the horizontal offset of the initial 454 * sample 455 * @param subsamplingYOffset the vertical offset of the initial 456 * sample 457 * 458 * @exception IllegalArgumentException if either subsamplingXOffset 459 * or subsamplingYOffset is < 0 460 * @exception IllegalStateException if the current source region 461 * combined with the given sub-sampling parameters would produce 462 * zero pixel samples 463 */ 464 public void setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, 465 int subsamplingXOffset, int subsamplingYOffset) 466 { 467 if (subsamplingXOffset < 0 || subsamplingYOffset < 0) 468 throw new IllegalArgumentException("subsampling offset < 0"); 469 470 if (sourceRegion != null) 471 { 472 int num_rows = 473 (sourceRegion.height - subsamplingYOffset + sourceYSubsampling - 1) 474 / sourceYSubsampling; 475 476 int num_columns = 477 (sourceRegion.width - subsamplingXOffset + sourceXSubsampling - 1) 478 / sourceXSubsampling; 479 480 if (num_rows <= 0 || num_columns <= 0) 481 throw new IllegalStateException("subsampling parameters would" 482 + " produce zero pixel samples" 483 + " in source region"); 484 } 485 486 this.sourceXSubsampling = sourceXSubsampling; 487 this.sourceYSubsampling = sourceYSubsampling; 488 this.subsamplingXOffset = subsamplingXOffset; 489 this.subsamplingYOffset = subsamplingYOffset; 490 } 491 }