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 * Returns 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 }