GraphicsContext3D (Java 3D Javadocs 0-SNAPSHOT API)

java.lang.Object
- org.scijava.java3d.GraphicsContext3D

```
public class GraphicsContext3D
extends Object
```
A GraphicsContext3D object is used for immediate mode rendering into a 3D canvas. It is created by, and associated with, a specific Canvas3D object. A GraphicsContext3D defines methods to set 3D graphics state and draw 3D geometric primitives. There are no public constructors of GraphicsContext3D. An application obtains a 3D graphics context object from the Canvas3D object that the application wishes to render into by using the getGraphicsContext3D method. A new graphics context is created if one does not already exist. A new GraphicsContext3D initializes its state variables to the following defaults:
- Background object: null
- Fog object: null
- ModelClip object: null
- Appearance object: null
- List of Light objects: empty
- high-res coordinate: (0, 0, 0)
- modelTransform: identity
- AuralAttributes object: null
- List of Sound objects: empty
- buffer override: false
- front buffer rendering: false
- stereo mode: STEREO_BOTH
Note that the drawing methods in this class 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 readRaster method calls flush(true)
- 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 Also:

Canvas3D.getGraphicsContext3D()

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`STEREO_BOTH` Specifies that rendering is done to both eyes.
`static int`	`STEREO_LEFT` Specifies that rendering is done to the left eye.
`static int`	`STEREO_RIGHT` Specifies that rendering is done to the right eye.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addLight(Light light)` Appends the specified light to this graphics context's list of lights.
`void`	`addSound(Sound sound)` Appends the specified sound to this graphics context's list of sounds.
`void`	`clear()` Clear the Canvas3D to the color or image specified by the current background node.
`void`	`draw(Geometry geometry)` Draw the specified Geometry component object.
`void`	`draw(Shape3D shape)` Draw the specified Shape3D leaf node object.
`void`	`flush(boolean wait)` Flushes all previously executed rendering operations to the drawing buffer for this 3D graphics context.
`Enumeration<Light>`	`getAllLights()` Retrieves the enumeration object of all the lights.
`Enumeration<Sound>`	`getAllSounds()` Retrieves the enumeration object of all the sounds.
`Appearance`	`getAppearance()` Retrieves the current Appearance component object.
`AuralAttributes`	`getAuralAttributes()` Retrieves the current AuralAttributes component object.
`Background`	`getBackground()` Retrieves the current Background leaf node object.
`boolean`	`getBufferOverride()` Returns the current buffer override flag.
`Canvas3D`	`getCanvas3D()` Gets the Canvas3D that created this GraphicsContext3D.
`Fog`	`getFog()` Retrieves the current Fog leaf node object.
`boolean`	`getFrontBufferRendering()` Returns the current front buffer rendering flag.
`void`	`getHiRes(HiResCoord hiRes)` Retrieves the current HiRes coordinate of this context.
`Light`	`getLight(int index)` Retrieves the index selected light.
`ModelClip`	`getModelClip()` Retrieves the current ModelClip leaf node object.
`void`	`getModelTransform(Transform3D t)` Retrieves the current model transform.
`Sound`	`getSound(int index)` Retrieves the index selected sound.
`int`	`getStereoMode()` Returns the current stereo mode.
`void`	`insertLight(Light light, int index)` Inserts the specified light at the specified index location.
`void`	`insertSound(Sound sound, int index)` Inserts the specified sound at the specified index location.
`boolean`	`isSoundPlaying(int index)` Retrieves the sound playing flag.
`void`	`multiplyModelTransform(Transform3D t)` Multiplies the current model transform by the specified transform and stores the result back into the current transform.
`int`	`numLights()` Retrieves the current number of lights in this graphics context.
`int`	`numSounds()` Retrieves the current number of sounds in this graphics context.
`void`	`readRaster(Raster raster)` Read an image from the frame buffer and copy it into the ImageComponent and/or DepthComponent objects referenced by the specified Raster object.
`void`	`removeLight(int index)` Removes the light at the specified index location.
`void`	`removeSound(int index)` Removes the sound at the specified index location.
`void`	`setAppearance(Appearance appearance)` Sets the current Appearance object to the specified Appearance component object.
`void`	`setAuralAttributes(AuralAttributes attributes)` Sets the current AuralAttributes object to the specified AuralAttributes component object.
`void`	`setBackground(Background background)` Sets the current Background to the specified Background leaf node object.
`void`	`setBufferOverride(boolean bufferOverride)` Sets a flag that specifies whether the double buffering and stereo mode from the Canvas3D are overridden.
`void`	`setFog(Fog fog)` Sets the current Fog to the specified Fog leaf node object.
`void`	`setFrontBufferRendering(boolean frontBufferRendering)` Sets a flag that enables or disables immediate mode rendering into the front buffer of a double buffered Canvas3D.
`void`	`setHiRes(HiResCoord hiRes)` Sets the HiRes coordinate of this context to the location specified by the HiRes argument.
`void`	`setHiRes(int[] x, int[] y, int[] z)` Sets the HiRes coordinate of this context to the location specified by the parameters provided.
`void`	`setLight(Light light, int index)` Replaces the specified light with the light provided.
`void`	`setModelClip(ModelClip modelClip)` Sets the current ModelClip leaf node to the specified object.
`void`	`setModelTransform(Transform3D t)` Sets the current model transform to a copy of the specified transform.
`void`	`setSound(Sound sound, int index)` Replaces the specified sound with the sound provided.
`void`	`setStereoMode(int stereoMode)` Sets the stereo mode for immediate mode rendering.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - STEREO_LEFT
```
public static final int STEREO_LEFT
```
    Specifies that rendering is done to the left eye.
    
    Since:
    
    Java 3D 1.2
    
    See Also:
    
    setStereoMode(int), Constant Field Values
  - STEREO_RIGHT
```
public static final int STEREO_RIGHT
```
    Specifies that rendering is done to the right eye.
    
    Since:
    
    Java 3D 1.2
    
    See Also:
    
    setStereoMode(int), Constant Field Values
  - STEREO_BOTH
```
public static final int STEREO_BOTH
```
    Specifies that rendering is done to both eyes. This is the default.
    
    Since:
    
    Java 3D 1.2
    
    See Also:
    
    setStereoMode(int), Constant Field Values
- Method Detail
  - getCanvas3D
```
public Canvas3D getCanvas3D()
```
    Gets the Canvas3D that created this GraphicsContext3D.
    
    Returns:
    
    the Canvas3D that created this GraphicsContext3D
  - setAppearance
```
public void setAppearance(Appearance appearance)
```
    Sets the current Appearance object to the specified Appearance component object. The graphics context stores a reference to the specified Appearance object. This means that the application may modify individual appearance attributes by using the appropriate methods on the Appearance object. If the Appearance object is null, default values will be used for all appearance attributes - it is as if an Appearance node were created using the default constructor.
    
    Parameters:
    
    appearance - the new Appearance object
    
    Throws:
    
    IllegalSharingException - if the specified appearance refers to an ImageComponent2D that is being used by a Canvas3D as an off-screen buffer.
  - getAppearance
```
public Appearance getAppearance()
```
    Retrieves the current Appearance component object.
    
    Returns:
    
    the current Appearance object
  - setBackground
```
public void setBackground(Background background)
```
    Sets the current Background to the specified Background leaf node object. The graphics context stores a reference to the specified Background node. This means that the application may modify the background color or image by using the appropriate methods on the Background node. The Background node must not be part of a live scene graph, nor may it subsequently be made part of a live scene graph-an IllegalSharingException is thrown in such cases. If the Background object is null, the default background color of black (0,0,0) is used to clear the canvas prior to rendering a new frame. The Background node's application region is ignored for immediate-mode rendering.
    
    Parameters:
    
    background - the new Background object
    
    Throws:
    
    IllegalSharingException - if the Background node is part of or is subsequently made part of a live scene graph.
    
    IllegalSharingException - if the specified background node refers to an ImageComponent2D that is being used by a Canvas3D as an off-screen buffer.
  - getBackground
```
public Background getBackground()
```
    Retrieves the current Background leaf node object.
    
    Returns:
    
    the current Background object
  - setFog
```
public void setFog(Fog fog)
```
    Sets the current Fog to the specified Fog leaf node object. The graphics context stores a reference to the specified Fog node. This means that the application may modify the fog attributes using the appropriate methods on the Fog node object. The Fog node must not be part of a live scene graph, nor may it subsequently be made part of a live scene graph-an IllegalSharingException is thrown in such cases. If the Fog object is null, fog is disabled. Both the region of influence and the hierarchical scope of the Fog node are ignored for immediate-mode rendering.
    
    Parameters:
    
    fog - the new Fog object
    
    Throws:
    
    IllegalSharingException - if the Fog node is part of or is subsequently made part of a live scene graph.
  - getFog
```
public Fog getFog()
```
    Retrieves the current Fog leaf node object.
    
    Returns:
    
    the current Fog object
  - setModelClip
```
public void setModelClip(ModelClip modelClip)
```
    Sets the current ModelClip leaf node to the specified object. The graphics context stores a reference to the specified ModelClip node. This means that the application may modify the model clipping attributes using the appropriate methods on the ModelClip node object. The ModelClip node must not be part of a live scene graph, nor may it subsequently be made part of a live scene graph-an IllegalSharingException is thrown in such cases. If the ModelClip object is null, model clipping is disabled. Both the region of influence and the hierarchical scope of the ModelClip node are ignored for immediate-mode rendering.
    
    Parameters:
    
    modelClip - the new ModelClip node
    
    Throws:
    
    IllegalSharingException - if the ModelClip node is part of or is subsequently made part of a live scene graph.
    
    Since:
    
    Java 3D 1.2
  - getModelClip
```
public ModelClip getModelClip()
```
    Retrieves the current ModelClip leaf node object.
    
    Returns:
    
    the current ModelClip object
    
    Since:
    
    Java 3D 1.2
  - setLight
```
public void setLight(Light light,
                     int index)
```
    Replaces the specified light with the light provided. The graphics context stores a reference to each light object in the list of lights. This means that the application may modify the light attributes for any of the lights using the appropriate methods on that Light node object. None of the Light nodes in the list of lights may be part of a live scene graph, nor may they subsequently be made part of a live scene graph - an IllegalSharingException is thrown in such cases.
    
    Parameters:
    
    light - the new light
    
    index - which light to replace
    
    Throws:
    
    IllegalSharingException - if the Light node is part of or is subsequently made part of a live scene graph.
    
    NullPointerException - if the Light object is null.
  - insertLight
```
public void insertLight(Light light,
                        int index)
```
    Inserts the specified light at the specified index location.
    
    Parameters:
    
    light - the new light
    
    index - at which location to insert
    
    Throws:
    
    IllegalSharingException - if the Light node is part of or is subsequently made part of a live scene graph.
    
    NullPointerException - if the Light object is null.
  - removeLight
```
public void removeLight(int index)
```
    Removes the light at the specified index location.
    
    Parameters:
    
    index - which light to remove
  - getLight
```
public Light getLight(int index)
```
    Retrieves the index selected light.
    
    Parameters:
    
    index - which light to return
    
    Returns:
    
    the light at location index
  - getAllLights
```
public Enumeration<Light> getAllLights()
```
    Retrieves the enumeration object of all the lights.
    
    Returns:
    
    the enumeration object of all the lights
  - addLight
```
public void addLight(Light light)
```
    Appends the specified light to this graphics context's list of lights. Adding a null Light object to the list will result in a NullPointerException. Both the region of influence and the hierarchical scope of all lights in the list are ignored for immediate-mode rendering.
    
    Parameters:
    
    light - the light to add
    
    Throws:
    
    IllegalSharingException - if the Light node is part of or is subsequently made part of a live scene graph.
    
    NullPointerException - if the Light object is null.
  - numLights
```
public int numLights()
```
    Retrieves the current number of lights in this graphics context.
    
    Returns:
    
    the current number of lights
  - setHiRes
```
public void setHiRes(int[] x,
                     int[] y,
                     int[] z)
```
    Sets the HiRes coordinate of this context to the location specified by the parameters provided. The parameters x, y, and z are arrays of eight 32-bit integers that specify the high-resolution coordinates point.
    
    Parameters:
    
    x - an eight element array specifying the x position
    
    y - an eight element array specifying the y position
    
    z - an eight element array specifying the z position
    
    See Also:
    
    HiResCoord
  - setHiRes
```
public void setHiRes(HiResCoord hiRes)
```
    Sets the HiRes coordinate of this context to the location specified by the HiRes argument.
    
    Parameters:
    
    hiRes - the HiRes coordinate specifying the a new location
  - getHiRes
```
public void getHiRes(HiResCoord hiRes)
```
    Retrieves the current HiRes coordinate of this context.
    
    Parameters:
    
    hiRes - a HiResCoord object that will receive the HiRes coordinate of this context
  - setModelTransform
```
public void setModelTransform(Transform3D t)
```
    Sets the current model transform to a copy of the specified transform. A BadTransformException is thrown if an attempt is made to specify an illegal Transform3D.
    
    Parameters:
    
    t - the new model transform
    
    Throws:
    
    BadTransformException - if the transform is not affine.
  - multiplyModelTransform
```
public void multiplyModelTransform(Transform3D t)
```
    Multiplies the current model transform by the specified transform and stores the result back into the current transform. The specified transformation must be affine.
    
    Parameters:
    
    t - the model transform to be concatenated with the current model transform
    
    Throws:
    
    BadTransformException - if the transform is not affine.
  - getModelTransform
```
public void getModelTransform(Transform3D t)
```
    Retrieves the current model transform.
    
    Parameters:
    
    t - the model transform that will receive the current model transform
  - setSound
```
public void setSound(Sound sound,
                     int index)
```
    Replaces the specified sound with the sound provided. The graphics context stores a reference to each sound object in the list of sounds. This means that the application may modify the sound attributes for any of the sounds by using the appropriate methods on that Sound node object.
    
    Parameters:
    
    sound - the new sound
    
    index - which sound to replace
    
    Throws:
    
    IllegalSharingException - if the Sound node is part of or is subsequently made part of a live scene graph.
    
    NullPointerException - if the Sound object is null.
  - insertSound
```
public void insertSound(Sound sound,
                        int index)
```
    Inserts the specified sound at the specified index location. Inserting a sound to the list of sounds implicitly starts the sound playing. Once a sound is finished playing, it can be restarted by setting the sound's enable flag to true. The scheduling region of all sounds in the list is ignored for immediate-mode rendering.
    
    Parameters:
    
    sound - the new sound
    
    index - at which location to insert
    
    Throws:
    
    IllegalSharingException - if the Sound node is part or is subsequently made part of a live scene graph.
    
    NullPointerException - if the Sound object is null.
  - removeSound
```
public void removeSound(int index)
```
    Removes the sound at the specified index location.
    
    Parameters:
    
    index - which sound to remove
  - getSound
```
public Sound getSound(int index)
```
    Retrieves the index selected sound.
    
    Parameters:
    
    index - which sound to return
    
    Returns:
    
    the sound at location index
  - getAllSounds
```
public Enumeration<Sound> getAllSounds()
```
    Retrieves the enumeration object of all the sounds.
    
    Returns:
    
    the enumeration object of all the sounds
  - addSound
```
public void addSound(Sound sound)
```
    Appends the specified sound to this graphics context's list of sounds. Adding a sound to the list of sounds implicitly starts the sound playing. Once a sound is finished playing, it can be restarted by setting the sound's enable flag to true. The scheduling region of all sounds in the list is ignored for immediate-mode rendering.
    
    Parameters:
    
    sound - the sound to add
    
    Throws:
    
    IllegalSharingException - if the Sound node is part of or is subsequently made part of a live scene graph.
    
    NullPointerException - if the Sound object is null.
  - numSounds
```
public int numSounds()
```
    Retrieves the current number of sounds in this graphics context.
    
    Returns:
    
    the current number of sounds
  - isSoundPlaying
```
public boolean isSoundPlaying(int index)
```
    Retrieves the sound playing flag.
    
    Parameters:
    
    index - which sound
    
    Returns:
    
    flag denoting if sound is currently playing
  - setAuralAttributes
```
public void setAuralAttributes(AuralAttributes attributes)
```
    Sets the current AuralAttributes object to the specified AuralAttributes component object. This means that the application may modify individual audio attributes by using the appropriate methods in the Aural-Attributes object.
    
    Parameters:
    
    attributes - the new AuralAttributes object
  - getAuralAttributes
```
public AuralAttributes getAuralAttributes()
```
    Retrieves the current AuralAttributes component object.
    
    Returns:
    
    the current AuralAttributes object
  - setBufferOverride
```
public void setBufferOverride(boolean bufferOverride)
```
    Sets a flag that specifies whether the double buffering and stereo mode from the Canvas3D are overridden. When set to true, this attribute enables the frontBufferRendering and stereoMode attributes.
    
    Parameters:
    
    bufferOverride - the new buffer override flag
    
    Since:
    
    Java 3D 1.2
    
    See Also:
    
    setFrontBufferRendering(boolean), setStereoMode(int)
  - getBufferOverride
```
public boolean getBufferOverride()
```
    Returns the current buffer override flag.
    
    Returns:
    
    true if buffer override is enabled; otherwise, false is returned
    
    Since:
    
    Java 3D 1.2
  - setFrontBufferRendering
```
public void setFrontBufferRendering(boolean frontBufferRendering)
```
    Sets a flag that enables or disables immediate mode rendering into the front buffer of a double buffered Canvas3D. This attribute is only used when the bufferOverride flag is enabled.
    Note that this attribute has no effect if double buffering is disabled or is not available on the Canvas3D.
    
    Parameters:
    
    frontBufferRendering - the new front buffer rendering flag
    
    Since:
    
    Java 3D 1.2
    
    See Also:
    
    setBufferOverride(boolean)
  - getFrontBufferRendering
```
public boolean getFrontBufferRendering()
```
    Returns the current front buffer rendering flag.
    
    Returns:
    
    true if front buffer rendering is enabled; otherwise, false is returned
    
    Since:
    
    Java 3D 1.2
  - setStereoMode
```
public void setStereoMode(int stereoMode)
```
    Sets the stereo mode for immediate mode rendering. The parameter specifies which stereo buffer or buffers is rendered into. This attribute is only used when the bufferOverride flag is enabled.
    - STEREO_LEFT specifies that rendering is done into the left eye.
    - STEREO_RIGHT specifies that rendering is done into the right eye.
    - STEREO_BOTH specifies that rendering is done into both eyes. This is the default.
    Note that this attribute has no effect if stereo is disabled or is not available on the Canvas3D.
    Parameters:
    
    stereoMode - the new stereo mode
    
    Since:
    
    Java 3D 1.2
    
    See Also:
    
    setBufferOverride(boolean)
  - getStereoMode
```
public int getStereoMode()
```
    Returns the current stereo mode.
    
    Returns:
    
    the stereo mode, one of STEREO_LEFT, STEREO_RIGHT, or STEREO_BOTH.
    
    Since:
    
    Java 3D 1.2
  - clear
```
public void clear()
```
    Clear the Canvas3D to the color or image specified by the current background node.
  - draw
```
public void draw(Geometry geometry)
```
    Draw the specified Geometry component object.
    
    Parameters:
    
    geometry - the Geometry object to draw.
    
    Throws:
    
    IllegalSharingException - if the specified geometry is a Raster that refers to an ImageComponent2D that is being used by a Canvas3D as an off-screen buffer.
  - draw
```
public void draw(Shape3D shape)
```
    Draw the specified Shape3D leaf node object. This is a convenience method that is identical to calling the setAppearance(Appearance) and draw(Geometry) methods passing the appearance and geometry component objects of the specified shape node as arguments.
    
    Parameters:
    
    shape - the Shape3D node containing the Appearance component object to set and Geometry component object to draw
    
    Throws:
    
    IllegalSharingException - if the Shape3D node is part of or is subsequently made part of a live scene graph.
    
    IllegalSharingException - if the Shape3D node's Appearance refers to an ImageComponent2D that is being used by a Canvas3D as an off-screen buffer.
  - readRaster
```
public void readRaster(Raster raster)
```
    Read an image from the frame buffer and copy it into the ImageComponent and/or DepthComponent objects referenced by the specified Raster object. All parameters of the Raster object and the component ImageComponent and/or DepthComponentImage objects must be set to the desired values prior to calling this method. These values determine the location, size, and format of the pixel data that is read. This method calls flush(true) prior to reading the frame buffer.
    
    Parameters:
    
    raster - the Raster object used to read the contents of the frame buffer
    
    Throws:
    
    IllegalArgumentException - if the image class of the specified Raster's ImageComponent2D is not ImageClass.BUFFERED_IMAGE.
    
    IllegalArgumentException - if the specified Raster's ImageComponent2D is in by-reference mode and its RenderedImage is null.
    
    IllegalArgumentException - if the the Raster's ImageComponent2D format is not a 3-component format (e.g., FORMAT_RGB) or a 4-component format (e.g., FORMAT_RGBA).
    
    IllegalSharingException - if the Raster object is part of a live scene graph, or if the Raster's ImageComponent2D is part of a live scene graph.
    
    IllegalSharingException - if the Raster's ImageComponent2D is being used by an immediate mode context, or by a Canvas3D as an off-screen buffer.
    
    See Also:
    
    flush(boolean), ImageComponent, DepthComponent
  - flush
```
public void flush(boolean wait)
```
    Flushes all previously executed rendering operations to the drawing buffer for this 3D graphics context.
    
    Parameters:
    
    wait - flag indicating whether or not to wait for the rendering to be complete before returning from this call.
    
    Since:
    
    Java 3D 1.2

Class GraphicsContext3D

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

STEREO_LEFT

STEREO_RIGHT

STEREO_BOTH

Method Detail

getCanvas3D

setAppearance

getAppearance

setBackground

getBackground

setFog

getFog

setModelClip

getModelClip

setLight

insertLight

removeLight

getLight

getAllLights

addLight

numLights

setHiRes

setHiRes

getHiRes

setModelTransform

multiplyModelTransform

getModelTransform

setSound

insertSound

removeSound

getSound

getAllSounds

addSound

numSounds

isSoundPlaying

setAuralAttributes

getAuralAttributes

setBufferOverride

getBufferOverride

setFrontBufferRendering

getFrontBufferRendering

setStereoMode

getStereoMode

clear

draw

draw

readRaster

flush