Aviatrix3D
2.0 Dev

org.j3d.aviatrix3d
Class ViewEnvironment

java.lang.Object
  extended byorg.j3d.aviatrix3d.SceneGraphObject
      extended byorg.j3d.aviatrix3d.ViewEnvironment

public class ViewEnvironment
extends SceneGraphObject

Representation of the physical environment setup used to connect a virtual Viewpoint object to the real one that is rendered on a drawable surface.

Most of the properties of this class are changed during the app update observer callback cycle.

Frustum Generation

The view frustum is generated depends on the aspect ratio. If the user sets an explicit aspect ratio, this is used in preference. If no aspect ratio is set (or the value set to <= 0) then the dimensions of the viewport that this is contained within are used to automatically calculate an aspect ratio.

The aspect ratio is not set by default.

Stereo support

If the output device is capable of supporting stereo rendering, this class can be used to enable it. Since the stereo flags are supplied here, that allows the end user to control which layer(s) should be rendered in stereo and which should not. For example, a HUD may want to have a text overlay that has no depth applied, rendered over the top of the main layer, which has stereo applied. One environment has the flag set, the other does not.

By default, stereo is disabled.

Field of View and aspect ratio

The field of view calculation defines the viewing angle that is used in the Y axis - definition the minimum and maximum Y extents for the view frustum. If an explicit aspect ratio is set then the X extents are calculated using that, otherwise the dimensions of the viewport are used to calculate an aspect ratio, and finally the X extents.

Version:
$Revision: 1.20 $
Author:
Justin Couch

Field Summary
static int ORTHOGRAPHIC_PROJECTION
          The projection type is perspective mode
static int PERSPECTIVE_PROJECTION
          The projection type is perspective mode
static int VIEW_HEIGHT
          Index into the viewport size array for the height
static int VIEW_WIDTH
          Index into the viewport size array for the width
static int VIEW_X
          Index into the viewport size array for the X position
static int VIEW_Y
          Index into the viewport size array for the Y position
 
Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject
alive, LISTENER_SET_NOT_LIVE_MESSAGE, updateHandler, WRITE_TIMING_MSG
 
Method Summary
 void generateViewFrustum(double[] frustum)
          Generate a frustum based on the projectionType.
 double getAspectRatio()
          Get the currently set aspect ratio.
 double getFarClipDistance()
          Get the current setting of the far clip plane.
 double getFieldOfView()
          Get the currently set field of view.
 double getNearClipDistance()
          Get the current setting of the far clip plane.
 void getPixelLocationInSurface(float x, float y, javax.vecmath.Point3f position)
          Convert a pixel location to surface coordinates.
 void getPixelLocationInSurface(float x, float y, javax.vecmath.Point3f offset, javax.vecmath.Point3f position)
          Convert a pixel location to surface coordinates.
 int getProjectionType()
          Check to see if stereo has been enabled for this environment.
 boolean getStereoEnabled()
          Check to see if stereo has been enabled for this environment.
 int[] getViewportDimensions()
          Get the currently set dimensions of the viewport.
 void setAspectRatio(double aspect)
          Set aspect ratio, which is the ratio of window Width / Height.
 void setClipDistance(double near, double far)
          Set the near clipping distance to be used by the application.
 void setFarClipDistance(double d)
          Set the far clipping distance to be used by the application.
 void setFieldOfView(double angle)
          Set the field of view to be used.
 void setNearClipDistance(double d)
          Set the near clipping distance to be used by the application.
 void setOrthoParams(double left, double right, double bottom, double top)
          Set the Orthographic view parameters.
 void setProjectionType(int type)
          Set the perspective projection flag used for this environment.
 void setStereoEnabled(boolean stereo)
          Set the stereo flag used for this environment.
 
Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject
checkForCyclicChild, checkForCyclicParent, dataChanged, getUserData, isLive, setLive, setUpdateHandler, setUserData
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PERSPECTIVE_PROJECTION

public static final int PERSPECTIVE_PROJECTION
The projection type is perspective mode

See Also:
Constant Field Values

ORTHOGRAPHIC_PROJECTION

public static final int ORTHOGRAPHIC_PROJECTION
The projection type is perspective mode

See Also:
Constant Field Values

VIEW_X

public static final int VIEW_X
Index into the viewport size array for the X position

See Also:
Constant Field Values

VIEW_Y

public static final int VIEW_Y
Index into the viewport size array for the Y position

See Also:
Constant Field Values

VIEW_WIDTH

public static final int VIEW_WIDTH
Index into the viewport size array for the width

See Also:
Constant Field Values

VIEW_HEIGHT

public static final int VIEW_HEIGHT
Index into the viewport size array for the height

See Also:
Constant Field Values
Method Detail

setStereoEnabled

public void setStereoEnabled(boolean stereo)
Set the stereo flag used for this environment.

Parameters:
stereo - True if stereo should be rendered
Throws:
InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method

getStereoEnabled

public boolean getStereoEnabled()
Check to see if stereo has been enabled for this environment.

Returns:
true if stereo rendering is to be used

setProjectionType

public void setProjectionType(int type)
                       throws java.lang.IllegalArgumentException
Set the perspective projection flag used for this environment.

Parameters:
type - One of ORTHOGRAPHIC_PROJECTION or PERSPECTIVE_PROJECTION
Throws:
InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method
java.lang.IllegalArgumentException - The type is not valid

getProjectionType

public int getProjectionType()
Check to see if stereo has been enabled for this environment.

Returns:
true if stereo rendering is to be used

setFieldOfView

public void setFieldOfView(double angle)
                    throws java.lang.IllegalArgumentException
Set the field of view to be used. The value supplied must be in degrees.

Parameters:
angle - The angle in degress
Throws:
java.lang.IllegalArgumentException - The angle is less than or equal to zero
InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method

getFieldOfView

public double getFieldOfView()
Get the currently set field of view. The field of view is specified in degrees.

Returns:
A value 0 <= x <= 180;

setAspectRatio

public void setAspectRatio(double aspect)
Set aspect ratio, which is the ratio of window Width / Height. An aspect ratio of <= 0 will be calculated from the current window or viewport dimensions.

Parameters:
aspect - The new aspectRatio ratio.
Throws:
InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method

getAspectRatio

public double getAspectRatio()
Get the currently set aspect ratio. Width / Height.

Returns:
The aspect ratio

getViewportDimensions

public int[] getViewportDimensions()
Get the currently set dimensions of the viewport. This is automatically pushed down from the parent Viewport instance. The values are described as
viewport[0] = x
viewport[1] = y
viewport[2] = width
viewport[3] = height

Returns:
The current viewport size

setNearClipDistance

public void setNearClipDistance(double d)
Set the near clipping distance to be used by the application.

Parameters:
d - The distance to set the near clip plane to
Throws:
InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method

getNearClipDistance

public double getNearClipDistance()
Get the current setting of the far clip plane.

Returns:
The current value, which is less than the far plane

setClipDistance

public void setClipDistance(double near,
                            double far)
Set the near clipping distance to be used by the application.

Parameters:
near - The distance to set the near clip plane
far - The distance to the far clip plane
Throws:
InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method

setFarClipDistance

public void setFarClipDistance(double d)
Set the far clipping distance to be used by the application.

Parameters:
d - The distance to set the near clip plane to
Throws:
InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method

getFarClipDistance

public double getFarClipDistance()
Get the current setting of the far clip plane.

Returns:
The current value, which is greater than the near plane

setOrthoParams

public void setOrthoParams(double left,
                           double right,
                           double bottom,
                           double top)
Set the Orthographic view parameters.

Parameters:
left - The left plane coordinate
right - The right plane coordinate
bottom - The bottom plane coordinate
top - The top plane coordinate

generateViewFrustum

public void generateViewFrustum(double[] frustum)
Generate a frustum based on the projectionType. Perspective used the current view setup of FoV, near and far clipping distances and the aspectRatio ratio, generate the 6 parameters that describe a view frustum. These parameters are what could be used as arguments to the glFrustum call. The parameter order for perspective is: [x min, x max, y min, y max, z near, z far] Orthographic uses the parameters specified in the setOrthoParams. The parameter order for orthographic: [left, right, bottom, top, near, far]

Parameters:
frustum - An array at least 6 in length for the values generated

getPixelLocationInSurface

public void getPixelLocationInSurface(float x,
                                      float y,
                                      javax.vecmath.Point3f position)
Convert a pixel location to surface coordinates. This uses the current view frustum calculation.

Parameters:
x - The X coordinate
y - The Y coordinate
position - The converted position. It must be preallocated.

getPixelLocationInSurface

public void getPixelLocationInSurface(float x,
                                      float y,
                                      javax.vecmath.Point3f offset,
                                      javax.vecmath.Point3f position)
Convert a pixel location to surface coordinates. This uses the current view frustum calculation and an optional amount of eye offset (which is particularly useful for stereo calculations).

Parameters:
x - The X coordinate
y - The Y coordinate
offset - Any Eye offset amount needed for a canvas offset or null
position - The converted position. It must be preallocated.

Aviatrix3D
2.0 Dev

Latest Info from http://aviatrix3d.j3d.org/
Copyright © 2003 - 2005 j3d.org