1 /* 2 * Copyright (c) 1995, 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 package java.awt; 26 27 import java.awt.image.ImageProducer; 28 import java.awt.image.ImageObserver; 29 import java.awt.image.ImageFilter; 30 import java.awt.image.FilteredImageSource; 31 import java.awt.image.AreaAveragingScaleFilter; 32 import java.awt.image.ReplicateScaleFilter; 33 34 import sun.awt.image.SurfaceManager; 35 36 37 /** 38 * The abstract class {@code Image} is the superclass of all 39 * classes that represent graphical images. The image must be 40 * obtained in a platform-specific manner. 41 * 42 * @author Sami Shaio 43 * @author Arthur van Hoff 44 * @since 1.0 45 */ 46 public abstract class Image { 47 48 /** 49 * convenience object; we can use this single static object for 50 * all images that do not create their own image caps; it holds the 51 * default (unaccelerated) properties. 52 */ 53 private static ImageCapabilities defaultImageCaps = 54 new ImageCapabilities(false); 55 56 /** 57 * Priority for accelerating this image. Subclasses are free to 58 * set different default priorities and applications are free to 59 * set the priority for specific images via the 60 * {@code setAccelerationPriority(float)} method. 61 * @since 1.5 62 */ 63 protected float accelerationPriority = .5f; 64 65 /** 66 * Determines the width of the image. If the width is not yet known, 67 * this method returns {@code -1} and the specified 68 * {@code ImageObserver} object is notified later. 69 * @param observer an object waiting for the image to be loaded. 70 * @return the width of this image, or {@code -1} 71 * if the width is not yet known. 72 * @see java.awt.Image#getHeight 73 * @see java.awt.image.ImageObserver 74 */ 75 public abstract int getWidth(ImageObserver observer); 76 77 /** 78 * Determines the height of the image. If the height is not yet known, 79 * this method returns {@code -1} and the specified 80 * {@code ImageObserver} object is notified later. 81 * @param observer an object waiting for the image to be loaded. 82 * @return the height of this image, or {@code -1} 83 * if the height is not yet known. 84 * @see java.awt.Image#getWidth 85 * @see java.awt.image.ImageObserver 86 */ 87 public abstract int getHeight(ImageObserver observer); 88 89 /** 90 * Gets the object that produces the pixels for the image. 91 * This method is called by the image filtering classes and by 92 * methods that perform image conversion and scaling. 93 * @return the image producer that produces the pixels 94 * for this image. 95 * @see java.awt.image.ImageProducer 96 */ 97 public abstract ImageProducer getSource(); 98 99 /** 100 * Creates a graphics context for drawing to an off-screen image. 101 * This method can only be called for off-screen images. 102 * @return a graphics context to draw to the off-screen image. 103 * @exception UnsupportedOperationException if called for a 104 * non-off-screen image. 105 * @see java.awt.Graphics 106 * @see java.awt.Component#createImage(int, int) 107 */ 108 public abstract Graphics getGraphics(); 109 110 /** 111 * Gets a property of this image by name. 112 * <p> 113 * Individual property names are defined by the various image 114 * formats. If a property is not defined for a particular image, this 115 * method returns the {@code UndefinedProperty} object. 116 * <p> 117 * If the properties for this image are not yet known, this method 118 * returns {@code null}, and the {@code ImageObserver} 119 * object is notified later. 120 * <p> 121 * The property name {@code "comment"} should be used to store 122 * an optional comment which can be presented to the application as a 123 * description of the image, its source, or its author. 124 * @param name a property name. 125 * @param observer an object waiting for this image to be loaded. 126 * @return the value of the named property. 127 * @throws NullPointerException if the property name is null. 128 * @see java.awt.image.ImageObserver 129 * @see java.awt.Image#UndefinedProperty 130 */ 131 public abstract Object getProperty(String name, ImageObserver observer); 132 133 /** 134 * The {@code UndefinedProperty} object should be returned whenever a 135 * property which was not defined for a particular image is fetched. 136 */ 137 public static final Object UndefinedProperty = new Object(); 138 139 /** 140 * Creates a scaled version of this image. 141 * A new {@code Image} object is returned which will render 142 * the image at the specified {@code width} and 143 * {@code height} by default. The new {@code Image} object 144 * may be loaded asynchronously even if the original source image 145 * has already been loaded completely. 146 * 147 * <p> 148 * 149 * If either {@code width} 150 * or {@code height} is a negative number then a value is 151 * substituted to maintain the aspect ratio of the original image 152 * dimensions. If both {@code width} and {@code height} 153 * are negative, then the original image dimensions are used. 154 * 155 * @param width the width to which to scale the image. 156 * @param height the height to which to scale the image. 157 * @param hints flags to indicate the type of algorithm to use 158 * for image resampling. 159 * @return a scaled version of the image. 160 * @exception IllegalArgumentException if {@code width} 161 * or {@code height} is zero. 162 * @see java.awt.Image#SCALE_DEFAULT 163 * @see java.awt.Image#SCALE_FAST 164 * @see java.awt.Image#SCALE_SMOOTH 165 * @see java.awt.Image#SCALE_REPLICATE 166 * @see java.awt.Image#SCALE_AREA_AVERAGING 167 * @since 1.1 168 */ 169 public Image getScaledInstance(int width, int height, int hints) { 170 ImageFilter filter; 171 if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) { 172 filter = new AreaAveragingScaleFilter(width, height); 173 } else { 174 filter = new ReplicateScaleFilter(width, height); 175 } 176 ImageProducer prod; 177 prod = new FilteredImageSource(getSource(), filter); 178 return Toolkit.getDefaultToolkit().createImage(prod); 179 } 180 181 /** 182 * Use the default image-scaling algorithm. 183 * @since 1.1 184 */ 185 public static final int SCALE_DEFAULT = 1; 186 187 /** 188 * Choose an image-scaling algorithm that gives higher priority 189 * to scaling speed than smoothness of the scaled image. 190 * @since 1.1 191 */ 192 public static final int SCALE_FAST = 2; 193 194 /** 195 * Choose an image-scaling algorithm that gives higher priority 196 * to image smoothness than scaling speed. 197 * @since 1.1 198 */ 199 public static final int SCALE_SMOOTH = 4; 200 201 /** 202 * Use the image scaling algorithm embodied in the 203 * {@code ReplicateScaleFilter} class. 204 * The {@code Image} object is free to substitute a different filter 205 * that performs the same algorithm yet integrates more efficiently 206 * into the imaging infrastructure supplied by the toolkit. 207 * @see java.awt.image.ReplicateScaleFilter 208 * @since 1.1 209 */ 210 public static final int SCALE_REPLICATE = 8; 211 212 /** 213 * Use the Area Averaging image scaling algorithm. The 214 * image object is free to substitute a different filter that 215 * performs the same algorithm yet integrates more efficiently 216 * into the image infrastructure supplied by the toolkit. 217 * @see java.awt.image.AreaAveragingScaleFilter 218 * @since 1.1 219 */ 220 public static final int SCALE_AREA_AVERAGING = 16; 221 222 /** 223 * Flushes all reconstructable resources being used by this Image object. 224 * This includes any pixel data that is being cached for rendering to 225 * the screen as well as any system resources that are being used 226 * to store data or pixels for the image if they can be recreated. 227 * The image is reset to a state similar to when it was first created 228 * so that if it is again rendered, the image data will have to be 229 * recreated or fetched again from its source. 230 * <p> 231 * Examples of how this method affects specific types of Image object: 232 * <ul> 233 * <li> 234 * BufferedImage objects leave the primary Raster which stores their 235 * pixels untouched, but flush any information cached about those 236 * pixels such as copies uploaded to the display hardware for 237 * accelerated blits. 238 * <li> 239 * Image objects created by the Component methods which take a 240 * width and height leave their primary buffer of pixels untouched, 241 * but have all cached information released much like is done for 242 * BufferedImage objects. 243 * <li> 244 * VolatileImage objects release all of their pixel resources 245 * including their primary copy which is typically stored on 246 * the display hardware where resources are scarce. 247 * These objects can later be restored using their 248 * {@link java.awt.image.VolatileImage#validate validate} 249 * method. 250 * <li> 251 * Image objects created by the Toolkit and Component classes which are 252 * loaded from files, URLs or produced by an {@link ImageProducer} 253 * are unloaded and all local resources are released. 254 * These objects can later be reloaded from their original source 255 * as needed when they are rendered, just as when they were first 256 * created. 257 * </ul> 258 */ 259 public void flush() { 260 if (surfaceManager != null) { 261 surfaceManager.flush(); 262 } 263 } 264 265 /** 266 * Returns an ImageCapabilities object which can be 267 * inquired as to the capabilities of this 268 * Image on the specified GraphicsConfiguration. 269 * This allows programmers to find 270 * out more runtime information on the specific Image 271 * object that they have created. For example, the user 272 * might create a BufferedImage but the system may have 273 * no video memory left for creating an image of that 274 * size on the given GraphicsConfiguration, so although the object 275 * may be acceleratable in general, it 276 * does not have that capability on this GraphicsConfiguration. 277 * @param gc a {@code GraphicsConfiguration} object. A value of null 278 * for this parameter will result in getting the image capabilities 279 * for the default {@code GraphicsConfiguration}. 280 * @return an {@code ImageCapabilities} object that contains 281 * the capabilities of this {@code Image} on the specified 282 * GraphicsConfiguration. 283 * @see java.awt.image.VolatileImage#getCapabilities() 284 * VolatileImage.getCapabilities() 285 * @since 1.5 286 */ 287 public ImageCapabilities getCapabilities(GraphicsConfiguration gc) { 288 if (surfaceManager != null) { 289 return surfaceManager.getCapabilities(gc); 290 } 291 // Note: this is just a default object that gets returned in the 292 // absence of any more specific information from a surfaceManager. 293 // Subclasses of Image should either override this method or 294 // make sure that they always have a non-null SurfaceManager 295 // to return an ImageCapabilities object that is appropriate 296 // for their given subclass type. 297 return defaultImageCaps; 298 } 299 300 /** 301 * Sets a hint for this image about how important acceleration is. 302 * This priority hint is used to compare to the priorities of other 303 * Image objects when determining how to use scarce acceleration 304 * resources such as video memory. When and if it is possible to 305 * accelerate this Image, if there are not enough resources available 306 * to provide that acceleration but enough can be freed up by 307 * de-accelerating some other image of lower priority, then that other 308 * Image may be de-accelerated in deference to this one. Images 309 * that have the same priority take up resources on a first-come, 310 * first-served basis. 311 * @param priority a value between 0 and 1, inclusive, where higher 312 * values indicate more importance for acceleration. A value of 0 313 * means that this Image should never be accelerated. Other values 314 * are used simply to determine acceleration priority relative to other 315 * Images. 316 * @throws IllegalArgumentException if {@code priority} is less 317 * than zero or greater than 1. 318 * @since 1.5 319 */ 320 public void setAccelerationPriority(float priority) { 321 if (priority < 0 || priority > 1) { 322 throw new IllegalArgumentException("Priority must be a value " + 323 "between 0 and 1, inclusive"); 324 } 325 accelerationPriority = priority; 326 if (surfaceManager != null) { 327 surfaceManager.setAccelerationPriority(accelerationPriority); 328 } 329 } 330 331 /** 332 * Returns the current value of the acceleration priority hint. 333 * @see #setAccelerationPriority(float priority) setAccelerationPriority 334 * @return value between 0 and 1, inclusive, which represents the current 335 * priority value 336 * @since 1.5 337 */ 338 public float getAccelerationPriority() { 339 return accelerationPriority; 340 } 341 342 SurfaceManager surfaceManager; 343 344 static { 345 SurfaceManager.setImageAccessor(new SurfaceManager.ImageAccessor() { 346 public SurfaceManager getSurfaceManager(Image img) { 347 return img.surfaceManager; 348 } 349 public void setSurfaceManager(Image img, SurfaceManager mgr) { 350 img.surfaceManager = mgr; 351 } 352 }); 353 } 354 }