/* * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.imageio; import java.awt.Dimension;import java.awt.Rectangle;import java.awt.image.BufferedImage;import java.awt.image.RenderedImage;import java.awt.image.Raster;import java.io.IOException;import java.util.ArrayList;import java.util.List;import java.util.Locale;import java.util.MissingResourceException;import java.util.ResourceBundle;import javax.imageio.event.IIOWriteWarningListener;import javax.imageio.event.IIOWriteProgressListener;import javax.imageio.metadata.IIOMetadata;import javax.imageio.stream.ImageOutputStream;import javax.imageio.spi.ImageWriterSpi; /** * An abstract superclass for encoding and writing images. This class * must be subclassed by classes that write out images in the context * of the Java Image I/O framework. * * <p> <code>ImageWriter</code> objects are normally instantiated by * the service provider class for the specific format. Service * provider classes are registered with the <code>IIORegistry</code>, * which uses them for format recognition and presentation of * available format readers and writers. * * <p> * * @see ImageReader * @see ImageWriteParam * @see javax.imageio.spi.IIORegistry * @see javax.imageio.spi.ImageWriterSpi * */public abstract class ImageWriter implements ImageTranscoder { /** * The <code>ImageWriterSpi</code> that instantiated this object, * or <code>null</code> if its identity is not known or none * exists. By default it is initialized to <code>null</code>. */ protected ImageWriterSpi originatingProvider = null; /** * The <code>ImageOutputStream</code> or other <code>Object</code> * set by <code>setOutput</code> and retrieved by * <code>getOutput</code>. By default it is initialized to * <code>null</code>. */ protected Object output = null; /** * An array of <code>Locale</code>s that may be used to localize * warning messages and compression setting values, or * <code>null</code> if localization is not supported. By default * it is initialized to <code>null</code>. */ protected Locale[] availableLocales = null; /** * The current <code>Locale</code> to be used for localization, or * <code>null</code> if none has been set. By default it is * initialized to <code>null</code>. */ protected Locale locale = null; /** * A <code>List</code> of currently registered * <code>IIOWriteWarningListener</code>s, initialized by default to * <code>null</code>, which is synonymous with an empty * <code>List</code>. */ protected List<IIOWriteWarningListener> warningListeners = null; /** * A <code>List</code> of <code>Locale</code>s, one for each * element of <code>warningListeners</code>, initialized by default * <code>null</code>, which is synonymous with an empty * <code>List</code>. */ protected List<Locale> warningLocales = null; /** * A <code>List</code> of currently registered * <code>IIOWriteProgressListener</code>s, initialized by default * <code>null</code>, which is synonymous with an empty * <code>List</code>. */ protected List<IIOWriteProgressListener> progressListeners = null; /** * If <code>true</code>, the current write operation should be * aborted. */ private boolean abortFlag = false; /** * Constructs an <code>ImageWriter</code> and sets its * <code>originatingProvider</code> instance variable to the * supplied value. * * <p> Subclasses that make use of extensions should provide a * constructor with signature <code>(ImageWriterSpi, * Object)</code> in order to retrieve the extension object. If * the extension object is unsuitable, an * <code>IllegalArgumentException</code> should be thrown. * * @param originatingProvider the <code>ImageWriterSpi</code> that * is constructing this object, or <code>null</code>. */ protected ImageWriter(ImageWriterSpi originatingProvider) { this.originatingProvider = originatingProvider; } /** * Returns the <code>ImageWriterSpi</code> object that created * this <code>ImageWriter</code>, or <code>null</code> if this * object was not created through the <code>IIORegistry</code>. * * <p> The default implementation returns the value of the * <code>originatingProvider</code> instance variable. * * @return an <code>ImageWriterSpi</code>, or <code>null</code>. * * @see ImageWriterSpi */ public ImageWriterSpi getOriginatingProvider() { return originatingProvider; } /** * Sets the destination to the given * <code>ImageOutputStream</code> or other <code>Object</code>. * The destination is assumed to be ready to accept data, and will * not be closed at the end of each write. This allows distributed * imaging applications to transmit a series of images over a * single network connection. If <code>output</code> is * <code>null</code>, any currently set output will be removed. * * <p> If <code>output</code> is an * <code>ImageOutputStream</code>, calls to the * <code>write</code>, <code>writeToSequence</code>, and * <code>prepareWriteEmpty</code>/<code>endWriteEmpty</code> * methods will preserve the existing contents of the stream. * Other write methods, such as <code>writeInsert</code>, * <code>replaceStreamMetadata</code>, * <code>replaceImageMetadata</code>, <code>replacePixels</code>, * <code>prepareInsertEmpty</code>/<code>endInsertEmpty</code>, * and <code>endWriteSequence</code>, require the full contents * of the stream to be readable and writable, and may alter any * portion of the stream. * * <p> Use of a general <code>Object</code> other than an * <code>ImageOutputStream</code> is intended for writers that * interact directly with an output device or imaging protocol. * The set of legal classes is advertised by the writer's service * provider's <code>getOutputTypes</code> method; most writers * will return a single-element array containing only * <code>ImageOutputStream.class</code> to indicate that they * accept only an <code>ImageOutputStream</code>. * * <p> The default implementation sets the <code>output</code> * instance variable to the value of <code>output</code> after * checking <code>output</code> against the set of classes * advertised by the originating provider, if there is one. * * @param output the <code>ImageOutputStream</code> or other * <code>Object</code> to use for future writing. * * @exception IllegalArgumentException if <code>output</code> is * not an instance of one of the classes returned by the * originating service provider's <code>getOutputTypes</code> * method. * * @see #getOutput */ public void setOutput(Object output) { if (output != null) { ImageWriterSpi provider = getOriginatingProvider(); if (provider != null) { Class[] classes = provider.getOutputTypes(); boolean found = false; for (int i = 0; i < classes.length; i++) { if (classes[i].isInstance(output)) { found = true; break; } } if (!found) { throw new IllegalArgumentException("Illegal output type!"); } } } this.output = output; } /** * Returns the <code>ImageOutputStream</code> or other * <code>Object</code> set by the most recent call to the * <code>setOutput</code> method. If no destination has been * set, <code>null</code> is returned. * * <p> The default implementation returns the value of the * <code>output</code> instance variable. * * @return the <code>Object</code> that was specified using * <code>setOutput</code>, or <code>null</code>. * * @see #setOutput */ public Object getOutput() { return output; } // Localization /** * Returns an array of <code>Locale</code>s that may be used to * localize warning listeners and compression settings. A return * value of <code>null</code> indicates that localization is not * supported. * * <p> The default implementation returns a clone of the * <code>availableLocales</code> instance variable if it is * non-<code>null</code>, or else returns <code>null</code>. * * @return an array of <code>Locale</code>s that may be used as * arguments to <code>setLocale</code>, or <code>null</code>. */ public Locale[] getAvailableLocales() { return (availableLocales == null) ? null : (Locale[])availableLocales.clone(); } /** * Sets the current <code>Locale</code> of this * <code>ImageWriter</code> to the given value. A value of * <code>null</code> removes any previous setting, and indicates * that the writer should localize as it sees fit. * * <p> The default implementation checks <code>locale</code> * against the values returned by * <code>getAvailableLocales</code>, and sets the * <code>locale</code> instance variable if it is found. If * <code>locale</code> is <code>null</code>, the instance variable * is set to <code>null</code> without any checking. * * @param locale the desired <code>Locale</code>, or * <code>null</code>. * * @exception IllegalArgumentException if <code>locale</code> is * non-<code>null</code> but is not one of the values returned by * <code>getAvailableLocales</code>. * * @see #getLocale */ public void setLocale(Locale locale) { if (locale != null) { Locale[] locales = getAvailableLocales(); boolean found = false; if (locales != null) { for (int i = 0; i < locales.length; i++) { if (locale.equals(locales[i])) { found = true; break; } } } if (!found) { throw new IllegalArgumentException("Invalid locale!"); } } this.locale = locale; } /** * Returns the currently set <code>Locale</code>, or * <code>null</code> if none has been set. * * <p> The default implementation returns the value of the * <code>locale</code> instance variable. * * @return the current <code>Locale</code>, or <code>null</code>. * * @see #setLocale */ public Locale getLocale() { return locale; } // Write params /** * Returns a new <code>ImageWriteParam</code> object of the * appropriate type for this file format containing default * values, that is, those values that would be used * if no <code>ImageWriteParam</code> object were specified. This * is useful as a starting point for tweaking just a few parameters * and otherwise leaving the default settings alone. * * <p> The default implementation constructs and returns a new * <code>ImageWriteParam</code> object that does not allow tiling, * progressive encoding, or compression, and that will be * localized for the current <code>Locale</code> (<i>i.e.</i>, * what you would get by calling <code>new * ImageWriteParam(getLocale())</code>. * * <p> Individual plug-ins may return an instance of * <code>ImageWriteParam</code> with additional optional features * enabled, or they may return an instance of a plug-in specific * subclass of <code>ImageWriteParam</code>. * * @return a new <code>ImageWriteParam</code> object containing * default values. */ public ImageWriteParam getDefaultWriteParam() { return new ImageWriteParam(getLocale()); } // Metadata /** * Returns an <code>IIOMetadata</code> object containing default * values for encoding a stream of images. The contents of the * object may be manipulated using either the XML tree structure * returned by the <code>IIOMetadata.getAsTree</code> method, an * <code>IIOMetadataController</code> object, or via plug-in * specific interfaces, and the resulting data supplied to one of * the <code>write</code> methods that take a stream metadata * parameter. * * <p> An optional <code>ImageWriteParam</code> may be supplied * for cases where it may affect the structure of the stream * metadata. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * <p> Writers that do not make use of stream metadata * (<i>e.g.</i>, writers for single-image formats) should return * <code>null</code>. * * @param param an <code>ImageWriteParam</code> that will be used to * encode the image, or <code>null</code>. * * @return an <code>IIOMetadata</code> object. */ public abstract IIOMetadata getDefaultStreamMetadata(ImageWriteParam param); /** * Returns an <code>IIOMetadata</code> object containing default * values for encoding an image of the given type. The contents * of the object may be manipulated using either the XML tree * structure returned by the <code>IIOMetadata.getAsTree</code> * method, an <code>IIOMetadataController</code> object, or via * plug-in specific interfaces, and the resulting data supplied to * one of the <code>write</code> methods that take a stream * metadata parameter. * * <p> An optional <code>ImageWriteParam</code> may be supplied * for cases where it may affect the structure of the image * metadata. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * @param imageType an <code>ImageTypeSpecifier</code> indicating the * format of the image to be written later. * @param param an <code>ImageWriteParam</code> that will be used to * encode the image, or <code>null</code>. * * @return an <code>IIOMetadata</code> object. */ public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param); // comment inherited public abstract IIOMetadata convertStreamMetadata(IIOMetadata inData, ImageWriteParam param); // comment inherited public abstract IIOMetadata convertImageMetadata(IIOMetadata inData, ImageTypeSpecifier imageType, ImageWriteParam param); // Thumbnails /** * Returns the number of thumbnails suported by the format being * written, given the image type and any additional write * parameters and metadata objects that will be used during * encoding. A return value of <code>-1</code> indicates that * insufficient information is available. * * <p> An <code>ImageWriteParam</code> may optionally be supplied * for cases where it may affect thumbnail handling. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * <p> The default implementation returns 0. * * @param imageType an <code>ImageTypeSpecifier</code> indicating * the type of image to be written, or <code>null</code>. * @param param the <code>ImageWriteParam</code> that will be used for * writing, or <code>null</code>. * @param streamMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * @param imageMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * * @return the number of thumbnails that may be written given the * supplied parameters, or <code>-1</code> if insufficient * information is available. */ public int getNumThumbnailsSupported(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata) { return 0; } /** * Returns an array of <code>Dimension</code>s indicating the * legal size ranges for thumbnail images as they will be encoded * in the output file or stream. This information is merely * advisory; the writer will resize any supplied thumbnails as * necessary. * * <p> The information is returned as a set of pairs; the first * element of a pair contains an (inclusive) minimum width and * height, and the second element contains an (inclusive) maximum * width and height. Together, each pair defines a valid range of * sizes. To specify a fixed size, the same width and height will * appear for both elements. A return value of <code>null</code> * indicates that the size is arbitrary or unknown. * * <p> An <code>ImageWriteParam</code> may optionally be supplied * for cases where it may affect thumbnail handling. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * <p> The default implementation returns <code>null</code>. * * @param imageType an <code>ImageTypeSpecifier</code> indicating the * type of image to be written, or <code>null</code>. * @param param the <code>ImageWriteParam</code> that will be used for * writing, or <code>null</code>. * @param streamMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * @param imageMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * * @return an array of <code>Dimension</code>s with an even length * of at least two, or <code>null</code>. */ public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType, ImageWriteParam param,Lines 1–500 of 2037. Load more
/* * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.imageio; import java.awt.Dimension; import java.awt.Rectangle; import java.awt.image.BufferedImage; import java.awt.image.RenderedImage; import java.awt.image.Raster; import java.io.IOException; import java.util.ArrayList; import java.util.List; import java.util.Locale; import java.util.MissingResourceException; import java.util.ResourceBundle; import javax.imageio.event.IIOWriteWarningListener; import javax.imageio.event.IIOWriteProgressListener; import javax.imageio.metadata.IIOMetadata; import javax.imageio.stream.ImageOutputStream; import javax.imageio.spi.ImageWriterSpi; /** * An abstract superclass for encoding and writing images. This class * must be subclassed by classes that write out images in the context * of the Java Image I/O framework. * * <p> <code>ImageWriter</code> objects are normally instantiated by * the service provider class for the specific format. Service * provider classes are registered with the <code>IIORegistry</code>, * which uses them for format recognition and presentation of * available format readers and writers. * * <p> * * @see ImageReader * @see ImageWriteParam * @see javax.imageio.spi.IIORegistry * @see javax.imageio.spi.ImageWriterSpi * */ public abstract class ImageWriter implements ImageTranscoder { /** * The <code>ImageWriterSpi</code> that instantiated this object, * or <code>null</code> if its identity is not known or none * exists. By default it is initialized to <code>null</code>. */ protected ImageWriterSpi originatingProvider = null; /** * The <code>ImageOutputStream</code> or other <code>Object</code> * set by <code>setOutput</code> and retrieved by * <code>getOutput</code>. By default it is initialized to * <code>null</code>. */ protected Object output = null; /** * An array of <code>Locale</code>s that may be used to localize * warning messages and compression setting values, or * <code>null</code> if localization is not supported. By default * it is initialized to <code>null</code>. */ protected Locale[] availableLocales = null; /** * The current <code>Locale</code> to be used for localization, or * <code>null</code> if none has been set. By default it is * initialized to <code>null</code>. */ protected Locale locale = null; /** * A <code>List</code> of currently registered * <code>IIOWriteWarningListener</code>s, initialized by default to * <code>null</code>, which is synonymous with an empty * <code>List</code>. */ protected List<IIOWriteWarningListener> warningListeners = null; /** * A <code>List</code> of <code>Locale</code>s, one for each * element of <code>warningListeners</code>, initialized by default * <code>null</code>, which is synonymous with an empty * <code>List</code>. */ protected List<Locale> warningLocales = null; /** * A <code>List</code> of currently registered * <code>IIOWriteProgressListener</code>s, initialized by default * <code>null</code>, which is synonymous with an empty * <code>List</code>. */ protected List<IIOWriteProgressListener> progressListeners = null; /** * If <code>true</code>, the current write operation should be * aborted. */ private boolean abortFlag = false; /** * Constructs an <code>ImageWriter</code> and sets its * <code>originatingProvider</code> instance variable to the * supplied value. * * <p> Subclasses that make use of extensions should provide a * constructor with signature <code>(ImageWriterSpi, * Object)</code> in order to retrieve the extension object. If * the extension object is unsuitable, an * <code>IllegalArgumentException</code> should be thrown. * * @param originatingProvider the <code>ImageWriterSpi</code> that * is constructing this object, or <code>null</code>. */ protected ImageWriter(ImageWriterSpi originatingProvider) { this.originatingProvider = originatingProvider; } /** * Returns the <code>ImageWriterSpi</code> object that created * this <code>ImageWriter</code>, or <code>null</code> if this * object was not created through the <code>IIORegistry</code>. * * <p> The default implementation returns the value of the * <code>originatingProvider</code> instance variable. * * @return an <code>ImageWriterSpi</code>, or <code>null</code>. * * @see ImageWriterSpi */ public ImageWriterSpi getOriginatingProvider() { return originatingProvider; } /** * Sets the destination to the given * <code>ImageOutputStream</code> or other <code>Object</code>. * The destination is assumed to be ready to accept data, and will * not be closed at the end of each write. This allows distributed * imaging applications to transmit a series of images over a * single network connection. If <code>output</code> is * <code>null</code>, any currently set output will be removed. * * <p> If <code>output</code> is an * <code>ImageOutputStream</code>, calls to the * <code>write</code>, <code>writeToSequence</code>, and * <code>prepareWriteEmpty</code>/<code>endWriteEmpty</code> * methods will preserve the existing contents of the stream. * Other write methods, such as <code>writeInsert</code>, * <code>replaceStreamMetadata</code>, * <code>replaceImageMetadata</code>, <code>replacePixels</code>, * <code>prepareInsertEmpty</code>/<code>endInsertEmpty</code>, * and <code>endWriteSequence</code>, require the full contents * of the stream to be readable and writable, and may alter any * portion of the stream. * * <p> Use of a general <code>Object</code> other than an * <code>ImageOutputStream</code> is intended for writers that * interact directly with an output device or imaging protocol. * The set of legal classes is advertised by the writer's service * provider's <code>getOutputTypes</code> method; most writers * will return a single-element array containing only * <code>ImageOutputStream.class</code> to indicate that they * accept only an <code>ImageOutputStream</code>. * * <p> The default implementation sets the <code>output</code> * instance variable to the value of <code>output</code> after * checking <code>output</code> against the set of classes * advertised by the originating provider, if there is one. * * @param output the <code>ImageOutputStream</code> or other * <code>Object</code> to use for future writing. * * @exception IllegalArgumentException if <code>output</code> is * not an instance of one of the classes returned by the * originating service provider's <code>getOutputTypes</code> * method. * * @see #getOutput */ public void setOutput(Object output) { if (output != null) { ImageWriterSpi provider = getOriginatingProvider(); if (provider != null) { Class[] classes = provider.getOutputTypes(); boolean found = false; for (int i = 0; i < classes.length; i++) { if (classes[i].isInstance(output)) { found = true; break; } } if (!found) { throw new IllegalArgumentException("Illegal output type!"); } } } this.output = output; } /** * Returns the <code>ImageOutputStream</code> or other * <code>Object</code> set by the most recent call to the * <code>setOutput</code> method. If no destination has been * set, <code>null</code> is returned. * * <p> The default implementation returns the value of the * <code>output</code> instance variable. * * @return the <code>Object</code> that was specified using * <code>setOutput</code>, or <code>null</code>. * * @see #setOutput */ public Object getOutput() { return output; } // Localization /** * Returns an array of <code>Locale</code>s that may be used to * localize warning listeners and compression settings. A return * value of <code>null</code> indicates that localization is not * supported. * * <p> The default implementation returns a clone of the * <code>availableLocales</code> instance variable if it is * non-<code>null</code>, or else returns <code>null</code>. * * @return an array of <code>Locale</code>s that may be used as * arguments to <code>setLocale</code>, or <code>null</code>. */ public Locale[] getAvailableLocales() { return (availableLocales == null) ? null : (Locale[])availableLocales.clone(); } /** * Sets the current <code>Locale</code> of this * <code>ImageWriter</code> to the given value. A value of * <code>null</code> removes any previous setting, and indicates * that the writer should localize as it sees fit. * * <p> The default implementation checks <code>locale</code> * against the values returned by * <code>getAvailableLocales</code>, and sets the * <code>locale</code> instance variable if it is found. If * <code>locale</code> is <code>null</code>, the instance variable * is set to <code>null</code> without any checking. * * @param locale the desired <code>Locale</code>, or * <code>null</code>. * * @exception IllegalArgumentException if <code>locale</code> is * non-<code>null</code> but is not one of the values returned by * <code>getAvailableLocales</code>. * * @see #getLocale */ public void setLocale(Locale locale) { if (locale != null) { Locale[] locales = getAvailableLocales(); boolean found = false; if (locales != null) { for (int i = 0; i < locales.length; i++) { if (locale.equals(locales[i])) { found = true; break; } } } if (!found) { throw new IllegalArgumentException("Invalid locale!"); } } this.locale = locale; } /** * Returns the currently set <code>Locale</code>, or * <code>null</code> if none has been set. * * <p> The default implementation returns the value of the * <code>locale</code> instance variable. * * @return the current <code>Locale</code>, or <code>null</code>. * * @see #setLocale */ public Locale getLocale() { return locale; } // Write params /** * Returns a new <code>ImageWriteParam</code> object of the * appropriate type for this file format containing default * values, that is, those values that would be used * if no <code>ImageWriteParam</code> object were specified. This * is useful as a starting point for tweaking just a few parameters * and otherwise leaving the default settings alone. * * <p> The default implementation constructs and returns a new * <code>ImageWriteParam</code> object that does not allow tiling, * progressive encoding, or compression, and that will be * localized for the current <code>Locale</code> (<i>i.e.</i>, * what you would get by calling <code>new * ImageWriteParam(getLocale())</code>. * * <p> Individual plug-ins may return an instance of * <code>ImageWriteParam</code> with additional optional features * enabled, or they may return an instance of a plug-in specific * subclass of <code>ImageWriteParam</code>. * * @return a new <code>ImageWriteParam</code> object containing * default values. */ public ImageWriteParam getDefaultWriteParam() { return new ImageWriteParam(getLocale()); } // Metadata /** * Returns an <code>IIOMetadata</code> object containing default * values for encoding a stream of images. The contents of the * object may be manipulated using either the XML tree structure * returned by the <code>IIOMetadata.getAsTree</code> method, an * <code>IIOMetadataController</code> object, or via plug-in * specific interfaces, and the resulting data supplied to one of * the <code>write</code> methods that take a stream metadata * parameter. * * <p> An optional <code>ImageWriteParam</code> may be supplied * for cases where it may affect the structure of the stream * metadata. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * <p> Writers that do not make use of stream metadata * (<i>e.g.</i>, writers for single-image formats) should return * <code>null</code>. * * @param param an <code>ImageWriteParam</code> that will be used to * encode the image, or <code>null</code>. * * @return an <code>IIOMetadata</code> object. */ public abstract IIOMetadata getDefaultStreamMetadata(ImageWriteParam param); /** * Returns an <code>IIOMetadata</code> object containing default * values for encoding an image of the given type. The contents * of the object may be manipulated using either the XML tree * structure returned by the <code>IIOMetadata.getAsTree</code> * method, an <code>IIOMetadataController</code> object, or via * plug-in specific interfaces, and the resulting data supplied to * one of the <code>write</code> methods that take a stream * metadata parameter. * * <p> An optional <code>ImageWriteParam</code> may be supplied * for cases where it may affect the structure of the image * metadata. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * @param imageType an <code>ImageTypeSpecifier</code> indicating the * format of the image to be written later. * @param param an <code>ImageWriteParam</code> that will be used to * encode the image, or <code>null</code>. * * @return an <code>IIOMetadata</code> object. */ public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param); // comment inherited public abstract IIOMetadata convertStreamMetadata(IIOMetadata inData, ImageWriteParam param); // comment inherited public abstract IIOMetadata convertImageMetadata(IIOMetadata inData, ImageTypeSpecifier imageType, ImageWriteParam param); // Thumbnails /** * Returns the number of thumbnails suported by the format being * written, given the image type and any additional write * parameters and metadata objects that will be used during * encoding. A return value of <code>-1</code> indicates that * insufficient information is available. * * <p> An <code>ImageWriteParam</code> may optionally be supplied * for cases where it may affect thumbnail handling. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * <p> The default implementation returns 0. * * @param imageType an <code>ImageTypeSpecifier</code> indicating * the type of image to be written, or <code>null</code>. * @param param the <code>ImageWriteParam</code> that will be used for * writing, or <code>null</code>. * @param streamMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * @param imageMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * * @return the number of thumbnails that may be written given the * supplied parameters, or <code>-1</code> if insufficient * information is available. */ public int getNumThumbnailsSupported(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata) { return 0; } /** * Returns an array of <code>Dimension</code>s indicating the * legal size ranges for thumbnail images as they will be encoded * in the output file or stream. This information is merely * advisory; the writer will resize any supplied thumbnails as * necessary. * * <p> The information is returned as a set of pairs; the first * element of a pair contains an (inclusive) minimum width and * height, and the second element contains an (inclusive) maximum * width and height. Together, each pair defines a valid range of * sizes. To specify a fixed size, the same width and height will * appear for both elements. A return value of <code>null</code> * indicates that the size is arbitrary or unknown. * * <p> An <code>ImageWriteParam</code> may optionally be supplied * for cases where it may affect thumbnail handling. * * <p> If the supplied <code>ImageWriteParam</code> contains * optional setting values not supported by this writer (<i>e.g.</i> * progressive encoding or any format-specific settings), they * will be ignored. * * <p> The default implementation returns <code>null</code>. * * @param imageType an <code>ImageTypeSpecifier</code> indicating the * type of image to be written, or <code>null</code>. * @param param the <code>ImageWriteParam</code> that will be used for * writing, or <code>null</code>. * @param streamMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * @param imageMetadata an <code>IIOMetadata</code> object that will * be used for writing, or <code>null</code>. * * @return an array of <code>Dimension</code>s with an even length * of at least two, or <code>null</code>. */ public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType, ImageWriteParam param,