javax.media.j3d

## Class J3DGraphics2D

- java.lang.Object
- - java.awt.Graphics
  - - java.awt.Graphics2D
    - - javax.media.j3d.J3DGraphics2D

-     public abstract class J3DGraphics2D
      extends java.awt.Graphics2D

  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.

  Since:
    Java 3D 1.2
  See Also:
    `Canvas3D.getGraphics2D()`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearRect(int x, int y, int width, int height)` This method is not supported.
    `java.awt.Graphics` | `create()` This method is not supported.
    `java.awt.Graphics` | `create(int x, int y, int width, int height)` This method is not supported.
    `abstract void` | `drawAndFlushImage(java.awt.image.BufferedImage img, int x, int y, java.awt.image.ImageObserver observer)` Draws the specified image and flushes the buffer.
    `abstract void` | `flush(boolean wait)` Flushes all previously executed rendering operations to the drawing buffer for this 2D graphics object.
    `java.awt.Color` | `getBackground()` This method is not supported.
    `void` | `setBackground(java.awt.Color color)` This method is not supported.

    - ### Methods inherited from class java.awt.Graphics2D

      `addRenderingHints, clip, draw, draw3DRect, drawGlyphVector, drawImage, drawImage, drawRenderableImage, drawRenderedImage, drawString, drawString, drawString, drawString, fill, fill3DRect, getComposite, getDeviceConfiguration, getFontRenderContext, getPaint, getRenderingHint, getRenderingHints, getStroke, getTransform, hit, rotate, rotate, scale, setComposite, setPaint, setRenderingHint, setRenderingHints, setStroke, setTransform, shear, transform, translate, translate`

    - ### Methods inherited from class java.awt.Graphics

      `clipRect, copyArea, dispose, drawArc, drawBytes, drawChars, drawImage, drawImage, drawImage, drawImage, drawImage, drawImage, drawLine, drawOval, drawPolygon, drawPolygon, drawPolyline, drawRect, drawRoundRect, fillArc, fillOval, fillPolygon, fillPolygon, fillRect, fillRoundRect, finalize, getClip, getClipBounds, getClipBounds, getClipRect, getColor, getFont, getFontMetrics, getFontMetrics, hitClip, setClip, setClip, setColor, setFont, setPaintMode, setXORMode, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### create

          public final java.awt.Graphics create()

      This method is not supported. The only way to obtain a J3DGraphics2D is from the associated Canvas3D.
      Specified by:
        `create` in class `java.awt.Graphics`
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      See Also:
        `Canvas3D.getGraphics2D()`

    - #### create

          public final java.awt.Graphics create(int x,
                                 int y,
                                 int width,
                                 int height)

      This method is not supported. The only way to obtain a J3DGraphics2D is from the associated Canvas3D.
      Overrides:
        `create` in class `java.awt.Graphics`
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      See Also:
        `Canvas3D.getGraphics2D()`

    - #### setBackground

          public final void setBackground(java.awt.Color color)

      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.
      Specified by:
        `setBackground` in class `java.awt.Graphics2D`
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      See Also:
        `Background`, `GraphicsContext3D.setBackground(javax.media.j3d.Background)`, `GraphicsContext3D.clear()`

    - #### getBackground

          public final java.awt.Color getBackground()

      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.
      Specified by:
        `getBackground` in class `java.awt.Graphics2D`
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      See Also:
        `Background`, `GraphicsContext3D.getBackground()`, `GraphicsContext3D.clear()`

    - #### clearRect

          public final void clearRect(int x,
                       int y,
                       int width,
                       int height)

      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.
      Specified by:
        `clearRect` in class `java.awt.Graphics`
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not supported
      See Also:
        `Background`, `GraphicsContext3D.setBackground(javax.media.j3d.Background)`, `GraphicsContext3D.clear()`

    - #### flush

          public abstract void flush(boolean wait)

      Flushes all previously executed rendering operations to the drawing buffer for this 2D graphics object.
      Parameters:
        `wait` - flag indicating whether or not to wait for the rendering to be complete before returning from this call.

    - #### drawAndFlushImage

          public abstract void drawAndFlushImage(java.awt.image.BufferedImage img,
                               int x,
                               int y,
                               java.awt.image.ImageObserver observer)

      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.
      Parameters:
        `img` - The image to draw
        `x` - The x location to draw at
        `y` - The y location to draw at
        `observer` - The ImageObserver
      Since:
        Java 3D 1.3

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.