001: /*
002: * @(#)BufferedImagePeer.java 1.12 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 sun.awt.image;
029:
030: import java.awt.image.ColorModel;
031: import java.awt.image.ImageObserver;
032: import java.awt.image.ImageProducer;
033: import java.awt.image.BufferedImage;
034: import java.awt.Graphics;
035:
036: /** Provides a peer for the implementation of BufferedImage. In basis and personal
037: profile, BufferedImage is a very much stripped down version of its J2SE couterpart.
038: In effect, it only allows the getting and setting of RGBs and cannot be constructed
039: with any public constructors. Instead, it can only be constructed by the
040: <code>GraphicsConfiguration.createCompatiableImage</create> method. The result is
041: that BufferedImage in basis and personal is abstract and final and an instance can only
042: be created via the factory method. This has the advantage of reducing the graphics
043: formats to be supported by BufferedImage to the formats of the native graphics library.
044: To implement BufferedImage this interface is used to provide an interface to the implemntation.
045: BufferedImage delegates its method calls to an instance of this interface.
046:
047: @author Nicholas Allen */
048:
049: public interface BufferedImagePeer {
050: /**
051: * Returns the image type. If it is not one of the known types,
052: * TYPE_CUSTOM is returned.
053: * @return the image type of this <code>BufferedImage</code>.
054: * @see #TYPE_INT_RGB
055: * @see #TYPE_INT_ARGB
056: * @see #TYPE_INT_ARGB_PRE
057: * @see #TYPE_INT_BGR
058: * @see #TYPE_3BYTE_BGR
059: * @see #TYPE_4BYTE_ABGR
060: * @see #TYPE_4BYTE_ABGR_PRE
061: * @see #TYPE_BYTE_GRAY
062: * @see #TYPE_BYTE_BINARY
063: * @see #TYPE_BYTE_INDEXED
064: * @see #TYPE_USHORT_GRAY
065: * @see #TYPE_USHORT_565_RGB
066: * @see #TYPE_USHORT_555_RGB
067: * @see #TYPE_CUSTOM
068: */
069:
070: int getType();
071:
072: /**
073: * Returns the <code>ColorModel</code>.
074: * @return the <code>ColorModel</code> of this
075: * <code>BufferedImage</code>.
076: */
077: ColorModel getColorModel();
078:
079: /**
080: * Returns an integer pixel in the default RGB color model
081: * (TYPE_INT_ARGB) and default sRGB colorspace. Color
082: * conversion takes place if this default model does not match
083: * the image <code>ColorModel</code>. There are only 8-bits of
084: * precision for each color component in the returned data when using
085: * this method.
086: * @param x, y the coordinates of the pixel from which to get
087: * the pixel in the default RGB color model and sRGB
088: * color space
089: * @return an integer pixel in the default RGB color model and
090: * default sRGB colorspace.
091: */
092: int getRGB(int x, int y);
093:
094: /**
095: * Returns an array of integer pixels in the default RGB color model
096: * (TYPE_INT_ARGB) and default sRGB color space,
097: * from a portion of the image data. Color conversion takes
098: * place if the default model does not match the image
099: * <code>ColorModel</code>. There are only 8-bits of precision for
100: * each color component in the returned data when
101: * using this method. With a specified coordinate (x, y) in the
102: * image, the ARGB pixel can be accessed in this way:
103: * <pre>
104: * pixel = rgbArray[offset + (y-startY)*scansize + (x-startX)];
105: * </pre>
106: * @param startX, startY the starting coordinates
107: * @param w width of region
108: * @param h height of region
109: * @param rgbArray if not <code>null</code>, the rgb pixels are
110: * written here
111: * @param offset offset into the <code>rgbArray</code>
112: * @param scansize scanline stride for the <code>rgbArray</code>
113: * @return array of RGB pixels.
114: * @exception <code>IllegalArgumentException</code> if an unknown
115: * datatype is specified
116: */
117: int[] getRGB(int startX, int startY, int w, int h, int[] rgbArray,
118: int offset, int scansize);
119:
120: /**
121: * Sets a pixel in this <code>BufferedImage</code> to the specified
122: * RGB value. The pixel is assumed to be in the default RGB color
123: * model, TYPE_INT_ARGB, and default sRGB color space. For images
124: * with an <code>IndexColorModel</code>, the index with the nearest
125: * color is chosen.
126: * @param x, y the coordinates of the pixel to set
127: * @param rgb the RGB value
128: */
129: void setRGB(int x, int y, int rgb);
130:
131: /**
132: * Sets an array of integer pixels in the default RGB color model
133: * (TYPE_INT_ARGB) and default sRGB color space,
134: * into a portion of the image data. Color conversion takes place
135: * if the default model does not match the image
136: * <code>ColorModel</code>. There are only 8-bits of precision for
137: * each color component in the returned data when
138: * using this method. With a specified coordinate (x, y) in the
139: * this image, the ARGB pixel can be accessed in this way:
140: * <pre>
141: * pixel = rgbArray[offset + (y-startY)*scansize + (x-startX)];
142: * </pre>
143: * WARNING: No dithering takes place.
144: *
145: * @param startX, startY the starting coordinates
146: * @param w width of the region
147: * @param h height of the region
148: * @param rgbArray the rgb pixels
149: * @param offset offset into the <code>rgbArray</code>
150: * @param scansize scanline stride for the <code>rgbArray</code>
151: */
152: void setRGB(int startX, int startY, int w, int h, int[] rgbArray,
153: int offset, int scansize);
154:
155: /**
156: * Returns the width of the <code>BufferedImage</code>.
157: * @return the width of this <code>BufferedImage</code>.
158: */
159: int getWidth();
160:
161: /**
162: * Returns the height of the <code>BufferedImage</code>.
163: * @return the height of this <code>BufferedImage</code>.
164: */
165: int getHeight();
166:
167: /**
168: * Returns the actual width of the image. If the width is not known
169: * yet then the {@link ImageObserver} is notified later and
170: * <code>-1</code> is returned.
171: * @param observer the <code>ImageObserver</code> that receives
172: * information about the image
173: * @return the width of the image or <code>-1</code> if the width
174: * is not yet known.
175: * @see java.awt.Image#getHeight(ImageObserver)
176: * @see ImageObserver
177: */
178: int getWidth(ImageObserver observer);
179:
180: /**
181: * Returns the actual height of the image. If the height is not known
182: * yet then the <code>ImageObserver</code> is notified later and
183: * <code>-1</code> is returned.
184: * @param observer the <code>ImageObserver</code> that receives
185: * information about the image
186: * @return the height of the image or <code>-1</code> if the height
187: * is not yet known.
188: * @see java.awt.Image#getWidth(ImageObserver)
189: * @see ImageObserver
190: */
191: int getHeight(ImageObserver observer);
192:
193: /**
194: * Returns the object that produces the pixels for the image.
195: * @return the {@link ImageProducer} that is used to produce the
196: * pixels for this image.
197: * @see ImageProducer
198: */
199: ImageProducer getSource();
200:
201: /**
202: * Returns a property of the image by name. Individual property names
203: * are defined by the various image formats. If a property is not
204: * defined for a particular image, this method returns the
205: * <code>UndefinedProperty</code> field. If the properties
206: * for this image are not yet known, then this method returns
207: * <code>null</code> and the <code>ImageObserver</code> object is
208: * notified later. The property name "comment" should be used to
209: * store an optional comment that can be presented to the user as a
210: * description of the image, its source, or its author.
211: * @param name the property name
212: * @param observer the <code>ImageObserver</code> that receives
213: * notification regarding image information
214: * @return an {@link Object} that is the property referred to by the
215: * specified <code>name</code> or <code>null</code> if the
216: * properties of this image are not yet known.
217: * @see ImageObserver
218: * @see java.awt.Image#UndefinedProperty
219: */
220: Object getProperty(String name, ImageObserver observer);
221:
222: /**
223: * Returns a property of the image by name.
224: * @param name the property name
225: * @return an <code>Object</code> that is the property referred to by
226: * the specified <code>name</code>.
227: */
228: Object getProperty(String name);
229:
230: /**
231: * Flushes all resources being used to cache optimization information.
232: * The underlying pixel data is unaffected.
233: */
234: void flush();
235:
236: /**
237: * This method returns a {@link Graphics2D}, but is here
238: * for backwards compatibility. {@link #createGraphics() createGraphics} is more
239: * convenient, since it is declared to return a
240: * <code>Graphics2D</code>.
241: * @return a <code>Graphics2D</code>, which can be used to draw into
242: * this image.
243: */
244: Graphics getGraphics();
245:
246: /**
247: * Returns a subimage defined by a specified rectangular region.
248: * The returned <code>BufferedImage</code> shares the same
249: * data array as the original image.
250: * @param x, y the coordinates of the upper-left corner of the
251: * specified rectangular region
252: * @param w the width of the specified rectangular region
253: * @param h the height of the specified rectangular region
254: * @return a <code>BufferedImage</code> that is the subimage of this
255: * <code>BufferedImage</code>.
256: * @exception <code>RasterFormatException</code> if the specified
257: * area is not contained within this <code>BufferedImage</code>.
258: */
259: BufferedImage getSubimage(int x, int y, int w, int h);
260:
261: /**
262: * Returns an array of names recognized by
263: * {@link #getProperty(String) getProperty(String)}
264: * or <code>null</code>, if no property names are recognized.
265: * @return a <code>String</code> array containing all of the property
266: * names that <code>getProperty(String)</code> recognizes;
267: * or <code>null</code> if no property names are recognized.
268: */
269: String[] getPropertyNames();
270: }
|