Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.media.jai.operator
Class ImageWriteDescriptor

    java.lang.Object
      |
      +--javax.media.jai.OperationDescriptorImpl
            |
            +--com.sun.media.jai.operator.ImageWriteDescriptor

All Implemented Interfaces:
  javax.media.jai.OperationDescriptor, javax.media.jai.RegistryElementDescriptor, Serializable

public class ImageWriteDescriptor
extends javax.media.jai.OperationDescriptorImpl

An `OperationDescriptor` describing the "ImageWrite" operation.

The "ImageWrite" operation uses the Java Image I/O Framework to write images to an output destination. Which formats may be written depends on which `ImageWriter` plug-ins are registered with the Image I/O Framework when the operation is invoked.

The output destination will usually be an `ImageOutputStream`, but may be a `File`, `RandomAccessFile`, `OutputStream`, `Socket`, `WritableByteChannel`, file path represented as a `String` or some other type compatible with a writer 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 "ImageWrite" operation supports rendered, renderable, and collection modes and requires a single source. The operation is "immediate" for all modes as specified by `OperationDescriptor.isImmediate()` so that `isImmediate()` returns `true`. The operation will therefore be rendered when created via either `JAI.create[NS]()` or `JAI.createCollection[NS]()`. A `RenderingHints` object supplied when the operation is created will have no effect except with respect to the mapping of `JAI.KEY_INTERPOLATION` and then only in renderable mode.

Image properties are used to pass metadata and other information to the writer plug-in and to make available metadata as actually written to the output destination. Property handling is mode-specific.

Resource List
Name | Value
--- | ---
GlobalName | ImageWrite
LocalName | ImageWrite
Vendor | com.sun.media.jai
Description | Writes 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/ImageWriteDescriptor.html
Version | 1.0
arg0Desc | The output destination.
arg1Desc | The format name of the output.
arg2Desc | Whether to use image metadata properties as fallbacks.
arg3Desc | Whether to transcode metadata before writing.
arg4Desc | Whether to verify the validity of the output destination.
arg5Desc | Whether to allow pixel replacement in the output image.
arg6Desc | The tile size of the output image.
arg7Desc | Stream metadata to write to the output.
arg8Desc | Image metadata to write to the output.
arg9Desc | Thumbnails to write to the output.
arg10Desc | EventListeners to be registered with the ImageWriter.
arg11Desc | The Locale for the ImageWriter to use.
arg12Desc | Java Image I/O write parameter instance.
arg13Desc | Java Image I/O writer instance.

## Rendered Mode

In rendered mode the "ImageWrite" operation writes a `RenderedImage` to the specified output destination.

### Rendered Mode Parameters

The parameter list of the "ImageWrite" operation in rendered mode is as in the following table.

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 Output is a String it is assumed to represent a file path.

- Format will be used to obtain an ImageWriter if one is not supplied. If this parameter is null and Writer is non-null and has an originating ImageWriterSpi, then the first format name listed by that provider will be used. If Writer is null and Output is a File or a String, an attempt will be made to derive the format name from the suffix of the file path. If this fails, then the format will default to "PNG" as this is the most versatile writer plug-in in the Java 2 core.

- If UseProperties is TRUE, then if stream or image metadata or thumbnails are not provided as parameters, an attempt will be made to derive them from the source image using the respective image properties previously described for the "ImageRead" operation.

- If Transcode is TRUE, then any stream or metadata derived either from operation parameters or source image properties will be converted using the ImageWriter's implementation of ImageTranscoder.

- If VerifyOutput is TRUE, then if the Output is a File or a String it will be verified that a file at the specified location may either be overwritten or created. If Output is a Socket, it will be verified that it is bound, connected, not closed, and its write-half is not shut down. If any of these checks fails, an exception will be thrown when the operation is created. This parameter is ignored for other output types.

- If AllowPixelReplacement is TRUE, and the ImageWriter supports pixel replacement, then a construct will be enabled to allow "live" updating of the output in response to RenderingChangeEvents or "InvalidRegion" events.

- TileSize specifies the desired tile size; it is used as defined by the tiling algorithm. This parameter is ignored if the ImageWriter does not support tiling. Regardless of the capabilities of the writer, an exception will be thrown when the operation is created if this parameter is non-null and either its width or height is not positive.

- If StreamMetadata is non-null, then the parameter will take priority over the corresponding image property as the source of stream metadata to be written.

- If ImageMetadata is non-null, then the parameter will take priority over the corresponding image property as the source of image metadata to be written.

- If Thumbnails is non-null, then the parameter will take priority over the corresponding image property as the source of image thumbnails to be written.

- Listeners will be used to set any progress or warning listeners of the ImageWriter. Each element in the java.util.EventListener array will be added for all types of listener it implements. For example if a listener object implements all of the javax.imageio.event.IIOWrite*Listeners interfaces then it will be added as a listener of each of the three types. Any elements in the array which do not implement any of the IIOWrite*Listeners will be ignored.

- Locale will be used to set the Locale of the ImageWriter. This parameter overrides the equivalent setting of the Writer parameter if the latter is also supplied.

- If WriteParam is null, an ImageWriteParam will be derived internally using ImageWriter.getDefaultWriteParam().

- If Writer is null, an attempt will be made to find an ImageWriter capable of writing the image. If this attempt to obtain an ImageWriter fails, an exception will be thrown.

#### Parameters and Synchronization Policy

Similarly to the case of any ImageReadParam or ImageReader supplied to the "ImageRead" operation, any ImageWriteParam or ImageWriter supplied to the "ImageWrite" operation is subject to modification within the operation classes. A policy similar to the "ImageRead" synchronization policy therefore applies as well for "ImageWrite".

In the Sun Microsystems implementation of this operation these potential conflicts have been mitigated to a certain extent:

- If the param is cloneable then it is cloned and the clone used internally. Otherwise if the param is an instance of ImageWriteParam itself rather than of a subclass thereof, i.e., getClass().getName() invoked on the param returns "javax.imageio.ImageWriteParam", then a new ImageWriteParam is constructed and the settings of the original param copied to it. If the param is not cloneable and is an instance of a proper subclass of ImageWriteParam then it is used directly.

- The only ImageWriter methods invoked after rendering are prepareReplacePixels(int,Rectangle), replacePixels(Raster,ImageWriteParam), and endReplacePixels() and these are invoked within a method synchronized on the ImageWriter object.

### Tiling

The following algorithm is used to determine the tile size of the image written to the output destination:

     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

There is no mechanism to set the tile grid offsets of the output.

### Pixel Replacement

If AllowPixelReplacement is TRUE, the ImageWriter can replace pixels, and the source is a PlanarImage, then the rendering of the operation will respond to RenderingChangeEvents and Shape-valued PropertyChangeEvents named "InvalidRegion". The rendering will be automatically registered as a sink of the rendering of the operation node's source. As the source rendering does not usually generate events, the calling code must also explicitly register the "ImageWrite" rendering as a sink of the source node. By whatever means the event is generated, when the rendering receives such an event, it will determine the indices of all tiles which overlap the invalid region and will replace the pixels of all these tiles in the output.

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;

At this point a reference to imageWriteRendering must be held as long as the data of the source of the operation may change. Then provided the events are correctly propagated to imageWriteRendering, the data in the output file will be automatically updated to match the source data.

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);

The image is written by the first statement and no reference to the rendering need be retained as before.

### Image Properties in Rendered Mode

Image properties are used for metadata, thumbnails, and writer-related information. The following properties may be set on the RenderedOp created for the "ImageWrite" operation in rendered mode:

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.

## Renderable Mode

In renderable mode the "ImageWrite" operation requires a `RenderableImage` source and writes a `RenderedImage` to the specified output destination. As the "immediate" designation specified by `isImmediate()` has no effect in renderable mode, no image will be written without further action by the calling code. To write an image, createRendering(), createScaledRendering(), or createDefaultRendering() must be invoked. Each of these will create a RenderedImage by forwarding the createRendering() or equivalent call to the source image. The resulting RenderedImage will be written to the output according to the rendered mode operation of "ImageWrite". If a mapping of `JAI.KEY_INTERPOLATION` is supplied via a `RenderingHints` passed to the operation, then the interpolation type it specifies will be used to create the rendering if interpolation is required.

### Renderable Mode Parameters

The parameter list of the "ImageRead" operation in renderable mode is identical to the rendered mode parameter list.

### Pixel Replacement in Renderable Mode

Pixel replacement pertains only to RenderedImages generated by rendering the RenderableOp. It may occur if the same conditions apply as described for pixel replacement in rendered mode. Due to the unspecified nature of the underlying rendered sources of any rendering, this is not a recommended procedure.

### Image Properties in Renderable Mode

The RenderableOp node itself does not have any ImageWrite-related properties. Any RenderedImages created by rendering the RenderableOp (thereby writing an image to the output as described), may have rendered mode properties set.

## Collection Mode

In collection mode the "ImageWrite" operation requires a `Collection` source and writes its contents to the specified output destination.

The Collection is treated as a sequence of images which will be extracted from the Collection in the order returned by a new Iterator. Elements in the Collection which are not RenderedImages will be ignored. The derived sequence of images will then be written to the output.

If there is only one RenderedImage in the source Collection, this image will be written as done in rendered mode operation. If there is more than one RenderedImage, the sequence of RenderedImages will be written as an image sequence. In the latter case the ImageWriter must be able to write sequences.

### Collection Mode Parameters

Identical parameter list to rendered mode except:

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

If the value of the AllowPixelReplacement parameter is TRUE, then the rendered Collection will contain RenderedImages which are registered as listeners of their respective sources. Each image in the rendered Collection will however be a rendering as opposed to a RenderedOp. This obviates the need to unhook such a RenderedOp from its source as suggested. Two actions on the part of the application are however necessary in this case: 1) the sequence must be manually ended, and 2) the Collection node must be removed as a sink of its source Collection. The first action is necessary as pixels may be replaced at various times in various images in the sequence and it is not possible to terminate the sequence at rendering time, and there is no reliable mechanism to detect programmatically when this may later be effected. The second action is necessary because a CollectionChangeEvent received by the Collection node would cause the node to be re-rendered, i.e., the collection data to be rewritten using the current state of all parameters. This will in fact also happen when AllowPixelReplacement is FALSE. In effect in both of these cases the behavior in response to a CollectionChangeEvent is unspecified and the result will likely be unexpected.

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);
            }

The image is written by the first statement and no reference to the rendering need be retained.

### Image Properties in Collection Mode

Contingent on parameter settings and the presence of the appropriate metadata, the rendered Collection may have the "JAI.StreamMetadata", "JAI.ImageReadParam", and "JAI.ImageReader" properties set. Each RenderedImage in the Collection may contain rendered mode properties contingent on parameter settings and data availability. Metadata properties may be transcoded.

See Also:
  `OperationDescriptor`, `ImageWriter`, `ImageWriteParam`, `IIOMetadata`, `ImageOutputStream`, Serialized Form

Field Summary
`static String` | `PROPERTY_NAME_IMAGE_WRITE_PARAM` ImageWriteParam property name "JAI.ImageWriteParam".
`static String` | `PROPERTY_NAME_IMAGE_WRITER` ImageWriter property name "JAI.ImageWriter".
`static String` | `PROPERTY_NAME_METADATA_IMAGE` Image metadata property name.
`static String` | `PROPERTY_NAME_METADATA_STREAM` Stream metadata property name.
`static String` | `PROPERTY_NAME_THUMBNAILS` Thumbnail property name.

Fields inherited from class javax.media.jai.OperationDescriptorImpl
`resources, sourceNames, supportedModes`

Fields inherited from interface javax.media.jai.OperationDescriptor
`NO_PARAMETER_DEFAULT`

Constructor Summary
`ImageWriteDescriptor()` Constructor.

Method Summary
`static javax.media.jai.RenderedOp` | `create(RenderedImage source, ImageOutputStream output, String format, Boolean useProperties, Boolean transcode, Boolean verifyOutput, Boolean allowPixelReplacement, Dimension tileSize, IIOMetadata streamMetadata, IIOMetadata imageMetadata, BufferedImage[] thumbnails, EventListener[] listeners, Locale locale, ImageWriteParam writeParam, ImageWriter writer, RenderingHints hints)` Type-safe convenience method for creating a `RenderedOp` representing the "ImageWrite" operation in rendered mode.
`static Collection` | `createCollection(Collection source, ImageOutputStream output, String format, Boolean useProperties, Boolean transcode, Boolean verifyOutput, Boolean allowPixelReplacement, Dimension tileSize, IIOMetadata streamMetadata, IIOMetadata[] imageMetadata, BufferedImage[][] thumbnails, EventListener[] listeners, Locale locale, ImageWriteParam writeParam, ImageWriter writer, RenderingHints hints)` Type-safe convenience method for creating a `Collection` representing the "ImageWrite" operation in collection mode.
`static javax.media.jai.RenderableOp` | `createRenderable(RenderableImage source, ImageOutputStream output, String format, Boolean useProperties, Boolean transcode, Boolean verifyOutput, Boolean allowPixelReplacement, Dimension tileSize, IIOMetadata streamMetadata, IIOMetadata imageMetadata, BufferedImage[] thumbnails, EventListener[] listeners, Locale locale, ImageWriteParam writeParam, ImageWriter writer, RenderingHints hints)` Type-safe convenience method for creating a `RenderableOp` representing the "ImageWrite" operation in renderable mode.
`boolean` | `isImmediate()` Returns true indicating that the operation should be rendered immediately during a call to `JAI.create[]()` or `JAI.createCollection[NS]()`.
`protected boolean` | `validateParameters(String modeName, ParameterBlock args, StringBuffer msg)` Validates the parameters in the supplied `ParameterBlock`.

Methods inherited from class javax.media.jai.OperationDescriptorImpl
`arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamMaxValue, getParamMinValue, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isModeSupported, isRenderableSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### PROPERTY_NAME_IMAGE_WRITE_PARAM

    public static final String PROPERTY_NAME_IMAGE_WRITE_PARAM

  ImageWriteParam property name "JAI.ImageWriteParam".

  See Also:
    Constant Field Values

### PROPERTY_NAME_IMAGE_WRITER

    public static final String PROPERTY_NAME_IMAGE_WRITER

  ImageWriter property name "JAI.ImageWriter".

  See Also:
    Constant Field Values

### PROPERTY_NAME_METADATA_IMAGE

    public static final String PROPERTY_NAME_METADATA_IMAGE

  Image metadata property name. Set to same value as `ImageReadDescriptor.PROPERTY_NAME_METADATA_IMAGE`.

  See Also:
    Constant Field Values

### PROPERTY_NAME_METADATA_STREAM

    public static final String PROPERTY_NAME_METADATA_STREAM

  Stream metadata property name. Set to same value as `ImageReadDescriptor.PROPERTY_NAME_METADATA_STREAM`.

  See Also:
    Constant Field Values

### PROPERTY_NAME_THUMBNAILS

    public static final String PROPERTY_NAME_THUMBNAILS

  Thumbnail property name. Set to same value as `ImageReadDescriptor.PROPERTY_NAME_THUMBNAILS`.

  See Also:
    Constant Field Values

Constructor Detail

### ImageWriteDescriptor

    public ImageWriteDescriptor()

  Constructor.

Method Detail

### create

    public static javax.media.jai.RenderedOp create(RenderedImage source,
                                                    ImageOutputStream output,
                                                    String format,
                                                    Boolean useProperties,
                                                    Boolean transcode,
                                                    Boolean verifyOutput,
                                                    Boolean allowPixelReplacement,
                                                    Dimension tileSize,
                                                    IIOMetadata streamMetadata,
                                                    IIOMetadata imageMetadata,
                                                    BufferedImage[] thumbnails,
                                                    EventListener[] listeners,
                                                    Locale locale,
                                                    ImageWriteParam writeParam,
                                                    ImageWriter writer,
                                                    RenderingHints hints)

  Type-safe convenience method for creating a `RenderedOp` representing the "ImageWrite" operation in rendered mode. The method packs the source and parameters into a new `ParameterBlock` and invokes `JAI.create(String,ParameterBlock,RenderingHints)`.

  Parameters:
    `source` - The image to be written.
    `output` - The output destination.
    `format` - The format name of the output.
    `useProperties` - Whether to use image metadata properties as fallbacks.
    `transcode` - Whether to transcode metadata before writing.
    `verifyOutput` - Whether to verify the validity of the output destination.
    `allowPixelReplacement` - Whether to allow pixel replacement in the output image.
    `tileSize` - The tile size of the output image.
    `streamMetadata` - Stream metadata to write to the output.
    `imageMetadata` - Image metadata to write to the output.
    `thumbnails` - Thumbnails to write to the output.
    `listeners` - EventListeners to be registered with the ImageWriter.
    `locale` - The Locale for the ImageWriter to use.
    `writeParam` - Java Image I/O write parameter instance.
    `writer` - Java Image I/O writer instance.
    `hints` - Operation hints.
  Returns:
    a reference to the operation source.

### createCollection

    public static Collection createCollection(Collection source,
                                              ImageOutputStream output,
                                              String format,
                                              Boolean useProperties,
                                              Boolean transcode,
                                              Boolean verifyOutput,
                                              Boolean allowPixelReplacement,
                                              Dimension tileSize,
                                              IIOMetadata streamMetadata,
                                              IIOMetadata[] imageMetadata,
                                              BufferedImage[][] thumbnails,
                                              EventListener[] listeners,
                                              Locale locale,
                                              ImageWriteParam writeParam,
                                              ImageWriter writer,
                                              RenderingHints hints)

  Type-safe convenience method for creating a `Collection` representing the "ImageWrite" operation in collection mode. The method packs the source and parameters into a new `ParameterBlock` and invokes `JAI.createCollection(String,ParameterBlock,RenderingHints)`.

  Parameters:
    `source` - The collection to be written.
    `output` - The output destination.
    `format` - The format name of the output.
    `useProperties` - Whether to use image metadata properties as fallbacks.
    `transcode` - Whether to transcode metadata before writing.
    `verifyOutput` - Whether to verify the validity of the output destination.
    `allowPixelReplacement` - Whether to allow pixel replacement in the output image.
    `tileSize` - The tile size of the output image.
    `streamMetadata` - Stream metadata to write to the output.
    `imageMetadata` - Image metadata to write to the output.
    `thumbnails` - Thumbnails to write to the output.
    `listeners` - EventListeners to be registered with the ImageWriter.
    `locale` - The Locale for the ImageWriter to use.
    `writeParam` - Java Image I/O write parameter instance.
    `writer` - Java Image I/O writer instance.
    `hints` - Operation hints.
  Returns:
    a reference to the operation source.

### createRenderable

    public static javax.media.jai.RenderableOp createRenderable(RenderableImage source,
                                                                ImageOutputStream output,
                                                                String format,
                                                                Boolean useProperties,
                                                                Boolean transcode,
                                                                Boolean verifyOutput,
                                                                Boolean allowPixelReplacement,
                                                                Dimension tileSize,
                                                                IIOMetadata streamMetadata,
                                                                IIOMetadata imageMetadata,
                                                                BufferedImage[] thumbnails,
                                                                EventListener[] listeners,
                                                                Locale locale,
                                                                ImageWriteParam writeParam,
                                                                ImageWriter writer,
                                                                RenderingHints hints)

  Type-safe convenience method for creating a `RenderableOp` representing the "ImageWrite" operation in renderable mode. The method packs the source and parameters into a new `ParameterBlock` and invokes `JAI.createRenderable(String,ParameterBlock,RenderingHints)`.

  Parameters:
    `source` - The renderable source to be written.
    `output` - The output destination.
    `format` - The format name of the output.
    `useProperties` - Whether to use image metadata properties as fallbacks.
    `transcode` - Whether to transcode metadata before writing.
    `verifyOutput` - Whether to verify the validity of the output destination.
    `allowPixelReplacement` - Whether to allow pixel replacement in the output image.
    `tileSize` - The tile size of the output image.
    `streamMetadata` - Stream metadata to write to the output.
    `imageMetadata` - Image metadata to write to the output.
    `thumbnails` - Thumbnails to write to the output.
    `listeners` - EventListeners to be registered with the ImageWriter.
    `locale` - The Locale for the ImageWriter to use.
    `writeParam` - Java Image I/O write parameter instance.
    `writer` - Java Image I/O writer instance.
    `hints` - Operation hints.
  Returns:
    a reference to the operation source.

### isImmediate

    public boolean isImmediate()

  Returns true indicating that the operation should be rendered immediately during a call to `JAI.create[]()` or `JAI.createCollection[NS]()`.

  Specified by:
    `isImmediate` in interface `javax.media.jai.OperationDescriptor`
  Overrides:
    `isImmediate` in class `javax.media.jai.OperationDescriptorImpl`
  See Also:
    `OperationDescriptor`

### validateParameters

    protected boolean validateParameters(String modeName,
                                         ParameterBlock args,
                                         StringBuffer msg)

  Validates the parameters in the supplied `ParameterBlock`.

  In addition to the standard validation performed by the corresponding superclass method, this method verifies the following:

  - if VerifyOutput is `TRUE` and Output is a `File` or `String`, whether the corresponding physical file is writable, i.e., exists and may be overwritten or does not exist and may be created; and
  - if VerifyOutput is `TRUE` and Output is a `Socket`, whether it is bound, connected, open, and the write-half is not shut down; and
  - if in collection mode (`modeName` equals `CollectionRegistryMode.MODE_NAME`), the source is not a `CollectionOp`, and the size of the source `Collection` is greater than unity, whether the `ImageWriter` cannot write sequences.
  If the superclass method finds that the arguments are invalid, or if this method determines that any of the foregoing conditions is true, an error message will be appended to `msg` and `false` will be returned; otherwise `true` will be returned.

  Overrides:
    `validateParameters` in class `javax.media.jai.OperationDescriptorImpl`
  Parameters:
    `modeName` - The operation mode.
    `args` - The source and parameters of the operation.
    `msg` - A container for any error messages.
  Returns:
    Whether the supplied parameters are valid.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD