Class ImageReadParam
- Direct Known Subclasses:
- JPEGImageReadParam,- TIFFImageReadParam
ImageReader.
  An image encoded as part of a file or stream may be thought of
 extending out in multiple dimensions: the spatial dimensions of
 width and height, a number of bands, and a number of progressive
 decoding passes.  This class allows a contiguous (hyper)rectangular
 subarea of the image in all of these dimensions to be selected for
 decoding.  Additionally, the spatial dimensions may be subsampled
 discontinuously.  Finally, color and format conversions may be
 specified by controlling the ColorModel and
 SampleModel of the destination image, either by
 providing a BufferedImage or by using an
 ImageTypeSpecifier.
 
 An ImageReadParam object is used to specify how an
 image, or a set of images, will be converted on input from
 a stream in the context of the Java Image I/O framework.  A plug-in for a
 specific image format will return instances of
 ImageReadParam from the
 getDefaultReadParam method of its
 ImageReader implementation.
 
 The state maintained by an instance of
 ImageReadParam is independent of any particular image
 being decoded.  When actual decoding takes place, the values set in
 the read param are combined with the actual properties of the image
 being decoded from the stream and the destination
 BufferedImage that will receive the decoded pixel
 data.  For example, the source region set using
 setSourceRegion will first be intersected with the
 actual valid source area.  The result will be translated by the
 value returned by getDestinationOffset, and the
 resulting rectangle intersected with the actual valid destination
 area to yield the destination area that will be written.
 
 The parameters specified by an ImageReadParam are
 applied to an image as follows.  First, if a rendering size has
 been set by setSourceRenderSize, the entire decoded
 image is rendered at the size given by
 getSourceRenderSize.  Otherwise, the image has its
 natural size given by ImageReader.getWidth and
 ImageReader.getHeight.
 
 Next, the image is clipped against the source region
 specified by getSourceXOffset, getSourceYOffset,
 getSourceWidth, and getSourceHeight.
 
 The resulting region is then subsampled according to the
 factors given in IIOParam.setSourceSubsampling.  The first pixel,
 the number of pixels per row, and the number of rows all depend
 on the subsampling settings.
 Call the minimum X and Y coordinates of the resulting rectangle
 (minX, minY), its width w
 and its height h.
 
 This rectangle is offset by
 (getDestinationOffset().x,
 getDestinationOffset().y) and clipped against the
 destination bounds.  If no destination image has been set, the
 destination is defined to have a width of
 getDestinationOffset().x + w, and a
 height of getDestinationOffset().y + h so
 that all pixels of the source region may be written to the
 destination.
 
 Pixels that land, after subsampling, within the destination
 image, and that are written in one of the progressive passes
 specified by getSourceMinProgressivePass and
 getSourceNumProgressivePasses are passed along to the
 next step.
 
 Finally, the source samples of each pixel are mapped into
 destination bands according to the algorithm described in the
 comment for setDestinationBands.
 
 Plug-in writers may extend the functionality of
 ImageReadParam by providing a subclass that implements
 additional, plug-in specific interfaces.  It is up to the plug-in
 to document what interfaces are available and how they are to be
 used.  Readers will silently ignore any extended features of an
 ImageReadParam subclass of which they are not aware.
 Also, they may ignore any optional features that they normally
 disable when creating their own ImageReadParam
 instances via getDefaultReadParam.
 
 Note that unless a query method exists for a capability, it must
 be supported by all ImageReader implementations
 (e.g. source render size is optional, but subsampling must be
 supported).
- See Also:
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected booleantrueif thisImageReadParamallows the source rendering dimensions to be set.protected BufferedImageThe current destinationBufferedImage, ornullif none has been set.protected int[]The set of destination bands to be used, as an array ofints.protected intThe minimum index of a progressive pass to read from the source.protected intThe maximum number of progressive passes to read from the source.protected DimensionThe desired rendering width and height of the source, ifcanSetSourceRenderSizeistrue, ornull.Fields declared in class javax.imageio.IIOParamcontroller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, subsamplingYOffset
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionbooleanReturnstrueif this reader allows the source image to be rendered at an arbitrary size as part of the decoding process, by means of thesetSourceRenderSizemethod.Returns theBufferedImagecurrently set by thesetDestinationmethod, ornullif none is set.int[]Returns the set of band indices where data will be placed.intIfgetSourceNumProgressivePassesis equal toInteger.MAX_VALUE, returnsInteger.MAX_VALUE.intReturns the index of the first progressive pass that will be decoded.intReturns the number of the progressive passes that will be decoded.Returns the width and height of the source image as it will be rendered during decoding, if they have been set via thesetSourceRenderSizemethod.voidsetDestination(BufferedImage destination) Supplies aBufferedImageto be used as the destination for decoded pixel data.voidsetDestinationBands(int[] destinationBands) Sets the indices of the destination bands where data will be placed.voidsetSourceProgressivePasses(int minPass, int numPasses) Sets the range of progressive passes that will be decoded.voidsetSourceRenderSize(Dimension size) If the image is able to be rendered at an arbitrary size, sets the source width and height to the supplied values.Methods declared in class javax.imageio.IIOParamactivateController, getController, getDefaultController, getDestinationOffset, getDestinationType, getSourceBands, getSourceRegion, getSourceXSubsampling, getSourceYSubsampling, getSubsamplingXOffset, getSubsamplingYOffset, hasController, setController, setDestinationOffset, setDestinationType, setSourceBands, setSourceRegion, setSourceSubsampling
- 
Field Details- 
canSetSourceRenderSizeprotected boolean canSetSourceRenderSizetrueif thisImageReadParamallows the source rendering dimensions to be set. By default, the value isfalse. Subclasses must set this value manually.ImageReaders that do not support setting of the source render size should set this value tofalse.
- 
sourceRenderSizeThe desired rendering width and height of the source, ifcanSetSourceRenderSizeistrue, ornull.ImageReaders that do not support setting of the source render size may ignore this value.
- 
destinationThe current destinationBufferedImage, ornullif none has been set. By default, the value isnull.
- 
destinationBandsprotected int[] destinationBandsThe set of destination bands to be used, as an array ofints. By default, the value isnull, indicating all destination bands should be written in order.
- 
minProgressivePassprotected int minProgressivePassThe minimum index of a progressive pass to read from the source. By default, the value is set to 0, which indicates that passes starting with the first available pass should be decoded.Subclasses should ensure that this value is non-negative. 
- 
numProgressivePassesprotected int numProgressivePassesThe maximum number of progressive passes to read from the source. By default, the value is set toInteger.MAX_VALUE, which indicates that passes up to and including the last available pass should be decoded.Subclasses should ensure that this value is positive. Additionally, if the value is not Integer.MAX_VALUE, thenminProgressivePass + numProgressivePasses - 1should not exceedInteger.MAX_VALUE.
 
- 
- 
Constructor Details- 
ImageReadParampublic ImageReadParam()Constructs anImageReadParam.
 
- 
- 
Method Details- 
setDestinationSupplies aBufferedImageto be used as the destination for decoded pixel data. The currently set image will be written to by theread,readAll, andreadRastermethods, and a reference to it will be returned by those methods.Pixel data from the aforementioned methods will be written starting at the offset specified by getDestinationOffset.If destinationisnull, a newly-createdBufferedImagewill be returned by those methods.At the time of reading, the image is checked to verify that its ColorModelandSampleModelcorrespond to one of theImageTypeSpecifiers returned from theImageReader'sgetImageTypesmethod. If it does not, the reader will throw anIIOException.- Parameters:
- destination- the BufferedImage to be written to, or- null.
- See Also:
 
- 
getDestinationReturns theBufferedImagecurrently set by thesetDestinationmethod, ornullif none is set.- Returns:
- the BufferedImage to be written to.
- See Also:
 
- 
setDestinationBandspublic void setDestinationBands(int[] destinationBands) Sets the indices of the destination bands where data will be placed. Duplicate indices are not allowed.A nullvalue indicates that all destination bands will be used.Choosing a destination band subset will not affect the number of bands in the output image of a read if no destination image is specified; the created destination image will still have the same number of bands as if this method had never been called. If a different number of bands in the destination image is desired, an image must be supplied using the ImageReadParam.setDestinationmethod.At the time of reading or writing, an IllegalArgumentExceptionwill be thrown by the reader or writer if a value larger than the largest destination band index has been specified, or if the number of source bands and destination bands to be used differ. TheImageReader.checkReadParamBandSettingsmethod may be used to automate this test.- Parameters:
- destinationBands- an array of integer band indices to be used.
- Throws:
- IllegalArgumentException- if- destinationBandscontains a negative or duplicate value.
- See Also:
 
- 
getDestinationBandspublic int[] getDestinationBands()Returns the set of band indices where data will be placed. If no value has been set,nullis returned to indicate that all destination bands will be used.- Returns:
- the indices of the destination bands to be used,
 or null.
- See Also:
 
- 
canSetSourceRenderSizepublic boolean canSetSourceRenderSize()Returnstrueif this reader allows the source image to be rendered at an arbitrary size as part of the decoding process, by means of thesetSourceRenderSizemethod. If this method returnsfalse, calls tosetSourceRenderSizewill throw anUnsupportedOperationException.- Returns:
- trueif setting source rendering size is supported.
- See Also:
 
- 
setSourceRenderSizeIf the image is able to be rendered at an arbitrary size, sets the source width and height to the supplied values. Note that the values returned from thegetWidthandgetHeightmethods onImageReaderare not affected by this method; they will continue to return the default size for the image. Similarly, if the image is also tiled the tile width and height are given in terms of the default size.Typically, the width and height should be chosen such that the ratio of width to height closely approximates the aspect ratio of the image, as returned from ImageReader.getAspectRatio.If this plug-in does not allow the rendering size to be set, an UnsupportedOperationExceptionwill be thrown.To remove the render size setting, pass in a value of nullforsize.- Parameters:
- size- a- Dimensionindicating the desired width and height.
- Throws:
- IllegalArgumentException- if either the width or the height is negative or 0.
- UnsupportedOperationException- if image resizing is not supported by this plug-in.
- See Also:
 
- 
getSourceRenderSizeReturns the width and height of the source image as it will be rendered during decoding, if they have been set via thesetSourceRenderSizemethod. Anullvalue indicates that no setting has been made.- Returns:
- the rendered width and height of the source image
 as a Dimension.
- See Also:
 
- 
setSourceProgressivePassespublic void setSourceProgressivePasses(int minPass, int numPasses) Sets the range of progressive passes that will be decoded. Passes outside of this range will be ignored.A progressive pass is a re-encoding of the entire image, generally at progressively higher effective resolutions, but requiring greater transmission bandwidth. The most common use of progressive encoding is found in the JPEG format, where successive passes include more detailed representations of the high-frequency image content. The actual number of passes to be decoded is determined during decoding, based on the number of actual passes available in the stream. Thus if minPass + numPasses - 1is larger than the index of the last available passes, decoding will end with that pass.A value of numPassesofInteger.MAX_VALUEindicates that all passes fromminPassforward should be read. Otherwise, the index of the last pass (i.e.,minPass + numPasses - 1) must not exceedInteger.MAX_VALUE.There is no unsetSourceProgressivePassesmethod; the same effect may be obtained by callingsetSourceProgressivePasses(0, Integer.MAX_VALUE).- Parameters:
- minPass- the index of the first pass to be decoded.
- numPasses- the maximum number of passes to be decoded.
- Throws:
- IllegalArgumentException- if- minPassis negative,- numPassesis negative or 0, or- numPassesis smaller than- Integer.MAX_VALUEbut- minPass + numPasses - 1is greater than- INTEGER.MAX_VALUE.
- See Also:
 
- 
getSourceMinProgressivePasspublic int getSourceMinProgressivePass()Returns the index of the first progressive pass that will be decoded. If no value has been set, 0 will be returned (which is the correct value).- Returns:
- the index of the first pass that will be decoded.
- See Also:
 
- 
getSourceMaxProgressivePasspublic int getSourceMaxProgressivePass()IfgetSourceNumProgressivePassesis equal toInteger.MAX_VALUE, returnsInteger.MAX_VALUE. Otherwise, returnsgetSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1.- Returns:
- the index of the last pass to be read, or
 Integer.MAX_VALUE.
 
- 
getSourceNumProgressivePassespublic int getSourceNumProgressivePasses()Returns the number of the progressive passes that will be decoded. If no value has been set,Integer.MAX_VALUEwill be returned (which is the correct value).- Returns:
- the number of the passes that will be decoded.
- See Also:
 
 
-