imagewriter.java

gcc的组建

/* ImageWriter.java -- Encodes raster images.
   Copyright (C) 2004, 2005  Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath 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 for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package javax.imageio;

import java.awt.Dimension;
import java.awt.Rectangle;
import java.awt.image.Raster;
import java.awt.image.RenderedImage;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.ResourceBundle;
import java.util.MissingResourceException;

import javax.imageio.event.IIOWriteProgressListener;
import javax.imageio.event.IIOWriteWarningListener;
import javax.imageio.metadata.IIOMetadata;

import javax.imageio.spi.ImageWriterSpi;

/**
 * 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.
 */
public abstract class ImageWriter
  implements ImageTranscoder
{
  private boolean aborted;
  
  /**
   * All locales available for localization of warning messages, or
   * null if localization is not supported.
   */
  protected Locale[] availableLocales = null;

  /**
   * The current locale used to localize warning messages, or null if
   * no locale has been set.
   */
  protected Locale locale = null;

  /**
   * The image writer SPI that instantiated this writer.
   */
  protected ImageWriterSpi originatingProvider = null;

  /**
   * An ImageInputStream to which image data is written.
   */
  protected Object output = null;

  /**
   * A list of installed progress listeners.  Initially null, meaning
   * no installed listeners.
   */
  protected List progressListeners = null;

  /**
   * A list of installed warning listeners.  Initially null, meaning
   * no installed listeners.
   */
  protected List warningListeners = null;

  /**
   * A list of warning locales corresponding with the list of
   * installed warning listeners.  Initially null, meaning no locales.
   */
  protected List warningLocales = null;

  /**
   * Construct an image writer.
   *
   * @param originatingProvider the provider that is constructing this
   * image writer, or null
   */
  protected ImageWriter(ImageWriterSpi originatingProvider)
  {
    this.originatingProvider = originatingProvider;
  }

  /**
   * Throw an IllegalStateException if output is null.
   *
   * @exception IllegalStateException if output is null
   */
  private void checkOutputSet()
  {
    if (output == null)
      throw new IllegalStateException("no output set");
  }
  
  /**
   * 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.
   */
  public void abort()
  {
    aborted = true;
  }

  /**
   * Check if the abort flag is set.
   *
   * @return true if the current write operation should be aborted,
   * false otherwise
   */
  protected boolean abortRequested()
  {
    return aborted;
  }

  /**
   * Install a write progress listener.  This method will return
   * immediately if listener is null.
   *
   * @param listener a write progress listener or null
   */
  public void addIIOWriteProgressListener(IIOWriteProgressListener listener)
  {
    if (listener == null)
      return;
    if (progressListeners == null)
      progressListeners = new ArrayList ();
    progressListeners.add(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.
   *
   * @param listener a write warning listener
   */
  public void addIIOWriteWarningListener (IIOWriteWarningListener listener)
  {
    if (listener == null)
      return;
    if (warningListeners == null)
      warningListeners = new ArrayList ();
    warningListeners.add(listener);
  }

  /**
   * 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.
   *
   * @param imageIndex the frame index
   *
   * @return true if an empty image can be inserted at imageIndex,
   * false otherwise
   *
   * @exception IllegalStateException if output is null
   * @exception IndexOutOfBoundsException if imageIndex is less than
   * -1 or greater than the last index in the current image list
   * @exception IOException if a write error occurs
   */
  public boolean canInsertEmpty(int imageIndex)
    throws IOException
  {
    checkOutputSet();
    return false;
  }

  /**
   * 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.
   *
   * @param imageIndex the frame index
   *
   * @return true if an image can be inserted at imageIndex, false
   * otherwise
   *
   * @exception IllegalStateException if output is null
   * @exception IndexOutOfBoundsException if imageIndex is less than
   * -1 or greater than the last index in the current image list
   * @exception IOException if a write error occurs
   */
  public boolean canInsertImage(int imageIndex)
    throws IOException
  {
    checkOutputSet();
    return false;
  }

  /**
   * Check whether an image can be removed from the given frame index.
   * Indices greater than the removal index will be decremented.
   *
   * @param imageIndex the frame index
   *
   * @return true if an image can be removed from imageIndex, false
   * otherwise
   *
   * @exception IllegalStateException if output is null
   * @exception IndexOutOfBoundsException if imageIndex is less than 0
   * or greater than the last index in the current image list
   * @exception IOException if a write error occurs
   */
  public boolean canRemoveImage(int imageIndex)
    throws IOException
  {
    checkOutputSet();
    return false;
  }

  /**
   * Check whether the metadata associated the image at the given
   * frame index can be replaced.
   *
   * @param imageIndex the frame index
   *
   * @return true if the metadata associated with the image at
   * imageIndex can be replaced, false otherwise
   *
   * @exception IllegalStateException if output is null
   * @exception IndexOutOfBoundsException if imageIndex is less than 0
   * or greater than the last index in the current image list
   * @exception IOException if a write error occurs
   */
  public boolean canReplaceImageMetadata(int imageIndex)
    throws IOException
  {
    checkOutputSet();
    return false;
  }

  /**
   * Check whether the pixels within the image at the given index can
   * be replaced.
   *
   * @param imageIndex the frame index
   *
   * @return true if the pixels in the image at imageIndex can be
   * replaced, false otherwise
   *
   * @exception IllegalStateException if output is null
   * @exception IndexOutOfBoundsException if imageIndex is less than 0
   * or greater than the last index in the current image list
   * @exception IOException if a write error occurs
   */
  public boolean canReplacePixels(int imageIndex)
    throws IOException
  {
    checkOutputSet();
    return false;
  }

  /**
   * Check whether the metadata associated the entire image stream can
   * be replaced.
   *
   * @return true if the stream metadata can be replaced, false
   * otherwise
   *
   * @exception IllegalStateException if output is null
   * @exception IOException if a write error occurs
   */
  public boolean canReplaceStreamMetadata()
    throws IOException
  {
    checkOutputSet();
    return false;
  }

  /**
   * 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.
   *
   * @return true if an entire empty image can be written before its
   * contents are filled in, false otherwise
   *
   * @exception IllegalStateException if output is null
   * @exception IOException if a write error occurs
   */
  public boolean canWriteEmpty()
    throws IOException
  {
    checkOutputSet();
    return false;
  }

  /**
   * Check if IIOImages containing raster data are supported.
   *
   * @return true if raster IIOImages are supported, false otherwise
   */
  public boolean canWriteRasters()
  {
    return false;
  }

  /**
   * Check if an image can be appended at the end of the current list
   * of images even if prior images have already been written.
   *
   * @return true if sequences of images can be written, false
   * otherwise
   */
  public boolean canWriteSequence()
  {
    return false;
  }

  /**
   * Clear the abort flag.
   */
  protected void clearAbortRequest()
  {
    aborted = false;
  }

  /**
   * 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.
   *
   * @param inData the metadata coming from an image reader
   * @param imageType the output image type of the writer
   * @param param the image writing parameters or null
   *
   * @return the converted metadata that should be used by the image
   * writer, or null if this ImageTranscoder has no knowledge of the
   * input metadata
   *
   * @exception IllegalArgumentException if either inData or imageType
   * is null
   */
  public abstract IIOMetadata convertImageMetadata (IIOMetadata inData,
		                                    ImageTypeSpecifier imageType,
				                    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.
   *
   * @param inData the metadata coming from an input image stream
   * @param param the image writing parameters or null
   *
   * @return the converted metadata that should be used by the image
   * writer, or null if this ImageTranscoder has no knowledge of the
   * input metadata
   *
   * @exception IllegalArgumentException if inData is null
   */
  public abstract IIOMetadata convertStreamMetadata (IIOMetadata inData,
					             ImageWriteParam param);

  /**
   * 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.
   */
  public void dispose()
  {
    // The default implementation is empty. Subclasses have to overwrite it.
  }
  
  /**
   * Retrieve the available locales.  Return null if no locales are
   * available or a clone of availableLocales.
   *
   * @return an array of locales or null
   */
  public Locale[] getAvailableLocales()
  {
    return availableLocales;
  }

  /**
   * Get a metadata object appropriate for encoding an image specified
   * by the given image type specifier and optional image write
   * parameters.
   *
   * @param imageType an image type specifier
   * @param param image writing parameters, or null
   *
   * @return a metadata object appropriate for encoding an image of
   * the given type with the given parameters
   */
  public abstract IIOMetadata getDefaultImageMetadata (ImageTypeSpecifier imageType, ImageWriteParam param);

  /**
   * Get a metadata object appropriate for encoding the default image
   * type handled by this writer, optionally considering image write
   * parameters.
   *
   * @param param image writing parameters, or null
   *
   * @return a metadata object appropriate for encoding an image of
   * the default type with the given parameters
   */
  public abstract IIOMetadata getDefaultStreamMetadata (ImageWriteParam param);

  /**