shout3d
Class Shout3DPanel

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--shout3d.Shout3DPanel
public class Shout3DPanel
extends java.awt.Panel
implements Shout3DViewer, java.lang.Runnable, Clock, DeviceListener, RenderObserver

Shout3D Panel - a Panel containing a Shout3DViewer

See Also:
Serialized Form

Field Summary
 Shout3DApplet applet
          The Shout3DApplet in which this panel is contained.
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Constructor Summary
Shout3DPanel(Shout3DApplet applet)
          Constructs a Shout3DPanel
Shout3DPanel(Shout3DApplet applet, int width, int height)
          Constructs a Shout3DPanel
Shout3DPanel(Shout3DApplet applet, int x, int y, int width, int height)
          Constructs a Shout3DPanel
 
Method Summary
 void addDeviceObserver(DeviceObserver devo, java.lang.String typeName, java.lang.Object userData)
          Adds the given DeviceObserver to the list of observers for which this DeviceObserver will invoke methods.
 boolean addRoute(Field fromField, Field toField)
          Adds a route that copies values from 'fromField' to 'toField' each time that fromField's value changes.
 void clearResourceCaches()
          Clears the cache of loaded resources, freeing the memory that holds them.
 Node createNodeFromString(java.lang.String stringToParse)
          Creates and returns Shout3D node by parsing the string given as an argument.
 void customInitialize()
          Subclasses should override to perform custom initialization tasks.
 boolean deleteRoute(Field fromField, Field toField)
          Removes any existing route from fromField to toField Returns true if a route existed and was removed, false otherwise Note: Routes of ArrayFields copy by reference, not by value.
 double getAbsoluteTime()
          this method gets the number of seconds since midnight GMT January 1, 1970, as of the last call to tick().
 Clock getClock()
          Returns a reference to the Clock
 java.awt.Component getComponent()
          Returns a reference to the java component in which this panel is drawn
 Bindable getCurrentBindableNode(java.lang.String typeName)
          Returns a reference to the currently bound node of the given type.
 DeviceListener getDeviceListener()
          Gets this panel's DeviceListener
 float getFramesPerSecond()
          Returns the rendering frame rate
 Picker getNewPicker()
          Gets a new Shout3DPicker
 Searcher getNewSearcher()
          Gets a new Searcher
 Node getNodeByName(java.lang.String nodeName)
          Gets a Node by DEF name.
 java.lang.String getNodeSearchPath()
          Returns a copy of the current node search path.
 java.lang.String getProfile()
          Gets a string denoting the profile of the current scene.
 Renderer getRenderer()
          Gets the renderer
 ResourceListener getResourceListener()
          Returns a reference to the ResourceListener
 Group getScene()
          Gets the scene in the panel
 java.lang.String getVersion()
          Gets a string denoting the version of this viewer.
 boolean handleEvent(java.awt.Event event)
           
 boolean isAntiAliased()
          Returns whether antialiasing is enabled
 boolean isBilinearFiltering()
          Returns whether bilinear filtering is enabled on textures
 boolean isLoadResourcesInSeparateThread()
          Returns whether resources should are being loaded in a separate thread.
 boolean isPanelAutoFillsApplet()
          Returns whether this panel will automatically reshape itself to fill the entire size of the applet.
 boolean isPixelDoubling()
          Returns whether pixel doubling is enabled.
 boolean isPixelDoublingSmooth()
          Returns true if pixel doubling is enabled and the style in use is smooth style.
 boolean isRenderLoopPaused()
          Gets whether the rendering loop is currently paused
 boolean isRouted(Field fromField, Field toField)
          Checks if a route currently exists from fromField to toField
 void loadURL(java.lang.String[] url, Node root)
          Loads an URL into the node root.
 void onPostRender(Renderer r, java.lang.Object userData)
          Called immediately following rendering.
 void onPreRender(Renderer r, java.lang.Object userData)
          Called immediately prior to rendering.
 void removeDeviceObserver(DeviceObserver devo, java.lang.String typeName)
          Removes the given ResourceObserver from the list of observers for which this ResourceObserver will invoke methods.
 boolean RendererCleanup()
          You should call this before releasing/dispose this Window ! Also you can overwrite this class, to dispose your own elements, e.g.
 void renderOnce()
          This method will render one frame if the render loop is paused.
 void run()
          Runnable's run method
 void setAntiAliased(boolean newVal)
          Sets whether antialiasing is enabled.
 void setBilinearFiltering(boolean newVal)
          Sets whether bilinear filtering is enabled on textures.
 void setLoadResourcesInSeparateThread(boolean newVal)
          Sets whether resources (textures and sounds) should be loaded in a separate thread from the main thread.
 void setNodeSearchPath(java.lang.String newSearchPath)
          Sets the search path for finding new nodes.

When loading a class for a node from a VRML97 or s3d file, the
packages are searched in the order given by a path contained in
a string.
 void setPanelAutoFillsApplet(boolean newVal)
          Sets whether this panel will automatically reshape itself to fill the entire size of the applet.
 void setPixelDoubling(boolean enabled, boolean useSmoothStyle)
          Sets whether pixel doubling is enabled on the view.
 void setRenderLoopPaused(boolean isPaused)
          Sets whether the rendering loop should be paused
 void setScene(Group root)
          Replaces the scene in the panel This includes applying all of the applet parameters (headlight, anti-aliasing, etc) to the newly loaded scene.
 void setSceneFromURL(java.lang.String[] url)
          Loads an URL into the panel's scene This includes applying all of the applet parameters (headlight, anti-aliasing, etc) to the newly loaded scene.
 void tick()
          This method updates the Clock and sets a new absolute time.
 void update(java.awt.Graphics g)
          Inherited Applet update method
 
Methods inherited from class java.awt.Panel
addNotify
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, remove, remove, removeAll, removeContainerListener, removeNotify, setFont, setLayout, validate
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, contains, contains, createImage, createImage, disable, dispatchEvent, enable, enable, enableInputMethods, getBackground, getBounds, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, hasFocus, hide, imageUpdate, inside, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

applet

public Shout3DApplet applet
The Shout3DApplet in which this panel is contained.
Constructor Detail

Shout3DPanel

public Shout3DPanel(Shout3DApplet applet)
Constructs a Shout3DPanel
Parameters:
applet - the Shout3DApplet in which this panel is to be drawn

Shout3DPanel

public Shout3DPanel(Shout3DApplet applet,
                    int width,
                    int height)
Constructs a Shout3DPanel
Parameters:
applet - the Shout3DApplet in which this panel is to be drawn
width - the width of the panel in pixels
height - the height of the panel in pixels

Shout3DPanel

public Shout3DPanel(Shout3DApplet applet,
                    int x,
                    int y,
                    int width,
                    int height)
Constructs a Shout3DPanel
Parameters:
applet - the Shout3DApplet in which this panel is to be drawn
x - the x position of the panel in pixels
y - the x position of the panel in pixels
width - the width of the panel in pixels
height - the height of the panel in pixels
Method Detail

getRenderer

public final Renderer getRenderer()
Gets the renderer
Returns:
the renderer

getDeviceListener

public final DeviceListener getDeviceListener()
Gets this panel's DeviceListener
Returns:
the deviceListener

getNewPicker

public final Picker getNewPicker()
Gets a new Shout3DPicker
Returns:
a new Picker

getNewSearcher

public final Searcher getNewSearcher()
Gets a new Searcher
Returns:
a new Searcher

setScene

public final void setScene(Group root)
                    throws Shout3DException
Replaces the scene in the panel This includes applying all of the applet parameters (headlight, anti-aliasing, etc) to the newly loaded scene.
Parameters:
root - the root of the new Scene

getScene

public final Group getScene()
Gets the scene in the panel
Returns:
root the root of the Scene

setNodeSearchPath

public final void setNodeSearchPath(java.lang.String newSearchPath)
                             throws Shout3DException
Sets the search path for finding new nodes.

When loading a class for a node from a VRML97 or s3d file, the
packages are searched in the order given by a path contained in
a string. This string may contain multiple directories,
separated by semicolons.

This method allows users to change the search path. Users may
add their own packages to this list. The new packages are assumed
to be specified relative to the codebase directory. For example,
by including "mynodes" to the search path, nodes will be sought in
the diretory codebase\mynodes.

Default Search Path:
The default value for the search path is
"shout3d.core;shout3d.sound;custom_nodes;RELATIVE_TO_CODEBASE"

Keywords:
There are 2 keywords which may be used in the search path string.
-- DEFAULT stands for the entire default search path. Hence,
the search path "DEFAULT;mynodes" will first search the 4
default directories, followed by looking in the "mynodes"
package within codebase.
-- RELATIVE_TO_CODEBASE stands for the codebase directory itself.

Qualifying a package name in the model file:
Nodes within model files may be qualified "in place."
For example, a model file may contain the following:
Shape {
appearance Appearance {}
geometry myGeometryClasses.Torus {}
}
In this case, given the default search path, the Torus class
will be sought in the following locations, in the following order:
- shout3d.core.myGeometryClasses.Torus
- shout3d.sound.myGeometryClasses.Torus
- custom_nodes.myGeometryClasses.Torus
- myGeometryClasses.Torus (relative to the codebase)

Special prefix "CODEBASE." for qualified class names in file:
When qualifying a package name in a file, the special "CODEBASE."
prefix instructs the parser to look in only one directory regardless
of the setting of the nodeSearchPath. This saves time that
might be spent checking the wrong directory and allows for fastest
downloading, but should only be used when you know exactly where the
node class must be stored.
For example, a model file may contain the following:
Shape {
appearance Appearance {}
geometry CODEBASE.myGeometryClasses.Torus {}
}
In this case, given any search path at all, the Torus class
will be sought only in the location myGeometryClasses.Torus, relative
to the codebase.

Caveat -- you can't place class files too freely:
It is important that any class file be properly compiled to reside
in the directory where it is located. For example, in order to
place a working class file in the directory codebase\myProject,
The Java file would need to be compiled in that directory, and would
need to contain the line:
package myProject;

Parameters:
newSearchPath - a String representation of the new searchPath

getNodeSearchPath

public final java.lang.String getNodeSearchPath()
Returns a copy of the current node search path. See setNodeSearchPath for more info.
Returns:
a copy of the current node search path

setSceneFromURL

public final void setSceneFromURL(java.lang.String[] url)
                           throws Shout3DException
Loads an URL into the panel's scene This includes applying all of the applet parameters (headlight, anti-aliasing, etc) to the newly loaded scene. This is always done in the same thread as the main thread.
Parameters:
url - a String representation of the URL

loadURL

public final void loadURL(java.lang.String[] url,
                          Node root)
                   throws Shout3DException
Loads an URL into the node root. If isLoadResourcesInSeparateThread() is true, then this is done in a separate thread from the main thread. Otherwise, it is done in the same thread.
Parameters:
url - the URL to load
root - the scene, once loaded

createNodeFromString

public final Node createNodeFromString(java.lang.String stringToParse)
                                throws Shout3DException
Creates and returns Shout3D node by parsing the string given as an argument. If the string denotes a node that has children, those children will be added as well. If the string contains more than one top-level node, the returned node will be a Transform node containing all of the top-level nodes in the string. This method always loads the resource in the same thread as the main thread, regardless of the setting of isLoadResourcesInSeparateThread().
Parameters:
stringToParse - the string to parse
Returns:
the node created by parsing the string

getNodeByName

public final Node getNodeByName(java.lang.String nodeName)
Gets a Node by DEF name. Returns null if no node is found with the given name
Parameters:
nodeName - the name of the node to find
Returns:
the node matching the given name

getProfile

public final java.lang.String getProfile()
Gets a string denoting the profile of the current scene. The format of the returned string is yet to be specified.
Returns:
the profile string

getVersion

public final java.lang.String getVersion()
Gets a string denoting the version of this viewer.
Returns:
the version string

getCurrentBindableNode

public final Bindable getCurrentBindableNode(java.lang.String typeName)
                                      throws Shout3DException
Returns a reference to the currently bound node of the given type. Takes a string specifying a subclass of Bindable node as input. Throws an exception if the input type is not a bindable class of node
Returns:
the currently bound node of the specified type

getClock

public final Clock getClock()
Returns a reference to the Clock
Returns:
the clock

getComponent

public final java.awt.Component getComponent()
Returns a reference to the java component in which this panel is drawn
Specified by:
getComponent in interface Shout3DViewer
Returns:
the component

addRoute

public boolean addRoute(Field fromField,
                        Field toField)
                 throws Shout3DException
Adds a route that copies values from 'fromField' to 'toField' each time that fromField's value changes. 'toField' will, in turn, notify any listeners or routed fields of this change. Does not copy the value immediately from fromField to toField. So the values will not be made to match until setValue() is called on fromField. (Note: this behavior was different in prior to Shout3D 1.0.3. In Shout3D 1.0, 1.0.1, and 1.0.2, addRoute() would copy the value from fromField to toField, so the values would match after this call.) Note: Routes of ArrayFields copy by reference, not by value. This makes routing of ArrayFields efficient, since a value change does not cause a copy of the array contents. However, deleting the route does not undo the fact that both fields refer to the array in memory. (See deleteRoute for more info). Throws a Shout3DException if the two fields are not of the same type. Will not add a second route if a route already exists. Returns true if a route was added, false otherwise
Specified by:
addRoute in interface Shout3DViewer
Parameters:
fromField - the field from which values will be copied
toField - the field to which values will be copied
Returns:
true if the route was added, false otherwise

deleteRoute

public boolean deleteRoute(Field fromField,
                           Field toField)
Removes any existing route from fromField to toField Returns true if a route existed and was removed, false otherwise Note: Routes of ArrayFields copy by reference, not by value. (see addRoute) Deleting a route does not undo the fact that both fields refer to the array in memory. If you want to insure that the toField refers to unique memory, you should allocate a new value array of the same size as the source field, copy the values into the new array, and set this new array as the toField's value.
Specified by:
deleteRoute in interface Shout3DViewer
Parameters:
fromField - the field from which values will be copied
toField - the field to which values will be copied
Returns:
true if the route was removed, false otherwise

isRouted

public boolean isRouted(Field fromField,
                        Field toField)
Checks if a route currently exists from fromField to toField
Specified by:
isRouted in interface Shout3DViewer
Returns:
true if the route exists, false otherwise

getResourceListener

public final ResourceListener getResourceListener()
Returns a reference to the ResourceListener
Returns:
the the resourceListener

getAbsoluteTime

public final double getAbsoluteTime()
this method gets the number of seconds since midnight GMT January 1, 1970, as of the last call to tick().
Specified by:
getAbsoluteTime in interface Clock
Returns:
the time

tick

public final void tick()
This method updates the Clock and sets a new absolute time. This is automatically invoked once each time the panel renders, just before the onPreRender() methods are called on all the registered RenderObservers. This method may also be invoked by a programmer whenever a new simulation tick is desired, in the case where simulation cycles are being run at a finer frequency than that of the rendering loop.
Specified by:
tick in interface Clock

addDeviceObserver

public final void addDeviceObserver(DeviceObserver devo,
                                    java.lang.String typeName,
                                    java.lang.Object userData)
Adds the given DeviceObserver to the list of observers for which this DeviceObserver will invoke methods.
Specified by:
addDeviceObserver in interface DeviceListener
Parameters:
devo - the observer to add
userData - the data given by the observer

removeDeviceObserver

public final void removeDeviceObserver(DeviceObserver devo,
                                       java.lang.String typeName)
Removes the given ResourceObserver from the list of observers for which this ResourceObserver will invoke methods.
Specified by:
removeDeviceObserver in interface DeviceListener
Parameters:
devo - the observer to remove

onPreRender

public void onPreRender(Renderer r,
                        java.lang.Object userData)
Called immediately prior to rendering.
Specified by:
onPreRender in interface RenderObserver
Parameters:
r - the renderer that is about to render
userData - the userdata that was passed by this panel to the renderer

onPostRender

public void onPostRender(Renderer r,
                         java.lang.Object userData)
Called immediately following rendering.
Specified by:
onPostRender in interface RenderObserver
Parameters:
r - the renderer that just finished rendering
userData - the userdata that was passed by this panel to the renderer

getFramesPerSecond

public final float getFramesPerSecond()
Returns the rendering frame rate
Returns:
the frame rate, in frames per second

customInitialize

public void customInitialize()
Subclasses should override to perform custom initialization tasks. The regular initialize() method may not be overriden, but calls this method at a point where it is safe to do so.

run

public final void run()
Runnable's run method
Specified by:
run in interface java.lang.Runnable

update

public final void update(java.awt.Graphics g)
Inherited Applet update method
Overrides:
update in class java.awt.Container

RendererCleanup

public boolean RendererCleanup()
You should call this before releasing/dispose this Window ! Also you can overwrite this class, to dispose your own elements, e.g. a Frame etc. - but be sure that you call RendererCleanup implementation call this one ! This function calls Destroy of current GL Context in OGLRenderDevice !

handleEvent

public final boolean handleEvent(java.awt.Event event)
Overrides:
handleEvent in class java.awt.Component

clearResourceCaches

public final void clearResourceCaches()
Clears the cache of loaded resources, freeing the memory that holds them. Normally, a texture, sound or Shout3d scene that is loaded by the applet is stored in a cache, so that if the resource is needed again, it does not need to be fetched by the server repeatedly. This method frees those caches, which frees memory while making it so that all resources will be fetched if they are requested anew. Note: Nodes (such as ImageTexture and JavaSound) store separate references to their resources. The caches are a second reference. So calling clearResourceCaches() will not cause any errors in the way those nodes function.
Specified by:
clearResourceCaches in interface Shout3DViewer

setAntiAliased

public final void setAntiAliased(boolean newVal)
Sets whether antialiasing is enabled. (Default is false) This performs antialiasing of all geometry against the background.
Specified by:
setAntiAliased in interface Shout3DViewer
Parameters:
newVal - whether antialiasing should be enabled

isAntiAliased

public final boolean isAntiAliased()
Returns whether antialiasing is enabled
Specified by:
isAntiAliased in interface Shout3DViewer
Returns:
whether antialiasing is currently enabled

setBilinearFiltering

public final void setBilinearFiltering(boolean newVal)
Sets whether bilinear filtering is enabled on textures. (Default is false) This results in higher quality, but slower rendering of the textures
Specified by:
setBilinearFiltering in interface Shout3DViewer
Parameters:
newVal - whether bilinear filtering should be enabled

isBilinearFiltering

public final boolean isBilinearFiltering()
Returns whether bilinear filtering is enabled on textures
Specified by:
isBilinearFiltering in interface Shout3DViewer
Returns:
whether bilinear filtering is currently enabled

setLoadResourcesInSeparateThread

public final void setLoadResourcesInSeparateThread(boolean newVal)
Sets whether resources (textures and sounds) should be loaded in a separate thread from the main thread. (Default is true)
Specified by:
setLoadResourcesInSeparateThread in interface Shout3DViewer
Parameters:
newVal - whether resources should be loaded in a separate thread.

isLoadResourcesInSeparateThread

public final boolean isLoadResourcesInSeparateThread()
Returns whether resources should are being loaded in a separate thread.
Specified by:
isLoadResourcesInSeparateThread in interface Shout3DViewer
Returns:
whether resources should are being loaded in a separate thread.

setPanelAutoFillsApplet

public final void setPanelAutoFillsApplet(boolean newVal)
Sets whether this panel will automatically reshape itself to fill the entire size of the applet. (Default is false)
Parameters:
newVal - whether the autosizing will occur

isPanelAutoFillsApplet

public final boolean isPanelAutoFillsApplet()
Returns whether this panel will automatically reshape itself to fill the entire size of the applet.
Returns:
the current value

setRenderLoopPaused

public final void setRenderLoopPaused(boolean isPaused)
Sets whether the rendering loop should be paused
Specified by:
setRenderLoopPaused in interface Shout3DViewer
Parameters:
isPaused -  

isRenderLoopPaused

public final boolean isRenderLoopPaused()
Gets whether the rendering loop is currently paused
Specified by:
isRenderLoopPaused in interface Shout3DViewer
Returns:
is the rendering loop paused

renderOnce

public final void renderOnce()
This method will render one frame if the render loop is paused. If the render loop is not paused, there is no effect. The rendering will include calls to the onPreRender and onPostRender of all the Renderer's registered RenderObservers.
Specified by:
renderOnce in interface Shout3DViewer

setPixelDoubling

public final void setPixelDoubling(boolean enabled,
                                   boolean useSmoothStyle)
Sets whether pixel doubling is enabled on the view. (Default is false) This results in faster rendering but lower detail. Rendering is done at half the resolution of the panel, then the rendering is blown up to fill the entire panel. If useSmoothStyle is false, then each pixel of the lo-res image is drawn as a square of 2x2 pixels exactly the same. If useSmoothStyle is true, then some filtering is done to smooth the image out a bit. This method is slower but looks better in some cases. By default, pixel doubling is not enabled.
Specified by:
setPixelDoubling in interface Shout3DViewer
Parameters:
enabled - whether pixel doubling should be enabled
useSmoothStyle - if enabled is true, whether the doubling should be smooth style

isPixelDoubling

public final boolean isPixelDoubling()
Returns whether pixel doubling is enabled.
Specified by:
isPixelDoubling in interface Shout3DViewer
Returns:
whether pixel doubling is enabled

isPixelDoublingSmooth

public final boolean isPixelDoublingSmooth()
Returns true if pixel doubling is enabled and the style in use is smooth style. Returns false otherwise
Specified by:
isPixelDoublingSmooth in interface Shout3DViewer