Module java.desktop
Package javax.imageio

# Class ImageTypeSpecifier

java.lang.Object
javax.imageio.ImageTypeSpecifier

public class ImageTypeSpecifier extends Object
A class that allows the format of an image (in particular, its `SampleModel` and `ColorModel`) to be specified in a convenient manner.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected ColorModel`
  `colorModel`
  The `ColorModel` to be used as a prototype.
  `protected SampleModel`
  `sampleModel`
  A `SampleModel` to be used as a prototype.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ImageTypeSpecifier(ColorModel colorModel, SampleModel sampleModel)`
  Constructs an `ImageTypeSpecifier` directly from a `ColorModel` and a `SampleModel`.
  `ImageTypeSpecifier(RenderedImage image)`
  Constructs an `ImageTypeSpecifier` from a `RenderedImage`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ImageTypeSpecifier`
  `createBanded(ColorSpace colorSpace, int[] bankIndices, int[] bandOffsets, int dataType, boolean hasAlpha, boolean isAlphaPremultiplied)`
  Returns a specifier for a banded image format that will use a `ComponentColorModel` and a `BandedSampleModel` to store each channel in a separate array.
  `BufferedImage`
  `createBufferedImage(int width, int height)`
  Creates a `BufferedImage` with a given width and height according to the specification embodied in this object.
  `static ImageTypeSpecifier`
  `createFromBufferedImageType(int bufferedImageType)`
  Returns an `ImageTypeSpecifier` that encodes one of the standard `BufferedImage` types (other than `TYPE_CUSTOM`).
  `static ImageTypeSpecifier`
  `createFromRenderedImage(RenderedImage image)`
  Returns an `ImageTypeSpecifier` that encodes the layout of a `RenderedImage` (which may be a `BufferedImage`).
  `static ImageTypeSpecifier`
  `createGrayscale(int bits, int dataType, boolean isSigned)`
  Returns a specifier for a grayscale image format that will pack pixels of the given bit depth into array elements of the specified data type.
  `static ImageTypeSpecifier`
  `createGrayscale(int bits, int dataType, boolean isSigned, boolean isAlphaPremultiplied)`
  Returns a specifier for a grayscale plus alpha image format that will pack pixels of the given bit depth into array elements of the specified data type.
  `static ImageTypeSpecifier`
  `createIndexed(byte[] redLUT, byte[] greenLUT, byte[] blueLUT, byte[] alphaLUT, int bits, int dataType)`
  Returns a specifier for an indexed-color image format that will pack index values of the given bit depth into array elements of the specified data type.
  `static ImageTypeSpecifier`
  `createInterleaved(ColorSpace colorSpace, int[] bandOffsets, int dataType, boolean hasAlpha, boolean isAlphaPremultiplied)`
  Returns a specifier for an interleaved image format that will use a `ComponentColorModel` and a `PixelInterleavedSampleModel` to store each pixel component in a separate byte, short, or int.
  `static ImageTypeSpecifier`
  `createPacked(ColorSpace colorSpace, int redMask, int greenMask, int blueMask, int alphaMask, int transferType, boolean isAlphaPremultiplied)`
  Returns a specifier for a packed image format that will use a `DirectColorModel` and a packed `SampleModel` to store each pixel packed into in a single byte, short, or int.
  `boolean`
  `equals(Object o)`
  Returns `true` if the given `Object` is an `ImageTypeSpecifier` and has a `SampleModel` and `ColorModel` that are equal to those of this object.
  `int`
  `getBitsPerBand(int band)`
  Return the number of bits used to represent samples of the given band.
  `int`
  `getBufferedImageType()`
  Returns an int containing one of the enumerated constant values describing image formats from `BufferedImage`.
  `ColorModel`
  `getColorModel()`
  Returns the `ColorModel` specified by this object.
  `int`
  `getNumBands()`
  Return the number of bands specified by this object.
  `int`
  `getNumComponents()`
  Return the number of color components specified by this object.
  `SampleModel`
  `getSampleModel()`
  Returns a `SampleModel` based on the settings encapsulated within this object.
  `SampleModel`
  `getSampleModel(int width, int height)`
  Returns a `SampleModel` based on the settings encapsulated within this object.
  `int`
  `hashCode()`
  Returns the hash code for this ImageTypeSpecifier.

  ### Methods declared in class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### colorModel

    protected ColorModel colorModel
    The `ColorModel` to be used as a prototype.

  - ### sampleModel

    protected SampleModel sampleModel
    A `SampleModel` to be used as a prototype.

- ## Constructor Details

  - ### ImageTypeSpecifier

    public ImageTypeSpecifier(ColorModel colorModel, SampleModel sampleModel)
    Constructs an `ImageTypeSpecifier` directly from a `ColorModel` and a `SampleModel`. It is the caller's responsibility to supply compatible parameters.
    Parameters:
      `colorModel` - a `ColorModel`.
      `sampleModel` - a `SampleModel`.
    Throws:
      `IllegalArgumentException` - if either parameter is `null`.
      `IllegalArgumentException` - if `sampleModel` is not compatible with `colorModel`.

  - ### ImageTypeSpecifier

    public ImageTypeSpecifier(RenderedImage image)
    Constructs an `ImageTypeSpecifier` from a `RenderedImage`. If a `BufferedImage` is being used, one of the factory methods `createFromRenderedImage` or `createFromBufferedImageType` should be used instead in order to get a more accurate result.
    Parameters:
      `image` - a `RenderedImage`.
    Throws:
      `IllegalArgumentException` - if the argument is `null`.

- ## Method Details

  - ### createPacked

    public static ImageTypeSpecifier createPacked(ColorSpace colorSpace, int redMask, int greenMask, int blueMask, int alphaMask, int transferType, boolean isAlphaPremultiplied)
    Returns a specifier for a packed image format that will use a `DirectColorModel` and a packed `SampleModel` to store each pixel packed into in a single byte, short, or int.
    Parameters:
      `colorSpace` - the desired `ColorSpace`.
      `redMask` - a contiguous mask indicated the position of the red channel.
      `greenMask` - a contiguous mask indicated the position of the green channel.
      `blueMask` - a contiguous mask indicated the position of the blue channel.
      `alphaMask` - a contiguous mask indicated the position of the alpha channel.
      `transferType` - the desired `SampleModel` transfer type.
      `isAlphaPremultiplied` - `true` if the color channels will be premultipled by the alpha channel.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `colorSpace` is `null`.
      `IllegalArgumentException` - if `colorSpace` is not of type `TYPE_RGB`.
      `IllegalArgumentException` - if no mask has at least 1 bit set.
      `IllegalArgumentException` - if `transferType` if not one of `DataBuffer.TYPE_BYTE`, `DataBuffer.TYPE_USHORT`, or `DataBuffer.TYPE_INT`.

  - ### createInterleaved

    public static ImageTypeSpecifier createInterleaved(ColorSpace colorSpace, int[] bandOffsets, int dataType, boolean hasAlpha, boolean isAlphaPremultiplied)
    Returns a specifier for an interleaved image format that will use a `ComponentColorModel` and a `PixelInterleavedSampleModel` to store each pixel component in a separate byte, short, or int.
    Parameters:
      `colorSpace` - the desired `ColorSpace`.
      `bandOffsets` - an array of `int`s indicating the offsets for each band.
      `dataType` - the desired data type, as one of the enumerations from the `DataBuffer` class.
      `hasAlpha` - `true` if an alpha channel is desired.
      `isAlphaPremultiplied` - `true` if the color channels will be premultipled by the alpha channel.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `colorSpace` is `null`.
      `IllegalArgumentException` - if `bandOffsets` is `null`.
      `IllegalArgumentException` - if `dataType` is not one of the legal `DataBuffer.TYPE_*` constants.
      `IllegalArgumentException` - if `bandOffsets.length` does not equal the number of color space components, plus 1 if `hasAlpha` is `true`.

  - ### createBanded

    public static ImageTypeSpecifier createBanded(ColorSpace colorSpace, int[] bankIndices, int[] bandOffsets, int dataType, boolean hasAlpha, boolean isAlphaPremultiplied)
    Returns a specifier for a banded image format that will use a `ComponentColorModel` and a `BandedSampleModel` to store each channel in a separate array.
    Parameters:
      `colorSpace` - the desired `ColorSpace`.
      `bankIndices` - an array of `int`s indicating the bank in which each band will be stored.
      `bandOffsets` - an array of `int`s indicating the starting offset of each band within its bank.
      `dataType` - the desired data type, as one of the enumerations from the `DataBuffer` class.
      `hasAlpha` - `true` if an alpha channel is desired.
      `isAlphaPremultiplied` - `true` if the color channels will be premultipled by the alpha channel.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `colorSpace` is `null`.
      `IllegalArgumentException` - if `bankIndices` is `null`.
      `IllegalArgumentException` - if `bandOffsets` is `null`.
      `IllegalArgumentException` - if the lengths of `bankIndices` and `bandOffsets` differ.
      `IllegalArgumentException` - if `bandOffsets.length` does not equal the number of color space components, plus 1 if `hasAlpha` is `true`.
      `IllegalArgumentException` - if `dataType` is not one of the legal `DataBuffer.TYPE_*` constants.

  - ### createGrayscale

    public static ImageTypeSpecifier createGrayscale(int bits, int dataType, boolean isSigned)
    Returns a specifier for a grayscale image format that will pack pixels of the given bit depth into array elements of the specified data type.
    Parameters:
      `bits` - the number of bits per gray value (1, 2, 4, 8, or 16).
      `dataType` - the desired data type, as one of the enumerations from the `DataBuffer` class.
      `isSigned` - `true` if negative values are to be represented.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `bits` is not one of 1, 2, 4, 8, or 16.
      `IllegalArgumentException` - if `dataType` is not one of `DataBuffer.TYPE_BYTE`, `DataBuffer.TYPE_SHORT`, or `DataBuffer.TYPE_USHORT`.
      `IllegalArgumentException` - if `bits` is larger than the bit size of the given `dataType`.

  - ### createGrayscale

    public static ImageTypeSpecifier createGrayscale(int bits, int dataType, boolean isSigned, boolean isAlphaPremultiplied)
    Returns a specifier for a grayscale plus alpha image format that will pack pixels of the given bit depth into array elements of the specified data type.
    Parameters:
      `bits` - the number of bits per gray value (1, 2, 4, 8, or 16).
      `dataType` - the desired data type, as one of the enumerations from the `DataBuffer` class.
      `isSigned` - `true` if negative values are to be represented.
      `isAlphaPremultiplied` - `true` if the luminance channel will be premultipled by the alpha channel.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `bits` is not one of 1, 2, 4, 8, or 16.
      `IllegalArgumentException` - if `dataType` is not one of `DataBuffer.TYPE_BYTE`, `DataBuffer.TYPE_SHORT`, or `DataBuffer.TYPE_USHORT`.
      `IllegalArgumentException` - if `bits` is larger than the bit size of the given `dataType`.

  - ### createIndexed

    public static ImageTypeSpecifier createIndexed(byte[] redLUT, byte[] greenLUT, byte[] blueLUT, byte[] alphaLUT, int bits, int dataType)
    Returns a specifier for an indexed-color image format that will pack index values of the given bit depth into array elements of the specified data type.
    Parameters:
      `redLUT` - an array of `byte`s containing the red values for each index.
      `greenLUT` - an array of `byte`s containing * the green values for each index.
      `blueLUT` - an array of `byte`s containing the blue values for each index.
      `alphaLUT` - an array of `byte`s containing the alpha values for each index, or `null` to create a fully opaque LUT.
      `bits` - the number of bits in each index.
      `dataType` - the desired output type, as one of the enumerations from the `DataBuffer` class.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `redLUT` is `null`.
      `IllegalArgumentException` - if `greenLUT` is `null`.
      `IllegalArgumentException` - if `blueLUT` is `null`.
      `IllegalArgumentException` - if `bits` is not one of 1, 2, 4, 8, or 16.
      `IllegalArgumentException` - if the non-`null` LUT parameters do not have lengths of exactly `1 << bits`.
      `IllegalArgumentException` - if `dataType` is not one of `DataBuffer.TYPE_BYTE`, `DataBuffer.TYPE_SHORT`, `DataBuffer.TYPE_USHORT`, or `DataBuffer.TYPE_INT`.
      `IllegalArgumentException` - if `bits` is larger than the bit size of the given `dataType`.

  - ### createFromBufferedImageType

    public static ImageTypeSpecifier createFromBufferedImageType(int bufferedImageType)
    Returns an `ImageTypeSpecifier` that encodes one of the standard `BufferedImage` types (other than `TYPE_CUSTOM`).
    Parameters:
      `bufferedImageType` - an int representing one of the standard `BufferedImage` types.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `bufferedImageType` is not one of the standard types, or is equal to `TYPE_CUSTOM`.
    See Also:
      - `BufferedImage`
      - `BufferedImage.TYPE_INT_RGB`
      - `BufferedImage.TYPE_INT_ARGB`
      - `BufferedImage.TYPE_INT_ARGB_PRE`
      - `BufferedImage.TYPE_INT_BGR`
      - `BufferedImage.TYPE_3BYTE_BGR`
      - `BufferedImage.TYPE_4BYTE_ABGR`
      - `BufferedImage.TYPE_4BYTE_ABGR_PRE`
      - `BufferedImage.TYPE_USHORT_565_RGB`
      - `BufferedImage.TYPE_USHORT_555_RGB`
      - `BufferedImage.TYPE_BYTE_GRAY`
      - `BufferedImage.TYPE_USHORT_GRAY`
      - `BufferedImage.TYPE_BYTE_BINARY`
      - `BufferedImage.TYPE_BYTE_INDEXED`

  - ### createFromRenderedImage

    public static ImageTypeSpecifier createFromRenderedImage(RenderedImage image)
    Returns an `ImageTypeSpecifier` that encodes the layout of a `RenderedImage` (which may be a `BufferedImage`).
    Parameters:
      `image` - a `RenderedImage`.
    Returns:
      an `ImageTypeSpecifier` with the desired characteristics.
    Throws:
      `IllegalArgumentException` - if `image` is `null`.

  - ### getBufferedImageType

    public int getBufferedImageType()
    Returns an int containing one of the enumerated constant values describing image formats from `BufferedImage`.
    Returns:
      an `int` representing a `BufferedImage` type.
    See Also:
      - `BufferedImage`
      - `BufferedImage.TYPE_CUSTOM`
      - `BufferedImage.TYPE_INT_RGB`
      - `BufferedImage.TYPE_INT_ARGB`
      - `BufferedImage.TYPE_INT_ARGB_PRE`
      - `BufferedImage.TYPE_INT_BGR`
      - `BufferedImage.TYPE_3BYTE_BGR`
      - `BufferedImage.TYPE_4BYTE_ABGR`
      - `BufferedImage.TYPE_4BYTE_ABGR_PRE`
      - `BufferedImage.TYPE_USHORT_565_RGB`
      - `BufferedImage.TYPE_USHORT_555_RGB`
      - `BufferedImage.TYPE_BYTE_GRAY`
      - `BufferedImage.TYPE_USHORT_GRAY`
      - `BufferedImage.TYPE_BYTE_BINARY`
      - `BufferedImage.TYPE_BYTE_INDEXED`

  - ### getNumComponents

    public int getNumComponents()
    Return the number of color components specified by this object. This is the same value as returned by `ColorModel.getNumComponents`
    Returns:
      the number of components in the image.

  - ### getNumBands

    public int getNumBands()
    Return the number of bands specified by this object. This is the same value as returned by `SampleModel.getNumBands`
    Returns:
      the number of bands in the image.

  - ### getBitsPerBand

    public int getBitsPerBand(int band)
    Return the number of bits used to represent samples of the given band.
    Parameters:
      `band` - the index of the band to be queried, as an int.
    Returns:
      an int specifying a number of bits.
    Throws:
      `IllegalArgumentException` - if `band` is negative or greater than the largest band index.

  - ### getSampleModel

    public SampleModel getSampleModel()
    Returns a `SampleModel` based on the settings encapsulated within this object. The width and height of the `SampleModel` will be set to arbitrary values.
    Returns:
      a `SampleModel` with arbitrary dimensions.

  - ### getSampleModel

    public SampleModel getSampleModel(int width, int height)
    Returns a `SampleModel` based on the settings encapsulated within this object. The width and height of the `SampleModel` will be set to the supplied values.
    Parameters:
      `width` - the desired width of the returned `SampleModel`.
      `height` - the desired height of the returned `SampleModel`.
    Returns:
      a `SampleModel` with the given dimensions.
    Throws:
      `IllegalArgumentException` - if either `width` or `height` are negative or zero.
      `IllegalArgumentException` - if the product of `width` and `height` is greater than `Integer.MAX_VALUE`

  - ### getColorModel

    public ColorModel getColorModel()
    Returns the `ColorModel` specified by this object.
    Returns:
      a `ColorModel`.

  - ### createBufferedImage

    public BufferedImage createBufferedImage(int width, int height)
    Creates a `BufferedImage` with a given width and height according to the specification embodied in this object.
    Parameters:
      `width` - the desired width of the returned `BufferedImage`.
      `height` - the desired height of the returned `BufferedImage`.
    Returns:
      a new `BufferedImage`
    Throws:
      `IllegalArgumentException` - if either `width` or `height` are negative or zero.
      `IllegalArgumentException` - if the product of `width` and `height` is greater than `Integer.MAX_VALUE`, or if the number of array elements needed to store the image is greater than `Integer.MAX_VALUE`.

  - ### equals

    public boolean equals(Object o)
    Returns `true` if the given `Object` is an `ImageTypeSpecifier` and has a `SampleModel` and `ColorModel` that are equal to those of this object.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `o` - the `Object` to be compared for equality.
    Returns:
      `true` if the given object is an equivalent `ImageTypeSpecifier`.
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### hashCode

    public int hashCode()
    Returns the hash code for this ImageTypeSpecifier.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code for this ImageTypeSpecifier
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`