Package org.web3d.vrml.renderer.ogl.input

Class NavigationProcessor

java.lang.Object

org.web3d.vrml.renderer.ogl.input.NavigationProcessor

All Implemented Interfaces:

org.j3d.aviatrix3d.NodeUpdateListener, OGLTransformNodeType

public class NavigationProcessor
extends Object
implements org.j3d.aviatrix3d.NodeUpdateListener, OGLTransformNodeType

A listener and handler responsible for executing all navigation commands from mice and keyboards to move a viewpoint around a scene.

This class does not contain any direct event handling. Instead it assumes that another class with either derive from it or delegate to it to do the actual movement processing. This allows it to be used as a standard AWT event listener. The class works like a standard VRML browser type navigation system. Press the mouse button and drag to get the viewpoint moving. The more you drag the button away from the start point, the faster the movement. The handler does not recognize the use of the Shift key as a modifier to produce an accelerated movement. This class will not change the cursor on the canvas in response to the current mouse and navigation state. It will only notify the state change listener. It is the responsibility of the listener to do this work. Separate states are allowed to be set for each button. Once one button is pressed, all the other button presses are ignored. By default, all the buttons start with no state set. The user will have to explicitly set the state for each button to get them to work.

Terrain Following

When doing terrain following, the handler will project a ray from the current viewpoint position to the ground position. It will then offset the current position by the new position that we should be going to. If the distance in the overall Y axis is less than the step height, the translation will be allowed to proceed and the height adjusted to the new value. If it is greater, then it will set the Z component to zero, allowing no forward movement. Thus, if the next translation also has a sideways component, it will simply shift sideways and not move forward. If there is no terrain under the current eye position, or the next eye position, it will not change the Y axis value at all. If you do not wish to have terrain following for all modes, then pass a null value for the terrain parameter to setWorldInfo().

Collision Detection

Collision detection is based on using a fixed point representation of the avatar - we do not have a volumetric body for it. A ray is cast in the direction that we are looking that is the length of the avatarSize plus the amount that we are due to move this next frame. If you do not wish to have collision detection for all modes, then pass a null value for the collidables parameter to setWorldInfo().

Navigation Modes NONE

All navigation is disabled. We ignore any requests from mouse or keyboard to move the viewpoint.

EXAMINE

The viewpoint is moved around the center of rotation provided by the user. There is no collision detection or terrain following in this mode. For movement input, direction is treated as the direction in the local coordinates on the surface of a sphere formed around the rotation origin. The scale represents the movement along the vector and then each component defines the proportion used to move in that direction. [0] is left/right, [1] is up/down, [2] is zoom in out where +Z is zoom out.

FLY

The user moves through the scene that moves the eyepoint in forward, reverse and side to side movements. There is collision detection, but no terrain following. For movement input the direction controls the scale of the input to translate and rotate about. [0] controls left/right rotation, [1] controls pitch and [2] controls the amount of forward movement.

WALK

The user moves through the scene with left/right options and forward reverse, but they are bound to the terrain and have collision detection. For movement input, the direction controls only two of the axes as gravity is used to constrain in the local Y axis. [0] is the amount of rotation left/right to perform each frame and [2] controls the forward/reverse movement.

PAN

The camera moves in a sliding fashion along the given axis - the local X or Z axis. There is not collision detection or terrain following. Move the viewpoint left/right/up/down while maintaining the current viewing direction. [0] is used for left/right and [1] is used for up/down. [2] is not used.

TILT

The camera rotates around the local axis in an up/down, left/right fashion. It stays anchored in the one place and does not have terrain following or collision detection. Movement input controls how the tilt is performed and is an absolute value that controls total tilt. [0] controls rotation of the camera in the X-Z plane, [1] controls rotation in the Y-Z plane.

TODO

The collision vector does not move according to the direction that we are traveling rather than the direction we are facing. Allows us to walk backwards through objects when we shouldn't. Implement Examine mode handling

This code is a direct copy and modified version of the code in the j3d.org library of the same name.

Version:

$Revision: 1.45 $

Author:

Justin Couch

Field Summary

Fields

Modifier and Type	Field	Description
static final int	AVATAR_CYLINDER	The avatar representation is a cylinder
static final int	AVATAR_POINT	The avatar representation is a floating eyeball
static final int	AVATAR_SHOULDERS	The avatar representation is two shoulder rays

Constructor Summary

Constructors

Constructor	Description
NavigationProcessor()	Create a new mouse handler with no view information set.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clear references that might be held.
int	getNavigationState()	Callback to ask the listener what navigation state it thinks it is in.
void	getOrientation(javax.vecmath.AxisAngle4f ori)	Get the current user orientation.
void	getPosition(javax.vecmath.Vector3f pos)	Get the current user position in world coordinates.
javax.vecmath.Matrix4f	getTransform()	Get the transform matrix for this node.
void	move(float[] direction, float scale)	Update the user movement to be going in this absolute direction.
void	orient(float[] direction)	Orient the viewer direction to this position, but do not change their movement direction.
void	originChanged()	Notification that the origin has changed.
void	processNextFrame()	Call to update the user position now based on the difference in time between the last call and this call.
void	setAvatarInfo(float height, float size, float stepHeight)	Set the information about the avatar that is used for collisions and navigation information.
void	setCenterOfRotation(float[] center, float[] lookPos)	Set the center of rotation explicitly to this place.
void	setCenterOfRotation(float[] center, float[] lookPos, boolean preserve)	Set the center of rotation explicitly to this place.
void	setCollisionListener(CollisionListener l)	Set the listener for collision notifications.
void	setNavigationSpeed(float newSpeed)	Set the navigation speed to the new value.
void	setNavigationState(int state)	Set the ability to use a given state within the handler for a specific mouse button (up to 3).
void	setOrbitTime(float time)	Set the time it takes in seconds to make one 360 degree rotation of the center position when in examine mode.
void	setOriginManager(OriginManager manager)	Set the manager for handling dynamic origin calculation.
void	setViewInfo(OGLViewpointNodeType vp, org.j3d.aviatrix3d.TransformGroup tg, org.j3d.aviatrix3d.SceneGraphPath path)	Set the view and it's related transform group to use and the path to get there from the root of the scene.
void	setWorldInfo(org.j3d.aviatrix3d.Group terrainGroup, org.j3d.aviatrix3d.Group worldGroup)	Set the branchgroups to use for terrain and collision information.
void	setWorldScale(float scale)	Set the world scale applied.
void	startMove()	Start the user moving in the current direction.
void	stopMove()	Halt the current movement being processed.
void	updateNodeBoundsChanges(Object src)	Notification that its safe to update the node now with any operations that could potentially effect the node's bounds.
void	updateNodeDataChanges(Object src)	Notification that its safe to update the node now with any operations that only change the node's properties, but do not change the bounds.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

AVATAR_POINT

public static final int AVATAR_POINT

The avatar representation is a floating eyeball

See Also:

• Constant Field Values

AVATAR_CYLINDER

public static final int AVATAR_CYLINDER

The avatar representation is a cylinder

See Also:

• Constant Field Values

AVATAR_SHOULDERS

public static final int AVATAR_SHOULDERS

The avatar representation is two shoulder rays

See Also:

• Constant Field Values

Constructor Details

NavigationProcessor

public NavigationProcessor()

Create a new mouse handler with no view information set. This handler will not do anything until the view transform references have been set and the navigation modes for at least one mouse button.

Method Details

setCenterOfRotation

public void setCenterOfRotation(float[] center,
 float[] lookPos)

Set the center of rotation explicitly to this place. Coordinates must be in the coordinate space of the current view transform group. The provided array must be of least length 3. Center of rotation is used in examine mode.

Parameters:

center - The new center to use

lookPos - The position to look from. NULL is the current user position.

setCenterOfRotation

public void setCenterOfRotation(float[] center,
 float[] lookPos,
 boolean preserve)

Set the center of rotation explicitly to this place. Coordinates must be in the coordinate space of the current view transform group. The provided array must be of least length 3. Center of rotation is used in examine mode.

Parameters:

center - The new center to use

lookPos - The position to look from. NULL is the current user position.

preserve - true to preserve the current up vector, false to reset the up vector to Y-UP.

setViewInfo

public void setViewInfo(OGLViewpointNodeType vp,
 org.j3d.aviatrix3d.TransformGroup tg,
 org.j3d.aviatrix3d.SceneGraphPath path)
                 throws IllegalArgumentException

Set the view and it's related transform group to use and the path to get there from the root of the scene. The transform group must allow for reading the local to Vworld coordinates so that we can accurately implement terrain following. A null value for the path is permitted.

Parameters:

vp - The current viewpoint

tg - The transform just about the viewpoint used to move it around in response to the UI device input

path - The path from the root to the transform to use

Throws:

IllegalArgumentException

setWorldInfo

public void setWorldInfo(org.j3d.aviatrix3d.Group terrainGroup,
 org.j3d.aviatrix3d.Group worldGroup)

Set the branchgroups to use for terrain and collision information. The two are treated separately for the different processes. The caller may choose to make them the same reference, but the code internally treats them separately.

Note For picking purposes, the code currently assumes that both groups do not have any parent transforms. That is, their world origin is the same as the transform group presented in the view information.

Parameters:

terrainGroup - The geometry to use as terrain for following

worldGroup - The geometry to use for collisions

setAvatarInfo

public void setAvatarInfo(float height,
 float size,
 float stepHeight)

Set the information about the avatar that is used for collisions and navigation information.

Parameters:

height - The heigth of the avatar above the terrain

size - The distance between the avatar and collidable objects

stepHeight - The height that an avatar can step over

setNavigationSpeed

public void setNavigationSpeed(float newSpeed)

Set the navigation speed to the new value. The speed must be a non-negative number.

Parameters:

newSpeed - The new speed value to use

Throws:

IllegalArgumentException - The value was negative

setOrbitTime

public void setOrbitTime(float time)

Set the time it takes in seconds to make one 360 degree rotation of the center position when in examine mode. Speed to the new value. The time must be a non-negative number.

Parameters:

time - The time value to use

Throws:

IllegalArgumentException - The value was <= 0

setNavigationState

public void setNavigationState(int state)

Set the ability to use a given state within the handler for a specific mouse button (up to 3). This allows the caller to control exactly what states are allowed to be used and with which buttons. Note that it is quite legal to set all three buttons to the same navigation state

Parameters:

state - The navigation state to use for that button

setCollisionListener

public void setCollisionListener(CollisionListener l)

Set the listener for collision notifications. By setting a value of null it will clear the currently set instance

Parameters:

l - The listener to use for updates

getNavigationState

public int getNavigationState()

Callback to ask the listener what navigation state it thinks it is in.

Returns:

The state that the listener thinks it is in

processNextFrame

public void processNextFrame()

Call to update the user position now based on the difference in time between the last call and this call. This is to be called when the user wishes to manually control the navigation process rather than relying on the inbuilt timer. The user should not be using both mechanisms at the same time although the code takes no steps to enforce this. If you do try to do manual updates while also having the automated system, the results are undefined.

startMove

public void startMove()

Start the user moving in the current direction. Initialises all the internal timers but does not actually start the movement.

stopMove

public void stopMove()

Halt the current movement being processed. Any move input after this will be ignored and the user will stop moving.

move

public void move(float[] direction,
 float scale)

Update the user movement to be going in this absolute direction. Scale gives a proportion of the set speed value to move in that direction. The interpretation of the 3 components of the vector are described in the class header documentation.

Parameters:

direction - The new direction to move the user

scale - fractional value of the set speed to use [0, inf)

orient

public void orient(float[] direction)

Orient the viewer direction to this position, but do not change their movement direction. The direction is a normalised 3D vector relative to the current movement. 0,0,0 means always look where the movement is taking you.

Parameters:

direction - 3D vector where the user should be looking

getTransform

public javax.vecmath.Matrix4f getTransform()

Get the transform matrix for this node. A reference is ok as the users of this method will not modify the matrix.

Specified by:

getTransform in interface OGLTransformNodeType

Returns:

The matrix.

updateNodeBoundsChanges

public void updateNodeBoundsChanges(Object src)

Notification that its safe to update the node now with any operations that could potentially effect the node's bounds.

Specified by:

updateNodeBoundsChanges in interface org.j3d.aviatrix3d.NodeUpdateListener

Parameters:

src - The node or Node Component that is to be updated.

updateNodeDataChanges

public void updateNodeDataChanges(Object src)

Notification that its safe to update the node now with any operations that only change the node's properties, but do not change the bounds.

Specified by:

updateNodeDataChanges in interface org.j3d.aviatrix3d.NodeUpdateListener

Parameters:

src - The node or Node Component that is to be updated.

originChanged

public void originChanged()

Notification that the origin has changed.

getOrientation

public void getOrientation(javax.vecmath.AxisAngle4f ori)

Get the current user orientation.

Parameters:

ori - The orientation vector to fill in

getPosition

public void getPosition(javax.vecmath.Vector3f pos)

Get the current user position in world coordinates.

Parameters:

pos - The position vector to fill in

setWorldScale

public void setWorldScale(float scale)

Set the world scale applied. This will scale down navinfo parameters to fit into the world.

Parameters:

scale - The new world scale.

clear

public void clear()

Clear references that might be held.

setOriginManager

public void setOriginManager(OriginManager manager)

Set the manager for handling dynamic origin calculation.

Parameters:

manager - Reference to the manager instance to use or null