001: /*
002: * @(#)ImageConsumer.java 1.21 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.awt.image;
029:
030: import java.util.Hashtable;
031:
032: /**
033: * The interface for objects expressing interest in image data through
034: * the ImageProducer interfaces. When a consumer is added to an image
035: * producer, the producer delivers all of the data about the image
036: * using the method calls defined in this interface.
037: *
038: * @see ImageProducer
039: *
040: * @version 1.17 08/19/02
041: * @author Jim Graham
042: */
043: public interface ImageConsumer {
044: /**
045: * The dimensions of the source image are reported using the
046: * setDimensions method call.
047: */
048: void setDimensions(int width, int height);
049:
050: /**
051: * Sets the extensible list of properties associated with this image.
052: */
053: void setProperties(Hashtable props);
054:
055: /**
056: * The ColorModel object used for the majority of
057: * the pixels reported using the setPixels method
058: * calls. Note that each set of pixels delivered using setPixels
059: * contains its own ColorModel object, so no assumption should
060: * be made that this model will be the only one used in delivering
061: * pixel values. A notable case where multiple ColorModel objects
062: * may be seen is a filtered image when for each set of pixels
063: * that it filters, the filter
064: * determines whether the
065: * pixels can be sent on untouched, using the original ColorModel,
066: * or whether the pixels should be modified (filtered) and passed
067: * on using a ColorModel more convenient for the filtering process.
068: * @see ColorModel
069: */
070: void setColorModel(ColorModel model);
071:
072: /**
073: * The ImageProducer can deliver the pixels in any order, but
074: * the ImageConsumer may be able to scale or convert the pixels
075: * to the destination ColorModel more efficiently or with higher
076: * quality if it knows some information about how the pixels will
077: * be delivered up front. The setHints method should be called
078: * before any calls to any of the setPixels methods with a bit mask
079: * of hints about the manner in which the pixels will be delivered.
080: * If the ImageProducer does not follow the guidelines for the
081: * indicated hint, the results are undefined.
082: */
083: void setHints(int hintflags);
084:
085: /**
086: * The pixels will be delivered in a random order. This tells the
087: * ImageConsumer not to use any optimizations that depend on the
088: * order of pixel delivery, which should be the default assumption
089: * in the absence of any call to the setHints method.
090: * @see #setHints
091: */
092: int RANDOMPIXELORDER = 1;
093: /**
094: * The pixels will be delivered in top-down, left-to-right order.
095: * @see #setHints
096: */
097: int TOPDOWNLEFTRIGHT = 2;
098: /**
099: * The pixels will be delivered in (multiples of) complete scanlines
100: * at a time.
101: * @see #setHints
102: */
103: int COMPLETESCANLINES = 4;
104: /**
105: * The pixels will be delivered in a single pass. Each pixel will
106: * appear in only one call to any of the setPixels methods. An
107: * example of an image format which does not meet this criterion
108: * is a progressive JPEG image which defines pixels in multiple
109: * passes, each more refined than the previous.
110: * @see #setHints
111: */
112: int SINGLEPASS = 8;
113: /**
114: * The image contain a single static image. The pixels will be defined
115: * in calls to the setPixels methods and then the imageComplete method
116: * will be called with the STATICIMAGEDONE flag after which no more
117: * image data will be delivered. An example of an image type which
118: * would not meet these criteria would be the output of a video feed,
119: * or the representation of a 3D rendering being manipulated
120: * by the user. The end of each frame in those types of images will
121: * be indicated by calling imageComplete with the SINGLEFRAMEDONE flag.
122: * @see #setHints
123: * @see #imageComplete
124: */
125: int SINGLEFRAME = 16;
126:
127: /**
128: * The pixels of the image are delivered using one or more calls
129: * to the setPixels method. Each call specifies the location and
130: * size of the rectangle of source pixels that are contained in
131: * the array of pixels. The specified ColorModel object should
132: * be used to convert the pixels into their corresponding color
133: * and alpha components. Pixel (m,n) is stored in the pixels array
134: * at index (n * scansize + m + off). The pixels delivered using
135: * this method are all stored as bytes.
136: * @see ColorModel
137: */
138: void setPixels(int x, int y, int w, int h, ColorModel model,
139: byte pixels[], int off, int scansize);
140:
141: /**
142: * The pixels of the image are delivered using one or more calls
143: * to the setPixels method. Each call specifies the location and
144: * size of the rectangle of source pixels that are contained in
145: * the array of pixels. The specified ColorModel object should
146: * be used to convert the pixels into their corresponding color
147: * and alpha components. Pixel (m,n) is stored in the pixels array
148: * at index (n * scansize + m + off). The pixels delivered using
149: * this method are all stored as ints.
150: * @see ColorModel
151: */
152: void setPixels(int x, int y, int w, int h, ColorModel model,
153: int pixels[], int off, int scansize);
154:
155: /**
156: * The imageComplete method is called when the ImageProducer is
157: * finished delivering all of the pixels that the source image
158: * contains, or when a single frame of a multi-frame animation has
159: * been completed, or when an error in loading or producing the
160: * image has occured. The ImageConsumer should remove itself from the
161: * list of consumers registered with the ImageProducer at this time,
162: * unless it is interested in successive frames.
163: * @see ImageProducer#removeConsumer
164: */
165: void imageComplete(int status);
166:
167: /**
168: * An error was encountered while producing the image.
169: * @see #imageComplete
170: */
171: int IMAGEERROR = 1;
172: /**
173: * One frame of the image is complete but there are more frames
174: * to be delivered.
175: * @see #imageComplete
176: */
177: int SINGLEFRAMEDONE = 2;
178: /**
179: * The image is complete and there are no more pixels or frames
180: * to be delivered.
181: * @see #imageComplete
182: */
183: int STATICIMAGEDONE = 3;
184: /**
185: * The image creation process was deliberately aborted.
186: * @see #imageComplete
187: */
188: int IMAGEABORTED = 4;
189: }
|