1 /*

     2  * Copyright 1995-2006 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.awt.image;

    27 

    28 import java.util.Hashtable;

    29 

    30 /**

    31  * The interface for objects expressing interest in image data through

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

    33  * producer, the producer delivers all of the data about the image

    34  * using the method calls defined in this interface.

    35  *

    36  * @see ImageProducer

    37  *

    38  * @author      Jim Graham

    39  */

    40 public interface ImageConsumer {

    41     /**

    42      * The dimensions of the source image are reported using the

    43      * setDimensions method call.

    44      * @param width the width of the source image

    45      * @param height the height of the source image

    46      */

    47     void setDimensions(int width, int height);

    48 

    49     /**

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

    51      * @param props the list of properties to be associated with this

    52      *        image

    53      */

    54     void setProperties(Hashtable<?,?> props);

    55 

    56     /**

    57      * Sets the ColorModel object used for the majority of

    58      * the pixels reported using the setPixels method

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

    60      * contains its own ColorModel object, so no assumption should

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

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

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

    64      * that it filters, the filter

    65      * determines  whether the

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

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

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

    69      * @param model the specified <code>ColorModel</code>

    70      * @see ColorModel

    71      */

    72     void setColorModel(ColorModel model);

    73 

    74     /**

    75      * Sets the hints that the ImageConsumer uses to process the

    76      * pixels delivered by the ImageProducer.

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

    78      * the ImageConsumer may be able to scale or convert the pixels

    79      * to the destination ColorModel more efficiently or with higher

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

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

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

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

    84      * If the ImageProducer does not follow the guidelines for the

    85      * indicated hint, the results are undefined.

    86      * @param hintflags a set of hints that the ImageConsumer uses to

    87      *        process the pixels

    88      */

    89     void setHints(int hintflags);

    90 

    91     /**

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

    93      * ImageConsumer not to use any optimizations that depend on the

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

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

    96      * @see #setHints

    97      */

    98     int RANDOMPIXELORDER = 1;

    99 

   100     /**

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

   102      * @see #setHints

   103      */

   104     int TOPDOWNLEFTRIGHT = 2;

   105 

   106     /**

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

   108      * at a time.

   109      * @see #setHints

   110      */

   111     int COMPLETESCANLINES = 4;

   112 

   113     /**

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

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

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

   117      * is a progressive JPEG image which defines pixels in multiple

   118      * passes, each more refined than the previous.

   119      * @see #setHints

   120      */

   121     int SINGLEPASS = 8;

   122 

   123     /**

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

   125      * in calls to the setPixels methods and then the imageComplete method

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

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

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

   129      * or the representation of a 3D rendering being manipulated

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

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

   132      * @see #setHints

   133      * @see #imageComplete

   134      */

   135     int SINGLEFRAME = 16;

   136 

   137     /**

   138      * Delivers the pixels of the image with one or more calls

   139      * to this method.  Each call specifies the location and

   140      * size of the rectangle of source pixels that are contained in

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

   142      * be used to convert the pixels into their corresponding color

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

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

   145      * this method are all stored as bytes.

   146      * @param x the X coordinate of the upper-left corner of the

   147      *        area of pixels to be set

   148      * @param y the Y coordinate of the upper-left corner of the

   149      *        area of pixels to be set

   150      * @param w the width of the area of pixels

   151      * @param h the height of the area of pixels

   152      * @param model the specified <code>ColorModel</code>

   153      * @param pixels the array of pixels

   154      * @param off the offset into the <code>pixels</code> array

   155      * @param scansize the distance from one row of pixels to the next in

   156      * the <code>pixels</code> array

   157      * @see ColorModel

   158      */

   159     void setPixels(int x, int y, int w, int h,

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

   161 

   162     /**

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

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

   165      * size of the rectangle of source pixels that are contained in

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

   167      * be used to convert the pixels into their corresponding color

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

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

   170      * this method are all stored as ints.

   171      * this method are all stored as ints.

   172      * @param x the X coordinate of the upper-left corner of the

   173      *        area of pixels to be set

   174      * @param y the Y coordinate of the upper-left corner of the

   175      *        area of pixels to be set

   176      * @param w the width of the area of pixels

   177      * @param h the height of the area of pixels

   178      * @param model the specified <code>ColorModel</code>

   179      * @param pixels the array of pixels

   180      * @param off the offset into the <code>pixels</code> array

   181      * @param scansize the distance from one row of pixels to the next in

   182      * the <code>pixels</code> array

   183      * @see ColorModel

   184      */

   185     void setPixels(int x, int y, int w, int h,

   186                    ColorModel model, int pixels[], int off, int scansize);

   187 

   188     /**

   189      * The imageComplete method is called when the ImageProducer is

   190      * finished delivering all of the pixels that the source image

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

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

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

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

   195      * unless it is interested in successive frames.

   196      * @param status the status of image loading

   197      * @see ImageProducer#removeConsumer

   198      */

   199     void imageComplete(int status);

   200 

   201     /**

   202      * An error was encountered while producing the image.

   203      * @see #imageComplete

   204      */

   205     int IMAGEERROR = 1;

   206 

   207     /**

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

   209      * to be delivered.

   210      * @see #imageComplete

   211      */

   212     int SINGLEFRAMEDONE = 2;

   213 

   214     /**

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

   216      * to be delivered.

   217      * @see #imageComplete

   218      */

   219     int STATICIMAGEDONE = 3;

   220 

   221     /**

   222      * The image creation process was deliberately aborted.

   223      * @see #imageComplete

   224      */

   225     int IMAGEABORTED = 4;

   226 }