RenderableImage


1   /*
2    * @(#)RenderableImage.java 1.15 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   /* ********************************************************************
9    **********************************************************************
10   **********************************************************************
11   *** COPYRIGHT (c) Eastman Kodak Company, 1997                      ***
12   *** As  an unpublished  work pursuant to Title 17 of the United    ***
13   *** States Code.  All rights reserved.                             ***
14   **********************************************************************
15   **********************************************************************
16   **********************************************************************/
17  
18  package java.awt.image.renderable;
19  import java.util.Vector  ;
20  import java.awt.RenderingHints  ;
21  import java.awt.image.*;
22  
23  /**
24   * A RenderableImage is a common interface for rendering-independent
25   * images (a notion which subsumes resolution independence).  That is,
26   * images which are described and have operations applied to them
27   * independent of any specific rendering of the image.  For example, a
28   * RenderableImage can be rotated and cropped in
29   * resolution-independent terms.  Then, it can be rendered for various
30   * specific contexts, such as a draft preview, a high-quality screen
31   * display, or a printer, each in an optimal fashion.
32   * 
33   * <p> A RenderedImage is returned from a RenderableImage via the
34   * createRendering() method, which takes a RenderContext.  The
35   * RenderContext specifies how the RenderedImage should be
36   * constructed.  Note that it is not possible to extract pixels
37   * directly from a RenderableImage.
38   * 
39   * <p> The createDefaultRendering() and createScaledRendering() methods are
40   * convenience methods that construct an appropriate RenderContext
41   * internally.  All of the rendering methods may return a reference to a
42   * previously produced rendering.
43   */
44  public interface RenderableImage {
45    
46      /**
47       * String constant that can be used to identify a property on
48       * a RenderedImage obtained via the createRendering or
49       * createScaledRendering methods.  If such a property exists,
50       * the value of the propoery will be a RenderingHints object
51       * specifying which hints were observed in creating the rendering.
52       */
53       static final String   HINTS_OBSERVED = "HINTS_OBSERVED";
54  
55      /** 
56       * Returns a vector of RenderableImages that are the sources of
57       * image data for this RenderableImage. Note that this method may
58       * return an empty vector, to indicate that the image has no sources,
59       * or null, to indicate that no information is available.
60       *
61       * @return a (possibly empty) Vector of RenderableImages, or null.
62       */
63      Vector  <RenderableImage  > getSources();
64      
65      /**
66       * Gets a property from the property set of this image.
67       * If the property name is not recognized, java.awt.Image.UndefinedProperty
68       * will be returned.
69       *
70       * @param name the name of the property to get, as a String.
71       * @return a reference to the property Object, or the value
72       *         java.awt.Image.UndefinedProperty.
73       */
74      Object   getProperty(String   name);
75  
76      /** 
77       * Returns a list of names recognized by getProperty. 
78       * @return a list of property names.
79       */
80      String  [] getPropertyNames();
81      
82      /**
83       * Returns true if successive renderings (that is, calls to
84       * createRendering() or createScaledRendering()) with the same arguments
85       * may produce different results.  This method may be used to
86       * determine whether an existing rendering may be cached and
87       * reused.  It is always safe to return true.
88       * @return <code>true</code> if successive renderings with the
89       *         same arguments might produce different results;
90       *         <code>false</code> otherwise.
91       */
92      boolean isDynamic();
93  
94      /** 
95       * Gets the width in user coordinate space.  By convention, the
96       * usual width of a RenderableImage is equal to the image's aspect
97       * ratio (width divided by height).
98       *
99       * @return the width of the image in user coordinates.
100      */
101     float getWidth();
102   
103     /**
104      * Gets the height in user coordinate space.  By convention, the
105      * usual height of a RenderedImage is equal to 1.0F.
106      *
107      * @return the height of the image in user coordinates.
108      */
109     float getHeight();
110     
111     /** 
112      * Gets the minimum X coordinate of the rendering-independent image data.
113      * @return the minimum X coordinate of the rendering-independent image
114      * data.
115      */
116     float getMinX();
117   
118     /** 
119      * Gets the minimum Y coordinate of the rendering-independent image data.
120      * @return the minimum Y coordinate of the rendering-independent image
121      * data.
122      */
123     float getMinY();
124 
125     /**
126      * Creates a RenderedImage instance of this image with width w, and
127      * height h in pixels.  The RenderContext is built automatically
128      * with an appropriate usr2dev transform and an area of interest
129      * of the full image.  All the rendering hints come from hints
130      * passed in.
131      *
132      * <p> If w == 0, it will be taken to equal
133      * Math.round(h*(getWidth()/getHeight())).
134      * Similarly, if h == 0, it will be taken to equal
135      * Math.round(w*(getHeight()/getWidth())).  One of
136      * w or h must be non-zero or else an IllegalArgumentException 
137      * will be thrown.
138      *
139      * <p> The created RenderedImage may have a property identified
140      * by the String HINTS_OBSERVED to indicate which RenderingHints
141      * were used to create the image.  In addition any RenderedImages
142      * that are obtained via the getSources() method on the created
143      * RenderedImage may have such a property.
144      *
145      * @param w the width of rendered image in pixels, or 0.
146      * @param h the height of rendered image in pixels, or 0.
147      * @param hints a RenderingHints object containg hints.
148      * @return a RenderedImage containing the rendered data.
149      */
150     RenderedImage createScaledRendering(int w, int h, RenderingHints   hints);
151   
152     /** 
153      * Returnd a RenderedImage instance of this image with a default
154      * width and height in pixels.  The RenderContext is built
155      * automatically with an appropriate usr2dev transform and an area
156      * of interest of the full image.  The rendering hints are
157      * empty.  createDefaultRendering may make use of a stored
158      * rendering for speed.
159      *
160      * @return a RenderedImage containing the rendered data.
161      */
162     RenderedImage createDefaultRendering();
163   
164     /** 
165      * Creates a RenderedImage that represented a rendering of this image
166      * using a given RenderContext.  This is the most general way to obtain a
167      * rendering of a RenderableImage.
168      *
169      * <p> The created RenderedImage may have a property identified
170      * by the String HINTS_OBSERVED to indicate which RenderingHints
171      * (from the RenderContext) were used to create the image.
172      * In addition any RenderedImages
173      * that are obtained via the getSources() method on the created
174      * RenderedImage may have such a property.
175      *
176      * @param renderContext the RenderContext to use to produce the rendering.
177      * @return a RenderedImage containing the rendered data.
178      */
179     RenderedImage createRendering(RenderContext   renderContext);
180 }
181
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags