1. /*

  2.  * @(#)ImageConsumer.java	1.17 00/02/02

  3.  *

  4.  * Copyright 1995-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.awt.image;

  12. 

  13. import java.util.Hashtable;

  14. 

  15. /**

  16.  * The interface for objects expressing interest in image data through

  17.  * the ImageProducer interfaces.  When a consumer is added to an image

  18.  * producer, the producer delivers all of the data about the image

  19.  * using the method calls defined in this interface.

  20.  *

  21.  * @see ImageProducer

  22.  *

  23.  * @version	1.17 02/02/00

  24.  * @author 	Jim Graham

  25.  */

  26. public interface ImageConsumer {

  27.     /**

  28.      * The dimensions of the source image are reported using the

  29.      * setDimensions method call.

  30.      */

  31.     void setDimensions(int width, int height);

  32. 

  33.     /**

  34.      * Sets the extensible list of properties associated with this image.

  35.      */

  36.     void setProperties(Hashtable props);

  37. 

  38.     /**

  39.      * The ColorModel object used for the majority of

  40.      * the pixels reported using the setPixels method

  41.      * calls.  Note that each set of pixels delivered using setPixels

  42.      * contains its own ColorModel object, so no assumption should

  43.      * be made that this model will be the only one used in delivering

  44.      * pixel values.  A notable case where multiple ColorModel objects

  45.      * may be seen is a filtered image when for each set of pixels

  46.      * that it filters, the filter

  47.      * determines  whether the

  48.      * pixels can be sent on untouched, using the original ColorModel,

  49.      * or whether the pixels should be modified (filtered) and passed

  50.      * on using a ColorModel more convenient for the filtering process.

  51.      * @see ColorModel

  52.      */

  53.     void setColorModel(ColorModel model);

  54. 

  55.     /**

  56.      * The ImageProducer can deliver the pixels in any order, but

  57.      * the ImageConsumer may be able to scale or convert the pixels

  58.      * to the destination ColorModel more efficiently or with higher

  59.      * quality if it knows some information about how the pixels will

  60.      * be delivered up front.  The setHints method should be called

  61.      * before any calls to any of the setPixels methods with a bit mask

  62.      * of hints about the manner in which the pixels will be delivered.

  63.      * If the ImageProducer does not follow the guidelines for the

  64.      * indicated hint, the results are undefined.

  65.      */

  66.     void setHints(int hintflags);

  67. 

  68.     /**

  69.      * The pixels will be delivered in a random order.  This tells the

  70.      * ImageConsumer not to use any optimizations that depend on the

  71.      * order of pixel delivery, which should be the default assumption

  72.      * in the absence of any call to the setHints method.

  73.      * @see #setHints

  74.      */

  75.     int RANDOMPIXELORDER = 1;

  76. 

  77.     /**

  78.      * The pixels will be delivered in top-down, left-to-right order.

  79.      * @see #setHints

  80.      */

  81.     int TOPDOWNLEFTRIGHT = 2;

  82. 

  83.     /**

  84.      * The pixels will be delivered in (multiples of) complete scanlines

  85.      * at a time.

  86.      * @see #setHints

  87.      */

  88.     int COMPLETESCANLINES = 4;

  89. 

  90.     /**

  91.      * The pixels will be delivered in a single pass.  Each pixel will

  92.      * appear in only one call to any of the setPixels methods.  An

  93.      * example of an image format which does not meet this criterion

  94.      * is a progressive JPEG image which defines pixels in multiple

  95.      * passes, each more refined than the previous.

  96.      * @see #setHints

  97.      */

  98.     int SINGLEPASS = 8;

  99. 

  100.     /**

  101.      * The image contain a single static image.  The pixels will be defined

  102.      * in calls to the setPixels methods and then the imageComplete method

  103.      * will be called with the STATICIMAGEDONE flag after which no more

  104.      * image data will be delivered.  An example of an image type which

  105.      * would not meet these criteria would be the output of a video feed,

  106.      * or the representation of a 3D rendering being manipulated

  107.      * by the user.  The end of each frame in those types of images will

  108.      * be indicated by calling imageComplete with the SINGLEFRAMEDONE flag.

  109.      * @see #setHints

  110.      * @see #imageComplete

  111.      */

  112.     int SINGLEFRAME = 16;

  113. 

  114.     /**

  115.      * The pixels of the image are delivered using one or more calls

  116.      * to the setPixels method.  Each call specifies the location and

  117.      * size of the rectangle of source pixels that are contained in

  118.      * the array of pixels.  The specified ColorModel object should

  119.      * be used to convert the pixels into their corresponding color

  120.      * and alpha components.  Pixel (m,n) is stored in the pixels array

  121.      * at index (n * scansize + m + off).  The pixels delivered using

  122.      * this method are all stored as bytes.

  123.      * @see ColorModel

  124.      */

  125.     void setPixels(int x, int y, int w, int h,

  126. 		   ColorModel model, byte pixels[], int off, int scansize);

  127. 

  128.     /**

  129.      * The pixels of the image are delivered using one or more calls

  130.      * to the setPixels method.  Each call specifies the location and

  131.      * size of the rectangle of source pixels that are contained in

  132.      * the array of pixels.  The specified ColorModel object should

  133.      * be used to convert the pixels into their corresponding color

  134.      * and alpha components.  Pixel (m,n) is stored in the pixels array

  135.      * at index (n * scansize + m + off).  The pixels delivered using

  136.      * this method are all stored as ints.

  137.      * @see ColorModel

  138.      */

  139.     void setPixels(int x, int y, int w, int h,

  140. 		   ColorModel model, int pixels[], int off, int scansize);

  141. 

  142.     /**

  143.      * The imageComplete method is called when the ImageProducer is

  144.      * finished delivering all of the pixels that the source image

  145.      * contains, or when a single frame of a multi-frame animation has

  146.      * been completed, or when an error in loading or producing the

  147.      * image has occured.  The ImageConsumer should remove itself from the

  148.      * list of consumers registered with the ImageProducer at this time,

  149.      * unless it is interested in successive frames.

  150.      * @see ImageProducer#removeConsumer

  151.      */

  152.     void imageComplete(int status);

  153. 

  154.     /**

  155.      * An error was encountered while producing the image.

  156.      * @see #imageComplete

  157.      */

  158.     int IMAGEERROR = 1;

  159. 

  160.     /**

  161.      * One frame of the image is complete but there are more frames

  162.      * to be delivered.

  163.      * @see #imageComplete

  164.      */

  165.     int SINGLEFRAMEDONE = 2;

  166. 

  167.     /**

  168.      * The image is complete and there are no more pixels or frames

  169.      * to be delivered.

  170.      * @see #imageComplete

  171.      */

  172.     int STATICIMAGEDONE = 3;

  173. 

  174.     /**

  175.      * The image creation process was deliberately aborted.

  176.      * @see #imageComplete

  177.      */

  178.     int IMAGEABORTED = 4;

  179. }