Java Doc for ImageWriteDescriptor.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » com » sun » media » jai » operator » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Rendered Mode Parameter List

Name	Class Type	Default Value
Output	java.lang.Object.class	NO_PARAMETER_DEFAULT
Format	java.lang.String	null
UseProperties	java.lang.Boolean	TRUE
Transcode	java.lang.Boolean	TRUE
VerifyOutput	java.lang.Boolean	TRUE
AllowPixelReplacement	java.lang.Boolean	FALSE
TileSize	java.awt.Dimension	null
StreamMetadata	javax.imageio.metadata.IIOMetadata	null
ImageMetadata	javax.imageio.metadata.IIOMetadata	null
Thumbnails	java.awt.BufferedImage[]	null
Listeners	java.util.EventListener[]	null
Locale	java.util.Locale	null
WriteParam	javax.imageio.ImageWriteParam	null
Writer	javax.imageio.ImageWriter	null

The rendered mode parameters are handled as follows:

 if ImageWriter cannot write tiles
 output is untiled
 else
 if TileSize parameter is non-null
 set tile size to TileSize
 else
 if WriteParam is null
 set tile size to source tile size
 else
 if tilingMode is ImageWriteParam.MODE_EXPLICIT
 if tile dimension is set in WriteParam
 set tile size to tile dimension from WriteParam
 else
 if preferred tile dimension is set in WriteParam
 set tile size to average of first two preferred dimensions
 else
 set tile size to source tile size
 else // tilingMode is not ImageWriteParam.MODE_EXPLICIT
 the plug-in decides the tile size
 

Note that this behavior differs from what would happen if the RenderedOp created by the operation received a RenderingChangeEvent: in this case a new rendering of the node would be created using the ParameterBlock and RenderingHints currently in effect. This would cause the entire image to be rewritten at the current position of the output. This will also happen when AllowPixelReplacement is FALSE. In effect in both of these cases the behavior in response to a RenderingChangeEvent is unspecified and the result will likely be unexpected.

To avoid any inadvertent overwriting of the destination as a result of events received by the RenderedOp, the following usage is recommended when the objective is automatic pixel replacement:

 // Sources, parameters, and hints.
 ParameterBlock args;
 RenderingHints hints;
 // Create the OperationNode.
 RenderedOp imageWriteNode = JAI.create("ImageWrite", args, hints);
 // Get the rendering which already exists due to "immediate" status.
 RenderedImage imageWriteRendering = imageWriteNode.getRendering();
 // Unhook the OperationNode as a sink of its source OperationNode.
 imageWriteNode.getSourceImage(0).removeSink(imageWriteNode);
 // Add the rendering as a sink of the source OperationNode.
 imageWriteNode.getSourceImage(0).addSink(imageWriteRendering);
 // Free the OperationNode for garbage collection.
 imageWriteNode = null;
 

If pixel replacement is not the objective and inadvertent overwriting is to be avoided then the safest approach would be the following:

 // Create the OperationNode.
 RenderedOp imageWriteNode = JAI.create("ImageWrite", args, hints);
 // Unhook the OperationNode as a sink of its source
 imageWriteNode.getSourceImage(0).removeSink(imageWriteNode);
 

Rendered Mode Image Properties

Property Name	Type	Comment
JAI.ImageWriteParam	ImageWriteParam	Set to ImageWriteParam actually used which may differ from the one passed in.
JAI.ImageWriter	ImageWriter	Set to ImageWriter actually used.
JAI.ImageMetadata	IIOMetadata	Set if and only if image metadata are available; may be transcoded.
JAI.StreamMetadata	IIOMetadata	Set if and only if stream metadata are available; may be transcoded.
JAI.Thumbnails	BufferedImage[]	Set if and only thumbnails are provided and the writer supportes writing them.

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 ImageWriter and ImageWriteParam may be used for subsequent invocations of the operation or for informational purposes. Care should be taken in using these property values with respect to the synchronization issues previously discussed.

Metadata properties will be set to those actually written to the output. They may be derived either from input parameters or source properties depending on the values of the StreamMetadata, ImageMetadata, and UseProperties parameters. They will be transcoded data if Transcode is TRUE and the ImageWriter supports transcoding.

All properties will be set when the node is rendered.

Collection Mode Parameter Differences

Name	Class Type	Default Value
ImageMetadata	javax.imageio.metadataIIOMetadata[]	null
Thumbnails	java.awt.image.BufferedImage[][]	null

• If the source is not a CollectionOp then the number of RenderedImages in the source is counted. If it is not at least one then an exception is thrown when the operation is created. If it is greater than one, then the ImageWriter is checked to determine whether it can write sequences. If it cannot then an exception is thrown when the operation is created.
• The first index of the thumbnails array corresponds to the ordinal position of the image in the collection and the second index to the thumbnails of that image.

The change to the ImageMetadata and Thumbnails parameters is that there can now be a distinct image metadata object and thumbnail array for each image in the Collection. The components of these respective arrays will be indexed using the sequence of RenderedImages extracted from the source Collection by the Iterator. It is the responsibility of the caller to ensure that this sequencing is correct. In this context it is advisable to use a source Collection which maintains the order of its elements such as a List.

Pixel Replacement in Collection Mode

To ensure proper termination of the image sequence and avoid any inadvertent overwriting of the destination as a result of events received by the CollectionOp, the following usage is recommended when the objective is automatic pixel replacement:

 // Sources, parameters, and hints.
 ParameterBlock args;
 RenderingHints hints;
 // Create the Collection.
 CollectionImage imageWriteCollection =
 (CollectionImage)JAI.createCollection("ImageWrite", args, hints);
 // Unhook the Collection node from the source to avoid
 // re-renderings caused by CollectionChangeEvents.
 if(args.getSource(0) instanceof CollectionImage) {
 CollectionImage sourceCollection =
 (CollectionImage)args.getSource(0);
 sourceCollection.removeSink(imageWriteCollection);
 }
 // !!! Pixel replacement activity happens here ... !!!
 // Get the ImageWriter.
 ImageWriter writer =
 (ImageWriter)imageWriteCollection.getProperty("JAI.ImageWriter");
 // End the sequence if necessary.
 if(writer.canWriteSequence()) {
 writer.endWriteSequence();
 }
 

Using the foregoing construct, all pixels in all images written to the output sequence will remain current with the in-memory data of their respective source provided all events are propagated as expected. Note that it is not necessary to end the sequence manually if pixel replacement is not allowed or is not supported. Also the sequence must be manually ended if and only if the writer is capable of writing sequences. This permits pixel replacement to work in the case where the source collection contains only a single image and the writer supports pixel replacement but cannot write sequences.

If pixel replacement is not the objective, i.e., AllowPixelReplacement is FALSE, and inadvertent overwriting is to be avoided then the safest approach would be the following:

 // Create the Collection.
 Collection imageWriteCollection =
 JAI.create("ImageWrite", args, hints);
 // Unhook the Collection node from the source to avoid
 // re-renderings caused by CollectionChangeEvents.
 if(args.getSource(0) instanceof CollectionImage) {
 CollectionImage sourceCollection =
 (CollectionImage)args.getSource(0);
 sourceCollection.removeSink(imageWriteCollection);
 }
 

Image Properties in Collection Mode