View Javadoc
1   /*
2    * Copyright (c) 1997, 2008, 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  /* ****************************************************************
27   ******************************************************************
28   ******************************************************************
29   *** COPYRIGHT (c) Eastman Kodak Company, 1997
30   *** As  an unpublished  work pursuant to Title 17 of the United
31   *** States Code.  All rights reserved.
32   ******************************************************************
33   ******************************************************************
34   ******************************************************************/
35  
36  package java.awt.image;
37  import java.awt.Rectangle;
38  import java.util.Dictionary;
39  import java.util.Vector;
40  
41  /**
42   * RenderedImage is a common interface for objects which contain
43   * or can produce image data in the form of Rasters.  The image
44   * data may be stored/produced as a single tile or a regular array
45   * of tiles.
46   */
47  
48  public interface RenderedImage {
49  
50      /**
51       * Returns a vector of RenderedImages that are the immediate sources of
52       * image data for this RenderedImage.  This method returns null if
53       * the RenderedImage object has no information about its immediate
54       * sources.  It returns an empty Vector if the RenderedImage object has
55       * no immediate sources.
56       * @return a Vector of <code>RenderedImage</code> objects.
57       */
58      Vector<RenderedImage> getSources();
59  
60      /**
61       * Gets a property from the property set of this image.  The set of
62       * properties and whether it is immutable is determined by the
63       * implementing class.  This method returns
64       * java.awt.Image.UndefinedProperty if the specified property is
65       * not defined for this RenderedImage.
66       * @param name the name of the property
67       * @return the property indicated by the specified name.
68       * @see java.awt.Image#UndefinedProperty
69       */
70      Object getProperty(String name);
71  
72      /**
73        * Returns an array of names recognized by
74        * {@link #getProperty(String) getProperty(String)}
75        * or <code>null</code>, if no property names are recognized.
76        * @return a <code>String</code> array containing all of the
77        * property names that <code>getProperty(String)</code> recognizes;
78        * or <code>null</code> if no property names are recognized.
79        */
80      String[] getPropertyNames();
81  
82      /**
83       * Returns the ColorModel associated with this image.  All Rasters
84       * returned from this image will have this as their ColorModel.  This
85       * can return null.
86       * @return the <code>ColorModel</code> of this image.
87       */
88      ColorModel getColorModel();
89  
90      /**
91       * Returns the SampleModel associated with this image.  All Rasters
92       * returned from this image will have this as their SampleModel.
93       * @return the <code>SampleModel</code> of this image.
94       */
95      SampleModel getSampleModel();
96  
97      /**
98       * Returns the width of the RenderedImage.
99       * @return the width of this <code>RenderedImage</code>.
100      */
101     int getWidth();
102 
103     /**
104      * Returns the height of the RenderedImage.
105      * @return the height of this <code>RenderedImage</code>.
106      */
107     int getHeight();
108 
109     /**
110      * Returns the minimum X coordinate (inclusive) of the RenderedImage.
111      * @return the X coordinate of this <code>RenderedImage</code>.
112      */
113     int getMinX();
114 
115     /**
116      * Returns the minimum Y coordinate (inclusive) of the RenderedImage.
117      * @return the Y coordinate of this <code>RenderedImage</code>.
118      */
119     int getMinY();
120 
121     /**
122      * Returns the number of tiles in the X direction.
123      * @return the number of tiles in the X direction.
124      */
125     int getNumXTiles();
126 
127     /**
128      * Returns the number of tiles in the Y direction.
129      * @return the number of tiles in the Y direction.
130      */
131     int getNumYTiles();
132 
133     /**
134      *  Returns the minimum tile index in the X direction.
135      *  @return the minimum tile index in the X direction.
136      */
137     int getMinTileX();
138 
139     /**
140      *  Returns the minimum tile index in the Y direction.
141      *  @return the minimum tile index in the X direction.
142      */
143     int getMinTileY();
144 
145     /**
146      *  Returns the tile width in pixels.  All tiles must have the same
147      *  width.
148      *  @return the tile width in pixels.
149      */
150     int getTileWidth();
151 
152     /**
153      *  Returns the tile height in pixels.  All tiles must have the same
154      *  height.
155      *  @return the tile height in pixels.
156      */
157     int getTileHeight();
158 
159     /**
160      * Returns the X offset of the tile grid relative to the origin,
161      * i.e., the X coordinate of the upper-left pixel of tile (0, 0).
162      * (Note that tile (0, 0) may not actually exist.)
163      * @return the X offset of the tile grid relative to the origin.
164      */
165     int getTileGridXOffset();
166 
167     /**
168      * Returns the Y offset of the tile grid relative to the origin,
169      * i.e., the Y coordinate of the upper-left pixel of tile (0, 0).
170      * (Note that tile (0, 0) may not actually exist.)
171      * @return the Y offset of the tile grid relative to the origin.
172      */
173     int getTileGridYOffset();
174 
175     /**
176      * Returns tile (tileX, tileY).  Note that tileX and tileY are indices
177      * into the tile array, not pixel locations.  The Raster that is returned
178      * is live and will be updated if the image is changed.
179      * @param tileX the X index of the requested tile in the tile array
180      * @param tileY the Y index of the requested tile in the tile array
181      * @return the tile given the specified indices.
182      */
183    Raster getTile(int tileX, int tileY);
184 
185     /**
186      * Returns the image as one large tile (for tile based
187      * images this will require fetching the whole image
188      * and copying the image data over).  The Raster returned is
189      * a copy of the image data and will not be updated if the image
190      * is changed.
191      * @return the image as one large tile.
192      */
193     Raster getData();
194 
195     /**
196      * Computes and returns an arbitrary region of the RenderedImage.
197      * The Raster returned is a copy of the image data and will not
198      * be updated if the image is changed.
199      * @param rect the region of the RenderedImage to be returned.
200      * @return the region of the <code>RenderedImage</code>
201      * indicated by the specified <code>Rectangle</code>.
202      */
203     Raster getData(Rectangle rect);
204 
205     /**
206      * Computes an arbitrary rectangular region of the RenderedImage
207      * and copies it into a caller-supplied WritableRaster.  The region
208      * to be computed is determined from the bounds of the supplied
209      * WritableRaster.  The supplied WritableRaster must have a
210      * SampleModel that is compatible with this image.  If raster is null,
211      * an appropriate WritableRaster is created.
212      * @param raster a WritableRaster to hold the returned portion of the
213      *               image, or null.
214      * @return a reference to the supplied or created WritableRaster.
215      */
216     WritableRaster copyData(WritableRaster raster);
217 }