From 78da4d2e8476b54273d1d50a4d739d4f7d31732c Mon Sep 17 00:00:00 2001 From: Thomas Fitzsimmons Date: Wed, 4 May 2005 03:18:49 +0000 Subject: [PATCH] VolatileImage.java: Document. 2005-05-03 Thomas Fitzsimmons * java/awt/image/VolatileImage.java: Document. From-SVN: r99208 --- libjava/ChangeLog | 4 + libjava/java/awt/image/VolatileImage.java | 256 +++++++++++++++++++++++++----- 2 files changed, 222 insertions(+), 38 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 77a571c..5433712 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,5 +1,9 @@ 2005-05-03 Thomas Fitzsimmons + * java/awt/image/VolatileImage.java: Document. + +2005-05-03 Thomas Fitzsimmons + * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkToolkit.c (init_glib_threads): Check if threading system is already initialized. diff --git a/libjava/java/awt/image/VolatileImage.java b/libjava/java/awt/image/VolatileImage.java index c1abb35..63d1952 100644 --- a/libjava/java/awt/image/VolatileImage.java +++ b/libjava/java/awt/image/VolatileImage.java @@ -1,39 +1,39 @@ -/* VolatileImage.java -- - Copyright (C) 2002 Free Software Foundation, Inc. - -This file is part of GNU Classpath. - -GNU Classpath is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2, or (at your option) -any later version. - -GNU Classpath is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Classpath; see the file COPYING. If not, write to the -Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA -02111-1307 USA. - -Linking this library statically or dynamically with other modules is -making a combined work based on this library. Thus, the terms and -conditions of the GNU General Public License cover the whole -combination. - -As a special exception, the copyright holders of this library give you -permission to link this library with independent modules to produce an -executable, regardless of the license terms of these independent -modules, and to copy and distribute the resulting executable under -terms of your choice, provided that you also meet, for each linked -independent module, the terms and conditions of the license of that -module. An independent module is a module which is not derived from -or based on this library. If you modify this library, you may extend -this exception to your version of the library, but you are not -obligated to do so. If you do not wish to do so, delete this -exception statement from your version. */ +/* VolatileImage.java -- a hardware-accelerated image buffer + Copyright (C) 2002, 2005 Free Software Foundation, Inc. + + This file is part of GNU Classpath. + + GNU Classpath is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + GNU Classpath is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNU Classpath; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA + 02111-1307 USA. + + Linking this library statically or dynamically with other modules is + making a combined work based on this library. Thus, the terms and + conditions of the GNU General Public License cover the whole + combination. + + As a special exception, the copyright holders of this library give you + permission to link this library with independent modules to produce an + executable, regardless of the license terms of these independent + modules, and to copy and distribute the resulting executable under + terms of your choice, provided that you also meet, for each linked + independent module, the terms and conditions of the license of that + module. An independent module is a module which is not derived from + or based on this library. If you modify this library, you may extend + this exception to your version of the library, but you are not + obligated to do so. If you do not wish to do so, delete this + exception statement from your version. */ package java.awt.image; @@ -42,33 +42,213 @@ import java.awt.Graphics; import java.awt.Graphics2D; import java.awt.GraphicsConfiguration; import java.awt.Image; +import java.awt.Transparency; import java.awt.ImageCapabilities; -/** STUBS ONLY */ +/** + * VolatileImage represents a hardware-accelerated graphics buffer. + * The native graphics system may free or damage the resources + * occupied by a VolatileImage at any time. As such, one must + * frequently check the "validity" of the image buffer's resources. + * + * A volatile image's "validity" depends on multiple factors. Its + * resources may have become unavailble in which case you must + * reallocate them. If you move the image from one output device to + * another, you may need to recreate the image's resources if the new + * output device's capabilities don't match the old one's. Finally, + * if the contents of the image's buffer have been damaged you must + * re-render the image. + * + * VolatileImages should always be created using either + * Component.createVolatileImage or + * GraphicsConfiguration.createCompatibleVolatileImage. + */ public abstract class VolatileImage extends Image + implements Transparency { + /** + * One of validate's possible return values. Indicates that the + * image buffer matches its graphics configuration's capabilities + * and that its resources are initialized and ready to be drawn + * into. Also implies that any existing image rendered to the + * buffer is intact and need not be re-rendered. + */ public static final int IMAGE_OK = 0; + + /** + * One of validate's possible return values. Indicates that the + * image buffer has been restored, meaning that it is valid and + * ready-to-use but that its previous contents have been lost. This + * return value implies IMAGE_OK but that the image needs to be + * re-rendered. + */ public static final int IMAGE_RESTORED = 1; + + /** + * One of validate's possible return values. Indicates that the + * image buffer type is unsupported by the current graphics + * configuration. The graphics configuration may have changed, for + * example if the image moved from one output device to another. + * This return value implies that the image buffer's resources + * should be re-acquired. + */ public static final int IMAGE_INCOMPATIBLE = 2; + + /** + * This image's transparency type. One of Transparency.BITMASK, + * Transparency.OPAQUE or Transparency.TRANSLUCENT. + * + * @since 1.5 + */ + protected int transparency; + + /** + * Default constructor. VolatileImages should not be created + * directly. Rather, you should use Component.createVolatileImage + * or GraphicsConfiguration.createCompatibleVolatileImage. + */ public VolatileImage() { } + + /** + * Returns an image representing the current state of the volatile + * image buffer. The returned image is static meaning that it is + * not updated after being created. It is a snapshot of the + * volatile image buffer at the time getSnapshot is called. + * + * This method, which reads pixels from the volatile image buffer, + * may be less-performant than methods that write pixels since + * VolatileImages are typically optimized for writing. + * + * @return a BufferedImage representing this VolatileImage + */ public abstract BufferedImage getSnapshot(); + + /** + * Returns the width of this image buffer. + * + * @return the width of this VolatileImage + */ public abstract int getWidth(); + + /** + * Returns the height of this image buffer. + * + * @return the height of this VolatileImage + */ public abstract int getHeight(); + + /** + * Calling this method is equivalent to calling + * getSnapshot().getSource(). The ImageProducer produces pixels + * from the BufferedImage snapshot and not from the VolatileImage + * itself. Thus, changes to the VolatileImage that occur after this + * ImageProducer has been retrieved will not be reflected in the + * produced pixels. + * + * This method, which reads pixels from the volatile image buffer, + * may be less-performant than methods that write pixels since + * VolatileImages are typically optimized for writing. + * + * @return an ImageProducer for a static BufferedImage snapshot of + * this image buffer. + */ public ImageProducer getSource() { return getSnapshot().getSource(); } + + /** + * Releases the system resources taken by this image. + */ public void flush() { } + + /** + * Returns a Graphics2D object that can be used to draw onto this + * image. This method is present for backwards-compatibility. It + * simply returns the result of createGraphics. + * + * @return a Graphics2D object that can be used to draw onto this + * image + */ public Graphics getGraphics() { return createGraphics(); } + + /** + * Returns a Graphics2D object that can be used to draw onto this + * image. + * + * @return a Graphics2D object that can be used to draw onto this + * image + */ public abstract Graphics2D createGraphics(); + + /** + * Validates and restores this image. If the image buffer has + * become unavailable for further use since the last call to + * validate, validate will allocate a new image buffer. The image + * is also "validated" against the GraphicsConfiguration parameter. + * + * "Validating" the image means checking that the capabilities it + * requires of the output device are indeed supported by the given + * output device. If the image's characteristics, which can be + * highly output device-specific, are not supported by the graphics + * configuration, then IMAGE_INCOMPATIBLE will be returned. This + * can happen, for example, if this image was created on one output + * device, then validated against a different output device with + * different capabilities. Calling validate with a NULL gc argument + * causes validate to skip the validation test. + * + * @param gc graphics configuration against which to validate or + * NULL + * + * @return a code indicating the result of validation. One of: + *
    + *
  • IMAGE_OK if the image did not need to be + * validated and didn't need to be restored
    • + *
  • IMAGE_RESTORED if the image may need to be + * re-rendered. This return value implies IMAGE_OK.
    • + *
  • IMAGE_INCOMPATIBLE if this image's + * requirements are not fulfilled by the graphics configuration + * parameter. This implies that you need to create a new + * VolatileImage for the different GraphicsConfiguration or + * Component. This return value implies nothing about whether the + * image is valid or needs to be re-rendered.
    • + *
+ */ public abstract int validate(GraphicsConfiguration gc); + + /** + * Returns true if the contents of the image buffer have been + * damaged or if the image buffer's resources have been reclaimed by + * the graphics system. You should call this method after a series + * of rendering operations to or from the image, to see if the image + * buffer needs to be revalidated or the image re-rendered. + * + * @return true if the validate should be called, false otherwise + */ public abstract boolean contentsLost(); + + /** + * Returns the capabilities of this image buffer. + * + * @return the capabilities of this image buffer + */ public abstract ImageCapabilities getCapabilities(); -} // class VolatileImage + + /** + * Returns the transparency type of this image. + * + * @return Transparency.OPAQUE, Transparency.BITMASK or + * Transparency.TRANSLUCENT. + */ + public int getTransparency() + { + return transparency; + } +} -- 2.7.4