javax.imageio

Class ImageWriter

java.lang.Object

javax.imageio.ImageWriter

All Implemented Interfaces:

ImageTranscoder

public abstract class ImageWriter
extends java.lang.Object
implements ImageTranscoder

A class for encoding images within the ImageIO framework. An ImageWriter for a given format is instantiated by an ImageWriterSpi for that format. ImageWriterSpis are registered with the IIORegistry. The ImageWriter API supports writing animated images that may have multiple frames; to support such images many methods take an index parameter. Images may also be written in multiple passes, where each successive pass increases the level of detail in the destination image.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Locale[]	availableLocales All locales available for localization of warning messages, or null if localization is not supported.
protected java.util.Locale	locale The current locale used to localize warning messages, or null if no locale has been set.
protected javax.imageio.spi.ImageWriterSpi	originatingProvider The image writer SPI that instantiated this writer.
protected java.lang.Object	output An ImageInputStream to which image data is written.
protected java.util.List<javax.imageio.event.IIOWriteProgressListener>	progressListeners A list of installed progress listeners.
protected java.util.List<javax.imageio.event.IIOWriteWarningListener>	warningListeners A list of installed warning listeners.
protected java.util.List<java.util.Locale>	warningLocales A list of warning locales corresponding with the list of installed warning listeners.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ImageWriter(javax.imageio.spi.ImageWriterSpi originatingProvider) Construct an image writer.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() Request that writing be aborted.
protected boolean	abortRequested() Check if the abort flag is set.
void	addIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener listener) Install a write progress listener.
void	addIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener listener) Install a write warning listener.
boolean	canInsertEmpty(int imageIndex) Check whether a new empty image can be inserted at the given frame index.
boolean	canInsertImage(int imageIndex) Check whether an image can be inserted at the given frame index.
boolean	canRemoveImage(int imageIndex) Check whether an image can be removed from the given frame index.
boolean	canReplaceImageMetadata(int imageIndex) Check whether the metadata associated the image at the given frame index can be replaced.
boolean	canReplacePixels(int imageIndex) Check whether the pixels within the image at the given index can be replaced.
boolean	canReplaceStreamMetadata() Check whether the metadata associated the entire image stream can be replaced.
boolean	canWriteEmpty() Check whether an entire empty image, including empty metadata and empty thumbnails, can be written to the output stream, leaving pixel values to be filled in later using the replacePixels methods.
boolean	canWriteRasters() Check if IIOImages containing raster data are supported.
boolean	canWriteSequence() Check if an image can be appended at the end of the current list of images even if prior images have already been written.
protected void	clearAbortRequest() Clear the abort flag.
abstract javax.imageio.metadata.IIOMetadata	convertImageMetadata(javax.imageio.metadata.IIOMetadata inData, ImageTypeSpecifier imageType, ImageWriteParam param) Convert IIOMetadata from an input reader format, returning an IIOMetadata suitable for use by an image writer.
abstract javax.imageio.metadata.IIOMetadata	convertStreamMetadata(javax.imageio.metadata.IIOMetadata inData, ImageWriteParam param) Convert IIOMetadata from an input stream format, returning an IIOMetadata suitable for use by an image writer.
void	dispose() Releases any resources allocated to this object.
void	endInsertEmpty() Complete inserting an empty image in the output stream.
void	endReplacePixels() Complete replacing pixels in an image in the output stream.
void	endWriteEmpty() Complete writing an empty image to the image output stream.
void	endWriteSequence() Complete writing a sequence of images to the output stream.
java.util.Locale[]	getAvailableLocales() Retrieve the available locales.
abstract javax.imageio.metadata.IIOMetadata	getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param) Get a metadata object appropriate for encoding an image specified by the given image type specifier and optional image write parameters.
abstract javax.imageio.metadata.IIOMetadata	getDefaultStreamMetadata(ImageWriteParam param) Get a metadata object appropriate for encoding the default image type handled by this writer, optionally considering image write parameters.
ImageWriteParam	getDefaultWriteParam() Retrieve the default write parameters for this writer's image format.
java.util.Locale	getLocale() Get this writer's locale.
int	getNumThumbnailsSupported(ImageTypeSpecifier imageType, ImageWriteParam param, javax.imageio.metadata.IIOMetadata streamMetadata, javax.imageio.metadata.IIOMetadata imageMetadata) Get the number of thumbnails supported by this image writer, based on the given image type, image writing parameters, and stream and image metadata.
javax.imageio.spi.ImageWriterSpi	getOriginatingProvider() Get the ImageWriterSpi that created this writer or null.
java.lang.Object	getOutput() Get this reader's image output destination.
java.awt.Dimension[]	getPreferredThumbnailSizes(ImageTypeSpecifier imageType, ImageWriteParam param, javax.imageio.metadata.IIOMetadata streamMetadata, javax.imageio.metadata.IIOMetadata imageMetadata) Get the preferred sizes for thumbnails based on the given image type, image writing parameters, and stream and image metadata.
void	prepareInsertEmpty(int imageIndex, ImageTypeSpecifier imageType, int width, int height, javax.imageio.metadata.IIOMetadata imageMetadata, java.util.List<? extends java.awt.image.BufferedImage> thumbnails, ImageWriteParam param) Start inserting an empty image in the image output stream.
void	prepareReplacePixels(int imageIndex, java.awt.Rectangle region) Start the replacement of pixels within an image in the output stream.
void	prepareWriteEmpty(javax.imageio.metadata.IIOMetadata streamMetadata, ImageTypeSpecifier imageType, int width, int height, javax.imageio.metadata.IIOMetadata imageMetadata, java.util.List<? extends java.awt.image.BufferedImage> thumbnails, ImageWriteParam param) Start writing an empty image to the end of the image output stream.
void	prepareWriteSequence(javax.imageio.metadata.IIOMetadata streamMetadata) Start the writing of a sequence of images.
protected void	processImageComplete() Notifies all installed write progress listeners that image loading has completed by calling their imageComplete methods.
protected void	processImageProgress(float percentageDone) Notifies all installed write progress listeners that a certain percentage of the image has been loaded, by calling their imageProgress methods.
protected void	processImageStarted(int imageIndex) Notifies all installed write progress listeners, by calling their imageStarted methods, that image loading has started on the given image.
protected void	processThumbnailComplete() Notifies all installed write progress listeners, by calling their thumbnailComplete methods, that a thumbnail has completed loading.
protected void	processThumbnailProgress(float percentageDone) Notifies all installed write progress listeners that a certain percentage of a thumbnail has been loaded, by calling their thumbnailProgress methods.
protected void	processThumbnailStarted(int imageIndex, int thumbnailIndex) Notifies all installed write progress listeners, by calling their imageStarted methods, that thumbnail loading has started on the given thumbnail of the given image.
protected void	processWarningOccurred(int imageIndex, java.lang.String warning) Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
protected void	processWarningOccurred(int imageIndex, java.lang.String baseName, java.lang.String keyword) Notify all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
protected void	processWriteAborted() Notifies all installed write progress listeners that image loading has been aborted by calling their writeAborted methods.
void	removeAllIIOWriteProgressListeners() Uninstall all write progress listeners.
void	removeAllIIOWriteWarningListeners() Uninstall all write warning listeners.
void	removeIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener listener) Uninstall the given write progress listener.
void	removeIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener listener) Uninstall the given write warning listener.
void	removeImage(int imageIndex) Remove the image at the specified index from the output stream.
void	replaceImageMetadata(int imageIndex, javax.imageio.metadata.IIOMetadata imageMetadata) Replace the metadata associated with the image at the given index.
void	replacePixels(java.awt.image.Raster raster, ImageWriteParam param) Replace a region of an image in the output stream with a portion of the given raster data.
void	replacePixels(java.awt.image.RenderedImage image, ImageWriteParam param) Replace a region of an image in the output stream with a portion of the given rendered image.
void	replaceStreamMetadata(javax.imageio.metadata.IIOMetadata streamMetadata) Replace the metadata associated with this image stream.
void	reset() Reset this writer's internal state.
void	setLocale(java.util.Locale locale) Set the current locale or use the default locale.
void	setOutput(java.lang.Object output) Set the output destination of the given object.
void	write(IIOImage image) Write a image data, metadata and thumbnails to the output stream.
abstract void	write(javax.imageio.metadata.IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param) Write an image stream, including thumbnails and metadata to the output stream.
void	write(java.awt.image.RenderedImage image) Write a rendered image to the output stream.
void	writeInsert(int imageIndex, IIOImage image, ImageWriteParam param) Insert an image into the output stream.
void	writeToSequence(IIOImage image, ImageWriteParam param) Write a sequence of images, including thumbnails and metadata, to the output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

availableLocales

protected java.util.Locale[] availableLocales

All locales available for localization of warning messages, or null if localization is not supported.

locale

protected java.util.Locale locale

The current locale used to localize warning messages, or null if no locale has been set.

originatingProvider

protected javax.imageio.spi.ImageWriterSpi originatingProvider

The image writer SPI that instantiated this writer.

output

protected java.lang.Object output

An ImageInputStream to which image data is written.

progressListeners

protected java.util.List<javax.imageio.event.IIOWriteProgressListener> progressListeners

A list of installed progress listeners. Initially null, meaning no installed listeners.

warningListeners

protected java.util.List<javax.imageio.event.IIOWriteWarningListener> warningListeners

A list of installed warning listeners. Initially null, meaning no installed listeners.

warningLocales

protected java.util.List<java.util.Locale> warningLocales

A list of warning locales corresponding with the list of installed warning listeners. Initially null, meaning no locales.

Constructor Detail

ImageWriter

protected ImageWriter(javax.imageio.spi.ImageWriterSpi originatingProvider)

Construct an image writer.

Parameters:

originatingProvider - the provider that is constructing this image writer, or null

Method Detail

abort

public void abort()

Request that writing be aborted. The unwritten portions of the destination image will be undefined. Writers should clear the abort flag before starting a write operation, then poll it periodically during the write operation.

abortRequested

protected boolean abortRequested()

Check if the abort flag is set.

Returns:

true if the current write operation should be aborted, false otherwise

addIIOWriteProgressListener

public void addIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener listener)

Install a write progress listener. This method will return immediately if listener is null.

Parameters:

listener - a write progress listener or null

addIIOWriteWarningListener

public void addIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener listener)

Install a write warning listener. This method will return immediately if listener is null. Warning messages sent to this listener will be localized using the current locale. If the current locale is null then this writer will select a sensible default.

Parameters:

listener - a write warning listener

canInsertEmpty

public boolean canInsertEmpty(int imageIndex)
                       throws java.io.IOException

Check whether a new empty image can be inserted at the given frame index. Pixel values may be filled in later using the replacePixels methods. Indices greater than the insertion index will be incremented. If imageIndex is -1, the image will be appended at the end of the current image list.

Parameters:

imageIndex - the frame index

Returns:

true if an empty image can be inserted at imageIndex, false otherwise

Throws:

java.lang.IllegalStateException - if output is null

java.lang.IndexOutOfBoundsException - if imageIndex is less than -1 or greater than the last index in the current image list

java.io.IOException - if a write error occurs

canInsertImage

public boolean canInsertImage(int imageIndex)
                       throws java.io.IOException

Check whether an image can be inserted at the given frame index. Indices greater than the insertion index will be incremented. If imageIndex is -1, the image will be appended at the end of the current image list.

Parameters:

imageIndex - the frame index

Returns:

true if an image can be inserted at imageIndex, false otherwise

Throws:

java.lang.IllegalStateException - if output is null

java.lang.IndexOutOfBoundsException - if imageIndex is less than -1 or greater than the last index in the current image list

java.io.IOException - if a write error occurs

canRemoveImage

public boolean canRemoveImage(int imageIndex)
                       throws java.io.IOException

Check whether an image can be removed from the given frame index. Indices greater than the removal index will be decremented.

Parameters:

imageIndex - the frame index

Returns:

true if an image can be removed from imageIndex, false otherwise

Throws:

java.lang.IllegalStateException - if output is null

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the last index in the current image list

java.io.IOException - if a write error occurs

canReplaceImageMetadata

public boolean canReplaceImageMetadata(int imageIndex)
                                throws java.io.IOException

Check whether the metadata associated the image at the given frame index can be replaced.

Parameters:

imageIndex - the frame index

Returns:

true if the metadata associated with the image at imageIndex can be replaced, false otherwise

Throws:

java.lang.IllegalStateException - if output is null

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the last index in the current image list

java.io.IOException - if a write error occurs

canReplacePixels

public boolean canReplacePixels(int imageIndex)
                         throws java.io.IOException

Check whether the pixels within the image at the given index can be replaced.

Parameters:

imageIndex - the frame index

Returns:

true if the pixels in the image at imageIndex can be replaced, false otherwise

Throws:

java.lang.IllegalStateException - if output is null

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the last index in the current image list

java.io.IOException - if a write error occurs

canReplaceStreamMetadata

public boolean canReplaceStreamMetadata()
                                 throws java.io.IOException

Check whether the metadata associated the entire image stream can be replaced.

Returns:

true if the stream metadata can be replaced, false otherwise

Throws:

java.lang.IllegalStateException - if output is null

java.io.IOException - if a write error occurs

canWriteEmpty

public boolean canWriteEmpty()
                      throws java.io.IOException

Check whether an entire empty image, including empty metadata and empty thumbnails, can be written to the output stream, leaving pixel values to be filled in later using the replacePixels methods.

Returns:

true if an entire empty image can be written before its contents are filled in, false otherwise

Throws:

java.lang.IllegalStateException - if output is null

java.io.IOException - if a write error occurs

canWriteRasters

public boolean canWriteRasters()

Check if IIOImages containing raster data are supported.

Returns:

true if raster IIOImages are supported, false otherwise

canWriteSequence

public boolean canWriteSequence()

Check if an image can be appended at the end of the current list of images even if prior images have already been written.

Returns:

true if sequences of images can be written, false otherwise

clearAbortRequest

protected void clearAbortRequest()

Clear the abort flag.

convertImageMetadata

public abstract javax.imageio.metadata.IIOMetadata convertImageMetadata(javax.imageio.metadata.IIOMetadata inData,
                                                      ImageTypeSpecifier imageType,
                                                      ImageWriteParam param)

Convert IIOMetadata from an input reader format, returning an IIOMetadata suitable for use by an image writer. The ImageTypeSpecifier specifies the destination image type. An optional ImageWriteParam argument is available in case the image writing parameters affect the metadata conversion.

Specified by:

convertImageMetadata in interface ImageTranscoder

Parameters:

inData - the metadata coming from an image reader

imageType - the output image type of the writer

param - the image writing parameters or null

Returns:

the converted metadata that should be used by the image writer, or null if this ImageTranscoder has no knowledge of the input metadata

Throws:

java.lang.IllegalArgumentException - if either inData or imageType is null

convertStreamMetadata

public abstract javax.imageio.metadata.IIOMetadata convertStreamMetadata(javax.imageio.metadata.IIOMetadata inData,
                                                       ImageWriteParam param)

Convert IIOMetadata from an input stream format, returning an IIOMetadata suitable for use by an image writer. An optional ImageWriteParam argument is available in case the image writing parameters affect the metadata conversion.

Specified by:

convertStreamMetadata in interface ImageTranscoder

Parameters:

inData - the metadata coming from an input image stream

param - the image writing parameters or null

Returns:

the converted metadata that should be used by the image writer, or null if this ImageTranscoder has no knowledge of the input metadata

Throws:

java.lang.IllegalArgumentException - if inData is null

dispose

public void dispose()

Releases any resources allocated to this object. Subsequent calls to methods on this object will produce undefined results. The default implementation does nothing; subclasses should use this method ensure that native resources are released.

getAvailableLocales

public java.util.Locale[] getAvailableLocales()

Retrieve the available locales. Return null if no locales are available or a clone of availableLocales.

Returns:

an array of locales or null

getDefaultImageMetadata

public abstract javax.imageio.metadata.IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType,
                                                         ImageWriteParam param)

Get a metadata object appropriate for encoding an image specified by the given image type specifier and optional image write parameters.

Parameters:

imageType - an image type specifier

param - image writing parameters, or null

Returns:

a metadata object appropriate for encoding an image of the given type with the given parameters

getDefaultStreamMetadata

public abstract javax.imageio.metadata.IIOMetadata getDefaultStreamMetadata(ImageWriteParam param)

Get a metadata object appropriate for encoding the default image type handled by this writer, optionally considering image write parameters.

Parameters:

param - image writing parameters, or null

Returns:

a metadata object appropriate for encoding an image of the default type with the given parameters

getDefaultWriteParam

public ImageWriteParam getDefaultWriteParam()

Retrieve the default write parameters for this writer's image format. The default implementation returns new ImageWriteParam().

Returns:

image writing parameters

getLocale

public java.util.Locale getLocale()

Get this writer's locale. null is returned if the locale has not been set.

Returns:

this writer's locale, or null

getNumThumbnailsSupported

public int getNumThumbnailsSupported(ImageTypeSpecifier imageType,
                            ImageWriteParam param,
                            javax.imageio.metadata.IIOMetadata streamMetadata,
                            javax.imageio.metadata.IIOMetadata imageMetadata)

Get the number of thumbnails supported by this image writer, based on the given image type, image writing parameters, and stream and image metadata. The image writing parameters are optional, in case they affect the number of thumbnails supported.

Parameters:

imageType - an image type specifier, or null

param - image writing parameters, or null

streamMetadata - the metadata associated with this stream, or null

imageMetadata - the metadata associated with this image, or null

Returns:

the number of thumbnails that this writer supports writing or -1 if the given information is insufficient

getOriginatingProvider

public javax.imageio.spi.ImageWriterSpi getOriginatingProvider()

Get the ImageWriterSpi that created this writer or null.

Returns:

an ImageWriterSpi, or null

getOutput

public java.lang.Object getOutput()

Get this reader's image output destination. null is returned if the image destination has not been set.

Returns:

an image output destination object, or null

getPreferredThumbnailSizes

public java.awt.Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType,
                                              ImageWriteParam param,
                                              javax.imageio.metadata.IIOMetadata streamMetadata,
                                              javax.imageio.metadata.IIOMetadata imageMetadata)

Get the preferred sizes for thumbnails based on the given image type, image writing parameters, and stream and image metadata. The preferred sizes are returned in pairs of dimension values; the first value in the array is a dimension object representing the minimum thumbnail size, the second value is a dimension object representing a maximum thumbnail size. The writer can select a size within the range given by each pair, or it can ignore these size hints.

Parameters:

imageType - an image type specifier, or null

param - image writing parameters, or null

streamMetadata - the metadata associated with this stream, or null

imageMetadata - the metadata associated with this image, or null

Returns:

an array of dimension pairs whose length is a multiple of 2, or null if there is no preferred size (any size is allowed) or if the size is unknown (insufficient information was provided)

processImageComplete

protected void processImageComplete()

Notifies all installed write progress listeners that image loading has completed by calling their imageComplete methods.

processImageProgress

protected void processImageProgress(float percentageDone)

Notifies all installed write progress listeners that a certain percentage of the image has been loaded, by calling their imageProgress methods.

Parameters:

percentageDone - the percentage of image data that has been loaded

processImageStarted

protected void processImageStarted(int imageIndex)

Notifies all installed write progress listeners, by calling their imageStarted methods, that image loading has started on the given image.

Parameters:

imageIndex - the frame index of the image that has started loading

processThumbnailComplete

protected void processThumbnailComplete()

Notifies all installed write progress listeners, by calling their thumbnailComplete methods, that a thumbnail has completed loading.

processThumbnailProgress

protected void processThumbnailProgress(float percentageDone)

Notifies all installed write progress listeners that a certain percentage of a thumbnail has been loaded, by calling their thumbnailProgress methods.

Parameters:

percentageDone - the percentage of thumbnail data that has been loaded

processThumbnailStarted

protected void processThumbnailStarted(int imageIndex,
                           int thumbnailIndex)

Notifies all installed write progress listeners, by calling their imageStarted methods, that thumbnail loading has started on the given thumbnail of the given image.

Parameters:

imageIndex - the frame index of the image one of who's thumbnails has started loading

thumbnailIndex - the index of the thumbnail that has started loading

processWarningOccurred

protected void processWarningOccurred(int imageIndex,
                          java.lang.String warning)

Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.

Parameters:

imageIndex - the index of the image that was being written when the warning was raised

warning - the warning message

Throws:

java.lang.IllegalArgumentException - if warning is null

processWarningOccurred

protected void processWarningOccurred(int imageIndex,
                          java.lang.String baseName,
                          java.lang.String keyword)

Notify all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised. The warning message is retrieved from a resource bundle, using the given basename and keyword.

Parameters:

imageIndex - the index of the image that was being written when the warning was raised

baseName - the basename of the resource from which to retrieve the warning message

keyword - the keyword used to retrieve the warning from the resource bundle

Throws:

java.lang.IllegalArgumentException - if either baseName or keyword is null

java.lang.IllegalArgumentException - if no resource bundle is found using baseName

java.lang.IllegalArgumentException - if the given keyword produces no results from the resource bundle

java.lang.IllegalArgumentException - if the retrieved object is not a String

processWriteAborted

protected void processWriteAborted()

Notifies all installed write progress listeners that image loading has been aborted by calling their writeAborted methods.

removeAllIIOWriteProgressListeners

public void removeAllIIOWriteProgressListeners()

Uninstall all write progress listeners.

removeAllIIOWriteWarningListeners

public void removeAllIIOWriteWarningListeners()

Uninstall all write warning listeners.

removeIIOWriteProgressListener

public void removeIIOWriteProgressListener(javax.imageio.event.IIOWriteProgressListener listener)

Uninstall the given write progress listener.

Parameters:

listener - the listener to remove

removeIIOWriteWarningListener

public void removeIIOWriteWarningListener(javax.imageio.event.IIOWriteWarningListener listener)

Uninstall the given write warning listener.

Parameters:

listener - the listener to remove

reset

public void reset()

Reset this writer's internal state.

setLocale

public void setLocale(java.util.Locale locale)

Set the current locale or use the default locale.

Parameters:

locale - the locale to set, or null

setOutput

public void setOutput(java.lang.Object output)

Set the output destination of the given object. The output destination must be set before many methods can be called on this writer. (see all ImageWriter methods that throw IllegalStateException). If input is null then the current input source will be removed.

Parameters:

output - the output destination object

Throws:

java.lang.IllegalArgumentException - if input is not a valid input source for this writer and is not an ImageInputStream

write

public abstract void write(javax.imageio.metadata.IIOMetadata streamMetadata,
         IIOImage image,
         ImageWriteParam param)
                    throws java.io.IOException

Write an image stream, including thumbnails and metadata to the output stream. The output must have been set prior to this method being called. Metadata associated with the stream may be supplied, or it can be left null. IIOImage may contain raster data if this writer supports rasters, or it will contain a rendered image. Thumbnails are resized if need be. Image writing parameters may be specified to affect writing, or may be left null.

Parameters:

streamMetadata - metadata associated with this stream, or null

image - an IIOImage containing image data, metadata and thumbnails to be written

param - image writing parameters, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if image contains raster data but this writer does not support rasters

java.lang.IllegalArgumentException - if image is null

java.io.IOException - if a write error occurs

endInsertEmpty

public void endInsertEmpty()
                    throws java.io.IOException

Complete inserting an empty image in the output stream.

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if inserting empty images is not supported

java.lang.IllegalArgumentException - if a call to prepareInsertEmpty was not called previous to this method being called (a sequence of prepareInsertEmpty calls must be terminated by a call to endInsertEmpty)

java.lang.IllegalArgumentException - if prepareWriteEmpty was called before this method being called (without a terminating call to endWriteEmpty)

java.lang.IllegalArgumentException - if prepareReplacePixels was called before this method being called (without a terminating call to endReplacePixels)

java.io.IOException - if a write error occurs

endReplacePixels

public void endReplacePixels()
                      throws java.io.IOException

Complete replacing pixels in an image in the output stream.

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if replacing pixels is not supported by this writer

java.lang.IllegalArgumentException - if prepareReplacePixels was not called before this method being called

java.io.IOException - if a write error occurs

endWriteEmpty

public void endWriteEmpty()
                   throws java.io.IOException

Complete writing an empty image to the image output stream.

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if writing empty images is not supported

java.lang.IllegalArgumentException - if a call to prepareWriteEmpty was not called previous to this method being called (a sequence of prepareWriteEmpty calls must be terminated by a call to endWriteEmpty)

java.lang.IllegalArgumentException - if prepareInsertEmpty was called before this method being called (without a terminating call to endInsertEmpty)

java.lang.IllegalArgumentException - if prepareReplacePixels was called before this method being called (without a terminating call to endReplacePixels)

java.io.IOException - if a write error occurs

endWriteSequence

public void endWriteSequence()
                      throws java.io.IOException

Complete writing a sequence of images to the output stream. This method may patch header data and write out footer data.

Throws:

java.lang.IllegalStateException - if output is null

java.lang.IllegalStateException - if prepareWriteSequence has not been called

java.lang.UnsupportedOperationException - if writing a sequence of images is not supported

java.io.IOException - if a write error occurs

prepareInsertEmpty

public void prepareInsertEmpty(int imageIndex,
                      ImageTypeSpecifier imageType,
                      int width,
                      int height,
                      javax.imageio.metadata.IIOMetadata imageMetadata,
                      java.util.List<? extends java.awt.image.BufferedImage> thumbnails,
                      ImageWriteParam param)
                        throws java.io.IOException

Start inserting an empty image in the image output stream. All indices after the specified index are incremented. An index of -1 implies that the empty image should be appended to the end of the current image list. The insertion that this method call starts is not complete until endInsertEmpty is called. prepareInsertEmpty cannot be called again until endInsertEmpty is called and calls to prepareWriteEmpty and prepareInsertEmpty may not be intersperced.

Parameters:

imageIndex - the image index

imageType - the image type specifier

width - the image width

height - the image height

imageMetadata - the image metadata, or null

thumbnails - a list of thumbnails, or null

param - image write parameters, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if inserting empty images is not supported

java.lang.IndexOutOfBoundsException - if imageIndex is less than -1 or greater than the last index in the current image list

java.lang.IllegalStateException - if a previous call to prepareInsertEmpty was made (without a terminating call to endInsertEmpty)

java.lang.IllegalStateException - if a previous call to prepareWriteEmpty was made (without a terminating call to endWriteEmpty)

java.lang.IllegalArgumentException - if imageType is null or thumbnails contain non-BufferedImage objects

java.lang.IllegalArgumentException - if either width or height is less than 1

java.io.IOException - if a write error occurs

prepareReplacePixels

public void prepareReplacePixels(int imageIndex,
                        java.awt.Rectangle region)
                          throws java.io.IOException

Start the replacement of pixels within an image in the output stream. Output pixels will be clipped to lie within region.

Parameters:

imageIndex - the index of the image in which pixels are being replaced

region - the rectangle to which to limit pixel replacement

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if replacing pixels is not supported

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the last index in the current image list

java.lang.IllegalStateException - if a previous call to prepareReplacePixels was made (without a terminating call to endReplacePixels)

java.lang.IllegalArgumentException - if either region.width or region.height is less than 1, or if region is null

java.io.IOException - if a write error occurs

prepareWriteEmpty

public void prepareWriteEmpty(javax.imageio.metadata.IIOMetadata streamMetadata,
                     ImageTypeSpecifier imageType,
                     int width,
                     int height,
                     javax.imageio.metadata.IIOMetadata imageMetadata,
                     java.util.List<? extends java.awt.image.BufferedImage> thumbnails,
                     ImageWriteParam param)
                       throws java.io.IOException

Start writing an empty image to the end of the image output stream. The writing that this method call starts is not complete until endWriteEmpty is called. prepareWritetEmpty cannot be called again until endWriteEmpty is called and calls to prepareWriteEmpty and prepareInsertEmpty may not be intersperced.

Parameters:

streamMetadata - metadata associated with the stream, or null

imageType - the image type specifier

width - the image width

height - the image height

imageMetadata - the image metadata, or null

thumbnails - a list of thumbnails, or null

param - image write parameters, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if writing empty images is not supported

java.lang.IndexOutOfBoundsException - if imageIndex is less than -1 or greater than the last index in the current image list

java.lang.IllegalStateException - if a previous call to prepareInsertEmpty was made (without a terminating call to endInsertEmpty)

java.lang.IllegalStateException - if a previous call to prepareWriteEmpty was made (without a terminating call to endWriteEmpty)

java.lang.IllegalArgumentException - if imageType is null or thumbnails contain non-BufferedImage objects

java.lang.IllegalArgumentException - if either width or height is less than 1

java.io.IOException - if a write error occurs

prepareWriteSequence

public void prepareWriteSequence(javax.imageio.metadata.IIOMetadata streamMetadata)
                          throws java.io.IOException

Start the writing of a sequence of images.

Parameters:

streamMetadata - the stream metadata, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if writing sequences of images is not supported

java.io.IOException - if a write error occurs

removeImage

public void removeImage(int imageIndex)
                 throws java.io.IOException

Remove the image at the specified index from the output stream.

Parameters:

imageIndex - the frame index from which to remove the image

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if removing this image is not supported

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the last index in the current image list

java.io.IOException - if a write error occurs

replaceImageMetadata

public void replaceImageMetadata(int imageIndex,
                        javax.imageio.metadata.IIOMetadata imageMetadata)
                          throws java.io.IOException

Replace the metadata associated with the image at the given index.

Parameters:

imageIndex - the index of the image whose metadata should be replaced

imageMetadata - the metadata, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if replacing this image's metadata is not supported

java.lang.IndexOutOfBoundsException - if imageIndex is less than 0 or greater than the last index in the current image list

java.io.IOException - if a write error occurs

replacePixels

public void replacePixels(java.awt.image.RenderedImage image,
                 ImageWriteParam param)
                   throws java.io.IOException

Replace a region of an image in the output stream with a portion of the given rendered image. The image data must be of the same type as that in the output stream. The destination region is given by the image writing parameters and the source region is the one given to prepareReplacePixels.

Parameters:

image - the rendered image with which to overwrite the image region in the stream

param - the image writing parameters

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if replacing pixels is not supported

java.lang.IllegalStateException - if prepareReplacePixels was not called before this method was called

java.lang.IllegalArgumentException - if image is null or if param is null or if the overlap of the source and destination regions contains no pixels or if the image types differ and no conversion is possible

java.io.IOException - if a write error occurs

replacePixels

public void replacePixels(java.awt.image.Raster raster,
                 ImageWriteParam param)
                   throws java.io.IOException

Replace a region of an image in the output stream with a portion of the given raster data. The image data must be of the same type as that in the output stream. The destination region is given by the image writing parameters and the source region is the one given to prepareReplacePixels.

Parameters:

raster - the raster data with which to overwrite the image region in the stream

param - the image writing parameters

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if replacing pixels is not supported

java.lang.IllegalStateException - if prepareReplacePixels was not called before this method was called

java.lang.UnsupportedOperationException - if raster data is not supported

java.lang.IllegalArgumentException - if raster is null or if param is null or if the overlap of the source and destination regions contains no pixels or if the image types differ and no conversion is possible

java.io.IOException - if a write error occurs

replaceStreamMetadata

public void replaceStreamMetadata(javax.imageio.metadata.IIOMetadata streamMetadata)
                           throws java.io.IOException

Replace the metadata associated with this image stream.

Parameters:

streamMetadata - the stream metadata, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if replacing the stream metadata is not supported

java.io.IOException - if a write error occurs

write

public void write(java.awt.image.RenderedImage image)
           throws java.io.IOException

Write a rendered image to the output stream.

Parameters:

image - a rendered image containing image data to be written

Throws:

java.lang.IllegalStateException - if output is null

java.lang.IllegalArgumentException - if image is null

java.io.IOException - if a write error occurs

write

public void write(IIOImage image)
           throws java.io.IOException

Write a image data, metadata and thumbnails to the output stream.

Parameters:

image - image data, metadata and thumbnails to be written

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if image contains raster data but this writer does not support rasters

java.lang.IllegalArgumentException - if image is null

java.io.IOException - if a write error occurs

writeInsert

public void writeInsert(int imageIndex,
               IIOImage image,
               ImageWriteParam param)
                 throws java.io.IOException

Insert an image into the output stream. Indices greater than the specified index are incremented accordingly. Specifying an index of -1 causes the image to be appended at the end of the current image list.

Parameters:

imageIndex - the frame index at which to insert the image

image - the image data, metadata and thumbnails to be inserted

param - image write parameters, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if image insertion is not supported

java.lang.IllegalArgumentException - if image is null

java.lang.IndexOutOfBoundsException - if imageIndex is less than -1 or greater than the last index in the current image list

java.lang.UnsupportedOperationException - if image contains raster data but this writer does not support rasters

java.io.IOException - if a write error occurs

writeToSequence

public void writeToSequence(IIOImage image,
                   ImageWriteParam param)
                     throws java.io.IOException

Write a sequence of images, including thumbnails and metadata, to the output stream. The output must have been set prior to this method being called. Metadata associated with the stream may be supplied, or it can be left null. IIOImage may contain raster data if this writer supports rasters, or it will contain a rendered image. Thumbnails are resized if need be. Image writing parameters may be specified to affect writing, or may be left null.

Parameters:

streamMetadata - metadata associated with this stream, or null

image - an IIOImage containing image data, metadata and thumbnails to be written

param - image writing parameters, or null

Throws:

java.lang.IllegalStateException - if output is null

java.lang.UnsupportedOperationException - if writing sequences of images is not supported

java.lang.IllegalArgumentException - if image is null

java.lang.UnsupportedOperationException - if image contains raster data but this writer does not support rasters

java.io.IOException - if a write error occurs