VolatileImage.java: Document.
2005-05-03 Thomas Fitzsimmons <fitzsim@redhat.com> * java/awt/image/VolatileImage.java: Document. From-SVN: r99208
This commit is contained in:
Thomas Fitzsimmons
Thomas Fitzsimmons
parent
a7e1c9287c
commit
78da4d2e84
2 changed files with 216 additions and 32 deletions
|
|
@ -1,39 +1,39 @@
|
|||
/* VolatileImage.java --
|
||||
Copyright (C) 2002 Free Software Foundation, Inc.
|
||||
/* VolatileImage.java -- a hardware-accelerated image buffer
|
||||
Copyright (C) 2002, 2005 Free Software Foundation, Inc.
|
||||
|
||||
This file is part of GNU Classpath.
|
||||
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 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.
|
||||
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.
|
||||
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.
|
||||
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. */
|
||||
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:
|
||||
* <ul>
|
||||
* <li><code>IMAGE_OK</code> if the image did not need to be
|
||||
* validated and didn't need to be restored</li>
|
||||
* <li><code>IMAGE_RESTORED</code> if the image may need to be
|
||||
* re-rendered. This return value implies IMAGE_OK.</li>
|
||||
* <li><code>IMAGE_INCOMPATIBLE</code> 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.</li>
|
||||
* </ul>
|
||||
*/
|
||||
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;
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue