com.sun.media.imageio.plugins.tiff
public abstract class TIFFDecompressor extends Object
The mapping between source and destination Y coordinates is given by the equations:
dx = (sx - sourceXOffset)/subsampleX + dstXOffset; dy = (sy - sourceYOffset)/subsampleY + dstYOffset;Note that the mapping from source coordinates to destination coordinates is not one-to-one if subsampling is being used, since only certain source pixels are to be copied to the destination. However, * the inverse mapping is always one-to-one:
sx = (dx - dstXOffset)*subsampleX + sourceXOffset; sy = (dy - dstYOffset)*subsampleY + sourceYOffset;
Decompressors may be written with various levels of complexity.
The most complex decompressors will override the
decode
method, and will perform all the work of
decoding, subsampling, offsetting, clipping, and format conversion.
This approach may be the most efficient, since it is possible to
avoid the use of extra image buffers, and it may be possible to
avoid decoding portions of the image that will not be copied into
the destination.
Less ambitious decompressors may override the
decodeRaw
method, which is responsible for
decompressing the entire tile or strip into a byte array (or other
appropriate datatype). The default implementation of
decode
will perform all necessary setup of buffers,
call decodeRaw
to perform the actual decoding, perform
subsampling, and copy the results into the final destination image.
Where possible, it will pass the real image buffer to
decodeRaw
in order to avoid making an extra copy.
Slightly more ambitious decompressors may override
decodeRaw
, but avoid writing pixels that will be
discarded in the subsampling phase.
Field Summary | |
---|---|
protected int | activeSrcHeight
The height of the source region that will actually be copied
into the destination image, taking into account all
susbampling, offsetting, and clipping.
|
protected int | activeSrcMinX
The X coordinate of the upper-left source pixel that will
actually be copied into the destination image, taking into
account all subsampling, offsetting, and clipping. |
protected int | activeSrcMinY
The Y coordinate of the upper-left source pixel that will
actually be copied into the destination image, taking into account
all subsampling, offsetting, and clipping.
|
protected int | activeSrcWidth
The width of the source region that will actually be copied
into the destination image, taking into account all
susbampling, offsetting, and clipping.
|
protected int[] | bitsPerSample
The value of the BitsPerSample tag.
|
protected int | byteCount
The number of bytes of data from the source
ImageInputStream to be decompressed. |
protected TIFFColorConverter | colorConverter
A TIFFColorConverter object describing the color space of
the encoded pixel data, or null . |
protected char[] | colorMap
The value of the ColorMap tag.
|
protected int | compression
The value of the Compression tag. |
protected int[] | destinationBands
The sequence of destination bands to receive the source data. |
protected int | dstHeight
The height of the region of the destination image to be written. |
protected int | dstMinX
The X coordinate of the upper left pixel to be written in the
destination image. |
protected int | dstMinY
The Y coordinate of the upper left pixel to be written in the
destination image. |
protected int | dstWidth
The width of the region of the destination image to be written. |
protected int | dstXOffset
The horizontal destination offset used, along with
sourceXOffset and subsampleX , to map
between horizontal source and destination pixel coordinates.
|
protected int | dstYOffset
The vertical destination offset used, along with
sourceYOffset and subsampleY , to map
between horizontal source and destination pixel coordinates.
|
protected int[] | extraSamples
The value of the ExtraSamples tag. |
protected BufferedImage | image
The final destination image. |
protected IIOMetadata | metadata
The IIOMetadata object containing metadata for the
current image. |
protected long | offset
The offset in the source ImageInputStream of the
start of the data to be decompressed. |
protected int | photometricInterpretation
The value of the PhotometricInterpretation tag.
|
protected boolean | planartrue if the image is encoded using separate planes. |
protected BufferedImage | rawImage
A BufferedImage for the decodeRaw
method to write into. |
protected ImageReader | reader
The ImageReader calling this
TIFFDecompressor . |
protected int[] | sampleFormat
The value of the SampleFormat tag. |
protected int | samplesPerPixel
The value of the SamplesPerPixel tag. |
protected int[] | sourceBands
The sequence of source bands that are to be copied into the
destination. |
protected int | sourceXOffset
The source X offset used, along with dstXOffset
and subsampleX , to map between horizontal source
and destination pixel coordinates. |
protected int | sourceYOffset
The source Y offset used, along with dstYOffset
and subsampleY , to map between vertical source and
destination pixel coordinates. |
protected int | srcHeight
The height of the source region being decoded from the source
stream. |
protected int | srcMinX
The X coordinate of the upper-left pixel of the source region
being decoded from the source stream. |
protected int | srcMinY
The Y coordinate of the upper-left pixel of the source region
being decoded from the source stream. |
protected int | srcWidth
The width of the source region being decoded from the source
stream. |
protected ImageInputStream | stream
The ImageInputStream containing the TIFF source
data. |
protected int | subsampleX
The horizontal subsampling factor. |
protected int | subsampleY
The vertical subsampling factor. |
Method Summary | |
---|---|
void | beginDecoding()
This routine is called prior to a sequence of calls to the
decode method, in order to allow any necessary
tables or other structures to be initialized based on metadata
values. |
BufferedImage | createRawImage()
Creates a BufferedImage whose underlying data
array will be suitable for holding the raw decoded output of
the decodeRaw method.
|
void | decode()
Decodes the input bit stream (located in the
ImageInputStream stream , at offset
offset , and continuing for byteCount
bytes) into the output BufferedImage
image .
|
abstract void | decodeRaw(byte[] b, int dstOffset, int bitsPerPixel, int scanlineStride)
Decodes the source data into the provided byte
array b , starting at the offset given by
dstOffset . |
void | decodeRaw(short[] s, int dstOffset, int bitsPerPixel, int scanlineStride)
Decodes the source data into the provided short
array s , starting at the offset given by
dstOffset . |
void | decodeRaw(int[] i, int dstOffset, int bitsPerPixel, int scanlineStride)
Decodes the source data into the provided int
array i , starting at the offset given by
dstOffset . |
void | decodeRaw(float[] f, int dstOffset, int bitsPerPixel, int scanlineStride)
Decodes the source data into the provided float
array f , starting at the offset given by
dstOffset . |
ImageTypeSpecifier | getRawImageType()
Returns an ImageTypeSpecifier describing an image
whose underlying data array has the same format as the raw
source pixel data.
|
static ImageTypeSpecifier | getRawImageTypeSpecifier(int photometricInterpretation, int compression, int samplesPerPixel, int[] bitsPerSample, int[] sampleFormat, int[] extraSamples, char[] colorMap)
A utility method that returns an
ImageTypeSpecifier suitable for decoding an image
with the given parameters.
|
void | setActiveSrcHeight(int activeSrcHeight)
Sets the value of the activeSrcHeight field.
|
void | setActiveSrcMinX(int activeSrcMinX)
Sets the value of the activeSrcMinX field.
|
void | setActiveSrcMinY(int activeSrcMinY)
Sets the value of the activeSrcMinY field.
|
void | setActiveSrcWidth(int activeSrcWidth)
Sets the value of the activeSrcWidth field.
|
void | setBitsPerSample(int[] bitsPerSample)
Sets the value of the bitsPerSample field.
|
void | setByteCount(int byteCount)
Sets the value of the byteCount field.
|
void | setColorConverter(TIFFColorConverter colorConverter)
Sets the TIFFColorConverter object describing the color
space of the encoded data in the input stream. |
void | setColorMap(char[] colorMap)
Sets the value of the colorMap field.
|
void | setCompression(int compression)
Sets the value of the compression field.
|
void | setDestinationBands(int[] destinationBands)
Sets the value of the destinationBands field.
|
void | setDstHeight(int dstHeight)
Sets the value of the dstHeight field.
|
void | setDstMinX(int dstMinX)
Sets the value of the dstMinX field.
|
void | setDstMinY(int dstMinY)
Sets the value of the dstMinY field.
|
void | setDstWidth(int dstWidth)
Sets the value of the dstWidth field.
|
void | setDstXOffset(int dstXOffset)
Sets the value of the dstXOffset field.
|
void | setDstYOffset(int dstYOffset)
Sets the value of the dstYOffset field.
|
void | setExtraSamples(int[] extraSamples)
Sets the value of the extraSamples field.
|
void | setImage(BufferedImage image)
Sets the value of the image field.
|
void | setMetadata(IIOMetadata metadata)
Sets the value of the metadata field.
|
void | setOffset(long offset)
Sets the value of the offset field.
|
void | setPhotometricInterpretation(int photometricInterpretation)
Sets the value of the photometricInterpretation
field.
|
void | setPlanar(boolean planar)
Sets the value of the planar field.
|
void | setReader(ImageReader reader)
Sets the value of the reader field.
|
void | setSampleFormat(int[] sampleFormat)
Sets the value of the sampleFormat field.
|
void | setSamplesPerPixel(int samplesPerPixel)
Sets the value of the samplesPerPixel field.
|
void | setSourceBands(int[] sourceBands)
Sets the value of the sourceBands field.
|
void | setSourceXOffset(int sourceXOffset)
Sets the value of the sourceXOffset field.
|
void | setSourceYOffset(int sourceYOffset)
Sets the value of the sourceYOffset .
|
void | setSrcHeight(int srcHeight)
Sets the value of the srcHeight field.
|
void | setSrcMinX(int srcMinX)
Sets the value of the srcMinX field.
|
void | setSrcMinY(int srcMinY)
Sets the value of the srcMinY field.
|
void | setSrcWidth(int srcWidth)
Sets the value of the srcWidth field.
|
void | setStream(ImageInputStream stream)
Sets the value of the stream field.
|
void | setSubsampleX(int subsampleX)
Sets the value of the subsampleX field.
|
void | setSubsampleY(int subsampleY)
Sets the value of the subsampleY field.
|
The active source height will always be equal to
(dstHeight - 1)*subsampleY + 1
.
activeSrcMinX
,
activeSrcMinY
) is to be copied into the
destination pixel at (dstMinX
,
dstMinY
).
The pixels in the source region to be copied are
those with X coordinates of the form activeSrcMinX +
k*subsampleX
, where k
is an integer such
that 0 <= k < dstWidth
.
The pixels in the source region to be copied are
those with Y coordinates of the form activeSrcMinY +
k*subsampleY
, where k
is an integer such
that 0 <= k < dstHeight
.
The active source width will always be equal to
(dstWidth - 1)*subsampleX + 1
.
BitsPerSample
tag.
ImageInputStream
to be decompressed.TIFFColorConverter
object describing the color space of
the encoded pixel data, or null
.ColorMap
tag.
Compression
tag. Legal values are
COMPRESSION_NONE, COMPRESSION_CCITT_RLE, COMPRESSION_CCITT_T_4, COMPRESSION_CCITT_T_6, COMPRESSION_LZW, COMPRESSION_OLD_JPEG, COMPRESSION_JPEG, COMPRESSION_ZLIB, COMPRESSION_PACKBITS, COMPRESSION_DEFLATE, or other value
defined by a TIFF extension.sourceXOffset
and subsampleX
, to map
between horizontal source and destination pixel coordinates.
See the comment for sourceXOffset
for the mapping equations.sourceYOffset
and subsampleY
, to map
between horizontal source and destination pixel coordinates.
See the comment for sourceYOffset
for the mapping equations.ExtraSamples
tag. Legal values
are EXTRA_SAMPLES_UNSPECIFIED,
EXTRA_SAMPLES_ASSOCIATED_ALPHA,
EXTRA_SAMPLES_UNASSOCIATED_ALPHA,
or other value defined by a TIFF extension.IIOMetadata
object containing metadata for the
current image.ImageInputStream
of the
start of the data to be decompressed.PhotometricInterpretation
tag.
Legal values are PHOTOMETRIC_INTERPRETATION_WHITE_IS_ZERO,
PHOTOMETRIC_INTERPRETATION_BLACK_IS_ZERO,
PHOTOMETRIC_INTERPRETATION_RGB,
PHOTOMETRIC_INTERPRETATION_PALETTE_COLOR,
PHOTOMETRIC_INTERPRETATION_TRANSPARENCY_MASK,
PHOTOMETRIC_INTERPRETATION_Y_CB_CR,
PHOTOMETRIC_INTERPRETATION_CIELAB,
PHOTOMETRIC_INTERPRETATION_ICCLAB,
or other value defined by a TIFF extension.true
if the image is encoded using separate planes.BufferedImage
for the decodeRaw
method to write into.ImageReader
calling this
TIFFDecompressor
.SampleFormat
tag. Legal values
are SAMPLE_FORMAT_UNSIGNED_INTEGER,
SAMPLE_FORMAT_SIGNED_INTEGER, SAMPLE_FORMAT_FLOATING_POINT, SAMPLE_FORMAT_UNDEFINED, or other value
defined by a TIFF extension.SamplesPerPixel
tag.dstXOffset
and subsampleX
, to map between horizontal source
and destination pixel coordinates.dstYOffset
and subsampleY
, to map between vertical source and
destination pixel coordinates.ImageInputStream
containing the TIFF source
data.decode
method, in order to allow any necessary
tables or other structures to be initialized based on metadata
values. This routine is guaranteed to be called any time the
metadata values have changed.
The default implementation computes tables used by the
decode
method to rescale components to different
bit depths. Thus, if this method is overridden, it is
important for the subclass method to call super()
,
unless it overrides decode
as well.
BufferedImage
whose underlying data
array will be suitable for holding the raw decoded output of
the decodeRaw
method.
The default implementation calls
getRawImageType
, and calls the resulting
ImageTypeSpecifier
's
createBufferedImage
method.
Returns: a BufferedImage
whose underlying data
array has the same format as the raw source pixel data, or
null
if it is not possible to create such an
image.
ImageInputStream
stream
, at offset
offset
, and continuing for byteCount
bytes) into the output BufferedImage
image
.
The default implementation analyzes the destination image
to determine if it is suitable as the destination for the
decodeRaw
method. If not, a suitable image is
created. Next, decodeRaw
is called to perform the
actual decoding, and the results are copied into the
destination image if necessary. Subsampling and offsetting are
performed automatically.
The precise responsibilities of this routine are as
follows. The input bit stream is defined by the instance
variables stream
, offset
, and
byteCount
. These bits contain the data for the
region of the source image defined by srcMinX
,
srcMinY
, srcWidth
, and
srcHeight
.
The source data is required to be subsampling, starting at
the sourceXOffset
th column and including
every subsampleX
th pixel thereafter (and similarly
for sourceYOffset
and
subsampleY
).
Pixels are copied into the destination with an addition shift of
(dstXOffset
, dstYOffset
). The complete
set of formulas relating the source and destination coordinate spaces
are:
dx = (sx - sourceXOffset)/subsampleX + dstXOffset; dy = (sy - sourceYOffset)/subsampleY + dstYOffset;Only source pixels such that
(sx - sourceXOffset) %
subsampleX == 0
and (sy - sourceYOffset) %
subsampleY == 0
are copied.
The inverse mapping, from destination to source coordinates, is one-to-one:
sx = (dx - dstXOffset)*subsampleX + sourceXOffset; sy = (dy - dstYOffset)*subsampleY + sourceYOffset;
The region of the destination image to be updated is given
by the instance variables dstMinX
,
dstMinY
, dstWidth
, and
dstHeight
.
It is possible that not all of the source data being read
will contribute to the destination image. For example, the
destination offsets could be set such that some of the source
pixels land outside of the bounds of the image. As a
convenience, the bounds of the active source region (that is,
the region of the strip or tile being read that actually
contributes to the destination image, taking clipping into
account) are available as activeSrcMinX
,
activeSrcMinY
, activeSrcWidth
and
activeSrcHeight
. Thus, the source pixel at
(activeSrcMinX
, activeSrcMinY
) will
map to the destination pixel (dstMinX
,
dstMinY
).
The sequence of source bands given by
sourceBands
are to be copied into the sequence of
bands in the destination given by
destinationBands
.
Some standard tag information is provided the instance
variables photometricInterpretation
,
compression
, samplesPerPixel
,
bitsPerSample
, sampleFormat
,
extraSamples
, and colorMap
.
In practice, unless there is a significant performance
advantage to be gained by overriding this routine, most users
will prefer to use the default implementation of this routine,
and instead override the decodeRaw
and/or
getRawImageType
methods.
Throws: IOException if an error occurs in
decodeRaw
.
byte
array b
, starting at the offset given by
dstOffset
. Each pixel occupies
bitsPerPixel
bits, with no padding between pixels.
Scanlines are separated by scanlineStride
byte
s.
Parameters: b a byte
array to be written. dstOffset the starting offset in b
to be
written. bitsPerPixel the number of bits for each pixel. scanlineStride the number of byte
s to
advance between that starting pixels of each scanline.
Throws: IOException if an error occurs reading from the source
ImageInputStream
.
short
array s
, starting at the offset given by
dstOffset
. Each pixel occupies
bitsPerPixel
bits, with no padding between pixels.
Scanlines are separated by scanlineStride
short
s
The default implementation calls decodeRaw(byte[] b,
...)
and copies the resulting data into s
.
Parameters: s a short
array to be written. dstOffset the starting offset in s
to be
written. bitsPerPixel the number of bits for each pixel. scanlineStride the number of short
s to
advance between that starting pixels of each scanline.
Throws: IOException if an error occurs reading from the source
ImageInputStream
.
int
array i
, starting at the offset given by
dstOffset
. Each pixel occupies
bitsPerPixel
bits, with no padding between pixels.
Scanlines are separated by scanlineStride
int
s.
The default implementation calls decodeRaw(byte[] b,
...)
and copies the resulting data into i
.
Parameters: i an int
array to be written. dstOffset the starting offset in i
to be
written. bitsPerPixel the number of bits for each pixel. scanlineStride the number of int
s to
advance between that starting pixels of each scanline.
Throws: IOException if an error occurs reading from the source
ImageInputStream
.
float
array f
, starting at the offset given by
dstOffset
. Each pixel occupies
bitsPerPixel
bits, with no padding between pixels.
Scanlines are separated by scanlineStride
float
s.
The default implementation calls decodeRaw(byte[] b,
...)
and copies the resulting data into f
.
Parameters: f a float
array to be written. dstOffset the starting offset in f
to be
written. bitsPerPixel the number of bits for each pixel. scanlineStride the number of float
s to
advance between that starting pixels of each scanline.
Throws: IOException if an error occurs reading from the source
ImageInputStream
.
ImageTypeSpecifier
describing an image
whose underlying data array has the same format as the raw
source pixel data.
Returns: an ImageTypeSpecifier
.
ImageTypeSpecifier
suitable for decoding an image
with the given parameters.
Parameters: photometricInterpretation the value of the
PhotometricInterpretation
field. compression the value of the Compression
field. samplesPerPixel the value of the
SamplesPerPixel
field. bitsPerSample the value of the BitsPerSample
field. sampleFormat the value of the SampleFormat
field. extraSamples the value of the ExtraSamples
field. colorMap the value of the ColorMap
field.
Returns: a suitable ImageTypeSpecifier
, or
null
if it is not possible to create one.
activeSrcHeight
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: activeSrcHeight the height of the active source region.
activeSrcMinX
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: activeSrcMinX the minimum X coordinate of the active source region.
activeSrcMinY
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: activeSrcMinY the minimum Y coordinate of the active source region.
activeSrcWidth
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: activeSrcWidth the width of the active source region.
bitsPerSample
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: bitsPerSample the number of bits for each source image sample.
byteCount
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: byteCount the number of bytes of compressed data.
TIFFColorConverter
object describing the color
space of the encoded data in the input stream. If no
TIFFColorConverter
is set, no conversion will be performed.
Parameters: colorConverter a TIFFColorConverter
object, or
null
.
colorMap
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: colorMap the color map to apply to the source data,
as an array of char
s.
compression
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: compression the compression type.
destinationBands
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: destinationBands an array of int
s
specifying the destination bands to be written.
dstHeight
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: dstHeight the height of the destination region.
dstMinX
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: dstMinX the minimum X coordinate of the destination region.
dstMinY
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: dstMinY the minimum Y coordinate of the destination region.
dstWidth
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: dstWidth the width of the destination region.
dstXOffset
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: dstXOffset the horizontal destination offset to be used when mapping between source and destination coordinates.
dstYOffset
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: dstYOffset the vertical destination offset to be used when mapping between source and destination coordinates.
extraSamples
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: extraSamples the interpretation of any samples in the source file beyond those used for basic color or grayscale information.
image
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: image the destination BufferedImage
.
metadata
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: metadata the IIOMetadata
object for the
image being read.
offset
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: offset the offset of the beginning of the compressed data.
photometricInterpretation
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: photometricInterpretation the photometric interpretation value.
planar
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: planar true
if the image to be decoded is
stored in planar format.
reader
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: reader the current ImageReader
.
sampleFormat
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: sampleFormat the format of the source image data, for example unsigned integer or floating-point.
samplesPerPixel
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: samplesPerPixel the number of samples in each source pixel.
sourceBands
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: sourceBands an array of int
s
specifying the source bands to be read.
sourceXOffset
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: sourceXOffset the horizontal source offset to be used when mapping between source and destination coordinates.
sourceYOffset
.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: sourceYOffset the vertical source offset to be used when mapping between source and destination coordinates.
srcHeight
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: srcHeight the height of the source region being decoded, irrespective of how it will be copied into the destination.
srcMinX
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: srcMinX the minimum X coordinate of the source region being decoded, irrespective of how it will be copied into the destination.
srcMinY
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: srcMinY the minimum Y coordinate of the source region being decoded, irrespective of how it will be copied into the destination.
srcWidth
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: srcWidth the width of the source region being decoded, irrespective of how it will be copied into the destination.
stream
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: stream the ImageInputStream
to be read.
subsampleX
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: subsampleX the horizontal subsampling factor.
Throws: IllegalArgumentException if subsampleX
is
less than or equal to 0.
subsampleY
field.
If this method is called, the beginDecoding
method must be called prior to calling any of the decode
methods.
Parameters: subsampleY the vertical subsampling factor.
Throws: IllegalArgumentException if subsampleY
is
less than or equal to 0.