ImageConsumer


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