001: /*
002: * $RCSfile: J3DGraphics2D.java,v $
003: *
004: * Copyright 1999-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.5 $
028: * $Date: 2008/02/28 20:17:25 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import java.awt.*;
035: import java.awt.image.BufferedImage;
036: import java.awt.image.ImageObserver;
037:
038: /**
039: * The J3DGraphics2D class extends Graphics2D to provide 2D rendering
040: * into a Canvas3D. It is an abstract base class that is further
041: * extended by a non-public Java 3D implementation class. This class
042: * allows Java 2D rendering to be mixed with Java 3D rendering in the
043: * same Canvas3D, subject to the same restrictions as imposed for 3D
044: * immediate-mode rendering: In mixed-mode rendering, all Java 2D
045: * requests must be done from one of the Canvas3D callback methods; in
046: * pure-immediate mode, the Java 3D renderer must be stopped for the
047: * Canvas3D being rendered into.
048: *
049: * <p>
050: * An application obtains a J3D 2D graphics context object from the
051: * Canvas3D object that the application wishes to render into by using
052: * the getGraphics2D method. A new J3DGraphics2D object is created if
053: * one does not already exist.
054: *
055: * <p>
056: * Note that the drawing methods in this class, including those
057: * inherited from Graphics2D, are not necessarily executed
058: * immediately. They may be buffered up for future execution.
059: * Applications must call the <code><a
060: * href="#flush(boolean)">flush</a>(boolean)</code> method to ensure
061: * that the rendering actually happens. The flush method is implicitly
062: * called in the following cases:
063: *
064: * <ul>
065: * <li>The <code>Canvas3D.swap</code> method calls
066: * <code>flush(true)</code></li>
067: * <li>The Java 3D renderer calls <code>flush(true)</code> prior to
068: * swapping the buffer for a double buffered on-screen Canvas3D</li>
069: * <li>The Java 3D renderer calls <code>flush(true)</code> prior to
070: * copying into the off-screen buffer of an off-screen Canvas3D</li>
071: * <li>The Java 3D renderer calls <code>flush(false)</code> after
072: * calling the preRender, renderField, postRender, and postSwap
073: * Canvas3D callback methods.</li>
074: * </ul>
075: *
076: * <p>
077: * A single-buffered, pure-immediate mode application must explicitly
078: * call flush to ensure that the graphics will be rendered to the
079: * Canvas3D.
080: *
081: * @see Canvas3D#getGraphics2D
082: *
083: * @since Java 3D 1.2
084: */
085:
086: public abstract class J3DGraphics2D extends Graphics2D {
087:
088: // Package scope contructor
089: J3DGraphics2D() {
090: }
091:
092: /**
093: * This method is not supported. The only way to obtain a
094: * J3DGraphics2D is from the associated Canvas3D.
095: *
096: * @exception UnsupportedOperationException this method is not supported
097: *
098: * @see Canvas3D#getGraphics2D
099: */
100: public final Graphics create() {
101: throw new UnsupportedOperationException();
102: }
103:
104: /**
105: * This method is not supported. The only way to obtain a
106: * J3DGraphics2D is from the associated Canvas3D.
107: *
108: * @exception UnsupportedOperationException this method is not supported
109: *
110: * @see Canvas3D#getGraphics2D
111: */
112: public final Graphics create(int x, int y, int width, int height) {
113: throw new UnsupportedOperationException();
114: }
115:
116: /**
117: * This method is not supported. Clearing a Canvas3D is done implicitly
118: * via a Background node in the scene graph or explicitly via the clear
119: * method in a 3D graphics context.
120: *
121: * @exception UnsupportedOperationException this method is not supported
122: *
123: * @see Background
124: * @see GraphicsContext3D#setBackground
125: * @see GraphicsContext3D#clear
126: */
127: public final void setBackground(Color color) {
128: throw new UnsupportedOperationException();
129: }
130:
131: /**
132: * This method is not supported. Clearing a Canvas3D is done implicitly
133: * via a Background node in the scene graph or explicitly via the clear
134: * method in a 3D graphics context.
135: *
136: * @exception UnsupportedOperationException this method is not supported
137: *
138: * @see Background
139: * @see GraphicsContext3D#getBackground
140: * @see GraphicsContext3D#clear
141: */
142: public final Color getBackground() {
143: throw new UnsupportedOperationException();
144: }
145:
146: /**
147: * This method is not supported. Clearing a Canvas3D is done implicitly
148: * via a Background node in the scene graph or explicitly via the clear
149: * method in a 3D graphics context.
150: *
151: * @exception UnsupportedOperationException this method is not supported
152: *
153: * @see Background
154: * @see GraphicsContext3D#setBackground
155: * @see GraphicsContext3D#clear
156: */
157: public final void clearRect(int x, int y, int width, int height) {
158: throw new UnsupportedOperationException();
159: }
160:
161: /**
162: * Flushes all previously executed rendering operations to the
163: * drawing buffer for this 2D graphics object.
164: *
165: * @param wait flag indicating whether or not to wait for the
166: * rendering to be complete before returning from this call.
167: */
168: public abstract void flush(boolean wait);
169:
170: /**
171: * Draws the specified image and flushes the buffer. This is
172: * functionally equivalent to calling <code>drawImage(...)</code>
173: * followed by <code>flush(false)</code>, but can avoid the cost
174: * of making an extra copy of the image in some cases. Anything
175: * previously drawn to this J3DGraphics2D will be flushed before
176: * the image is drawn.
177: *
178: * @param img The image to draw
179: * @param x The x location to draw at
180: * @param y The y location to draw at
181: * @param observer The ImageObserver
182: *
183: * @since Java 3D 1.3
184: */
185: public abstract void drawAndFlushImage(BufferedImage img, int x,
186: int y, ImageObserver observer);
187:
188: }
|