Source Code Cross Referenced for VolatileImage.java in  » 6.0-JDK-Modules » j2me » java » awt » image » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules » j2me » java.awt.image 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        /*
002:         * @(#)VolatileImage.java	1.5 %E
003:         *
004:         * Copyright  1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005:         * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006:         * 
007:         * This program is free software; you can redistribute it and/or
008:         * modify it under the terms of the GNU General Public License version
009:         * 2 only, as published by the Free Software Foundation. 
010:         * 
011:         * This program is distributed in the hope that it will be useful, but
012:         * WITHOUT ANY WARRANTY; without even the implied warranty of
013:         * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014:         * General Public License version 2 for more details (a copy is
015:         * included at /legal/license.txt). 
016:         * 
017:         * You should have received a copy of the GNU General Public License
018:         * version 2 along with this work; if not, write to the Free Software
019:         * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020:         * 02110-1301 USA 
021:         * 
022:         * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023:         * Clara, CA 95054 or visit www.sun.com if you need additional
024:         * information or have any questions. 
025:         */
026:
027:        package java.awt.image;
028:
029:        import java.awt.Color;
030:        import java.awt.Graphics;
031:        import java.awt.Graphics2D;
032:        import java.awt.GraphicsConfiguration;
033:        import java.awt.GraphicsDevice;
034:        import java.awt.Image;
035:        import java.awt.ImageCapabilities;
036:        import java.awt.Toolkit;
037:
038:        /**
039:         * VolatileImage is an image which can lose its 
040:         * contents at any time due to circumstances beyond the control of the 
041:         * application (e.g., situations caused by the operating system or by
042:         * other applications). Because of the potential for hardware acceleration,
043:         * a VolatileImage object can have significant performance benefits on 
044:         * some platforms.
045:         * <p>
046:         * The drawing surface of an image (the memory where the image contents 
047:         * actually reside) can be lost or invalidated, causing the contents of that 
048:         * memory to go away.  The drawing surface thus needs to be restored
049:         * or recreated and the contents of that surface need to be
050:         * re-rendered.  VolatileImage provides an interface for 
051:         * allowing the user to detect these problems and fix them
052:         * when they occur.
053:         * <p>
054:         * This image should not be subclassed directly but should be created
055:         * by using the {@link java.awt.Component#createVolatileImage(int, int)
056:         * Component.createVolatileImage} or 
057:         * {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int)
058:         * GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods.
059:         * <P>
060:         * An example of using a VolatileImage object follows:
061:         * <pre>
062:         * // image creation
063:         * VolatileImage vImg = createVolatileImage(w, h);
064:         *
065:         * 
066:         * // rendering to the image
067:         * void renderOffscreen() {
068:         *	do {
069:         *	    if (vImg.validate(getGraphicsConfiguration()) ==
070:         *		VolatileImage.IMAGE_INCOMPATIBLE)
071:         *	    {
072:         *		// old vImg doesn't work with new GraphicsConfig; re-create it
073:         *		vImg = createVolatileImage(w, h);
074:         *	    }
075:         *	    Graphics2D g = vImg.createGraphics();
076:         *	    //
077:         *	    // miscellaneous rendering commands...
078:         *	    //
079:         *	    g.dispose();
080:         *	} while (vImg.contentsLost());
081:         * }
082:         *
083:         *
084:         * // copying from the image (here, gScreen is the Graphics
085:         * // object for the onscreen window)
086:         * do {
087:         *	int returnCode = vImg.validate(getGraphicsConfiguration());
088:         *	if (returnCode == VolatileImage.IMAGE_RESTORED) {
089:         *	    // Contents need to be restored
090:         *	    renderOffscreen();	    // restore contents
091:         *	} else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {
092:         *	    // old vImg doesn't work with new GraphicsConfig; re-create it
093:         *	    vImg = createVolatileImage(w, h);
094:         *	    renderOffscreen();
095:         *	}
096:         *	gScreen.drawImage(vImg, 0, 0, this);
097:         * } while (vImg.contentsLost());
098:         * </pre>
099:         * <P>
100:         * Note that this class subclasses from the {@link Image} class, which
101:         * includes methods that take an {@link ImageObserver} parameter for
102:         * asynchronous notifications as information is received from
103:         * a potential {@link ImageProducer}.  Since this <code>VolatileImage</code> 
104:         * is not loaded from an asynchronous source, the various methods that take
105:         * an <code>ImageObserver</code> parameter will behave as if the data has
106:         * already been obtained from the <code>ImageProducer</code>.  
107:         * Specifically, this means that the return values from such methods 
108:         * will never indicate that the information is not yet available and 
109:         * the <code>ImageObserver</code> used in such methods will never 
110:         * need to be recorded for an asynchronous callback notification.
111:         */
112:        public abstract class VolatileImage extends Image {
113:
114:            // Return codes for validate() method
115:
116:            /**
117:             * Validated image is ready to use as-is.
118:             */
119:            public static final int IMAGE_OK = 0;
120:
121:            /**
122:             * Validated image has been restored and is now ready to use.
123:             * Note that restoration causes contents of the image to be lost.
124:             */
125:            public static final int IMAGE_RESTORED = 1;
126:
127:            /**
128:             * Validated image is incompatible with supplied 
129:             * <code>GraphicsConfiguration</code> object and should be
130:             * re-created as appropriate.  Usage of the image as-is
131:             * after receiving this return code from <code>validate</code>
132:             * is undefined.
133:             */
134:            public static final int IMAGE_INCOMPATIBLE = 2;
135:
136:            /**
137:             * Returns a static snapshot image of this object.  The
138:             * <code>BufferedImage</code> returned is only current with
139:             * the <code>VolatileImage</code> at the time of the request 
140:             * and will not be updated with any future changes to the 
141:             * <code>VolatileImage</code>.
142:             * @return a {@link BufferedImage} representation of this
143:             *		<code>VolatileImage</code>
144:             * @see BufferedImage
145:             */
146:            public abstract BufferedImage getSnapshot();
147:
148:            /**
149:             * Returns the width of the <code>VolatileImage</code>.
150:             * @return the width of this <code>VolatileImage</code>.
151:             */
152:            public abstract int getWidth();
153:
154:            /**
155:             * Returns the height of the <code>VolatileImage</code>.
156:             * @return the height of this <code>VolatileImage</code>.
157:             */
158:            public abstract int getHeight();
159:
160:            // Image overrides
161:
162:            /** 
163:             * This returns an ImageProducer for this VolatileImage.
164:             * Note that the VolatileImage object is optimized for 
165:             * rendering operations and blitting to the screen or other
166:             * VolatileImage objects, as opposed to reading back the
167:             * pixels of the image.  Therefore, operations such as
168:             * <code>getSource</code> may not perform as fast as
169:             * operations that do not rely on reading the pixels.
170:             * Note also that the pixel values read from the image are current
171:             * with those in the image only at the time that they are 
172:             * retrieved. This method takes a snapshot
173:             * of the image at the time the request is made and the
174:             * ImageProducer object returned works with
175:             * that static snapshot image, not the original VolatileImage.
176:             * Calling getSource()
177:             * is equivalent to calling getSnapshot().getSource().
178:             * @return an {@link ImageProducer} that can be used to produce the
179:             * pixels for a <code>BufferedImage</code> representation of
180:             * this Image.
181:             * @see ImageProducer
182:             * @see #getSnapshot()
183:             */
184:            public ImageProducer getSource() {
185:                // NOTE: Make sure this functionality is in line with the
186:                // spec.  In particular, we are returning the Source for a 
187:                // static image (the snapshot), not a changing image (the 
188:                // VolatileImage).  So if the user expects the Source to be
189:                // up-to-date with the current contents of the VolatileImage,
190:                // they will be disappointed...
191:                // NOTE: This assumes that getSnapshot() returns something
192:                // valid and not the default null object returned by this class
193:                // (so it assumes that the actual VolatileImage object is 
194:                // subclassed off something that does the right thing 
195:                // (e.g., SunVolatileImage).
196:                return getSnapshot().getSource();
197:            }
198:
199:            // NOTE: if we want any decent performance for getScaledInstance(),
200:            // we should override the Image implementation of it...
201:
202:            /**
203:             * Releases system resources currently consumed by this image.
204:             * <p>
205:             * When a VolatileImage object is created, limited system resources
206:             * such as video memory (VRAM) may be allocated in order to
207:             * support the image.  When a VolatileImage object is no longer
208:             * used, it may be garbage-collected and those system resources
209:             * will be returned, but this process does 
210:             * not happen at guaranteed times.  Applications that create
211:             * many VolatileImage objects (for example, a resizing window
212:             * may force recreation of its back buffer as the size
213:             * changes) may run out of optimal system
214:             * resources for new VolatileImage objects simply because the
215:             * old objects have not yet been removed from the system.  
216:             * (New VolatileImage objects may still be created, but they
217:             * may not perform as well as those created in accelerated
218:             * memory).
219:             * <p>
220:             * By calling this flush method, applications can have more control over
221:             * the state of the resources taken up by obsolete VolatileImage objects.
222:             * <p>
223:             * This method will cause the contents of the image to be lost, so
224:             * calls to {@link #contentsLost} will return <code>true</code>
225:             * and the image must be validated before it can be used again.
226:             * @see #contentsLost
227:             * @see #validate
228:             */
229:            public void flush() {
230:            }
231:
232:            /**
233:             * This method returns a {@link Graphics2D}, but is here
234:             * for backwards compatibility.  {@link #createGraphics() createGraphics} is more
235:             * convenient, since it is declared to return a 
236:             * <code>Graphics2D</code>.
237:             * @return a <code>Graphics2D</code>, which can be used to draw into
238:             *          this image.
239:             */
240:            public Graphics getGraphics() {
241:                return createGraphics();
242:            }
243:
244:            /**
245:             * Creates a <code>Graphics2D</code>, which can be used to draw into
246:             * this <code>VolatileImage</code>.
247:             * @return a <code>Graphics2D</code>, used for drawing into this
248:             *          image. 
249:             */
250:            public abstract Graphics2D createGraphics();
251:
252:            // Volatile management methods
253:
254:            /**
255:             * Attempts to restore the drawing surface of the image if the surface
256:             * had been lost since the last <code>validate</code> call.  Also
257:             * validates this image against the given GraphicsConfiguration
258:             * parameter to see whether operations from this image to the
259:             * GraphicsConfiguration are compatible.  An example of an
260:             * incompatible combination might be a situation where a VolatileImage
261:             * object was created on one graphics device and then was used
262:             * to render to a different graphics device.  Since VolatileImage
263:             * objects tend to be very device-specific, this operation might
264:             * not work as intended, so the return code from this validate
265:             * call would note that incompatibility.  A null or incorrect 
266:             * value for gc may cause incorrect values to be returned from
267:             * <code>validate</code> and may cause later problems with rendering.
268:             *
269:             * @param   gc   a <code>GraphicsConfiguration</code> object for this
270:             *		image to be validated against.  A null gc implies that the
271:             *		validate method should skip the compatibility test.
272:             * @return	<code>IMAGE_OK</code> if the image did not need validation<BR>
273:             *		<code>IMAGE_RESTORED</code> if the image needed restoration.  
274:             *		Restoration implies that the contents of the image may have 
275:             *		been affected and the image may need to be re-rendered.<BR>
276:             *		<code>IMAGE_INCOMPATIBLE</code> if the image is incompatible
277:             *		with the <code>GraphicsConfiguration</code> object passed
278:             *		into the <code>validate</code> method.  Incompatibility
279:             *		implies that the image may need to be recreated with a
280:             *		new <code>Component</code> or 
281:             *		<code>GraphicsConfiguration</code> in order to get an image
282:             *		that can be used successfully with this 
283:             *		<code>GraphicsConfiguration</code>.
284:             *		An incompatible image is not checked for whether restoration
285:             *		was necessary, so the state of the image is unchanged 
286:             *		after a return value of <code>IMAGE_INCOMPATIBLE</code>
287:             *		and this return value implies nothing about whether the
288:             *		image needs to be restored.
289:             * @see java.awt.GraphicsConfiguration
290:             * @see java.awt.Component
291:             * @see #IMAGE_OK
292:             * @see #IMAGE_RESTORED
293:             * @see #IMAGE_INCOMPATIBLE
294:             */
295:            public abstract int validate(GraphicsConfiguration gc);
296:
297:            /**
298:             * Returns <code>true</code> if rendering data was lost since last 
299:             * <code>validate</code> call.  This method should be called by the 
300:             * application at the end of any series of rendering operations to 
301:             * or from the image to see whether
302:             * the image needs to be validated and the rendering redone.
303:             * @return <code>true</code> if the drawing surface needs to be restored;
304:             * <code>false</code> otherwise.
305:             */
306:            public abstract boolean contentsLost();
307:
308:            /**
309:             * Returns an ImageCapabilities object which can be
310:             * inquired as to the specific capabilities of this
311:             * VolatileImage.  This would allow programmers to find
312:             * out more runtime information on the specific VolatileImage
313:             * object that they have created.  For example, the user
314:             * might create a VolatileImage but the system may have
315:             * no video memory left for creating an image of that
316:             * size, so although the object is a VolatileImage, it is
317:             * not as accelerated as other VolatileImage objects on
318:             * this platform might be.  The user might want that
319:             * information to find other solutions to their problem.
320:             * @return an <code>ImageCapabilities</code> object that contains
321:             *         the capabilities of this <code>VolatileImage</code>.
322:             * @since 1.4
323:             */
324:            public abstract ImageCapabilities getCapabilities();
325:
326:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.