libjava/classpath/javax/imageio/ImageTypeSpecifier.java

   1 /* ImageTypeSpecifier.java --
   2    Copyright (C) 2004  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.imageio;
  40
  41 import java.awt.Transparency;
  42 import java.awt.color.ColorSpace;
  43 import java.awt.image.DataBuffer;
  44 import java.awt.image.BandedSampleModel;
  45 import java.awt.image.BufferedImage;
  46 import java.awt.image.ColorModel;
  47 import java.awt.image.ComponentColorModel;
  48 import java.awt.image.DirectColorModel;
  49 import java.awt.image.IndexColorModel;
  50 import java.awt.image.MultiPixelPackedSampleModel;
  51 import java.awt.image.PixelInterleavedSampleModel;
  52 import java.awt.image.RenderedImage;
  53 import java.awt.image.SampleModel;
  54
  55 /**
  56  * ImageTypeSpecifier store the color and sample models associated
  57  * with an IIOImage.
  58  */
  59 public class ImageTypeSpecifier
  60 {
  61   /**
  62    * The image's color model.
  63    */
  64   protected ColorModel colorModel;
  65
  66   /**
  67    * The image's sample model.
  68    */
  69   protected SampleModel sampleModel;
  70
  71   /**
  72    * Construct an image type specifier with the given models.
  73    *
  74    * @param colorModel the color model
  75    * @param sampleModel the sample model
  76    *
  77    * @exception IllegalArgumentException if either model argument is
  78    * null
  79    * @exception IllegalArgumentException if the models are
  80    * incompatible with one another
  81    */
  82   public ImageTypeSpecifier(ColorModel colorModel, SampleModel sampleModel)
  83   {
  84     if (colorModel == null)
  85       throw new IllegalArgumentException("colorModel may not be null");
  86
  87     if (sampleModel == null)
  88       throw new IllegalArgumentException("sampleModel may not be null");
  89
  90     if (!colorModel.isCompatibleSampleModel(sampleModel))
  91       throw new IllegalArgumentException
  92         ("sample Model not compatible with colorModel");
  93
  94     this.colorModel = colorModel;
  95     this.sampleModel = sampleModel;
  96   }
  97
  98   /**
  99    * Construct an image type specifier that describes the given
 100    * rendered image.
 101    *
 102    * @param image a rendered image
 103    *
 104    * @exception IllegalArgumentException if image is null
 105    */
 106   public ImageTypeSpecifier(RenderedImage image)
 107   {
 108     if (image == null)
 109       throw new IllegalArgumentException("image may not be null");
 110
 111     this.colorModel = image.getColorModel();
 112     this.sampleModel = image.getSampleModel();
 113   }
 114
 115   /**
 116    * Create an image type specifier for a banded image using a
 117    * component color model and a banded sample model.
 118    *
 119    * @param colorSpace the color space
 120    * @param bankIndices the bank indices at which each band will be
 121    * stored
 122    * @param bankOffsets the starting band offset for each band within
 123    * its bank
 124    * @param dataType the data type, a DataBuffer constant
 125    * @param hasAlpha true if this image type specifier should have an
 126    * alpha component, false otherwise
 127    * @param isAlphaPremultiplied true if other color components should
 128    * be premultiplied by the alpha component, false otherwise
 129    *
 130    * @return a banded image type specifier
 131    *
 132    * @exception IllegalArgumentException if any of colorSpace,
 133    * bankIndices or bankOffsets is null
 134    * @exception IllegalArgumentException if bankIndices and
 135    * bankOffsets differ in length
 136    * @excpetion IllegalArgumentException if the number of color space
 137    * components, including the alpha component if requested, is
 138    * different from bandOffsets.length
 139    * @exception if dataType is not a valid DataBuffer constant
 140    */
 141   public static ImageTypeSpecifier createBanded (ColorSpace colorSpace,
 142                                                  int[] bankIndices,
 143                                                  int[] bankOffsets,
 144                                                  int dataType,
 145                                                  boolean hasAlpha,
 146                                                  boolean isAlphaPremultiplied)
 147   {
 148     if (colorSpace == null || bankIndices == null || bankOffsets == null)
 149       throw new IllegalArgumentException ("null argument");
 150
 151     if (bankIndices.length != bankOffsets.length)
 152       throw new IllegalArgumentException ("array lengths differ");
 153
 154     if (bankOffsets.length != (colorSpace.getNumComponents() + (hasAlpha ? 1 : 0)))
 155       throw new IllegalArgumentException ("invalid bankOffsets length");
 156
 157     return new ImageTypeSpecifier (new ComponentColorModel (colorSpace,
 158                                                             hasAlpha,
 159                                                             isAlphaPremultiplied,
 160                                                             hasAlpha ? Transparency.TRANSLUCENT : Transparency.OPAQUE,
 161                                                             dataType),
 162                                    new BandedSampleModel (dataType, 1, 1, 1,
 163                                                           bankIndices,
 164                                                           bankOffsets));
 165   }
 166
 167   /**
 168    * Create a buffered image with the given dimensions using that has
 169    * the characteristics specified by this image type specifier.
 170    *
 171    * @param width  width of the buffered image, in pixels
 172    * @param height the height of the buffered image, in pixels
 173    *
 174    * @return a buffered image
 175    *
 176    * @exception IllegalArgumentException if either width or height is
 177    * less than or equal to zero
 178    * @exception IllegalArgumentException if width * height is greater
 179    * than Integer.MAX_VALUE or if the storage required is greater than
 180    * Integer.MAX_VALUE
 181    */
 182   public BufferedImage createBufferedImage (int width, int height)
 183   {
 184     if (width <= 0 || height <= 0)
 185       throw new IllegalArgumentException ("dimension <= 0");
 186
 187     // test for overflow
 188     if (width * height < Math.min (width, height))
 189       throw new IllegalArgumentException ("width * height > Integer.MAX_VALUE");
 190
 191     if (width * height * sampleModel.getNumBands() < Math.min (width, height))
 192       throw new IllegalArgumentException ("storage required >"
 193                                           + " Integer.MAX_VALUE");
 194
 195     // FIXME: this is probably wrong:
 196     return new BufferedImage (width, height, BufferedImage.TYPE_INT_RGB);
 197   }
 198
 199   /**
 200    * Create an image type specifier that describes the given buffered
 201    * image type.
 202    *
 203    * @param bufferedImageType the buffered image type to represent
 204    * with the returned image type specifier
 205    *
 206    * @return a new image type specifier
 207    *
 208    * @exception IllegalArgumentException if bufferedImageType is not a
 209    * BufferedImage constant or is BufferedImage.TYPE_CUSTOM
 210    */
 211   public static ImageTypeSpecifier createFromBufferedImageType (int bufferedImageType)
 212   {
 213     if (bufferedImageType <= BufferedImage.TYPE_CUSTOM
 214         || bufferedImageType > BufferedImage.TYPE_BYTE_INDEXED)
 215       throw new IllegalArgumentException ("invalid buffered image type");
 216
 217     return new ImageTypeSpecifier (new BufferedImage (1, 1, bufferedImageType));
 218   }
 219
 220   /**
 221    * Create an image type specifier that describes the given rendered
 222    * image's type.
 223    *
 224    * @param image the rendered image
 225    *
 226    * @return a new image type specifier
 227    *
 228    * @exception IllegalArgumentException if image is null
 229    */
 230   public static ImageTypeSpecifier createFromRenderedImage (RenderedImage image)
 231   {
 232     if (image == null)
 233       throw new IllegalArgumentException ("image null");
 234
 235     return new ImageTypeSpecifier (image);
 236   }
 237
 238   /**
 239    * Create a grayscale image type specifier, given the number of
 240    * bits, data type and whether or not the data is signed.
 241    *
 242    * @param bits the number of bits used to specify a greyscale value
 243    * @param dataType a DataBuffer type constant
 244    * @param isSigned true if this type specifier should support
 245    * negative values, false otherwise
 246    *
 247    * @return a greyscal image type specifier
 248    *
 249    * @exception IllegalArgumentException if bits is not 1, 2, 4, 8 or 16
 250    * @exception IllegalArgumentException if dataType is not
 251    * DataBuffer.TYPE_BYTE, DataBuffer.TYPE_SHORT or
 252    * DataBuffer.TYPE_USHORT
 253    * @exception if bits is larger than the number of bits in the given
 254    * data type
 255    */
 256   public static ImageTypeSpecifier createGrayscale (int bits, int dataType, boolean isSigned)
 257   {
 258     return createGrayscale (bits, dataType, isSigned, false);
 259   }
 260
 261   /**
 262    * Create a grayscale image type specifier, given the number of
 263    * bits, data type and whether or not the data is signed.
 264    *
 265    * @param bits the number of bits used to specify a greyscale value
 266    * @param dataType a DataBuffer type constant
 267    * @param isSigned true if this type specifier should support
 268    * negative values, false otherwise
 269    *
 270    * @return a greyscal image type specifier
 271    *
 272    * @exception IllegalArgumentException if bits is not 1, 2, 4, 8 or
 273    * 16
 274    * @exception IllegalArgumentException if dataType is not
 275    * DataBuffer.TYPE_BYTE, DataBuffer.TYPE_SHORT or
 276    * DataBuffer.TYPE_USHORT
 277    * @exception if bits is larger than the number of bits in the given
 278    * data type
 279    */
 280   public static ImageTypeSpecifier createGrayscale (int bits, int dataType,
 281                                                     boolean isSigned,
 282                                                     boolean isAlphaPremultiplied)
 283   {
 284     if (bits != 1 && bits != 2 && bits != 4 && bits != 8 && bits != 16)
 285       throw new IllegalArgumentException ("invalid bit size");
 286
 287     if (dataType != DataBuffer.TYPE_BYTE && dataType != DataBuffer.TYPE_SHORT
 288         && dataType != DataBuffer.TYPE_USHORT)
 289       throw new IllegalArgumentException ("invalid data type");
 290
 291     if (dataType == DataBuffer.TYPE_BYTE && bits > 8)
 292       throw new IllegalArgumentException ("number of bits too large for data type");
 293
 294     // FIXME: this is probably wrong:
 295     return new ImageTypeSpecifier (new DirectColorModel (bits, 0xff, 0x0,
 296                                                          0x0, 0xff),
 297                                    new MultiPixelPackedSampleModel (dataType,
 298                                                                     1, 1,
 299                                                                     bits));
 300   }
 301
 302   /**
 303    * Return an image type specifier for an image that uses an indexed
 304    * colour model where each colour value has the specified number of
 305    * bits and type and where the colour tables are those given.
 306    *
 307    * @param redLUT the red index values
 308    * @param greenLUT the green index values
 309    * @param blueLUT the blue index values
 310    * @param alphaLUT the alpha index values
 311    * @param bits the number of bits per index value
 312    * @param dataType the type of each index value
 313    *
 314    * @return an indexed image type specifier
 315    *
 316    * @exception IllegalArgumentException if any of the colour arrays,
 317    * not including alphaLUT, is null
 318    * @exception IllegalArgumentException if bits is not 1, 2, 4, 8 or
 319    * 16
 320    * @exception IllegalArgumentException if dataType is not
 321    * DataBuffer.TYPE_BYTE, DataBuffer.TYPE_SHORT or
 322    * DataBuffer.TYPE_USHORT
 323    * @exception if bits is larger than the number of bits in the given
 324    * data type
 325    */
 326   public static ImageTypeSpecifier createIndexed (byte[] redLUT,
 327                                                   byte[] greenLUT,
 328                                                   byte[] blueLUT,
 329                                                   byte[] alphaLUT,
 330                                                   int bits,
 331                                                   int dataType)
 332   {
 333     if (redLUT == null || greenLUT == null || blueLUT == null)
 334       throw new IllegalArgumentException ("null colour table");
 335
 336     if (bits != 1 && bits != 2 && bits != 4 && bits != 8 && bits != 16)
 337       throw new IllegalArgumentException ("invalid bit size");
 338
 339     if (dataType != DataBuffer.TYPE_BYTE && dataType != DataBuffer.TYPE_SHORT
 340         && dataType != DataBuffer.TYPE_USHORT)
 341       throw new IllegalArgumentException ("invalid data type");
 342
 343     if (dataType == DataBuffer.TYPE_BYTE && bits > 8)
 344       throw new IllegalArgumentException ("number of bits too large for data type");
 345
 346     // FIXME: this is probably wrong:
 347     return new ImageTypeSpecifier (new IndexColorModel (bits, redLUT.length,
 348                                                         redLUT, greenLUT, blueLUT,
 349                                                         alphaLUT),
 350                                    new MultiPixelPackedSampleModel (dataType,
 351                                                                     1, 1,
 352                                                                     bits));
 353   }
 354
 355   /**
 356    * Create an image type specifier that uses a component colour model
 357    * and a pixel interleaved sample model.  Each pixel component will
 358    * be stored in a separate value of the given data type.
 359    *
 360    * @param colorSpace the colour space used by the colour model
 361    * @param bandOffsets the starting band offset for each band within
 362    * its bank
 363    * @param dataType the type of each pixel value
 364    * @param hasAlpha true if an alpha channel should be specified,
 365    * false otherwise
 366    * @param isAlphaPremultiplied true if other colour channels should
 367    * be premultiplied by the alpha value, false otherwise
 368    *
 369    * @return an interleaved image type specifier
 370    *
 371    * @exception IllegalArgumentException if either colorSpace or
 372    * bandOffsets is null
 373    * @excpetion IllegalArgumentException if the number of color space
 374    * components, including the alpha component if requested, is
 375    * different from bandOffsets.length
 376    * @exception if dataType is not a valid DataBuffer constant
 377    */
 378   public static ImageTypeSpecifier createInterleaved (ColorSpace colorSpace,
 379                                                       int[] bandOffsets,
 380                                                       int dataType,
 381                                                       boolean hasAlpha,
 382                                                       boolean isAlphaPremultiplied)
 383   {
 384     if (colorSpace == null || bandOffsets == null)
 385       throw new IllegalArgumentException ("null argument");
 386
 387     if (bandOffsets.length != (colorSpace.getNumComponents() + (hasAlpha ? 1 : 0)))
 388       throw new IllegalArgumentException ("invalid bankOffsets length");
 389
 390     return new ImageTypeSpecifier (new ComponentColorModel (colorSpace,
 391                                                             hasAlpha,
 392                                                             isAlphaPremultiplied,
 393                                                             hasAlpha ? Transparency.TRANSLUCENT : Transparency.OPAQUE,
 394                                                             dataType),
 395                                    new PixelInterleavedSampleModel (dataType, 1, 1, 1, 1,
 396                                                                     bandOffsets));
 397   }
 398
 399   /**
 400    * Create an image type specifier using a direct color model and a
 401    * packed sample model.  All pixel components will be packed into
 402    * one value of the given data type.
 403    *
 404    * @param colorSpace the color space to use in the color model
 405    * @param redMask the bitmask for the red bits
 406    * @param greenMask the bitmask for the green bits
 407    * @param blueMask the bitmask for the blue bits
 408    * @param alphaMask the bitmask for the alpha bits
 409    * @param transferType the data type used to store pixel values
 410    * @param isAlphaPremultiplied true if other colour channels should
 411    * be premultiplied by the alpha value, false otherwise
 412    *
 413    * @return a packed image type specifier
 414    *
 415    * @exception IllegalArgumentException if colorSpace is null
 416    * @exception IllegalArgumentException if colorSpace does not have
 417    * type ColorSpace.TYPE_RGB
 418    * @exception IllegalArgumentException if all masks are 0
 419    * @exception IllegalArgumentException if dataType is not
 420    * DataBuffer.TYPE_BYTE, DataBuffer.TYPE_SHORT or
 421    * DataBuffer.TYPE_INT
 422    */
 423   public static ImageTypeSpecifier createPacked (ColorSpace colorSpace,
 424                                                  int redMask,
 425                                                  int greenMask,
 426                                                  int blueMask,
 427                                                  int alphaMask,
 428                                                  int transferType,
 429                                                  boolean isAlphaPremultiplied)
 430   {
 431     if (colorSpace == null)
 432       throw new IllegalArgumentException ("null color space");
 433
 434     if (colorSpace.getType() != ColorSpace.TYPE_RGB)
 435       throw new IllegalArgumentException ("invalid color space type");
 436
 437     if (redMask == 0 && greenMask == 0 && blueMask == 0 && alphaMask == 0)
 438       throw new IllegalArgumentException ("no non-zero mask");
 439
 440     if (transferType != DataBuffer.TYPE_BYTE && transferType != DataBuffer.TYPE_USHORT
 441         && transferType != DataBuffer.TYPE_INT)
 442       throw new IllegalArgumentException ("invalid data type");
 443
 444     // Assume DataBuffer.TYPE_BYTE.
 445     int numBits = 8;
 446
 447     if (transferType == DataBuffer.TYPE_SHORT)
 448       numBits = 16;
 449     else if (transferType == DataBuffer.TYPE_INT)
 450       numBits = 32;
 451
 452     return new ImageTypeSpecifier (new DirectColorModel (colorSpace,
 453                                                          numBits,
 454                                                          redMask,
 455                                                          greenMask,
 456                                                          blueMask,
 457                                                          alphaMask,
 458                                                          isAlphaPremultiplied,
 459                                                          transferType),
 460                                    new MultiPixelPackedSampleModel (transferType,
 461                                                                     1, 1, numBits));
 462   }
 463
 464   /**
 465    * Get the number of bits per sample in the given band.
 466    *
 467    * @param band the band from which to get the number of bits
 468    *
 469    * @return the number of bits in the given band
 470    *
 471    * @exception IllegalArgumentException if band is out-of-bounds
 472    */
 473   public int getBitsPerBand (int band)
 474   {
 475     if (band < 0 || band > sampleModel.getNumBands())
 476       throw new IllegalArgumentException ("band out-of-bounds");
 477
 478     return sampleModel.getSampleSize (band);
 479   }
 480
 481   /**
 482    * Get the buffered image constant specified by this image type
 483    * specifier.
 484    *
 485    * @return a buffered image constant
 486    */
 487   public int getBufferedImageType ()
 488   {
 489     // FIXME:
 490     return BufferedImage.TYPE_INT_RGB;
 491   }
 492
 493   /**
 494    * Create a sample model that is compatible with the one specified
 495    * by this image type specifier, with the given dimensions.
 496    *
 497    * @param width the width of the returned sample model
 498    * @param height the height of the returned sample model
 499    *
 500    * @return a sample model compatible with the one in this image type
 501    * specifier, with the given dimensions
 502    *
 503    * @exception IllegalArgumentException if either width or height is
 504    * less than or equal to 0
 505    * @exception IllegalArgumentException if width * height is greater
 506    * than Intere.MAX_VALUE
 507    */
 508   public SampleModel getSampleModel (int width, int height)
 509   {
 510     if (width <= 0 || height <= 0)
 511       throw new IllegalArgumentException ("invalid dimension");
 512
 513     // test for overflow
 514     if (width * height < Math.min (width, height))
 515       throw new IllegalArgumentException ("width * height > Integer.MAX_VALUE");
 516
 517     return sampleModel.createCompatibleSampleModel (width, height);
 518   }
 519
 520   /**
 521    * Get the color model specified by this image type specifier.
 522    *
 523    * @return the color model
 524    */
 525   public ColorModel getColorModel()
 526   {
 527     return colorModel;
 528   }
 529
 530   /**
 531    * Get the number of bands specified by this image type specifier's
 532    * sample model.
 533    *
 534    * @return the number of bands in the sample model
 535    */
 536   public int getNumBands()
 537   {
 538     return sampleModel.getNumBands();
 539   }
 540
 541   /**
 542    * Get the number of components specified by this image type
 543    * specifier's color model.
 544    *
 545    * @return the number of color components per pixel
 546    */
 547   public int getNumComponents()
 548   {
 549     return colorModel.getNumComponents();
 550   }
 551
 552   /**
 553    * Get the sample model specified by this image type specifier.
 554    *
 555    * @return the sample model
 556    */
 557   public SampleModel getSampleModel()
 558   {
 559     return sampleModel;
 560   }
 561 }