View Javadoc
1   /*
2    * Copyright (c) 1998, 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  /* ********************************************************************
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.renderable;
37  import java.util.Vector;
38  import java.awt.RenderingHints;
39  import java.awt.image.*;
40  
41  /**
42   * A RenderableImage is a common interface for rendering-independent
43   * images (a notion which subsumes resolution independence).  That is,
44   * images which are described and have operations applied to them
45   * independent of any specific rendering of the image.  For example, a
46   * RenderableImage can be rotated and cropped in
47   * resolution-independent terms.  Then, it can be rendered for various
48   * specific contexts, such as a draft preview, a high-quality screen
49   * display, or a printer, each in an optimal fashion.
50   *
51   * <p> A RenderedImage is returned from a RenderableImage via the
52   * createRendering() method, which takes a RenderContext.  The
53   * RenderContext specifies how the RenderedImage should be
54   * constructed.  Note that it is not possible to extract pixels
55   * directly from a RenderableImage.
56   *
57   * <p> The createDefaultRendering() and createScaledRendering() methods are
58   * convenience methods that construct an appropriate RenderContext
59   * internally.  All of the rendering methods may return a reference to a
60   * previously produced rendering.
61   */
62  public interface RenderableImage {
63  
64      /**
65       * String constant that can be used to identify a property on
66       * a RenderedImage obtained via the createRendering or
67       * createScaledRendering methods.  If such a property exists,
68       * the value of the property will be a RenderingHints object
69       * specifying which hints were observed in creating the rendering.
70       */
71       static final String HINTS_OBSERVED = "HINTS_OBSERVED";
72  
73      /**
74       * Returns a vector of RenderableImages that are the sources of
75       * image data for this RenderableImage. Note that this method may
76       * return an empty vector, to indicate that the image has no sources,
77       * or null, to indicate that no information is available.
78       *
79       * @return a (possibly empty) Vector of RenderableImages, or null.
80       */
81      Vector<RenderableImage> getSources();
82  
83      /**
84       * Gets a property from the property set of this image.
85       * If the property name is not recognized, java.awt.Image.UndefinedProperty
86       * will be returned.
87       *
88       * @param name the name of the property to get, as a String.
89       * @return a reference to the property Object, or the value
90       *         java.awt.Image.UndefinedProperty.
91       */
92      Object getProperty(String name);
93  
94      /**
95       * Returns a list of names recognized by getProperty.
96       * @return a list of property names.
97       */
98      String[] getPropertyNames();
99  
100     /**
101      * Returns true if successive renderings (that is, calls to
102      * createRendering() or createScaledRendering()) with the same arguments
103      * may produce different results.  This method may be used to
104      * determine whether an existing rendering may be cached and
105      * reused.  It is always safe to return true.
106      * @return <code>true</code> if successive renderings with the
107      *         same arguments might produce different results;
108      *         <code>false</code> otherwise.
109      */
110     boolean isDynamic();
111 
112     /**
113      * Gets the width in user coordinate space.  By convention, the
114      * usual width of a RenderableImage is equal to the image's aspect
115      * ratio (width divided by height).
116      *
117      * @return the width of the image in user coordinates.
118      */
119     float getWidth();
120 
121     /**
122      * Gets the height in user coordinate space.  By convention, the
123      * usual height of a RenderedImage is equal to 1.0F.
124      *
125      * @return the height of the image in user coordinates.
126      */
127     float getHeight();
128 
129     /**
130      * Gets the minimum X coordinate of the rendering-independent image data.
131      * @return the minimum X coordinate of the rendering-independent image
132      * data.
133      */
134     float getMinX();
135 
136     /**
137      * Gets the minimum Y coordinate of the rendering-independent image data.
138      * @return the minimum Y coordinate of the rendering-independent image
139      * data.
140      */
141     float getMinY();
142 
143     /**
144      * Creates a RenderedImage instance of this image with width w, and
145      * height h in pixels.  The RenderContext is built automatically
146      * with an appropriate usr2dev transform and an area of interest
147      * of the full image.  All the rendering hints come from hints
148      * passed in.
149      *
150      * <p> If w == 0, it will be taken to equal
151      * Math.round(h*(getWidth()/getHeight())).
152      * Similarly, if h == 0, it will be taken to equal
153      * Math.round(w*(getHeight()/getWidth())).  One of
154      * w or h must be non-zero or else an IllegalArgumentException
155      * will be thrown.
156      *
157      * <p> The created RenderedImage may have a property identified
158      * by the String HINTS_OBSERVED to indicate which RenderingHints
159      * were used to create the image.  In addition any RenderedImages
160      * that are obtained via the getSources() method on the created
161      * RenderedImage may have such a property.
162      *
163      * @param w the width of rendered image in pixels, or 0.
164      * @param h the height of rendered image in pixels, or 0.
165      * @param hints a RenderingHints object containing hints.
166      * @return a RenderedImage containing the rendered data.
167      */
168     RenderedImage createScaledRendering(int w, int h, RenderingHints hints);
169 
170     /**
171      * Returnd a RenderedImage instance of this image with a default
172      * width and height in pixels.  The RenderContext is built
173      * automatically with an appropriate usr2dev transform and an area
174      * of interest of the full image.  The rendering hints are
175      * empty.  createDefaultRendering may make use of a stored
176      * rendering for speed.
177      *
178      * @return a RenderedImage containing the rendered data.
179      */
180     RenderedImage createDefaultRendering();
181 
182     /**
183      * Creates a RenderedImage that represented a rendering of this image
184      * using a given RenderContext.  This is the most general way to obtain a
185      * rendering of a RenderableImage.
186      *
187      * <p> The created RenderedImage may have a property identified
188      * by the String HINTS_OBSERVED to indicate which RenderingHints
189      * (from the RenderContext) were used to create the image.
190      * In addition any RenderedImages
191      * that are obtained via the getSources() method on the created
192      * RenderedImage may have such a property.
193      *
194      * @param renderContext the RenderContext to use to produce the rendering.
195      * @return a RenderedImage containing the rendered data.
196      */
197     RenderedImage createRendering(RenderContext renderContext);
198 }