/*
 * 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.
 *
 * <p>
 * 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.
 *
 * <p>
 * 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 <code><a
 * href="#flush(boolean)">flush</a>(boolean)</code> method to ensure
 * that the rendering actually happens. The flush method is implicitly
 * called in the following cases:
 *
 * <ul>
 * <li>The <code>Canvas3D.swap</code> method calls
 * <code>flush(true)</code></li>
 * <li>The Java 3D renderer calls <code>flush(true)</code> prior to
 * swapping the buffer for a double buffered on-screen Canvas3D</li>
 * <li>The Java 3D renderer calls <code>flush(true)</code> prior to
 * copying into the off-screen buffer of an off-screen Canvas3D</li>
 * <li>The Java 3D renderer calls <code>flush(false)</code> after
 * calling the preRender, renderField, postRender, and postSwap
 * Canvas3D callback methods.</li>
 * </ul>
 *
 * <p>
 * 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 <code>drawImage(...)</code>
     * followed by <code>flush(false)</code>, 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);

}