View Javadoc
1   /*
2    * Copyright (c) 1995, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.awt.image;
27  
28  import java.util.Hashtable;
29  
30  
31  /**
32   * The interface for objects expressing interest in image data through
33   * the ImageProducer interfaces.  When a consumer is added to an image
34   * producer, the producer delivers all of the data about the image
35   * using the method calls defined in this interface.
36   *
37   * @see ImageProducer
38   *
39   * @author      Jim Graham
40   */
41  public interface ImageConsumer {
42      /**
43       * The dimensions of the source image are reported using the
44       * setDimensions method call.
45       * @param width the width of the source image
46       * @param height the height of the source image
47       */
48      void setDimensions(int width, int height);
49  
50      /**
51       * Sets the extensible list of properties associated with this image.
52       * @param props the list of properties to be associated with this
53       *        image
54       */
55      void setProperties(Hashtable<?,?> props);
56  
57      /**
58       * Sets the ColorModel object used for the majority of
59       * the pixels reported using the setPixels method
60       * calls.  Note that each set of pixels delivered using setPixels
61       * contains its own ColorModel object, so no assumption should
62       * be made that this model will be the only one used in delivering
63       * pixel values.  A notable case where multiple ColorModel objects
64       * may be seen is a filtered image when for each set of pixels
65       * that it filters, the filter
66       * determines  whether the
67       * pixels can be sent on untouched, using the original ColorModel,
68       * or whether the pixels should be modified (filtered) and passed
69       * on using a ColorModel more convenient for the filtering process.
70       * @param model the specified <code>ColorModel</code>
71       * @see ColorModel
72       */
73      void setColorModel(ColorModel model);
74  
75      /**
76       * Sets the hints that the ImageConsumer uses to process the
77       * pixels delivered by the ImageProducer.
78       * The ImageProducer can deliver the pixels in any order, but
79       * the ImageConsumer may be able to scale or convert the pixels
80       * to the destination ColorModel more efficiently or with higher
81       * quality if it knows some information about how the pixels will
82       * be delivered up front.  The setHints method should be called
83       * before any calls to any of the setPixels methods with a bit mask
84       * of hints about the manner in which the pixels will be delivered.
85       * If the ImageProducer does not follow the guidelines for the
86       * indicated hint, the results are undefined.
87       * @param hintflags a set of hints that the ImageConsumer uses to
88       *        process the pixels
89       */
90      void setHints(int hintflags);
91  
92      /**
93       * The pixels will be delivered in a random order.  This tells the
94       * ImageConsumer not to use any optimizations that depend on the
95       * order of pixel delivery, which should be the default assumption
96       * in the absence of any call to the setHints method.
97       * @see #setHints
98       */
99      int RANDOMPIXELORDER = 1;
100 
101     /**
102      * The pixels will be delivered in top-down, left-to-right order.
103      * @see #setHints
104      */
105     int TOPDOWNLEFTRIGHT = 2;
106 
107     /**
108      * The pixels will be delivered in (multiples of) complete scanlines
109      * at a time.
110      * @see #setHints
111      */
112     int COMPLETESCANLINES = 4;
113 
114     /**
115      * The pixels will be delivered in a single pass.  Each pixel will
116      * appear in only one call to any of the setPixels methods.  An
117      * example of an image format which does not meet this criterion
118      * is a progressive JPEG image which defines pixels in multiple
119      * passes, each more refined than the previous.
120      * @see #setHints
121      */
122     int SINGLEPASS = 8;
123 
124     /**
125      * The image contain a single static image.  The pixels will be defined
126      * in calls to the setPixels methods and then the imageComplete method
127      * will be called with the STATICIMAGEDONE flag after which no more
128      * image data will be delivered.  An example of an image type which
129      * would not meet these criteria would be the output of a video feed,
130      * or the representation of a 3D rendering being manipulated
131      * by the user.  The end of each frame in those types of images will
132      * be indicated by calling imageComplete with the SINGLEFRAMEDONE flag.
133      * @see #setHints
134      * @see #imageComplete
135      */
136     int SINGLEFRAME = 16;
137 
138     /**
139      * Delivers the pixels of the image with one or more calls
140      * to this method.  Each call specifies the location and
141      * size of the rectangle of source pixels that are contained in
142      * the array of pixels.  The specified ColorModel object should
143      * be used to convert the pixels into their corresponding color
144      * and alpha components.  Pixel (m,n) is stored in the pixels array
145      * at index (n * scansize + m + off).  The pixels delivered using
146      * this method are all stored as bytes.
147      * @param x the X coordinate of the upper-left corner of the
148      *        area of pixels to be set
149      * @param y the Y coordinate of the upper-left corner of the
150      *        area of pixels to be set
151      * @param w the width of the area of pixels
152      * @param h the height of the area of pixels
153      * @param model the specified <code>ColorModel</code>
154      * @param pixels the array of pixels
155      * @param off the offset into the <code>pixels</code> array
156      * @param scansize the distance from one row of pixels to the next in
157      * the <code>pixels</code> array
158      * @see ColorModel
159      */
160     void setPixels(int x, int y, int w, int h,
161                    ColorModel model, byte pixels[], int off, int scansize);
162 
163     /**
164      * The pixels of the image are delivered using one or more calls
165      * to the setPixels method.  Each call specifies the location and
166      * size of the rectangle of source pixels that are contained in
167      * the array of pixels.  The specified ColorModel object should
168      * be used to convert the pixels into their corresponding color
169      * and alpha components.  Pixel (m,n) is stored in the pixels array
170      * at index (n * scansize + m + off).  The pixels delivered using
171      * this method are all stored as ints.
172      * this method are all stored as ints.
173      * @param x the X coordinate of the upper-left corner of the
174      *        area of pixels to be set
175      * @param y the Y coordinate of the upper-left corner of the
176      *        area of pixels to be set
177      * @param w the width of the area of pixels
178      * @param h the height of the area of pixels
179      * @param model the specified <code>ColorModel</code>
180      * @param pixels the array of pixels
181      * @param off the offset into the <code>pixels</code> array
182      * @param scansize the distance from one row of pixels to the next in
183      * the <code>pixels</code> array
184      * @see ColorModel
185      */
186     void setPixels(int x, int y, int w, int h,
187                    ColorModel model, int pixels[], int off, int scansize);
188 
189     /**
190      * The imageComplete method is called when the ImageProducer is
191      * finished delivering all of the pixels that the source image
192      * contains, or when a single frame of a multi-frame animation has
193      * been completed, or when an error in loading or producing the
194      * image has occurred.  The ImageConsumer should remove itself from the
195      * list of consumers registered with the ImageProducer at this time,
196      * unless it is interested in successive frames.
197      * @param status the status of image loading
198      * @see ImageProducer#removeConsumer
199      */
200     void imageComplete(int status);
201 
202     /**
203      * An error was encountered while producing the image.
204      * @see #imageComplete
205      */
206     int IMAGEERROR = 1;
207 
208     /**
209      * One frame of the image is complete but there are more frames
210      * to be delivered.
211      * @see #imageComplete
212      */
213     int SINGLEFRAMEDONE = 2;
214 
215     /**
216      * The image is complete and there are no more pixels or frames
217      * to be delivered.
218      * @see #imageComplete
219      */
220     int STATICIMAGEDONE = 3;
221 
222     /**
223      * The image creation process was deliberately aborted.
224      * @see #imageComplete
225      */
226     int IMAGEABORTED = 4;
227 }