/[classpath]/classpath/javax/imageio/ImageWriter.java
ViewVC logotype

Diff of /classpath/javax/imageio/ImageWriter.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.6 by mark, Sat Jul 2 20:32:45 2005 UTC revision 1.7 by fitzsim, Sun Oct 2 05:29:55 2005 UTC
# Line 39  exception statement from your version. * Line 39  exception statement from your version. *
39  package javax.imageio;  package javax.imageio;
40    
41  import java.awt.Dimension;  import java.awt.Dimension;
42    import java.awt.Rectangle;
43    import java.awt.image.Raster;
44    import java.awt.image.RenderedImage;
45  import java.io.IOException;  import java.io.IOException;
46  import java.util.ArrayList;  import java.util.ArrayList;
47  import java.util.Iterator;  import java.util.Iterator;
# Line 51  import javax.imageio.metadata.IIOMetadat Line 54  import javax.imageio.metadata.IIOMetadat
54    
55  import javax.imageio.spi.ImageWriterSpi;  import javax.imageio.spi.ImageWriterSpi;
56    
57    /**
58     * A class for encoding images within the ImageIO framework.
59     *
60     * An ImageWriter for a given format is instantiated by an
61     * ImageWriterSpi for that format.  ImageWriterSpis are registered
62     * with the IIORegistry.
63     *
64     * The ImageWriter API supports writing animated images that may have
65     * multiple frames; to support such images many methods take an index
66     * parameter.
67     *
68     * Images may also be written in multiple passes, where each
69     * successive pass increases the level of detail in the destination
70     * image.
71     */
72  public abstract class ImageWriter  public abstract class ImageWriter
73    implements ImageTranscoder    implements ImageTranscoder
74  {  {
75    private boolean aborted;    private boolean aborted;
76        
77      /**
78       * All locales available for localization of warning messages, or
79       * null if localization is not supported.
80       */
81    protected Locale[] availableLocales;    protected Locale[] availableLocales;
82    
83      /**
84       * The current locale used to localize warning messages, or null if
85       * no locale has been set.
86       */
87    protected Locale locale;    protected Locale locale;
88    
89      /**
90       * The image writer SPI that instantiated this writer.
91       */
92    protected ImageWriterSpi originatingProvider;    protected ImageWriterSpi originatingProvider;
93    
94      /**
95       * An ImageInputStream to which image data is written.
96       */
97    protected Object output;    protected Object output;
98    
99      /**
100       * A list of installed progress listeners.  Initially null, meaning
101       * no installed listeners.
102       */
103    protected List progressListeners = new ArrayList();    protected List progressListeners = new ArrayList();
104    
105      /**
106       * A list of installed warning listeners.  Initially null, meaning
107       * no installed listeners.
108       */
109    protected List warningListeners = new ArrayList();    protected List warningListeners = new ArrayList();
110    
111      /**
112       * A list of warning locales corresponding with the list of
113       * installed warning listeners.  Initially null, meaning no locales.
114       */
115    protected List warningLocales = new ArrayList();    protected List warningLocales = new ArrayList();
116    
117      /**
118       * Construct an image writer.
119       *
120       * @param originatingProvider the provider that is constructing this
121       * image writer, or null
122       */
123    protected ImageWriter(ImageWriterSpi originatingProvider)    protected ImageWriter(ImageWriterSpi originatingProvider)
124    {    {
125      this.originatingProvider = originatingProvider;      this.originatingProvider = originatingProvider;
126    }    }
127    
128      /**
129       * Throw an IllegalStateException if output is null.
130       *
131       * @exception IllegalStateException if output is null
132       */
133    private void checkOutputSet()    private void checkOutputSet()
134    {    {
135      if (output == null)      if (output == null)
136        throw new IllegalStateException("no output set");        throw new IllegalStateException("no output set");
137    }    }
138        
139      /**
140       * Request that writing be aborted.  The unwritten portions of the
141       * destination image will be undefined.
142       *
143       * Writers should clear the abort flag before starting a write
144       * operation, then poll it periodically during the write operation.
145       */
146    public void abort()    public void abort()
147    {    {
148      aborted = true;      aborted = true;
149    }    }
150    
151      /**
152       * Check if the abort flag is set.
153       *
154       * @return true if the current write operation should be aborted,
155       * false otherwise
156       */
157    protected boolean abortRequested()    protected boolean abortRequested()
158    {    {
159      return aborted;      return aborted;
160    }    }
161    
162      /**
163       * Install a write progress listener.  This method will return
164       * immediately if listener is null.
165       *
166       * @param listener a write progress listener or null
167       */
168    public void addIIOWriteProgressListener(IIOWriteProgressListener listener)    public void addIIOWriteProgressListener(IIOWriteProgressListener listener)
169    {    {
170      if (listener == null)      if (listener == null)
# Line 93  public abstract class ImageWriter Line 173  public abstract class ImageWriter
173      progressListeners.add(listener);      progressListeners.add(listener);
174    }    }
175        
176      /**
177       * Install a write warning listener.  This method will return
178       * immediately if listener is null.  Warning messages sent to this
179       * listener will be localized using the current locale.  If the
180       * current locale is null then this writer will select a sensible
181       * default.
182       *
183       * @param listener a write warning listener
184       */
185    public void addIIOWriteWarningListener (IIOWriteWarningListener listener)    public void addIIOWriteWarningListener (IIOWriteWarningListener listener)
186    {    {
187      if (listener == null)      if (listener == null)
# Line 101  public abstract class ImageWriter Line 190  public abstract class ImageWriter
190      warningListeners.add(listener);      warningListeners.add(listener);
191    }    }
192    
193      /**
194       * Check whether a new empty image can be inserted at the given
195       * frame index.  Pixel values may be filled in later using the
196       * replacePixels methods.  Indices greater than the insertion index
197       * will be incremented.  If imageIndex is -1, the image will be
198       * appended at the end of the current image list.
199       *
200       * @param imageIndex the frame index
201       *
202       * @return true if an empty image can be inserted at imageIndex,
203       * false otherwise
204       *
205       * @exception IllegalStateException if output is null
206       * @exception IndexOutOfBoundsException if imageIndex is less than
207       * -1 or greater than the last index in the current image list
208       * @exception IOException if a write error occurs
209       */
210    public boolean canInsertEmpty(int imageIndex)    public boolean canInsertEmpty(int imageIndex)
211      throws IOException      throws IOException
212    {    {
# Line 108  public abstract class ImageWriter Line 214  public abstract class ImageWriter
214      return false;      return false;
215    }    }
216    
217      /**
218       * Check whether an image can be inserted at the given frame index.
219       * Indices greater than the insertion index will be incremented.  If
220       * imageIndex is -1, the image will be appended at the end of the
221       * current image list.
222       *
223       * @param imageIndex the frame index
224       *
225       * @return true if an image can be inserted at imageIndex, false
226       * otherwise
227       *
228       * @exception IllegalStateException if output is null
229       * @exception IndexOutOfBoundsException if imageIndex is less than
230       * -1 or greater than the last index in the current image list
231       * @exception IOException if a write error occurs
232       */
233    public boolean canInsertImage(int imageIndex)    public boolean canInsertImage(int imageIndex)
234      throws IOException      throws IOException
235    {    {
# Line 115  public abstract class ImageWriter Line 237  public abstract class ImageWriter
237      return false;      return false;
238    }    }
239    
240      /**
241       * Check whether an image can be removed from the given frame index.
242       * Indices greater than the removal index will be decremented.
243       *
244       * @param imageIndex the frame index
245       *
246       * @return true if an image can be removed from imageIndex, false
247       * otherwise
248       *
249       * @exception IllegalStateException if output is null
250       * @exception IndexOutOfBoundsException if imageIndex is less than 0
251       * or greater than the last index in the current image list
252       * @exception IOException if a write error occurs
253       */
254    public boolean canRemoveImage(int imageIndex)    public boolean canRemoveImage(int imageIndex)
255      throws IOException      throws IOException
256    {    {
# Line 122  public abstract class ImageWriter Line 258  public abstract class ImageWriter
258      return false;      return false;
259    }    }
260    
261      /**
262       * Check whether the metadata associated the image at the given
263       * frame index can be replaced.
264       *
265       * @param imageIndex the frame index
266       *
267       * @return true if the metadata associated with the image at
268       * imageIndex can be replaced, false otherwise
269       *
270       * @exception IllegalStateException if output is null
271       * @exception IndexOutOfBoundsException if imageIndex is less than 0
272       * or greater than the last index in the current image list
273       * @exception IOException if a write error occurs
274       */
275    public boolean canReplaceImageMetadata(int imageIndex)    public boolean canReplaceImageMetadata(int imageIndex)
276      throws IOException      throws IOException
277    {    {
# Line 129  public abstract class ImageWriter Line 279  public abstract class ImageWriter
279      return false;      return false;
280    }    }
281    
282      /**
283       * Check whether the pixels within the image at the given index can
284       * be replaced.
285       *
286       * @param imageIndex the frame index
287       *
288       * @return true if the pixels in the image at imageIndex can be
289       * replaced, false otherwise
290       *
291       * @exception IllegalStateException if output is null
292       * @exception IndexOutOfBoundsException if imageIndex is less than 0
293       * or greater than the last index in the current image list
294       * @exception IOException if a write error occurs
295       */
296    public boolean canReplacePixels(int imageIndex)    public boolean canReplacePixels(int imageIndex)
297      throws IOException      throws IOException
298    {    {
# Line 136  public abstract class ImageWriter Line 300  public abstract class ImageWriter
300      return false;      return false;
301    }    }
302    
303      /**
304       * Check whether the metadata associated the entire image stream can
305       * be replaced.
306       *
307       * @return true if the stream metadata can be replaced, false
308       * otherwise
309       *
310       * @exception IllegalStateException if output is null
311       * @exception IOException if a write error occurs
312       */
313    public boolean canReplaceStreamMetadata()    public boolean canReplaceStreamMetadata()
314      throws IOException      throws IOException
315    {    {
# Line 143  public abstract class ImageWriter Line 317  public abstract class ImageWriter
317      return false;      return false;
318    }    }
319    
320      /**
321       * Check whether an entire empty image, including empty metadata and
322       * empty thumbnails, can be written to the output stream, leaving
323       * pixel values to be filled in later using the replacePixels
324       * methods.
325       *
326       * @return true if an entire empty image can be written before its
327       * contents are filled in, false otherwise
328       *
329       * @exception IllegalStateException if output is null
330       * @exception IOException if a write error occurs
331       */
332    public boolean canWriteEmpty()    public boolean canWriteEmpty()
333      throws IOException      throws IOException
334    {    {
# Line 150  public abstract class ImageWriter Line 336  public abstract class ImageWriter
336      return false;      return false;
337    }    }
338    
339      /**
340       * Check if IIOImages containing raster data are supported.
341       *
342       * @return true if raster IIOImages are supported, false otherwise
343       */
344    public boolean canWriteRasters()    public boolean canWriteRasters()
345    {    {
346      return false;      return false;
347    }    }
348    
349      /**
350       * Check if an image can be appended at the end of the current list
351       * of images even if prior images have already been written.
352       *
353       * @return true if sequences of images can be written, false
354       * otherwise
355       */
356    public boolean canWriteSequence()    public boolean canWriteSequence()
357    {    {
358      return false;      return false;
359    }    }
360    
361      /**
362       * Clear the abort flag.
363       */
364    protected void clearAbortRequest()    protected void clearAbortRequest()
365    {    {
366      aborted = false;      aborted = false;
367    }    }
368      
369      /**
370       * Convert IIOMetadata from an input reader format, returning an
371       * IIOMetadata suitable for use by an image writer.
372       *
373       * The ImageTypeSpecifier specifies the destination image type.
374       *
375       * An optional ImageWriteParam argument is available in case the
376       * image writing parameters affect the metadata conversion.
377       *
378       * @param inData the metadata coming from an image reader
379       * @param imageType the output image type of the writer
380       * @param param the image writing parameters or null
381       *
382       * @return the converted metadata that should be used by the image
383       * writer, or null if this ImageTranscoder has no knowledge of the
384       * input metadata
385       *
386       * @exception IllegalArgumentException if either inData or imageType
387       * is null
388       */
389    public abstract IIOMetadata convertImageMetadata (IIOMetadata inData,    public abstract IIOMetadata convertImageMetadata (IIOMetadata inData,
390                                                      ImageTypeSpecifier imageType,                                                      ImageTypeSpecifier imageType,
391                                                      ImageWriteParam param);                                                      ImageWriteParam param);
392    
393      /**
394       * Convert IIOMetadata from an input stream format, returning an
395       * IIOMetadata suitable for use by an image writer.
396       *
397       * An optional ImageWriteParam argument is available in case the
398       * image writing parameters affect the metadata conversion.
399       *
400       * @param inData the metadata coming from an input image stream
401       * @param param the image writing parameters or null
402       *
403       * @return the converted metadata that should be used by the image
404       * writer, or null if this ImageTranscoder has no knowledge of the
405       * input metadata
406       *
407       * @exception IllegalArgumentException if inData is null
408       */
409    public abstract IIOMetadata convertStreamMetadata (IIOMetadata inData,    public abstract IIOMetadata convertStreamMetadata (IIOMetadata inData,
410                                                       ImageWriteParam param);                                                       ImageWriteParam param);
411    
412      /**
413       * Releases any resources allocated to this object.  Subsequent
414       * calls to methods on this object will produce undefined results.
415       *
416       * The default implementation does nothing; subclasses should use
417       * this method ensure that native resources are released.
418       */
419    public void dispose()    public void dispose()
420    {    {
421      // The default implementation is empty. Subclasses have to overwrite it.      // The default implementation is empty. Subclasses have to overwrite it.
422    }    }
423        
424      /**
425       * Retrieve the available locales.  Return null if no locales are
426       * available or a clone of availableLocales.
427       *
428       * @return an array of locales or null
429       */
430    public Locale[] getAvailableLocales()    public Locale[] getAvailableLocales()
431    {    {
432      return availableLocales;      return availableLocales;
433    }    }
434    
435      /**
436       * Get a metadata object appropriate for encoding an image specified
437       * by the given image type specifier and optional image write
438       * parameters.
439       *
440       * @param imageType an image type specifier
441       * @param param image writing parameters, or null
442       *
443       * @return a metadata object appropriate for encoding an image of
444       * the given type with the given parameters
445       */
446    public abstract IIOMetadata getDefaultImageMetadata (ImageTypeSpecifier imageType, ImageWriteParam param);    public abstract IIOMetadata getDefaultImageMetadata (ImageTypeSpecifier imageType, ImageWriteParam param);
447    
448      /**
449       * Get a metadata object appropriate for encoding the default image
450       * type handled by this writer, optionally considering image write
451       * parameters.
452       *
453       * @param param image writing parameters, or null
454       *
455       * @return a metadata object appropriate for encoding an image of
456       * the default type with the given parameters
457       */
458    public abstract IIOMetadata getDefaultStreamMetadata (ImageWriteParam param);    public abstract IIOMetadata getDefaultStreamMetadata (ImageWriteParam param);
459    
460      /**
461       * Retrieve the default write parameters for this writer's image
462       * format.
463       *
464       * The default implementation returns new ImageWriteParam().
465       *
466       * @return image writing parameters
467       */
468    public ImageWriteParam getDefaultWriteParam()    public ImageWriteParam getDefaultWriteParam()
469    {    {
470      return new ImageWriteParam(getLocale());      return new ImageWriteParam(getLocale());
471    }    }
472    
473      /**
474       * Get this writer's locale.  null is returned if the locale has not
475       * been set.
476       *
477       * @return this writer's locale, or null
478       */
479    public Locale getLocale()    public Locale getLocale()
480    {    {
481      return locale;      return locale;
482    }    }
483    
484    public int getNumThumbnailsSupported (ImageTypeSpecifier imageType, ImageWriteParam param,    /**
485                                          IIOMetadata streamMetadata, IIOMetadata imageMetadata)     * Get the number of thumbnails supported by this image writer,
486       * based on the given image type, image writing parameters, and
487       * stream and image metadata.  The image writing parameters are
488       * optional, in case they affect the number of thumbnails supported.
489       *
490       * @param imageType an image type specifier, or null
491       * @param param image writing parameters, or null
492       * @param streamMetadata the metadata associated with this stream,
493       * or null
494       * @param imageMetadata the metadata associated with this image, or
495       * null
496       *
497       * @return the number of thumbnails that this writer supports
498       * writing or -1 if the given information is insufficient
499       */
500      public int getNumThumbnailsSupported (ImageTypeSpecifier imageType,
501                                            ImageWriteParam param,
502                                            IIOMetadata streamMetadata,
503                                            IIOMetadata imageMetadata)
504    {    {
505      return 0;      return 0;
506    }    }
507    
508      /**
509       * Get the ImageWriterSpi that created this writer or null.
510       *
511       * @return an ImageWriterSpi, or null
512       */
513    public ImageWriterSpi getOriginatingProvider()    public ImageWriterSpi getOriginatingProvider()
514    {    {
515      return originatingProvider;      return originatingProvider;
516    }    }
517    
518      /**
519       * Get this reader's image output destination.  null is returned if
520       * the image destination has not been set.
521       *
522       * @return an image output destination object, or null
523       */
524    public Object getOutput()    public Object getOutput()
525    {    {
526      return output;      return output;
527    }    }
528    
529      /**
530       * Get the preferred sizes for thumbnails based on the given image
531       * type, image writing parameters, and stream and image metadata.
532       * The preferred sizes are returned in pairs of dimension values;
533       * the first value in the array is a dimension object representing
534       * the minimum thumbnail size, the second value is a dimension
535       * object representing a maximum thumbnail size.  The writer can
536       * select a size within the range given by each pair, or it can
537       * ignore these size hints.
538       *
539       * @param imageType an image type specifier, or null
540       * @param param image writing parameters, or null
541       * @param streamMetadata the metadata associated with this stream,
542       * or null
543       * @param imageMetadata the metadata associated with this image, or
544       * null
545       *
546       * @return an array of dimension pairs whose length is a multiple of
547       * 2, or null if there is no preferred size (any size is allowed) or
548       * if the size is unknown (insufficient information was provided)
549       */
550    public Dimension[] getPreferredThumbnailSizes (ImageTypeSpecifier imageType,    public Dimension[] getPreferredThumbnailSizes (ImageTypeSpecifier imageType,
551                                                   ImageWriteParam param,                                                   ImageWriteParam param,
552                                                   IIOMetadata streamMetadata,                                                   IIOMetadata streamMetadata,
# Line 220  public abstract class ImageWriter Line 555  public abstract class ImageWriter
555      return null;      return null;
556    }    }
557    
558      /**
559       * Notifies all installed write progress listeners that image
560       * loading has completed by calling their imageComplete methods.
561       */
562    protected void processImageComplete()    protected void processImageComplete()
563    {    {
564      Iterator it = progressListeners.iterator();      Iterator it = progressListeners.iterator();
# Line 231  public abstract class ImageWriter Line 570  public abstract class ImageWriter
570        }        }
571    }    }
572    
573      /**
574       * Notifies all installed write progress listeners that a certain
575       * percentage of the image has been loaded, by calling their
576       * imageProgress methods.
577       *
578       * @param percentageDone the percentage of image data that has been
579       * loaded
580       */
581    protected void processImageProgress(float percentageDone)    protected void processImageProgress(float percentageDone)
582    {    {
583      Iterator it = progressListeners.iterator();      Iterator it = progressListeners.iterator();
# Line 242  public abstract class ImageWriter Line 589  public abstract class ImageWriter
589        }        }
590    }    }
591    
592      /**
593       * Notifies all installed write progress listeners, by calling their
594       * imageStarted methods, that image loading has started on the given
595       * image.
596       *
597       * @param imageIndex the frame index of the image that has started
598       * loading
599       */
600    protected void processImageStarted(int imageIndex)    protected void processImageStarted(int imageIndex)
601    {    {
602      Iterator it = progressListeners.iterator();      Iterator it = progressListeners.iterator();
# Line 253  public abstract class ImageWriter Line 608  public abstract class ImageWriter
608        }        }
609    }    }
610    
611      /**
612       * Notifies all installed write progress listeners, by calling their
613       * thumbnailComplete methods, that a thumbnail has completed
614       * loading.
615       */
616    protected void processThumbnailComplete()    protected void processThumbnailComplete()
617    {    {
618      Iterator it = progressListeners.iterator();      Iterator it = progressListeners.iterator();
# Line 264  public abstract class ImageWriter Line 624  public abstract class ImageWriter
624        }        }
625    }    }
626    
627      /**
628       * Notifies all installed write progress listeners that a certain
629       * percentage of a thumbnail has been loaded, by calling their
630       * thumbnailProgress methods.
631       *
632       * @param percentageDone the percentage of thumbnail data that has
633       * been loaded
634       */
635    protected void processThumbnailProgress(float percentageDone)    protected void processThumbnailProgress(float percentageDone)
636    {    {
637      Iterator it = progressListeners.iterator();      Iterator it = progressListeners.iterator();
# Line 275  public abstract class ImageWriter Line 643  public abstract class ImageWriter
643        }        }
644    }    }
645    
646      /**
647       * Notifies all installed write progress listeners, by calling their
648       * imageStarted methods, that thumbnail loading has started on the
649       * given thumbnail of the given image.
650       *
651       * @param imageIndex the frame index of the image one of who's
652       * thumbnails has started loading
653       * @param thumbnailIndex the index of the thumbnail that has started
654       * loading
655       */
656    protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)    protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
657    {    {
658      Iterator it = progressListeners.iterator();      Iterator it = progressListeners.iterator();
# Line 286  public abstract class ImageWriter Line 664  public abstract class ImageWriter
664        }        }
665    }    }
666    
667      /**
668       * Notifies all installed warning listeners, by calling their
669       * warningOccurred methods, that a warning message has been raised.
670       *
671       * @param imageIndex the index of the image that was being written
672       * when the warning was raised
673       * @param warning the warning message
674       *
675       * @throw IllegalArgumentException if warning is null
676       */
677    protected void processWarningOccurred(int imageIndex, String warning)    protected void processWarningOccurred(int imageIndex, String warning)
678    {    {
679      Iterator it = warningListeners.iterator();      Iterator it = warningListeners.iterator();
# Line 297  public abstract class ImageWriter Line 685  public abstract class ImageWriter
685        }        }
686    }    }
687    
688      /**
689       * Notifies all installed write progress listeners that image
690       * loading has been aborted by calling their writeAborted methods.
691       */
692    protected void processWriteAborted()    protected void processWriteAborted()
693    {    {
694      Iterator it = progressListeners.iterator();      Iterator it = progressListeners.iterator();
# Line 308  public abstract class ImageWriter Line 700  public abstract class ImageWriter
700        }        }
701    }    }
702    
703      /**
704       * Uninstall all write progress listeners.
705       */
706    public void removeAllIIOWriteProgressListeners()    public void removeAllIIOWriteProgressListeners()
707    {    {
708      progressListeners.clear();      progressListeners.clear();
709    }    }
710    
711      /**
712       * Uninstall all write warning listeners.
713       */
714    public void removeAllIIOWriteWarningListeners()    public void removeAllIIOWriteWarningListeners()
715    {    {
716      progressListeners.clear();      progressListeners.clear();
717    }    }
718        
719      /**
720       * Uninstall the given write progress listener.
721       *
722       * @param listener the listener to remove
723       */
724    public void removeIIOWriteProgressListener (IIOWriteProgressListener listener)    public void removeIIOWriteProgressListener (IIOWriteProgressListener listener)
725    {    {
726      if (listener == null)      if (listener == null)
# Line 326  public abstract class ImageWriter Line 729  public abstract class ImageWriter
729      progressListeners.remove(listener);      progressListeners.remove(listener);
730    }    }
731        
732      /**
733       * Uninstall the given write warning listener.
734       *
735       * @param listener the listener to remove
736       */
737    public void removeIIOWriteWarningListener (IIOWriteWarningListener listener)    public void removeIIOWriteWarningListener (IIOWriteWarningListener listener)
738    {    {
739      if (listener == null)      if (listener == null)
# Line 334  public abstract class ImageWriter Line 742  public abstract class ImageWriter
742      warningListeners.remove(listener);      warningListeners.remove(listener);
743    }    }
744        
745      /**
746       * Reset this writer's internal state.
747       */
748    public void reset()    public void reset()
749    {    {
750      setOutput(null);      setOutput(null);
# Line 343  public abstract class ImageWriter Line 754  public abstract class ImageWriter
754      clearAbortRequest();      clearAbortRequest();
755    }    }
756        
757      /**
758       * Set the current locale or use the default locale.
759       *
760       * @param locale the locale to set, or null
761       */
762    public void setLocale(Locale locale)    public void setLocale(Locale locale)
763    {    {
764      if (locale != null)      if (locale != null)
# Line 362  public abstract class ImageWriter Line 778  public abstract class ImageWriter
778      this.locale = locale;      this.locale = locale;
779    }    }
780    
781      /**
782       * Set the output destination of the given object.  The output
783       * destination must be set before many methods can be called on this
784       * writer. (see all ImageWriter methods that throw
785       * IllegalStateException).  If input is null then the current input
786       * source will be removed.
787       *
788       * @param input the output destination object
789       *
790       * @exception IllegalArgumentException if input is not a valid input
791       * source for this writer and is not an ImageInputStream
792       */
793    public void setOutput(Object output)    public void setOutput(Object output)
794    {    {
795      if (output != null)      if (output != null)
# Line 385  public abstract class ImageWriter Line 813  public abstract class ImageWriter
813      this.output = output;      this.output = output;
814    }    }
815    
816      /**
817       * Write an image stream, including thumbnails and metadata to the
818       * output stream.  The output must have been set prior to this
819       * method being called.  Metadata associated with the stream may be
820       * supplied, or it can be left null.  IIOImage may contain raster
821       * data if this writer supports rasters, or it will contain a
822       * rendered image.  Thumbnails are resized if need be.  Image
823       * writing parameters may be specified to affect writing, or may be
824       * left null.
825       *
826       * @param streamMetadata metadata associated with this stream, or
827       * null
828       * @param image an IIOImage containing image data, metadata and
829       * thumbnails to be written
830       * @param param image writing parameters, or null
831       *
832       * @exception IllegalStateException if output is null
833       * @exception UnsupportedOperationException if image contains raster
834       * data but this writer does not support rasters
835       * @exception IllegalArgumentException if image is null
836       * @exception IOException if a write error occurs
837       */
838    public abstract void write (IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param)    public abstract void write (IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param)
839      throws IOException;      throws IOException;
840    
841      /**
842       * Complete inserting an empty image in the output stream.
843       *
844       * @exception IllegalStateException if output is null
845       * @exception UnsupportedOperationException if inserting empty
846       * images is not supported
847       * @exception IllegalArgumentException if a call to
848       * prepareInsertEmpty was not called previous to this method being
849       * called (a sequence of prepareInsertEmpty calls must be terminated
850       * by a call to endInsertEmpty)
851       * @exception IllegalArgumentException if prepareWriteEmpty was
852       * called before this method being called (without a terminating
853       * call to endWriteEmpty)
854       * @exception IllegalArgumentException if prepareReplacePixels was
855       * called before this method being called (without a terminating
856       * call to endReplacePixels)
857       * @exception IOException if a write error occurs
858       */
859      public void endInsertEmpty ()
860        throws IOException
861      {
862        if (!canInsertEmpty(0))
863          throw new UnsupportedOperationException();
864      }
865    
866      /**
867       * Complete replacing pixels in an image in the output stream.
868       *
869       * @exception IllegalStateException if output is null
870       * @exception UnsupportedOperationException if replacing pixels is
871       * not supported by this writer
872       * @exception IllegalArgumentException if prepareReplacePixels was
873       * not called before this method being called
874       * @exception IOException if a write error occurs
875       */
876      public void endReplacePixels ()
877        throws IOException
878      {
879        if (!canReplacePixels(0))
880          throw new UnsupportedOperationException();
881      }
882    
883      /**
884       * Complete writing an empty image to the image output stream.
885       *
886       * @exception IllegalStateException if output is null
887       * @exception UnsupportedOperationException if writing empty images
888       * is not supported
889       * @exception IllegalArgumentException if a call to
890       * prepareWriteEmpty was not called previous to this method being
891       * called (a sequence of prepareWriteEmpty calls must be terminated
892       * by a call to endWriteEmpty)
893       * @exception IllegalArgumentException if prepareInsertEmpty was
894       * called before this method being called (without a terminating
895       * call to endInsertEmpty)
896       * @exception IllegalArgumentException if prepareReplacePixels was
897       * called before this method being called (without a terminating
898       * call to endReplacePixels)
899       * @exception IOException if a write error occurs
900       */
901      public void endWriteEmpty ()
902        throws IOException
903      {
904        if (!canWriteEmpty())
905          throw new UnsupportedOperationException();
906      }
907    
908      /**
909       * Complete writing a sequence of images to the output stream.  This
910       * method may patch header data and write out footer data.
911       *
912       * @exception IllegalStateException if output is null
913       * @exception IllegalStateException if prepareWriteSequence has not
914       * been called
915       * @exception UnsupportedOperationException if writing a sequence of
916       * images is not supported
917       * @exception IOException if a write error occurs
918       */
919      public void endWriteSequence ()
920        throws IOException
921      {
922        checkOutputSet();
923        if (!canWriteSequence())
924          throw new UnsupportedOperationException();
925      }
926    
927      /**
928       * Start inserting an empty image in the image output stream.  All
929       * indices after the specified index are incremented.  An index of
930       * -1 implies that the empty image should be appended to the end of
931       * the current image list.
932       *
933       * The insertion that this method call starts is not complete until
934       * endInsertEmpty is called.  prepareInsertEmpty cannot be called
935       * again until endInsertEmpty is called and calls to
936       * prepareWriteEmpty and prepareInsertEmpty may not be intersperced.
937       *
938       * @param imageIndex the image index
939       * @param imageType the image type specifier
940       * @param width the image width
941       * @param height the image height
942       * @param imageMetadata the image metadata, or null
943       * @param thumbnails a list of thumbnails, or null
944       * @param param image write parameters, or null
945       *
946       * @exception IllegalStateException if output is null
947       * @exception UnsupportedOperationException if inserting empty
948       * images is not supported
949       * @exception IndexOutOfBoundsException if imageIndex is less than
950       * -1 or greater than the last index in the current image list
951       * @exception IllegalStateException if a previous call to
952       * prepareInsertEmpty was made (without a terminating call to
953       * endInsertEmpty)
954       * @exception IllegalStateException if a previous call to
955       * prepareWriteEmpty was made (without a terminating call to
956       * endWriteEmpty)
957       * @exception IllegalArgumentException if imageType is null or
958       * thumbnails contain non-BufferedImage objects
959       * @exception IllegalArgumentException if either width or height is
960       * less than 1
961       * @exception IOException if a write error occurs
962       */
963      public void prepareInsertEmpty (int imageIndex, ImageTypeSpecifier imageType,
964                                      int width, int height,
965                                      IIOMetadata imageMetadata,
966                                      List thumbnails,
967                                      ImageWriteParam param)
968        throws IOException
969      {
970        if (!canInsertEmpty(imageIndex))
971          throw new UnsupportedOperationException();
972      }
973    
974      /**
975       * Start the replacement of pixels within an image in the output
976       * stream.  Output pixels will be clipped to lie within region.
977       *
978       * @param imageIndex the index of the image in which pixels are
979       * being replaced
980       * @param region the rectangle to which to limit pixel replacement
981       *
982       * @exception IllegalStateException if output is null
983       * @exception UnsupportedOperationException if replacing pixels is
984       * not supported
985       * @exception IndexOutOfBoundsException if imageIndex is less than 0
986       * or greater than the last index in the current image list
987       * @exception IllegalStateException if a previous call to
988       * prepareReplacePixels was made (without a terminating call to
989       * endReplacePixels)
990       * @exception IllegalArgumentException if either region.width or
991       * region.height is less than 1, or if region is null
992       * @exception IOException if a write error occurs
993       */
994      public void prepareReplacePixels (int imageIndex, Rectangle region)
995        throws IOException
996      {
997        if (canReplacePixels(imageIndex))
998          throw new UnsupportedOperationException();
999      }
1000    
1001      /**
1002       * Start writing an empty image to the end of the image output
1003       * stream.
1004       *
1005       * The writing that this method call starts is not complete until
1006       * endWriteEmpty is called.  prepareWritetEmpty cannot be called
1007       * again until endWriteEmpty is called and calls to
1008       * prepareWriteEmpty and prepareInsertEmpty may not be intersperced.
1009       *
1010       * @param streamMetadata metadata associated with the stream, or null
1011       * @param imageType the image type specifier
1012       * @param width the image width
1013       * @param height the image height
1014       * @param imageMetadata the image metadata, or null
1015       * @param thumbnails a list of thumbnails, or null
1016       * @param param image write parameters, or null
1017       *
1018       * @exception IllegalStateException if output is null
1019       * @exception UnsupportedOperationException if writing empty images
1020       * is not supported
1021       * @exception IndexOutOfBoundsException if imageIndex is less than
1022       * -1 or greater than the last index in the current image list
1023       * @exception IllegalStateException if a previous call to
1024       * prepareInsertEmpty was made (without a terminating call to
1025       * endInsertEmpty)
1026       * @exception IllegalStateException if a previous call to
1027       * prepareWriteEmpty was made (without a terminating call to
1028       * endWriteEmpty)
1029       * @exception IllegalArgumentException if imageType is null or
1030       * thumbnails contain non-BufferedImage objects
1031       * @exception IllegalArgumentException if either width or height is
1032       * less than 1
1033       * @exception IOException if a write error occurs
1034       */
1035      public void prepareWriteEmpty (IIOMetadata streamMetadata,
1036                                     ImageTypeSpecifier imageType,
1037                                     int width, int height,
1038                                     IIOMetadata imageMetadata,
1039                                     List thumbnails,
1040                                     ImageWriteParam param)
1041        throws IOException
1042      {
1043        if (!canWriteEmpty())
1044          throw new UnsupportedOperationException();
1045      }
1046    
1047      /**
1048       * Start the writing of a sequence of images.
1049       *
1050       * @param streamMetadata the stream metadata, or null
1051       *
1052       * @exception IllegalStateException if output is null
1053       * @exception UnsupportedOperationException if writing sequences of
1054       * images is not supported
1055       * @exception IOException if a write error occurs
1056       */
1057      public void prepareWriteSequence (IIOMetadata streamMetadata)
1058        throws IOException
1059      {
1060        checkOutputSet();
1061        if (!canWriteSequence())
1062          throw new UnsupportedOperationException();
1063      }
1064    
1065      /**
1066       * Remove the image at the specified index from the output stream.
1067       *
1068       * @param imageIndex the frame index from which to remove the image
1069       *
1070       * @exception IllegalStateException if output is null
1071       * @exception UnsupportedOperationException if removing this image
1072       * is not supported
1073       * @exception IndexOutOfBoundsException if imageIndex is less than 0
1074       * or greater than the last index in the current image list
1075       * @exception IOException if a write error occurs
1076       */
1077      public void removeImage (int imageIndex)
1078        throws IOException
1079      {
1080        if (!canRemoveImage(imageIndex))
1081          throw new UnsupportedOperationException();
1082      }
1083    
1084      /**
1085       * Replace the metadata associated with the image at the given
1086       * index.
1087       *
1088       * @param imageIndex the index of the image whose metadata should be
1089       * replaced
1090       * @param imageMetadata the metadata, or null
1091       *
1092       * @exception IllegalStateException if output is null
1093       * @exception UnsupportedOperationException if replacing this
1094       * image's metadata is not supported
1095       * @exception IndexOutOfBoundsException if imageIndex is less than 0
1096       * or greater than the last index in the current image list
1097       * @exception IOException if a write error occurs
1098       */
1099      public void replaceImageMetadata (int imageIndex, IIOMetadata imageMetadata)
1100        throws IOException
1101      {
1102        if (!canReplaceImageMetadata(imageIndex))
1103          throw new UnsupportedOperationException();
1104      }
1105    
1106      /**
1107       * Replace a region of an image in the output stream with a portion
1108       * of the given rendered image.  The image data must be of the same
1109       * type as that in the output stream.  The destination region is
1110       * given by the image writing parameters and the source region is
1111       * the one given to prepareReplacePixels.
1112       *
1113       * @param image the rendered image with which to overwrite the image
1114       * region in the stream
1115       * @param param the image writing parameters
1116       *
1117       * @exception IllegalStateException if output is null
1118       * @exception UnsupportedOperationException if replacing pixels is
1119       * not supported
1120       * @exception IllegalStateException if prepareReplacePixels was not
1121       * called before this method was called
1122       * @exception IllegalArgumentException if image is null or if param
1123       * is null or if the overlap of the source and destination regions
1124       * contains no pixels or if the image types differ and no conversion
1125       * is possible
1126       * @exception IOException if a write error occurs
1127       */
1128      public void replacePixels (RenderedImage image,
1129                                 ImageWriteParam param)
1130        throws IOException
1131      {
1132        if (!canReplacePixels(0))
1133          throw new UnsupportedOperationException();
1134      }
1135    
1136      /**
1137       * Replace a region of an image in the output stream with a portion
1138       * of the given raster data.  The image data must be of the same
1139       * type as that in the output stream.  The destination region is
1140       * given by the image writing parameters and the source region is
1141       * the one given to prepareReplacePixels.
1142       *
1143       * @param raster the raster data with which to overwrite the image
1144       * region in the stream
1145       * @param param the image writing parameters
1146       *
1147       * @exception IllegalStateException if output is null
1148       * @exception UnsupportedOperationException if replacing pixels is
1149       * not supported
1150       * @exception IllegalStateException if prepareReplacePixels was not
1151       * called before this method was called
1152       * @exception UnsupportedOperationException if raster data is not
1153       * supported
1154       * @exception IllegalArgumentException if raster is null or if param
1155       * is null or if the overlap of the source and destination regions
1156       * contains no pixels or if the image types differ and no conversion
1157       * is possible
1158       * @exception IOException if a write error occurs
1159       */
1160      public void replacePixels (Raster raster, ImageWriteParam param)
1161        throws IOException
1162      {
1163        if (!canReplacePixels(0))
1164        throw new UnsupportedOperationException();
1165      }
1166    
1167      /**
1168       * Replace the metadata associated with this image stream.
1169       *
1170       * @param streamMetadata the stream metadata, or null
1171       *
1172       * @exception IllegalStateException if output is null
1173       * @exception UnsupportedOperationException if replacing the stream
1174       * metadata is not supported
1175       * @exception IOException if a write error occurs
1176       */
1177      public void replaceStreamMetadata (IIOMetadata streamMetadata)
1178        throws IOException
1179      {
1180        if (!canReplaceStreamMetadata())
1181          throw new UnsupportedOperationException();
1182      }
1183    
1184      /**
1185       * Write a rendered image to the output stream.
1186       *
1187       * @param image a rendered image containing image data to be written
1188       *
1189       * @exception IllegalStateException if output is null
1190       * @exception IllegalArgumentException if image is null
1191       * @exception IOException if a write error occurs
1192       */
1193      public void write (RenderedImage image)
1194        throws IOException
1195      {
1196        checkOutputSet();
1197        write (null, new IIOImage(image, null, null), null);
1198      }
1199    
1200      /**
1201       * Write a image data, metadata and thumbnails to the output stream.
1202       *
1203       * @param image image data, metadata and thumbnails to be written
1204       *
1205       * @exception IllegalStateException if output is null
1206       * @exception UnsupportedOperationException if image contains raster
1207       * data but this writer does not support rasters
1208       * @exception IllegalArgumentException if image is null
1209       * @exception IOException if a write error occurs
1210       */
1211      public void write (IIOImage image)
1212        throws IOException
1213      {
1214        checkOutputSet();
1215        write (null, image, null);
1216      }
1217    
1218      /**
1219       * Insert an image into the output stream.  Indices greater than the
1220       * specified index are incremented accordingly.  Specifying an index
1221       * of -1 causes the image to be appended at the end of the current
1222       * image list.
1223       *
1224       * @param imageIndex the frame index at which to insert the image
1225       * @param image the image data, metadata and thumbnails to be
1226       * inserted
1227       * @param the image write parameters, or null
1228       *
1229       * @exception IllegalStateException if output is null
1230       * @exception UnsupportedOperationException if image insertion is
1231       * not supported
1232       * @exception IllegalArgumentException if image is null
1233       * @exception IndexOutOfBoundsException if imageIndex is less than
1234       * -1 or greater than the last index in the current image list
1235       * @exception UnsupportedOperationException if image contains raster
1236       * data but this writer does not support rasters
1237       * @exception IOException if a write error occurs
1238       */
1239      public void writeInsert (int imageIndex, IIOImage image, ImageWriteParam param)
1240        throws IOException
1241      {
1242        if (!canInsertImage(imageIndex))
1243          throw new UnsupportedOperationException();
1244      }
1245    
1246      /**
1247       * Write a sequence of images, including thumbnails and metadata, to
1248       * the output stream.  The output must have been set prior to this
1249       * method being called.  Metadata associated with the stream may be
1250       * supplied, or it can be left null.  IIOImage may contain raster
1251       * data if this writer supports rasters, or it will contain a
1252       * rendered image.  Thumbnails are resized if need be.  Image
1253       * writing parameters may be specified to affect writing, or may be
1254       * left null.
1255       *
1256       * @param streamMetadata metadata associated with this stream, or
1257       * null
1258       * @param image an IIOImage containing image data, metadata and
1259       * thumbnails to be written
1260       * @param param image writing parameters, or null
1261       *
1262       * @exception IllegalStateException if output is null
1263       * @exception UnsupportedOperationException if writing sequences of
1264       * images is not supported
1265       * @exception IllegalArgumentException if image is null
1266       * @exception UnsupportedOperationException if image contains raster
1267       * data but this writer does not support rasters
1268       * @exception IOException if a write error occurs
1269       */
1270      public void writeToSequence (IIOImage image, ImageWriteParam param)
1271        throws IOException
1272      {
1273        if (!canWriteSequence())
1274          throw new UnsupportedOperationException();
1275      }
1276  }  }

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26