javax.media.j3d.J3DGraphics2D Maven / Gradle / Ivy
Show all versions of java3d-core Show documentation
/*
* Copyright 1999-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*
*/
package javax.media.j3d;
import java.awt.Color;
import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.image.BufferedImage;
import java.awt.image.ImageObserver;
/**
* The J3DGraphics2D class extends Graphics2D to provide 2D rendering
* into a Canvas3D. It is an abstract base class that is further
* extended by a non-public Java 3D implementation class. This class
* allows Java 2D rendering to be mixed with Java 3D rendering in the
* same Canvas3D, subject to the same restrictions as imposed for 3D
* immediate-mode rendering: In mixed-mode rendering, all Java 2D
* requests must be done from one of the Canvas3D callback methods; in
* pure-immediate mode, the Java 3D renderer must be stopped for the
* Canvas3D being rendered into.
*
*
* An application obtains a J3D 2D graphics context object from the
* Canvas3D object that the application wishes to render into by using
* the getGraphics2D method. A new J3DGraphics2D object is created if
* one does not already exist.
*
*
* Note that the drawing methods in this class, including those
* inherited from Graphics2D, are not necessarily executed
* immediately. They may be buffered up for future execution.
* Applications must call the flush(boolean) method to ensure
* that the rendering actually happens. The flush method is implicitly
* called in the following cases:
*
*
* - The
Canvas3D.swap method calls
* flush(true)
* - The Java 3D renderer calls
flush(true) prior to
* swapping the buffer for a double buffered on-screen Canvas3D
* - The Java 3D renderer calls
flush(true) prior to
* copying into the off-screen buffer of an off-screen Canvas3D
* - The Java 3D renderer calls
flush(false) after
* calling the preRender, renderField, postRender, and postSwap
* Canvas3D callback methods.
*
*
*
* A single-buffered, pure-immediate mode application must explicitly
* call flush to ensure that the graphics will be rendered to the
* Canvas3D.
*
* @see Canvas3D#getGraphics2D
*
* @since Java 3D 1.2
*/
public abstract class J3DGraphics2D extends Graphics2D {
// Package scope contructor
J3DGraphics2D() {
}
/**
* This method is not supported. The only way to obtain a
* J3DGraphics2D is from the associated Canvas3D.
*
* @exception UnsupportedOperationException this method is not supported
*
* @see Canvas3D#getGraphics2D
*/
@Override
public final Graphics create() {
throw new UnsupportedOperationException();
}
/**
* This method is not supported. The only way to obtain a
* J3DGraphics2D is from the associated Canvas3D.
*
* @exception UnsupportedOperationException this method is not supported
*
* @see Canvas3D#getGraphics2D
*/
@Override
public final Graphics create(int x, int y, int width, int height) {
throw new UnsupportedOperationException();
}
/**
* This method is not supported. Clearing a Canvas3D is done implicitly
* via a Background node in the scene graph or explicitly via the clear
* method in a 3D graphics context.
*
* @exception UnsupportedOperationException this method is not supported
*
* @see Background
* @see GraphicsContext3D#setBackground
* @see GraphicsContext3D#clear
*/
@Override
public final void setBackground(Color color) {
throw new UnsupportedOperationException();
}
/**
* This method is not supported. Clearing a Canvas3D is done implicitly
* via a Background node in the scene graph or explicitly via the clear
* method in a 3D graphics context.
*
* @exception UnsupportedOperationException this method is not supported
*
* @see Background
* @see GraphicsContext3D#getBackground
* @see GraphicsContext3D#clear
*/
@Override
public final Color getBackground() {
throw new UnsupportedOperationException();
}
/**
* This method is not supported. Clearing a Canvas3D is done implicitly
* via a Background node in the scene graph or explicitly via the clear
* method in a 3D graphics context.
*
* @exception UnsupportedOperationException this method is not supported
*
* @see Background
* @see GraphicsContext3D#setBackground
* @see GraphicsContext3D#clear
*/
@Override
public final void clearRect(int x, int y, int width, int height) {
throw new UnsupportedOperationException();
}
/**
* Flushes all previously executed rendering operations to the
* drawing buffer for this 2D graphics object.
*
* @param wait flag indicating whether or not to wait for the
* rendering to be complete before returning from this call.
*/
public abstract void flush(boolean wait);
/**
* Draws the specified image and flushes the buffer. This is
* functionally equivalent to calling drawImage(...)
* followed by flush(false), but can avoid the cost
* of making an extra copy of the image in some cases. Anything
* previously drawn to this J3DGraphics2D will be flushed before
* the image is drawn.
*
* @param img The image to draw
* @param x The x location to draw at
* @param y The y location to draw at
* @param observer The ImageObserver
*
* @since Java 3D 1.3
*/
public abstract void drawAndFlushImage(BufferedImage img, int x, int y,
ImageObserver observer);
}