/[classpath]/classpath/java/awt/image/VolatileImage.java
ViewVC logotype

Diff of /classpath/java/awt/image/VolatileImage.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.2 by mkoch, Thu Nov 7 08:50:38 2002 UTC revision 1.3 by fitzsim, Wed May 4 03:48:04 2005 UTC
# Line 1  Line 1 
1  /* VolatileImage.java --  /* VolatileImage.java -- a hardware-accelerated image buffer
2     Copyright (C) 2002 Free Software Foundation, Inc.     Copyright (C) 2002, 2005 Free Software Foundation, Inc.
3    
4  This file is part of GNU Classpath.     This file is part of GNU Classpath.
5    
6  GNU Classpath is free software; you can redistribute it and/or modify     GNU Classpath is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by     it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2, or (at your option)     the Free Software Foundation; either version 2, or (at your option)
9  any later version.     any later version.
10    
11  GNU Classpath is distributed in the hope that it will be useful, but     GNU Classpath is distributed in the hope that it will be useful, but
12  WITHOUT ANY WARRANTY; without even the implied warranty of     WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  General Public License for more details.     General Public License for more details.
15    
16  You should have received a copy of the GNU General Public License     You should have received a copy of the GNU General Public License
17  along with GNU Classpath; see the file COPYING.  If not, write to the     along with GNU Classpath; see the file COPYING.  If not, write to the
18  Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA     Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19  02111-1307 USA.     02111-1307 USA.
20    
21  Linking this library statically or dynamically with other modules is     Linking this library statically or dynamically with other modules is
22  making a combined work based on this library.  Thus, the terms and     making a combined work based on this library.  Thus, the terms and
23  conditions of the GNU General Public License cover the whole     conditions of the GNU General Public License cover the whole
24  combination.     combination.
25    
26  As a special exception, the copyright holders of this library give you     As a special exception, the copyright holders of this library give you
27  permission to link this library with independent modules to produce an     permission to link this library with independent modules to produce an
28  executable, regardless of the license terms of these independent     executable, regardless of the license terms of these independent
29  modules, and to copy and distribute the resulting executable under     modules, and to copy and distribute the resulting executable under
30  terms of your choice, provided that you also meet, for each linked     terms of your choice, provided that you also meet, for each linked
31  independent module, the terms and conditions of the license of that     independent module, the terms and conditions of the license of that
32  module.  An independent module is a module which is not derived from     module.  An independent module is a module which is not derived from
33  or based on this library.  If you modify this library, you may extend     or based on this library.  If you modify this library, you may extend
34  this exception to your version of the library, but you are not     this exception to your version of the library, but you are not
35  obligated to do so.  If you do not wish to do so, delete this     obligated to do so.  If you do not wish to do so, delete this
36  exception statement from your version. */     exception statement from your version. */
37    
38    
39  package java.awt.image;  package java.awt.image;
# Line 42  import java.awt.Graphics; Line 42  import java.awt.Graphics;
42  import java.awt.Graphics2D;  import java.awt.Graphics2D;
43  import java.awt.GraphicsConfiguration;  import java.awt.GraphicsConfiguration;
44  import java.awt.Image;  import java.awt.Image;
45    import java.awt.Transparency;
46  import java.awt.ImageCapabilities;  import java.awt.ImageCapabilities;
47    
48  /** STUBS ONLY */  /**
49     * VolatileImage represents a hardware-accelerated graphics buffer.
50     * The native graphics system may free or damage the resources
51     * occupied by a VolatileImage at any time.  As such, one must
52     * frequently check the "validity" of the image buffer's resources.
53     *
54     * A volatile image's "validity" depends on multiple factors.  Its
55     * resources may have become unavailble in which case you must
56     * reallocate them.  If you move the image from one output device to
57     * another, you may need to recreate the image's resources if the new
58     * output device's capabilities don't match the old one's.  Finally,
59     * if the contents of the image's buffer have been damaged you must
60     * re-render the image.
61     *
62     * VolatileImages should always be created using either
63     * Component.createVolatileImage or
64     * GraphicsConfiguration.createCompatibleVolatileImage.
65     */
66  public abstract class VolatileImage extends Image  public abstract class VolatileImage extends Image
67      implements Transparency
68  {  {
69      /**
70       * One of validate's possible return values.  Indicates that the
71       * image buffer matches its graphics configuration's capabilities
72       * and that its resources are initialized and ready to be drawn
73       * into.  Also implies that any existing image rendered to the
74       * buffer is intact and need not be re-rendered.
75       */
76    public static final int IMAGE_OK = 0;    public static final int IMAGE_OK = 0;
77    
78      /**
79       * One of validate's possible return values.  Indicates that the
80       * image buffer has been restored, meaning that it is valid and
81       * ready-to-use but that its previous contents have been lost.  This
82       * return value implies IMAGE_OK but that the image needs to be
83       * re-rendered.
84       */
85    public static final int IMAGE_RESTORED = 1;    public static final int IMAGE_RESTORED = 1;
86    
87      /**
88       * One of validate's possible return values.  Indicates that the
89       * image buffer type is unsupported by the current graphics
90       * configuration.  The graphics configuration may have changed, for
91       * example if the image moved from one output device to another.
92       * This return value implies that the image buffer's resources
93       * should be re-acquired.
94       */
95    public static final int IMAGE_INCOMPATIBLE = 2;    public static final int IMAGE_INCOMPATIBLE = 2;
96    
97      /**
98       * This image's transparency type.  One of Transparency.BITMASK,
99       * Transparency.OPAQUE or Transparency.TRANSLUCENT.
100       *
101       * @since 1.5
102       */
103      protected int transparency;
104    
105      /**
106       * Default constructor.  VolatileImages should not be created
107       * directly.  Rather, you should use Component.createVolatileImage
108       * or GraphicsConfiguration.createCompatibleVolatileImage.
109       */
110    public VolatileImage()    public VolatileImage()
111    {    {
112    }    }
113    
114      /**
115       * Returns an image representing the current state of the volatile
116       * image buffer.  The returned image is static meaning that it is
117       * not updated after being created.  It is a snapshot of the
118       * volatile image buffer at the time getSnapshot is called.
119       *
120       * This method, which reads pixels from the volatile image buffer,
121       * may be less-performant than methods that write pixels since
122       * VolatileImages are typically optimized for writing.
123       *
124       * @return a BufferedImage representing this VolatileImage
125       */
126    public abstract BufferedImage getSnapshot();    public abstract BufferedImage getSnapshot();
127    
128      /**
129       * Returns the width of this image buffer.
130       *
131       * @return the width of this VolatileImage
132       */
133    public abstract int getWidth();    public abstract int getWidth();
134    
135      /**
136       * Returns the height of this image buffer.
137       *
138       * @return the height of this VolatileImage
139       */
140    public abstract int getHeight();    public abstract int getHeight();
141    
142      /**
143       * Calling this method is equivalent to calling
144       * getSnapshot().getSource().  The ImageProducer produces pixels
145       * from the BufferedImage snapshot and not from the VolatileImage
146       * itself.  Thus, changes to the VolatileImage that occur after this
147       * ImageProducer has been retrieved will not be reflected in the
148       * produced pixels.
149       *
150       * This method, which reads pixels from the volatile image buffer,
151       * may be less-performant than methods that write pixels since
152       * VolatileImages are typically optimized for writing.
153       *
154       * @return an ImageProducer for a static BufferedImage snapshot of
155       * this image buffer.
156       */
157    public ImageProducer getSource()    public ImageProducer getSource()
158    {    {
159      return getSnapshot().getSource();      return getSnapshot().getSource();
160    }    }
161    
162      /**
163       * Releases the system resources taken by this image.
164       */
165    public void flush()    public void flush()
166    {    {
167    }    }
168    
169      /**
170       * Returns a Graphics2D object that can be used to draw onto this
171       * image.  This method is present for backwards-compatibility.  It
172       * simply returns the result of createGraphics.
173       *
174       * @return a Graphics2D object that can be used to draw onto this
175       * image
176       */
177    public Graphics getGraphics()    public Graphics getGraphics()
178    {    {
179      return createGraphics();      return createGraphics();
180    }    }
181    
182      /**
183       * Returns a Graphics2D object that can be used to draw onto this
184       * image.
185       *
186       * @return a Graphics2D object that can be used to draw onto this
187       * image
188       */
189    public abstract Graphics2D createGraphics();    public abstract Graphics2D createGraphics();
190    
191      /**
192       * Validates and restores this image.  If the image buffer has
193       * become unavailable for further use since the last call to
194       * validate, validate will allocate a new image buffer.  The image
195       * is also "validated" against the GraphicsConfiguration parameter.
196       *
197       * "Validating" the image means checking that the capabilities it
198       * requires of the output device are indeed supported by the given
199       * output device.  If the image's characteristics, which can be
200       * highly output device-specific, are not supported by the graphics
201       * configuration, then IMAGE_INCOMPATIBLE will be returned.  This
202       * can happen, for example, if this image was created on one output
203       * device, then validated against a different output device with
204       * different capabilities.  Calling validate with a NULL gc argument
205       * causes validate to skip the validation test.
206       *
207       * @param gc graphics configuration against which to validate or
208       * NULL
209       *
210       * @return a code indicating the result of validation. One of:
211       * <ul>
212       *   <li><code>IMAGE_OK</code> if the image did not need to be
213       *   validated and didn't need to be restored</li>
214       *   <li><code>IMAGE_RESTORED</code> if the image may need to be
215       *   re-rendered.  This return value implies IMAGE_OK.</li>
216       *   <li><code>IMAGE_INCOMPATIBLE</code> if this image's
217       *   requirements are not fulfilled by the graphics configuration
218       *   parameter.  This implies that you need to create a new
219       *   VolatileImage for the different GraphicsConfiguration or
220       *   Component. This return value implies nothing about whether the
221       *   image is valid or needs to be re-rendered.</li>
222       * </ul>
223       */
224    public abstract int validate(GraphicsConfiguration gc);    public abstract int validate(GraphicsConfiguration gc);
225    
226      /**
227       * Returns true if the contents of the image buffer have been
228       * damaged or if the image buffer's resources have been reclaimed by
229       * the graphics system.  You should call this method after a series
230       * of rendering operations to or from the image, to see if the image
231       * buffer needs to be revalidated or the image re-rendered.
232       *
233       * @return true if the validate should be called, false otherwise
234       */
235    public abstract boolean contentsLost();    public abstract boolean contentsLost();
236    
237      /**
238       * Returns the capabilities of this image buffer.
239       *
240       * @return the capabilities of this image buffer
241       */
242    public abstract ImageCapabilities getCapabilities();    public abstract ImageCapabilities getCapabilities();
243  } // class VolatileImage  
244      /**
245       * Returns the transparency type of this image.
246       *
247       * @return Transparency.OPAQUE, Transparency.BITMASK or
248       * Transparency.TRANSLUCENT.
249       */
250      public int getTransparency()
251      {
252        return transparency;
253      }
254    }

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26