/[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.2.2.1 by gnu_andrew, Fri May 20 18:20:54 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    
# 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 that the image needs to be re-rendered.
83       */
84    public static final int IMAGE_RESTORED = 1;    public static final int IMAGE_RESTORED = 1;
85    
86      /**
87       * One of validate's possible return values.  Indicates that the
88       * image buffer type is unsupported by the current graphics
89       * configuration.  The graphics configuration may have changed, for
90       * example if the image moved from one output device to another.
91       * This return value implies that the image buffer's resources
92       * should be re-acquired.
93       */
94    public static final int IMAGE_INCOMPATIBLE = 2;    public static final int IMAGE_INCOMPATIBLE = 2;
95    
96      /**
97       * This image's transparency type.  One of Transparency.BITMASK,
98       * Transparency.OPAQUE or Transparency.TRANSLUCENT.
99       *
100       * @since 1.5
101       */
102      protected int transparency;
103    
104      /**
105       * Default constructor.  VolatileImages should not be created
106       * directly.  Rather, you should use Component.createVolatileImage
107       * or GraphicsConfiguration.createCompatibleVolatileImage.
108       */
109    public VolatileImage()    public VolatileImage()
110    {    {
111    }    }
112    
113      /**
114       * Returns an image representing the current state of the volatile
115       * image buffer.  The returned image is static meaning that it is
116       * not updated after being created.  It is a snapshot of the
117       * volatile image buffer at the time getSnapshot is called.
118       *
119       * This method, which reads pixels from the volatile image buffer,
120       * may be less-performant than methods that write pixels since
121       * VolatileImages are typically optimized for writing.
122       *
123       * @return a BufferedImage representing this VolatileImage
124       */
125    public abstract BufferedImage getSnapshot();    public abstract BufferedImage getSnapshot();
126    
127      /**
128       * Returns the width of this image buffer.
129       *
130       * @return the width of this VolatileImage
131       */
132    public abstract int getWidth();    public abstract int getWidth();
133    
134      /**
135       * Returns the height of this image buffer.
136       *
137       * @return the height of this VolatileImage
138       */
139    public abstract int getHeight();    public abstract int getHeight();
140    
141      /**
142       * Calling this method is equivalent to calling
143       * getSnapshot().getSource().  The ImageProducer produces pixels
144       * from the BufferedImage snapshot and not from the VolatileImage
145       * itself.  Thus, changes to the VolatileImage that occur after this
146       * ImageProducer has been retrieved will not be reflected in the
147       * produced pixels.
148       *
149       * This method, which reads pixels from the volatile image buffer,
150       * may be less-performant than methods that write pixels since
151       * VolatileImages are typically optimized for writing.
152       *
153       * @return an ImageProducer for a static BufferedImage snapshot of
154       * this image buffer
155       */
156    public ImageProducer getSource()    public ImageProducer getSource()
157    {    {
158      return getSnapshot().getSource();      return getSnapshot().getSource();
159    }    }
160    
161      /**
162       * Releases the system resources taken by this image.
163       */
164    public void flush()    public void flush()
165    {    {
166    }    }
167    
168      /**
169       * Returns a Graphics2D object that can be used to draw onto this
170       * image.  This method is present for backwards-compatibility.  It
171       * simply returns the result of createGraphics.
172       *
173       * @return a Graphics2D object that can be used to draw onto this
174       * image
175       */
176    public Graphics getGraphics()    public Graphics getGraphics()
177    {    {
178      return createGraphics();      return createGraphics();
179    }    }
180    
181      /**
182       * Returns a Graphics2D object that can be used to draw onto this
183       * image.
184       *
185       * @return a Graphics2D object that can be used to draw onto this
186       * image
187       */
188    public abstract Graphics2D createGraphics();    public abstract Graphics2D createGraphics();
189    
190      /**
191       * Validates and restores this image.  If the image buffer has
192       * become unavailable for further use since the last call to
193       * validate, validate will allocate a new image buffer.  The image
194       * is also "validated" against the GraphicsConfiguration parameter.
195       *
196       * "Validating" the image means checking that the capabilities it
197       * requires of the output device are indeed supported by the given
198       * output device.  If the image's characteristics, which can be
199       * highly output device-specific, are not supported by the graphics
200       * configuration, then IMAGE_INCOMPATIBLE will be returned.  This
201       * can happen, for example, if this image was created on one output
202       * device, then validated against a different output device with
203       * different capabilities.  Calling validate with a NULL gc argument
204       * causes validate to skip the validation test.
205       *
206       * @param gc graphics configuration against which to validate or
207       * NULL
208       *
209       * @return a code indicating the result of validation. One of:
210       * <ul>
211       *   <li><code>IMAGE_OK</code> if the image did not need to be
212       *   validated and didn't need to be restored</li>
213       *   <li><code>IMAGE_RESTORED</code> if the image may need to be
214       *   re-rendered.</li>
215       *   <li><code>IMAGE_INCOMPATIBLE</code> if this image's
216       *   requirements are not fulfilled by the graphics configuration
217       *   parameter.  This implies that you need to create a new
218       *   VolatileImage for the different GraphicsConfiguration or
219       *   Component. This return value implies nothing about whether the
220       *   image is valid or needs to be re-rendered.</li>
221       * </ul>
222       */
223    public abstract int validate(GraphicsConfiguration gc);    public abstract int validate(GraphicsConfiguration gc);
224    
225      /**
226       * Returns true if the contents of the image buffer have been
227       * damaged or if the image buffer's resources have been reclaimed by
228       * the graphics system.  You should call this method after a series
229       * of rendering operations to or from the image, to see if the image
230       * buffer needs to be revalidated or the image re-rendered.
231       *
232       * @return true if the validate should be called, false otherwise
233       */
234    public abstract boolean contentsLost();    public abstract boolean contentsLost();
235    
236      /**
237       * Returns the capabilities of this image buffer.
238       *
239       * @return the capabilities of this image buffer
240       */
241    public abstract ImageCapabilities getCapabilities();    public abstract ImageCapabilities getCapabilities();
242  } // class VolatileImage  
243      /**
244       * Returns the transparency type of this image.
245       *
246       * @return Transparency.OPAQUE, Transparency.BITMASK or
247       * Transparency.TRANSLUCENT
248       */
249      public int getTransparency()
250      {
251        return transparency;
252      }
253    }

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

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