OSDN Git Service

2005-05-04 Thomas Fitzsimmons <fitzsim@redhat.com>
[pf3gnuchains/gcc-fork.git] / libjava / java / awt / image / BufferStrategy.java
1 /* BufferStrategy.java -- describes image buffering resources
2    Copyright (C) 2002, 2005 Free Software Foundation, Inc.
3
4 This file is part of GNU Classpath.
5
6 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
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15
16 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
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19 02111-1307 USA.
20
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library.  Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 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
34 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
36 exception statement from your version. */
37
38
39 package java.awt.image;
40
41 import java.awt.BufferCapabilities;
42 import java.awt.Graphics;
43
44 /**
45  * This class describes a strategy for managing image buffering
46  * resources on a Canvas or Window.  A given buffer strategy may make
47  * use of hardware acceleration or take advantage of features of the
48  * native graphics system.  Examples of buffering strategies are
49  * double or triple buffering using either flipping or blitting.  For
50  * the details of these algorithms see BufferCapabilities.
51  *
52  * To use a buffer strategy, you retrieve it from either the current
53  * GraphicsConfiguration or from the Component on which you'd like to
54  * draw.  Then you can query the strategy's capabilities to make sure
55  * they're suitable.
56  *
57  * If the strategy's capabilities are suitable, you can obtain a
58  * graphics object and use it to draw with this strategy.  Drawing
59  * with a buffer strategy requires extra care, however.  You'll need
60  * to manually cause the next buffer to be shown on the output device.
61  * And since buffer strategies are usually implemented with a
62  * VolatileImage, you must frequently check that the contents of the
63  * buffer are valid and that the buffer still exists.
64  *
65  * A buffer strategy is usually implemented using a VolatileImage.
66  *
67  * @see VolatileImage
68  * @since 1.4
69  */
70 public abstract class BufferStrategy
71 {
72   /**
73    * Creates a new buffer strategy.
74    */
75   public BufferStrategy()
76   {
77   }
78
79   /**
80    * Retrieves the capabilities of this buffer strategy.
81    *
82    * @return this buffer strategy's capabilities
83    */
84   public abstract BufferCapabilities getCapabilities();
85
86   /**
87    * Retrieves a graphics object that can be used to draw using this
88    * buffer strategy.  This method may not be synchronized so be
89    * careful when calling it from multiple threads.  You also must
90    * manually dispose of this graphics object.
91    *
92    * @return a graphics object that can be used to draw using this
93    * buffer strategy
94    */
95   public abstract Graphics getDrawGraphics();
96
97   /**
98    * Returns whether or not the buffer's resources have been reclaimed
99    * by the native graphics system since the last call to
100    * getDrawGraphics.  If the buffer resources have been lost then
101    * you'll need to obtain new resources before drawing again.  For
102    * details, see the documentation for VolatileImage.
103    *
104    * @return true if the contents were lost since the last call to
105    * getDrawGraphics, false otherwise
106    */
107   public abstract boolean contentsLost();
108
109   /**
110    * Returns whether or not the buffer's resources were re-created and
111    * cleared to the default background color since the last call to
112    * getDrawGraphics.  If the buffer's resources have recently been
113    * re-created and initialized then the buffer's image may need to be
114    * re-rendered.  For details, see the documentation for
115    * VolatileImage.
116    */
117   public abstract boolean contentsRestored();
118
119   /**
120    * Applies this buffer strategy.  In other words, this method brings
121    * the contents of the back or intermediate buffers to the front
122    * buffer.
123    */
124   public abstract void show();
125 }