|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.media.jai.OperationDescriptorImpl com.sun.media.jai.operator.ImageReadDescriptor
An OperationDescriptor
describing the "ImageRead" operation.
The "ImageRead" operation uses the
Java
Image I/O Framework to read images from an input source. Which formats
may be read depends on which ImageReader
plug-ins are
registered with the Image I/O Framework when the operation is invoked.
The input source will usually be an
ImageInputStream
, but may be a
File
, RandomAccessFile
,
InputStream
, URL
,
Socket
, ReadableByteChannel
,
file path represented as a String
or some other type
compatible with a reader plug-in. The
ImageIO
class should be used to specify the location
and enable the use of cache files via its setCacheDirectory()
and setUseCache()
methods, respectively. Note that this cache
pertains to image stream caching and is unrelated to the JAI
TileCache
.
The "ImageRead" operation supports rendered,
renderable, and
collection modes and requires no source image.
A RenderingHints
object may be supplied when the operation
is created. In addition to the RenderingHints.Key
hints
recognized by the eventual OpImage
constructor, an
ImageLayout
hint may also be
supplied. The settings of this ImageLayout
override any other
possible derivation of its components. In particular, it is possible that
the generated image(s) have a different tile layout than that present in
the image read from the input source.
Image properties are used to make available metadata and other information. Property provision is mode-specific.
Name | Value |
---|---|
GlobalName | ImageRead |
LocalName | ImageRead |
Vendor | com.sun.media.jai |
Description | Reads an image using the Java Image I/O Framework. |
DocURL | http://java.sun.com/products/java-media/jai/forDevelopers/jai-imageio-1_0-rc-docs/com/sun/media/jai/operator/ImageReadDescriptor.html |
Version | 1.0 |
arg0Desc | The input source. |
arg1Desc | The index or indices of the image(s) to read. |
arg2Desc | Whether metadata should be read if available. |
arg3Desc | Whether thumbnails should be read if available. |
arg4Desc | Whether to verify the validity of the input source. |
arg5Desc | EventListeners to be registered with the ImageReader. |
arg6Desc | The Locale for the ImageReader to use. |
arg7Desc | Java Image I/O read parameter instance. |
arg8Desc | Java Image I/O reader instance. |
RenderedImage
from the specified input source.
Name | Class Type | Default Value |
---|---|---|
Input | java.lang.Object.class | NO_PARAMETER_DEFAULT |
ImageChoice | java.lang.Integer | 0 |
ReadMetadata | java.lang.Boolean | TRUE |
ReadThumbnails | java.lang.Boolean | TRUE |
VerifyInput | java.lang.Boolean | TRUE |
Listeners | java.util.EventListener[] | null |
Locale | java.util.Locale | null |
ReadParam | javax.imageio.ImageReadParam | null |
Reader | javax.imageio.ImageReader | null |
The rendered mode parameters are handled as follows:
The foregoing policy regarding modification of any supplied ImageReadParam or ImageReader is necessary as neither of these classes is cloneable. Given that as a starting point there are in effect three possibilities: (A) do not accept them as parameters, (B) accept them via alternate parameters which do not pose these problems (for example an ImageReaderSpi and a long list of settings represented by the ImageReadParam), or (C) accept them explicitly. Option C has been deemed preferable despite the potential race condition issues.
In the Sun Microsystems implementation of this operation these potential conflicts have been mitigated to a certain extent:
Any fields of the supplied ImageLayout which are not set will be set to default values as follows. The ImageLayout will be cloned before it is modified.
Each value defaults to the corresponding value of the destination which would be derived on the basis of the source image dimensions and the settings of the ImageReadParam, i.e., source region, subsampling offsets and factors, and destination offset.
It should be noted that unlike in the Java Image I/O API itself, negative coordinates are permitted and the image origin is not required to be at (0,0) as for BufferedImages. Therefore it is possible that a given image be loaded using the same ImageReadParam by an ImageReader and by the "ImageRead" operation with different results. Possible differences would be that the portion of the image with negative coordinates is not clipped as it would be with direct Image I/O access, and no empty extent between (0,0) and the start of the data will be present.
For example, if the ImageReadParam had sourceRegion [0,0,w,h], destinationOffset [-w/2,-h/2], and no subsampling, then the Java Image I/O API would compute the effective source and destination regions to be [w/2,h/2,w/2,h/2] and [0,0,w/2,h/2], respectively. The JAI ImageRead operation would compute the effective source and destination regions to be [0,0,w,h] and [-w/2,-h/2,w,h], respectively. The Image I/O result would therefore be equal to the bottom right quadrant of the JAI result.
tileGridXOffset = ImageReader.getTileGridXOffset(imageIndex); tileGridYOffset = ImageReader.getTileGridYOffset(imageIndex); tileWidth = ImageReader.getTileWidth(imageIndex); tileHeight = ImageReader.getTileHeight(imageIndex);
ImageReader.getRawImageType(imageIndex).getColorModel();
ImageReader.getRawImageType(imageIndex).getSampleModel().createCompatibleSampleModel(tileWidth, tileHeight);
Property Name | Type | Comment |
---|---|---|
JAI.ImageReadParam | ImageReadParam | Set to ImageReadParam actually used which may differ from the one passed in. |
JAI.ImageReader | ImageReader | Set to ImageReader actually used. |
JAI.ImageMetadata | IIOMetadata | Set if and only if ReadMetadata parameter is TRUE and image metadata are available. |
JAI.StreamMetadata | IIOMetadata | Set if and only if ReadMetadata parameter is TRUE and stream metadata are available. |
JAI.Thumbnails | BufferedImage[] | Set if and only if ReadThumbnails parameter is TRUE and thumbnails are available. |
If a given property is not set, this implies of course that the names of absent properties will not appear in the array returned by getPropertyNames() and getProperty() invoked to obtain absent properties will return java.awt.Image.UndefinedProperty as usual.
The ImageReader and ImageReadParam may be used for subsequent invocations of the operation (for example to obtain different images in a multi-page file) or for informational purposes. Care should be taken in using these property values with respect to the synchronization issues previously discussed.
In all cases image metadata properties will be set when the node is rendered, i.e., metadata reading is not subject to the same deferred execution as is image data reading. The thumbnail property value will not be set however until its value is actually requested.
RenderableImage
from the specified
input source.
It should be noted that although they are discussed in the context of rendered mode, the parameter synchronization policy and ImageLayout handling methodology apply to renderable mode as well.
Name | Class Type | Default Value |
---|---|---|
ImageChoice | int[] | int[] {0,...,NumImages-1} |
In the Sun Microsystems renderable mode implementation of the "ImageRead" operation, when createRendering() is invoked on the RenderableImage created by the operation, a MultiResolutionRenderableImage is constructed from a Vector of RenderedImages consisting of the images at the specified indices. These images will be sorted into order of decreasing resolution (as determined by the product of width and height for each image) and inserted in this order in the Vector of images used to construct the MultiResolutionRenderableImage. Metadata will be set on the component RenderedImages as usual for rendered mode. Finally the createRendering() invocation will be forwarded to the underlying MultiResolutionRenderableImage and the resulting RenderedImage returned.
Note that using this approach the entire MultiResolutionRenderableImage must be regenerated for each invocation of createRendering(). If multiple renderings are to be created from the RenderableImage without changing the operation parameters, then a more efficient approach would be to use the "JAI.RenderableInput" property to be described.
Property Name | Type | Comment |
---|---|---|
JAI.RenderableInput | RenderableImage | A RenderableImage derived from the input source according to the supplied set of parameters. |
The RenderableImage which is the value of the foregoing property may have set on it any of the properties previously described for rendered mode contingent on parameter settings and data availability. The image metadata and thumbnail properties would be copied from the highest resolution image among those specified by the ImageChoice parameter.
If multiple renderings are to be created from the RenderableImage without changing the operation parameters, then an efficient alternative approach to multiple invocations of createRendering() on the RenderableImage is to obtain the RenderableImage value of the "JAI.RenderableInput" property and invoke createRendering() on this value.
Collection
of RenderedImage
s from the specified
input source. This could be used for example to load an animated GIF
image or a multi-page TIFF image.
It should be noted that although they are discussed in the context of rendered mode, the parameter synchronization policy and ImageLayout handling methodology apply to collection mode as well.
OperationDescriptor
,
ImageReader
,
ImageReadParam
,
IIOMetadata
,
ImageInputStream
,
Serialized FormField Summary | |
static String |
PROPERTY_NAME_IMAGE_READ_PARAM
ImageReadParam property name "JAI.ImageReadParam". |
static String |
PROPERTY_NAME_IMAGE_READER
ImageReader property name "JAI.ImageReader". |
static String |
PROPERTY_NAME_METADATA_IMAGE
Image metadata property name "JAI.ImageMetadata". |
static String |
PROPERTY_NAME_METADATA_STREAM
Stream metadata property name "JAI.StreamMetadata". |
static String |
PROPERTY_NAME_RENDERABLE_INPUT
Renderable input property name "JAI.RenderableInput". |
static String |
PROPERTY_NAME_THUMBNAILS
Thumbnail property name "JAI.Thumbnails". |
Fields inherited from class javax.media.jai.OperationDescriptorImpl |
sourceNames, supportedModes |
Fields inherited from interface javax.media.jai.OperationDescriptor |
NO_PARAMETER_DEFAULT |
Constructor Summary | |
ImageReadDescriptor()
Constructor. |
Method Summary | |
static RenderedOp |
create(ImageInputStream input,
Integer imageChoice,
Boolean readMetadata,
Boolean readThumbnails,
Boolean verifyInput,
EventListener[] listeners,
Locale locale,
ImageReadParam readParam,
ImageReader reader,
RenderingHints hints)
Type-safe convenience method for creating a RenderedOp
representing the "ImageRead" operation in rendered mode. |
static Collection |
createCollection(ImageInputStream input,
int[] imageChoice,
Boolean readMetadata,
Boolean readThumbnails,
Boolean verifyInput,
EventListener[] listeners,
Locale locale,
ImageReadParam readParam,
ImageReader reader,
RenderingHints hints)
Type-safe convenience method for creating a Collection
representing the "ImageRead" operation in collection mode. |
static RenderableOp |
createRenderable(ImageInputStream input,
int[] imageChoice,
Boolean readMetadata,
Boolean readThumbnails,
Boolean verifyInput,
EventListener[] listeners,
Locale locale,
ImageReadParam readParam,
ImageReader reader,
RenderingHints hints)
Type-safe convenience method for creating a RenderableOp
representing the "ImageRead" operation in renderable mode. |
PropertyGenerator[] |
getPropertyGenerators(String modeName)
Returns the array of PropertyGenerator s for the specified
mode of this operation. |
protected boolean |
validateParameters(String modeName,
ParameterBlock args,
StringBuffer msg)
Validates the parameters in the supplied ParameterBlock . |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final String PROPERTY_NAME_IMAGE_READ_PARAM
public static final String PROPERTY_NAME_IMAGE_READER
public static final String PROPERTY_NAME_METADATA_IMAGE
public static final String PROPERTY_NAME_METADATA_STREAM
public static final String PROPERTY_NAME_THUMBNAILS
public static final String PROPERTY_NAME_RENDERABLE_INPUT
Constructor Detail |
public ImageReadDescriptor()
Method Detail |
public static RenderedOp create(ImageInputStream input, Integer imageChoice, Boolean readMetadata, Boolean readThumbnails, Boolean verifyInput, EventListener[] listeners, Locale locale, ImageReadParam readParam, ImageReader reader, RenderingHints hints)
RenderedOp
representing the "ImageRead" operation in rendered mode. The
method packs the parameters into a new ParameterBlock
and invokes JAI.create(String,ParameterBlock,RenderingHints)
.
input
- The input source.imageChoice
- The index of the image to read.readMetadata
- Whether metadata should be read if available.readThumbnails
- Whether thumbnails should be read if available.verifyInput
- Whether to verify the validity of the input source.listeners
- EventListeners to be registered with the ImageReader.locale
- The Locale for the ImageReader to use.readParam
- Java Image I/O read parameter instance.reader
- Java Image I/O reader instance.hints
- Hints possibly including an ImageLayout
.
public static Collection createCollection(ImageInputStream input, int[] imageChoice, Boolean readMetadata, Boolean readThumbnails, Boolean verifyInput, EventListener[] listeners, Locale locale, ImageReadParam readParam, ImageReader reader, RenderingHints hints)
Collection
representing the "ImageRead" operation in collection mode. The
method packs the parameters into a new ParameterBlock
and invokes
JAI.createCollection(String,ParameterBlock, RenderingHints)
.
input
- The input source.imageChoice
- The indices of the images to read.readMetadata
- Whether metadata should be read if available.readThumbnails
- Whether thumbnails should be read if available.verifyInput
- Whether to verify the validity of the input source.listeners
- EventListeners to be registered with the ImageReader.locale
- The Locale for the ImageReader to use.readParam
- Java Image I/O read parameter instance.reader
- Java Image I/O reader instance.hints
- Hints possibly including an ImageLayout
.
public static RenderableOp createRenderable(ImageInputStream input, int[] imageChoice, Boolean readMetadata, Boolean readThumbnails, Boolean verifyInput, EventListener[] listeners, Locale locale, ImageReadParam readParam, ImageReader reader, RenderingHints hints)
RenderableOp
representing the "ImageRead" operation in renderable mode. The
method packs the parameters into a new ParameterBlock
and invokes
JAI.createRenderable(String,ParameterBlock,RenderingHints)
.
input
- The input source.imageChoice
- The indices of the images to read.readMetadata
- Whether metadata should be read if available.readThumbnails
- Whether thumbnails should be read if available.verifyInput
- Whether to verify the validity of the input source.listeners
- EventListeners to be registered with the ImageReader.locale
- The Locale for the ImageReader to use.readParam
- Java Image I/O read parameter instance.reader
- Java Image I/O reader instance.hints
- Hints possibly including an ImageLayout
.
public PropertyGenerator[] getPropertyGenerators(String modeName)
PropertyGenerator
s for the specified
mode of this operation.
For renderable mode returns an array containing a single
PropertyGenerator
which defines a
RenderableImage
-valued property named "JAI.RenderableInput".
For all other modes null
is returned.
modeName
- The name of the mode.
PropertyGenerator
if modeName
is "renderable" (case-insensitive) or
null
otherwise.protected boolean validateParameters(String modeName, ParameterBlock args, StringBuffer msg)
ParameterBlock
.
In addition to the standard validation performed by the corresponding superclass method, this method verifies the following:
TRUE
and Input
is a File
or String
, whether the
corresponding physical file exists and is readable; andTRUE
and Input
is a String
, converting which to a
corresponding physical file failed, whether it can be converted
to an InputStream accessed as a resource from a JAR file; andTRUE
and Input
is a Socket
, whether it is bound, connected, open,
and the read-half is not shut down.msg
and
false
will be returned; otherwise true
will
be returned.
The file existence and readability verification may be suppressed
by setting the VerifyInput parameter to FALSE
.
This might be desirable for example if the operation is being
created for remote rendering and Input is a file which is at
a location visible on the remote peer but not on the host on which
the operation is created.
modeName
- The operation mode.args
- The source and parameters of the operation.msg
- A container for any error messages.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |