< prev index next >
src/java.desktop/share/classes/java/awt/image/VolatileImage.java
Print this page
*** 118,134 ****
* </pre>
* <P>
* Note that this class subclasses from the {@link Image} class, which
* includes methods that take an {@link ImageObserver} parameter for
* asynchronous notifications as information is received from
! * a potential {@link ImageProducer}. Since this <code>VolatileImage</code>
* is not loaded from an asynchronous source, the various methods that take
! * an <code>ImageObserver</code> parameter will behave as if the data has
! * already been obtained from the <code>ImageProducer</code>.
* Specifically, this means that the return values from such methods
* will never indicate that the information is not yet available and
! * the <code>ImageObserver</code> used in such methods will never
* need to be recorded for an asynchronous callback notification.
* @since 1.4
*/
public abstract class VolatileImage extends Image implements Transparency
{
--- 118,134 ----
* </pre>
* <P>
* Note that this class subclasses from the {@link Image} class, which
* includes methods that take an {@link ImageObserver} parameter for
* asynchronous notifications as information is received from
! * a potential {@link ImageProducer}. Since this {@code VolatileImage}
* is not loaded from an asynchronous source, the various methods that take
! * an {@code ImageObserver} parameter will behave as if the data has
! * already been obtained from the {@code ImageProducer}.
* Specifically, this means that the return values from such methods
* will never indicate that the information is not yet available and
! * the {@code ImageObserver} used in such methods will never
* need to be recorded for an asynchronous callback notification.
* @since 1.4
*/
public abstract class VolatileImage extends Image implements Transparency
{
*** 146,183 ****
*/
public static final int IMAGE_RESTORED = 1;
/**
* Validated image is incompatible with supplied
! * <code>GraphicsConfiguration</code> object and should be
* re-created as appropriate. Usage of the image as-is
! * after receiving this return code from <code>validate</code>
* is undefined.
*/
public static final int IMAGE_INCOMPATIBLE = 2;
/**
* Returns a static snapshot image of this object. The
! * <code>BufferedImage</code> returned is only current with
! * the <code>VolatileImage</code> at the time of the request
* and will not be updated with any future changes to the
! * <code>VolatileImage</code>.
* @return a {@link BufferedImage} representation of this
! * <code>VolatileImage</code>
* @see BufferedImage
*/
public abstract BufferedImage getSnapshot();
/**
! * Returns the width of the <code>VolatileImage</code>.
! * @return the width of this <code>VolatileImage</code>.
*/
public abstract int getWidth();
/**
! * Returns the height of the <code>VolatileImage</code>.
! * @return the height of this <code>VolatileImage</code>.
*/
public abstract int getHeight();
// Image overrides
--- 146,183 ----
*/
public static final int IMAGE_RESTORED = 1;
/**
* Validated image is incompatible with supplied
! * {@code GraphicsConfiguration} object and should be
* re-created as appropriate. Usage of the image as-is
! * after receiving this return code from {@code validate}
* is undefined.
*/
public static final int IMAGE_INCOMPATIBLE = 2;
/**
* Returns a static snapshot image of this object. The
! * {@code BufferedImage} returned is only current with
! * the {@code VolatileImage} at the time of the request
* and will not be updated with any future changes to the
! * {@code VolatileImage}.
* @return a {@link BufferedImage} representation of this
! * {@code VolatileImage}
* @see BufferedImage
*/
public abstract BufferedImage getSnapshot();
/**
! * Returns the width of the {@code VolatileImage}.
! * @return the width of this {@code VolatileImage}.
*/
public abstract int getWidth();
/**
! * Returns the height of the {@code VolatileImage}.
! * @return the height of this {@code VolatileImage}.
*/
public abstract int getHeight();
// Image overrides
*** 185,206 ****
* This returns an ImageProducer for this VolatileImage.
* Note that the VolatileImage object is optimized for
* rendering operations and blitting to the screen or other
* VolatileImage objects, as opposed to reading back the
* pixels of the image. Therefore, operations such as
! * <code>getSource</code> may not perform as fast as
* operations that do not rely on reading the pixels.
* Note also that the pixel values read from the image are current
* with those in the image only at the time that they are
* retrieved. This method takes a snapshot
* of the image at the time the request is made and the
* ImageProducer object returned works with
* that static snapshot image, not the original VolatileImage.
* Calling getSource()
* is equivalent to calling getSnapshot().getSource().
* @return an {@link ImageProducer} that can be used to produce the
! * pixels for a <code>BufferedImage</code> representation of
* this Image.
* @see ImageProducer
* @see #getSnapshot()
*/
public ImageProducer getSource() {
--- 185,206 ----
* This returns an ImageProducer for this VolatileImage.
* Note that the VolatileImage object is optimized for
* rendering operations and blitting to the screen or other
* VolatileImage objects, as opposed to reading back the
* pixels of the image. Therefore, operations such as
! * {@code getSource} may not perform as fast as
* operations that do not rely on reading the pixels.
* Note also that the pixel values read from the image are current
* with those in the image only at the time that they are
* retrieved. This method takes a snapshot
* of the image at the time the request is made and the
* ImageProducer object returned works with
* that static snapshot image, not the original VolatileImage.
* Calling getSource()
* is equivalent to calling getSnapshot().getSource().
* @return an {@link ImageProducer} that can be used to produce the
! * pixels for a {@code BufferedImage} representation of
* this Image.
* @see ImageProducer
* @see #getSnapshot()
*/
public ImageProducer getSource() {
*** 223,284 ****
/**
* This method returns a {@link Graphics2D}, but is here
* for backwards compatibility. {@link #createGraphics() createGraphics} is more
* convenient, since it is declared to return a
! * <code>Graphics2D</code>.
! * @return a <code>Graphics2D</code>, which can be used to draw into
* this image.
*/
public Graphics getGraphics() {
return createGraphics();
}
/**
! * Creates a <code>Graphics2D</code>, which can be used to draw into
! * this <code>VolatileImage</code>.
! * @return a <code>Graphics2D</code>, used for drawing into this
* image.
*/
public abstract Graphics2D createGraphics();
// Volatile management methods
/**
* Attempts to restore the drawing surface of the image if the surface
! * had been lost since the last <code>validate</code> call. Also
* validates this image against the given GraphicsConfiguration
* parameter to see whether operations from this image to the
* GraphicsConfiguration are compatible. An example of an
* incompatible combination might be a situation where a VolatileImage
* object was created on one graphics device and then was used
* to render to a different graphics device. Since VolatileImage
* objects tend to be very device-specific, this operation might
* not work as intended, so the return code from this validate
* call would note that incompatibility. A null or incorrect
* value for gc may cause incorrect values to be returned from
! * <code>validate</code> and may cause later problems with rendering.
*
! * @param gc a <code>GraphicsConfiguration</code> object for this
* image to be validated against. A null gc implies that the
* validate method should skip the compatibility test.
! * @return <code>IMAGE_OK</code> if the image did not need validation<BR>
! * <code>IMAGE_RESTORED</code> if the image needed restoration.
* Restoration implies that the contents of the image may have
* been affected and the image may need to be re-rendered.<BR>
! * <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible
! * with the <code>GraphicsConfiguration</code> object passed
! * into the <code>validate</code> method. Incompatibility
* implies that the image may need to be recreated with a
! * new <code>Component</code> or
! * <code>GraphicsConfiguration</code> in order to get an image
* that can be used successfully with this
! * <code>GraphicsConfiguration</code>.
* An incompatible image is not checked for whether restoration
* was necessary, so the state of the image is unchanged
! * after a return value of <code>IMAGE_INCOMPATIBLE</code>
* and this return value implies nothing about whether the
* image needs to be restored.
* @see java.awt.GraphicsConfiguration
* @see java.awt.Component
* @see #IMAGE_OK
--- 223,284 ----
/**
* This method returns a {@link Graphics2D}, but is here
* for backwards compatibility. {@link #createGraphics() createGraphics} is more
* convenient, since it is declared to return a
! * {@code Graphics2D}.
! * @return a {@code Graphics2D}, which can be used to draw into
* this image.
*/
public Graphics getGraphics() {
return createGraphics();
}
/**
! * Creates a {@code Graphics2D}, which can be used to draw into
! * this {@code VolatileImage}.
! * @return a {@code Graphics2D}, used for drawing into this
* image.
*/
public abstract Graphics2D createGraphics();
// Volatile management methods
/**
* Attempts to restore the drawing surface of the image if the surface
! * had been lost since the last {@code validate} call. Also
* validates this image against the given GraphicsConfiguration
* parameter to see whether operations from this image to the
* GraphicsConfiguration are compatible. An example of an
* incompatible combination might be a situation where a VolatileImage
* object was created on one graphics device and then was used
* to render to a different graphics device. Since VolatileImage
* objects tend to be very device-specific, this operation might
* not work as intended, so the return code from this validate
* call would note that incompatibility. A null or incorrect
* value for gc may cause incorrect values to be returned from
! * {@code validate} and may cause later problems with rendering.
*
! * @param gc a {@code GraphicsConfiguration} object for this
* image to be validated against. A null gc implies that the
* validate method should skip the compatibility test.
! * @return {@code IMAGE_OK} if the image did not need validation<BR>
! * {@code IMAGE_RESTORED} if the image needed restoration.
* Restoration implies that the contents of the image may have
* been affected and the image may need to be re-rendered.<BR>
! * {@code IMAGE_INCOMPATIBLE} if the image is incompatible
! * with the {@code GraphicsConfiguration} object passed
! * into the {@code validate} method. Incompatibility
* implies that the image may need to be recreated with a
! * new {@code Component} or
! * {@code GraphicsConfiguration} in order to get an image
* that can be used successfully with this
! * {@code GraphicsConfiguration}.
* An incompatible image is not checked for whether restoration
* was necessary, so the state of the image is unchanged
! * after a return value of {@code IMAGE_INCOMPATIBLE}
* and this return value implies nothing about whether the
* image needs to be restored.
* @see java.awt.GraphicsConfiguration
* @see java.awt.Component
* @see #IMAGE_OK
*** 286,302 ****
* @see #IMAGE_INCOMPATIBLE
*/
public abstract int validate(GraphicsConfiguration gc);
/**
! * Returns <code>true</code> if rendering data was lost since last
! * <code>validate</code> call. This method should be called by the
* application at the end of any series of rendering operations to
* or from the image to see whether
* the image needs to be validated and the rendering redone.
! * @return <code>true</code> if the drawing surface needs to be restored;
! * <code>false</code> otherwise.
*/
public abstract boolean contentsLost();
/**
* Returns an ImageCapabilities object which can be
--- 286,302 ----
* @see #IMAGE_INCOMPATIBLE
*/
public abstract int validate(GraphicsConfiguration gc);
/**
! * Returns {@code true} if rendering data was lost since last
! * {@code validate} call. This method should be called by the
* application at the end of any series of rendering operations to
* or from the image to see whether
* the image needs to be validated and the rendering redone.
! * @return {@code true} if the drawing surface needs to be restored;
! * {@code false} otherwise.
*/
public abstract boolean contentsLost();
/**
* Returns an ImageCapabilities object which can be
*** 308,319 ****
* no video memory left for creating an image of that
* size, so although the object is a VolatileImage, it is
* not as accelerated as other VolatileImage objects on
* this platform might be. The user might want that
* information to find other solutions to their problem.
! * @return an <code>ImageCapabilities</code> object that contains
! * the capabilities of this <code>VolatileImage</code>.
* @since 1.4
*/
public abstract ImageCapabilities getCapabilities();
/**
--- 308,319 ----
* no video memory left for creating an image of that
* size, so although the object is a VolatileImage, it is
* not as accelerated as other VolatileImage objects on
* this platform might be. The user might want that
* information to find other solutions to their problem.
! * @return an {@code ImageCapabilities} object that contains
! * the capabilities of this {@code VolatileImage}.
* @since 1.4
*/
public abstract ImageCapabilities getCapabilities();
/**
*** 328,338 ****
protected int transparency = TRANSLUCENT;
/**
* Returns the transparency. Returns either OPAQUE, BITMASK,
* or TRANSLUCENT.
! * @return the transparency of this <code>VolatileImage</code>.
* @see Transparency#OPAQUE
* @see Transparency#BITMASK
* @see Transparency#TRANSLUCENT
* @since 1.5
*/
--- 328,338 ----
protected int transparency = TRANSLUCENT;
/**
* Returns the transparency. Returns either OPAQUE, BITMASK,
* or TRANSLUCENT.
! * @return the transparency of this {@code VolatileImage}.
* @see Transparency#OPAQUE
* @see Transparency#BITMASK
* @see Transparency#TRANSLUCENT
* @since 1.5
*/
< prev index next >