org.web3d.browser
Interface BrowserCore

All Known Implementing Classes:

NRUniverse, OGLMinimalBrowserCore, OGLStandardBrowserCore

public interface BrowserCore

Abstract representation of the core requirements of a browser implementation regardless of the renderer used.

Version:

$Revision: 1.19 $

Author:

Justin Couch

Method Summary

void	addCoreListener(BrowserCoreListener l) Add a listener for browser core events.
void	addNavigationStateListener(NavigationStateListener l) Add a listener for navigation state changes.
void	addNodeObserver(int nodeType, NodeObserver obs) Add an observer for a specific node type.
void	addProfilingListener(ProfilingListener l) Request notification of profiling information.
void	addSensorStatusListener(SensorStatusListener l) Add a listener for sensor state changes.
void	addViewpointStatusListener(ViewpointStatusListener l) Add a listener for viewpoint status changes.
void	changeViewpoint(VRMLViewpointNodeType vp) Request that this viewpoint object is bound at the start of the next frame.
void	dispose() Notify the core that it can dispose all resources.
void	fitToWorld(boolean animated) Move the user's location to see the entire world.
float	getCurrentFrameRate() Get the current frame rate of the browser in frames per second.
float	getCurrentSpeed() Get the current velocity of the bound viewpoint in meters per second.
java.util.Map	getDEFMappings() Get the mapping of DEF names to the node instances that they represent.
java.lang.String	getDescription() Get the description string currently used by the world.
java.lang.String	getIDString() Get the ID string for this renderer.
int	getMinimumFrameInterval() Get the currently set minimum frame cycle interval.
int	getRendererType() Get the type of renderer that implements the browser core.
int	getRenderingStyle() Get the currently set rendering style.
VRMLClock	getVRMLClock() Get the clock instance in use by the core.
VRMLExecutionSpace	getWorldExecutionSpace() Convenience method to ask for the execution space that the world is currently operating in.
java.lang.String	getWorldURL() Get the fully qualified URL of the currently loaded world.
void	removeCoreListener(BrowserCoreListener l) Remove a browser core listener.
void	removeNavigationStateListener(NavigationStateListener l) Remove a navigation state listener.
void	removeNodeObserver(int nodeType, NodeObserver obs) Remove the given node observer instance for the specific node type.
void	removeProfilingListener(ProfilingListener l) Remove notification of profiling information.
void	removeSensorStatusListener(SensorStatusListener l) Remove a sensor state listener.
void	removeViewpointStatusListener(ViewpointStatusListener l) Remove a viewpoint state listener.
void	sendURLFailEvent(java.lang.String msg) Send to the core listeners the error message that a URL failed to load for some reason.
void	setDescription(java.lang.String desc) Set the description of the current world.
void	setErrorReporter(ErrorReporter reporter) Register an error reporter with the engine so that any errors generated by the loading of script code can be reported in a nice, pretty fashion.
void	setEventModelStatusListener(EventModelStatusListener l) Set the eventModelStatus listener.
void	setLastRenderTime(long lastTime) Set the last frame render time used for FPS calculations.
void	setMinimumFrameInterval(int millis, boolean userSet) Set the minimum frame interval time to limit the CPU resources taken up by the 3D renderer.
void	setNavigationMode(java.lang.String mode) Set the desired navigation mode.
void	setRenderingStyle(int style) Change the rendering style that the browser should currently be using.
void	setScene(VRMLScene scene, java.lang.String viewpoint) Set the scene to use within this universe with the specifically named viewpoint.
void	syncUIUpdates() Sync UI updates with the Application thread.

Method Detail

getRendererType

int getRendererType()

Get the type of renderer that implements the browser core. The only valid values returned are the constants in this interface. The constants returned are defined in Xj3DConstants.

Returns:

The renderer type

getIDString

java.lang.String getIDString()

Get the ID string for this renderer. The constants returned are defined in Xj3DConstants.

Returns:

The String token for this renderer.

setErrorReporter

void setErrorReporter(ErrorReporter reporter)

Register an error reporter with the engine so that any errors generated by the loading of script code can be reported in a nice, pretty fashion. Setting a value of null will clear the currently set reporter. If one is already set, the new value replaces the old.

Parameters:

reporter - The instance to use or null

setMinimumFrameInterval

void setMinimumFrameInterval(int millis,
                             boolean userSet)

Set the minimum frame interval time to limit the CPU resources taken up by the 3D renderer. By default it will use all of them. The second parameter is used to control whether this is a user-set hard minimum or something set by the browser internals. User set values are always treated as the minimum unless the browser internals set a value that is a slower framerate than the user set. If the browser then sets a faster framerate than the user set value, the user value is used instead.

Parameters:

millis - The minimum time in milleseconds.

userSet - true if this is an end-user set minimum

getMinimumFrameInterval

int getMinimumFrameInterval()

Get the currently set minimum frame cycle interval. Note that this is the minimum interval, not the actual frame rate. Heavy content loads can easily drag this down below the max frame rate that this will generate.

Returns:

The current cycle interval time in milliseconds

setRenderingStyle

void setRenderingStyle(int style)
                       throws java.lang.IllegalArgumentException

Change the rendering style that the browser should currently be using. Various options are available based on the constants defined in this interface.

Parameters:

style - One of the RENDER_* constants

Throws:

java.lang.IllegalArgumentException - A style constant that is not recognized by the implementation was provided

getRenderingStyle

int getRenderingStyle()

Get the currently set rendering style. The default style is RENDER_SHADED.

Returns:

one of the RENDER_ constants from org.xj3d.sai.Xj3DBrowser

getVRMLClock

VRMLClock getVRMLClock()

Get the clock instance in use by the core. We need this for when new nodes are added to the scene to make sure they are all appropriately configured.

Returns:

The clock used by the browser core

setScene

void setScene(VRMLScene scene,
              java.lang.String viewpoint)

Set the scene to use within this universe with the specifically named viewpoint. If null, this will clear this scene and de-register all listeners.

Parameters:

scene - The new scene to load, or null

viewpoint - The viewpoint.description to bind to or null for default

getDEFMappings

java.util.Map getDEFMappings()

Get the mapping of DEF names to the node instances that they represent. Primarily used for the EAI functionality. The map instance changes each time a new world is loaded so will need to be re-fetched. If no mappings are available (eg scripting replaceWorld() type call) then the map will be empty.

Returns:

The current mapping of DEF names to node instances

getWorldExecutionSpace

VRMLExecutionSpace getWorldExecutionSpace()

Convenience method to ask for the execution space that the world is currently operating in. Sometimes this is not known, particularly if the end user has called a loadURL type function that is asynchronous. This will change each time a new scene is loaded.

Returns:

The current world execution space.

getDescription

java.lang.String getDescription()

Get the description string currently used by the world. Returns null if not set or supported.

Returns:

The current description string or null

setDescription

void setDescription(java.lang.String desc)

Set the description of the current world. If the world is operating as part of a web browser then it shall attempt to set the title of the window. If the browser is from a component then the result is dependent on the implementation

Parameters:

desc - The description string to set.

getCurrentSpeed

float getCurrentSpeed()

Get the current velocity of the bound viewpoint in meters per second. The velocity is defined in terms of the world values, not the local coordinate system of the viewpoint.

Returns:

The velocity in m/s or 0.0 if not supported

getCurrentFrameRate

float getCurrentFrameRate()

Get the current frame rate of the browser in frames per second.

Returns:

The current frame rate or 0.0 if not supported

getWorldURL

java.lang.String getWorldURL()

Get the fully qualified URL of the currently loaded world. This returns the entire URL including any possible arguments that might be associated with a CGI call or similar mechanism. If the initial world is replaced with loadURL then the string will reflect the new URL. If replaceWorld is called then the URL still represents the original world.

Returns:

A string of the URL or null if not supported.

sendURLFailEvent

void sendURLFailEvent(java.lang.String msg)

Send to the core listeners the error message that a URL failed to load for some reason. This is for the EAI/ESAI spec conformance.

Parameters:

msg - The message to send

setNavigationMode

void setNavigationMode(java.lang.String mode)

Set the desired navigation mode. The mode string is one of the spec-defined strings for the NavigationInfo node in the VRML/X3D specification.

Parameters:

mode - The requested mode.

fitToWorld

void fitToWorld(boolean animated)

Move the user's location to see the entire world. Change the users orientation to look at the center of the world.

Parameters:

animated - Should the transistion be animated. Defaults to FALSE.

changeViewpoint

void changeViewpoint(VRMLViewpointNodeType vp)

Request that this viewpoint object is bound at the start of the next frame. This method should only be called by external users such as UI toolkits etc that need to synchronize the viewpoint change with rendering loop, but are not able to synchronize themselves because they exist on a different thread that cannot block.

Parameters:

vp - The new viewpoint instance to bind to

setLastRenderTime

void setLastRenderTime(long lastTime)

Set the last frame render time used for FPS calculations. Only the per frame mamanger should call this.

Parameters:

lastTime - The time it took to render the last frame in milliseconds.

addCoreListener

void addCoreListener(BrowserCoreListener l)

Add a listener for browser core events. These events are used to notify all listeners of internal structure changes, such as the browser starting and stopping. A listener can only be added once. Duplicate requests are ignored.

Parameters:

l - The listener to add

removeCoreListener

void removeCoreListener(BrowserCoreListener l)

Remove a browser core listener. If the reference is null or not known, the request is silently ignored.

Parameters:

l - The listener to remove

setEventModelStatusListener

void setEventModelStatusListener(EventModelStatusListener l)

Set the eventModelStatus listener.

Parameters:

l - The listener. Null will clear it.

addNavigationStateListener

void addNavigationStateListener(NavigationStateListener l)

Add a listener for navigation state changes. A listener can only be added once. Duplicate requests are ignored.

Parameters:

l - The listener to add

removeNavigationStateListener

void removeNavigationStateListener(NavigationStateListener l)

Remove a navigation state listener. If the reference is null or not known, the request is silently ignored.

Parameters:

l - The listener to remove

addSensorStatusListener

void addSensorStatusListener(SensorStatusListener l)

Add a listener for sensor state changes. A listener can only be added once. Duplicate requests are ignored.

Parameters:

l - The listener to add

removeSensorStatusListener

void removeSensorStatusListener(SensorStatusListener l)

Remove a sensor state listener. If the reference is null or not known, the request is silently ignored.

Parameters:

l - The listener to remove

addViewpointStatusListener

void addViewpointStatusListener(ViewpointStatusListener l)

Add a listener for viewpoint status changes. A listener can only be added once. Duplicate requests are ignored.

Parameters:

l - The listener to add

removeViewpointStatusListener

void removeViewpointStatusListener(ViewpointStatusListener l)

Remove a viewpoint state listener. If the reference is null or not known, the request is silently ignored.

Parameters:

l - The listener to remove

addNodeObserver

void addNodeObserver(int nodeType,
                     NodeObserver obs)

Add an observer for a specific node type. A single instance may be registered for more than one type. Each type registered will result in a separate call per frame - one per type. If the observer is currently added for this type ID, the request is ignored.

Parameters:

nodeType - The type identifier of the node being observed

obs - The observer instance to add

removeNodeObserver

void removeNodeObserver(int nodeType,
                        NodeObserver obs)

Remove the given node observer instance for the specific node type. It will not be removed for any other requested node types. If the instance is not registered for the given node type ID, the request will be silently ignored.

Parameters:

nodeType - The type identifier of the node being observed

obs - The observer instance to remove

dispose

void dispose()

Notify the core that it can dispose all resources. The core cannot be used for rendering after that.

syncUIUpdates

void syncUIUpdates()

Sync UI updates with the Application thread. This method alls the core to push work off to the app thread.

addProfilingListener

void addProfilingListener(ProfilingListener l)

Request notification of profiling information.

Parameters:

l - The listener

removeProfilingListener

void removeProfilingListener(ProfilingListener l)

Remove notification of profiling information.

Parameters:

l - The listener