|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.imageio.ImageWriter
public abstract class ImageWriter
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 | |
---|---|
protected Locale[] |
availableLocales
All locales available for localization of warning messages, or null if localization is not supported. |
protected Locale |
locale
The current locale used to localize warning messages, or null if no locale has been set. |
protected ImageWriterSpi |
originatingProvider
The image writer SPI that instantiated this writer. |
protected Object |
output
An ImageInputStream to which image data is written. |
protected List<IIOWriteProgressListener> |
progressListeners
A list of installed progress listeners. |
protected List<IIOWriteWarningListener> |
warningListeners
A list of installed warning listeners. |
protected List<Locale> |
warningLocales
A list of warning locales corresponding with the list of installed warning listeners. |
Constructor Summary | |
---|---|
protected |
ImageWriter(ImageWriterSpi originatingProvider)
Construct an image writer. |
Method Summary | |
---|---|
void |
abort()
Request that writing be aborted. |
protected boolean |
abortRequested()
Check if the abort flag is set. |
void |
addIIOWriteProgressListener(IIOWriteProgressListener listener)
Install a write progress listener. |
void |
addIIOWriteWarningListener(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 IIOMetadata |
convertImageMetadata(IIOMetadata inData,
ImageTypeSpecifier imageType,
ImageWriteParam param)
Convert IIOMetadata from an input reader format, returning an IIOMetadata suitable for use by an image writer. |
abstract IIOMetadata |
convertStreamMetadata(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. |
Locale[] |
getAvailableLocales()
Retrieve the available locales. |
abstract 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 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. |
Locale |
getLocale()
Get this writer's locale. |
int |
getNumThumbnailsSupported(ImageTypeSpecifier imageType,
ImageWriteParam param,
IIOMetadata streamMetadata,
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. |
ImageWriterSpi |
getOriginatingProvider()
Get the ImageWriterSpi that created this writer or null. |
Object |
getOutput()
Get this reader's image output destination. |
Dimension[] |
getPreferredThumbnailSizes(ImageTypeSpecifier imageType,
ImageWriteParam param,
IIOMetadata streamMetadata,
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,
IIOMetadata imageMetadata,
List<? extends BufferedImage> thumbnails,
ImageWriteParam param)
Start inserting an empty image in the image output stream. |
void |
prepareReplacePixels(int imageIndex,
Rectangle region)
Start the replacement of pixels within an image in the output stream. |
void |
prepareWriteEmpty(IIOMetadata streamMetadata,
ImageTypeSpecifier imageType,
int width,
int height,
IIOMetadata imageMetadata,
List<? extends BufferedImage> thumbnails,
ImageWriteParam param)
Start writing an empty image to the end of the image output stream. |
void |
prepareWriteSequence(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,
String warning)
Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised. |
protected void |
processWarningOccurred(int imageIndex,
String baseName,
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(IIOWriteProgressListener listener)
Uninstall the given write progress listener. |
void |
removeIIOWriteWarningListener(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,
IIOMetadata imageMetadata)
Replace the metadata associated with the image at the given index. |
void |
replacePixels(Raster raster,
ImageWriteParam param)
Replace a region of an image in the output stream with a portion of the given raster data. |
void |
replacePixels(RenderedImage image,
ImageWriteParam param)
Replace a region of an image in the output stream with a portion of the given rendered image. |
void |
replaceStreamMetadata(IIOMetadata streamMetadata)
Replace the metadata associated with this image stream. |
void |
reset()
Reset this writer's internal state. |
void |
setLocale(Locale locale)
Set the current locale or use the default locale. |
void |
setOutput(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(IIOMetadata streamMetadata,
IIOImage image,
ImageWriteParam param)
Write an image stream, including thumbnails and metadata to the output stream. |
void |
write(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 |
---|
protected Locale[] availableLocales
protected Locale locale
protected ImageWriterSpi originatingProvider
protected Object output
protected List<IIOWriteProgressListener> progressListeners
protected List<IIOWriteWarningListener> warningListeners
protected List<Locale> warningLocales
Constructor Detail |
---|
protected ImageWriter(ImageWriterSpi originatingProvider)
originatingProvider
- the provider that is constructing this
image writer, or nullMethod Detail |
---|
public void abort()
protected boolean abortRequested()
public void addIIOWriteProgressListener(IIOWriteProgressListener listener)
listener
- a write progress listener or nullpublic void addIIOWriteWarningListener(IIOWriteWarningListener listener)
listener
- a write warning listenerpublic boolean canInsertEmpty(int imageIndex) throws IOException
imageIndex
- the frame index
IllegalStateException
- if output is null
IndexOutOfBoundsException
- if imageIndex is less than
-1 or greater than the last index in the current image list
IOException
- if a write error occurspublic boolean canInsertImage(int imageIndex) throws IOException
imageIndex
- the frame index
IllegalStateException
- if output is null
IndexOutOfBoundsException
- if imageIndex is less than
-1 or greater than the last index in the current image list
IOException
- if a write error occurspublic boolean canRemoveImage(int imageIndex) throws IOException
imageIndex
- the frame index
IllegalStateException
- if output is null
IndexOutOfBoundsException
- if imageIndex is less than 0
or greater than the last index in the current image list
IOException
- if a write error occurspublic boolean canReplaceImageMetadata(int imageIndex) throws IOException
imageIndex
- the frame index
IllegalStateException
- if output is null
IndexOutOfBoundsException
- if imageIndex is less than 0
or greater than the last index in the current image list
IOException
- if a write error occurspublic boolean canReplacePixels(int imageIndex) throws IOException
imageIndex
- the frame index
IllegalStateException
- if output is null
IndexOutOfBoundsException
- if imageIndex is less than 0
or greater than the last index in the current image list
IOException
- if a write error occurspublic boolean canReplaceStreamMetadata() throws IOException
IllegalStateException
- if output is null
IOException
- if a write error occurspublic boolean canWriteEmpty() throws IOException
IllegalStateException
- if output is null
IOException
- if a write error occurspublic boolean canWriteRasters()
public boolean canWriteSequence()
protected void clearAbortRequest()
public abstract IIOMetadata convertImageMetadata(IIOMetadata inData, ImageTypeSpecifier imageType, ImageWriteParam param)
convertImageMetadata
in interface ImageTranscoder
inData
- the metadata coming from an image readerimageType
- the output image type of the writerparam
- the image writing parameters or null
IllegalArgumentException
- if either inData or imageType
is nullpublic abstract IIOMetadata convertStreamMetadata(IIOMetadata inData, ImageWriteParam param)
convertStreamMetadata
in interface ImageTranscoder
inData
- the metadata coming from an input image streamparam
- the image writing parameters or null
IllegalArgumentException
- if inData is nullpublic void dispose()
public Locale[] getAvailableLocales()
public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param)
imageType
- an image type specifierparam
- image writing parameters, or null
public abstract IIOMetadata getDefaultStreamMetadata(ImageWriteParam param)
param
- image writing parameters, or null
public ImageWriteParam getDefaultWriteParam()
public Locale getLocale()
public int getNumThumbnailsSupported(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata)
imageType
- an image type specifier, or nullparam
- image writing parameters, or nullstreamMetadata
- the metadata associated with this stream,
or nullimageMetadata
- the metadata associated with this image, or
null
public ImageWriterSpi getOriginatingProvider()
public Object getOutput()
public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata)
imageType
- an image type specifier, or nullparam
- image writing parameters, or nullstreamMetadata
- the metadata associated with this stream,
or nullimageMetadata
- the metadata associated with this image, or
null
protected void processImageComplete()
protected void processImageProgress(float percentageDone)
percentageDone
- the percentage of image data that has been
loadedprotected void processImageStarted(int imageIndex)
imageIndex
- the frame index of the image that has started
loadingprotected void processThumbnailComplete()
protected void processThumbnailProgress(float percentageDone)
percentageDone
- the percentage of thumbnail data that has
been loadedprotected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
imageIndex
- the frame index of the image one of who's
thumbnails has started loadingthumbnailIndex
- the index of the thumbnail that has started
loadingprotected void processWarningOccurred(int imageIndex, String warning)
imageIndex
- the index of the image that was being written
when the warning was raisedwarning
- the warning message
IllegalArgumentException
- if warning is nullprotected void processWarningOccurred(int imageIndex, String baseName, String keyword)
imageIndex
- the index of the image that was being written
when the warning was raisedbaseName
- the basename of the resource from which to
retrieve the warning messagekeyword
- the keyword used to retrieve the warning from the
resource bundle
IllegalArgumentException
- if either baseName or keyword
is null
IllegalArgumentException
- if no resource bundle is
found using baseName
IllegalArgumentException
- if the given keyword produces
no results from the resource bundle
IllegalArgumentException
- if the retrieved object is
not a Stringprotected void processWriteAborted()
public void removeAllIIOWriteProgressListeners()
public void removeAllIIOWriteWarningListeners()
public void removeIIOWriteProgressListener(IIOWriteProgressListener listener)
listener
- the listener to removepublic void removeIIOWriteWarningListener(IIOWriteWarningListener listener)
listener
- the listener to removepublic void reset()
public void setLocale(Locale locale)
locale
- the locale to set, or nullpublic void setOutput(Object output)
output
- the output destination object
IllegalArgumentException
- if input is not a valid input
source for this writer and is not an ImageInputStreampublic abstract void write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param) throws IOException
streamMetadata
- metadata associated with this stream, or
nullimage
- an IIOImage containing image data, metadata and
thumbnails to be writtenparam
- image writing parameters, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if image contains raster
data but this writer does not support rasters
IllegalArgumentException
- if image is null
IOException
- if a write error occurspublic void endInsertEmpty() throws IOException
IllegalStateException
- if output is null
UnsupportedOperationException
- if inserting empty
images is not supported
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)
IllegalArgumentException
- if prepareWriteEmpty was
called before this method being called (without a terminating
call to endWriteEmpty)
IllegalArgumentException
- if prepareReplacePixels was
called before this method being called (without a terminating
call to endReplacePixels)
IOException
- if a write error occurspublic void endReplacePixels() throws IOException
IllegalStateException
- if output is null
UnsupportedOperationException
- if replacing pixels is
not supported by this writer
IllegalArgumentException
- if prepareReplacePixels was
not called before this method being called
IOException
- if a write error occurspublic void endWriteEmpty() throws IOException
IllegalStateException
- if output is null
UnsupportedOperationException
- if writing empty images
is not supported
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)
IllegalArgumentException
- if prepareInsertEmpty was
called before this method being called (without a terminating
call to endInsertEmpty)
IllegalArgumentException
- if prepareReplacePixels was
called before this method being called (without a terminating
call to endReplacePixels)
IOException
- if a write error occurspublic void endWriteSequence() throws IOException
IllegalStateException
- if output is null
IllegalStateException
- if prepareWriteSequence has not
been called
UnsupportedOperationException
- if writing a sequence of
images is not supported
IOException
- if a write error occurspublic void prepareInsertEmpty(int imageIndex, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) throws IOException
imageIndex
- the image indeximageType
- the image type specifierwidth
- the image widthheight
- the image heightimageMetadata
- the image metadata, or nullthumbnails
- a list of thumbnails, or nullparam
- image write parameters, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if inserting empty
images is not supported
IndexOutOfBoundsException
- if imageIndex is less than
-1 or greater than the last index in the current image list
IllegalStateException
- if a previous call to
prepareInsertEmpty was made (without a terminating call to
endInsertEmpty)
IllegalStateException
- if a previous call to
prepareWriteEmpty was made (without a terminating call to
endWriteEmpty)
IllegalArgumentException
- if imageType is null or
thumbnails contain non-BufferedImage objects
IllegalArgumentException
- if either width or height is
less than 1
IOException
- if a write error occurspublic void prepareReplacePixels(int imageIndex, Rectangle region) throws IOException
imageIndex
- the index of the image in which pixels are
being replacedregion
- the rectangle to which to limit pixel replacement
IllegalStateException
- if output is null
UnsupportedOperationException
- if replacing pixels is
not supported
IndexOutOfBoundsException
- if imageIndex is less than 0
or greater than the last index in the current image list
IllegalStateException
- if a previous call to
prepareReplacePixels was made (without a terminating call to
endReplacePixels)
IllegalArgumentException
- if either region.width or
region.height is less than 1, or if region is null
IOException
- if a write error occurspublic void prepareWriteEmpty(IIOMetadata streamMetadata, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) throws IOException
streamMetadata
- metadata associated with the stream, or nullimageType
- the image type specifierwidth
- the image widthheight
- the image heightimageMetadata
- the image metadata, or nullthumbnails
- a list of thumbnails, or nullparam
- image write parameters, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if writing empty images
is not supported
IndexOutOfBoundsException
- if imageIndex is less than
-1 or greater than the last index in the current image list
IllegalStateException
- if a previous call to
prepareInsertEmpty was made (without a terminating call to
endInsertEmpty)
IllegalStateException
- if a previous call to
prepareWriteEmpty was made (without a terminating call to
endWriteEmpty)
IllegalArgumentException
- if imageType is null or
thumbnails contain non-BufferedImage objects
IllegalArgumentException
- if either width or height is
less than 1
IOException
- if a write error occurspublic void prepareWriteSequence(IIOMetadata streamMetadata) throws IOException
streamMetadata
- the stream metadata, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if writing sequences of
images is not supported
IOException
- if a write error occurspublic void removeImage(int imageIndex) throws IOException
imageIndex
- the frame index from which to remove the image
IllegalStateException
- if output is null
UnsupportedOperationException
- if removing this image
is not supported
IndexOutOfBoundsException
- if imageIndex is less than 0
or greater than the last index in the current image list
IOException
- if a write error occurspublic void replaceImageMetadata(int imageIndex, IIOMetadata imageMetadata) throws IOException
imageIndex
- the index of the image whose metadata should be
replacedimageMetadata
- the metadata, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if replacing this
image's metadata is not supported
IndexOutOfBoundsException
- if imageIndex is less than 0
or greater than the last index in the current image list
IOException
- if a write error occurspublic void replacePixels(RenderedImage image, ImageWriteParam param) throws IOException
image
- the rendered image with which to overwrite the image
region in the streamparam
- the image writing parameters
IllegalStateException
- if output is null
UnsupportedOperationException
- if replacing pixels is
not supported
IllegalStateException
- if prepareReplacePixels was not
called before this method was called
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
IOException
- if a write error occurspublic void replacePixels(Raster raster, ImageWriteParam param) throws IOException
raster
- the raster data with which to overwrite the image
region in the streamparam
- the image writing parameters
IllegalStateException
- if output is null
UnsupportedOperationException
- if replacing pixels is
not supported
IllegalStateException
- if prepareReplacePixels was not
called before this method was called
UnsupportedOperationException
- if raster data is not
supported
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
IOException
- if a write error occurspublic void replaceStreamMetadata(IIOMetadata streamMetadata) throws IOException
streamMetadata
- the stream metadata, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if replacing the stream
metadata is not supported
IOException
- if a write error occurspublic void write(RenderedImage image) throws IOException
image
- a rendered image containing image data to be written
IllegalStateException
- if output is null
IllegalArgumentException
- if image is null
IOException
- if a write error occurspublic void write(IIOImage image) throws IOException
image
- image data, metadata and thumbnails to be written
IllegalStateException
- if output is null
UnsupportedOperationException
- if image contains raster
data but this writer does not support rasters
IllegalArgumentException
- if image is null
IOException
- if a write error occurspublic void writeInsert(int imageIndex, IIOImage image, ImageWriteParam param) throws IOException
imageIndex
- the frame index at which to insert the imageimage
- the image data, metadata and thumbnails to be
insertedparam
- image write parameters, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if image insertion is
not supported
IllegalArgumentException
- if image is null
IndexOutOfBoundsException
- if imageIndex is less than
-1 or greater than the last index in the current image list
UnsupportedOperationException
- if image contains raster
data but this writer does not support rasters
IOException
- if a write error occurspublic void writeToSequence(IIOImage image, ImageWriteParam param) throws IOException
streamMetadata
- metadata associated with this stream, or
nullimage
- an IIOImage containing image data, metadata and
thumbnails to be writtenparam
- image writing parameters, or null
IllegalStateException
- if output is null
UnsupportedOperationException
- if writing sequences of
images is not supported
IllegalArgumentException
- if image is null
UnsupportedOperationException
- if image contains raster
data but this writer does not support rasters
IOException
- if a write error occurs
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |