org.j3d.aviatrix3d
Class ViewEnvironment

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.ViewEnvironment

All Implemented Interfaces:

Cullable, ViewEnvironmentCullable

public class ViewEnvironment
extends SceneGraphObject
implements ViewEnvironmentCullable

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. Anything that is generated will be done using the currently set data at that time.

A view environment cannot be directly created. You must fetch the environment from it's parent Scene instance.

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.

Internationalisation Resource Names

• invalidStencilFunctionMsg: Error message when the given function type does not match one of the available types.
• invalidStencilOpMsg: Error message when the given operation type does not match one of the available types.

Version:

$Revision: 1.35 $

Author:

Justin Couch

Field Summary

static int	CUSTOM_PROJECTION The projection type is a custom user-provided matrix
static int	INFINITE_PROJECTION The projection type is an infinite perspective matrix
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_TIMING_ERR_PROP, updateHandler

Method Summary

void	generateViewFrustum(double[] frustum) Generate a frustum based on the projectionType.
void	generateViewFrustumPlanes(javax.vecmath.Vector4f[] planes) Convenience method to generate the 6 frustum planes from the current projection information held.
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.
void	getProjectionMatrix(float[] matrix) Get the projection matrix that is generated for this environment.
int	getProjectionType() Check to see if stereo has been enabled for this environment.
int[]	getScissorDimensions() Get the currently set dimensions of the scissor area.
void	getViewFrustum(double[] frustum) Get the frustum based on the projectionType.
int[]	getViewportDimensions() Get the currently set dimensions of the viewport.
boolean	isStereoEnabled() Check to see if stereo has been enabled for this environment.
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	setProjectionMatrix(float[] matrix) Set a custom projection matrix for this view environment.
void	setProjectionType(int type) Set the perspective projection flag used for this environment.
void	setScissorDimensions(int x, int y, int width, int height) Set the scissor area dimensions to reduce the amount of the parent viewport that is rendered to.
void	setStereoEnabled(boolean stereo) Set the stereo flag used for this environment.

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

checkForCyclicChild, checkForCyclicParent, dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, 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

INFINITE_PROJECTION

public static final int INFINITE_PROJECTION

The projection type is an infinite perspective matrix

See Also:

Constant Field Values

CUSTOM_PROJECTION

public static final int CUSTOM_PROJECTION

The projection type is a custom user-provided matrix

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

isStereoEnabled

public boolean isStereoEnabled()

Check to see if stereo has been enabled for this environment.

Specified by:

isStereoEnabled in interface ViewEnvironmentCullable

Returns:

true if stereo rendering is to be used

getProjectionType

public int getProjectionType()

Check to see if stereo has been enabled for this environment.

Specified by:

getProjectionType in interface ViewEnvironmentCullable

Returns:

true if stereo rendering is to be used

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

Specified by:

getViewportDimensions in interface ViewEnvironmentCullable

Returns:

The current viewport size

getScissorDimensions

public int[] getScissorDimensions()

Get the currently set dimensions of the scissor area. The values are described as
viewport[0] = x
viewport[1] = y
viewport[2] = width
viewport[3] = height

Specified by:

getScissorDimensions in interface ViewEnvironmentCullable

Returns:

The current viewport size

getViewFrustum

public void getViewFrustum(double[] frustum)

Get the 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]

Specified by:

getViewFrustum in interface ViewEnvironmentCullable

Parameters:

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

getFieldOfView

public double getFieldOfView()

Get the currently set field of view. The field of view is specified in degrees.

Specified by:

getFieldOfView in interface ViewEnvironmentCullable

Returns:

A value 0 <= x <= 180;

getProjectionMatrix

public void getProjectionMatrix(float[] matrix)

Get the projection matrix that is generated for this environment. The projection matrix may be customised, or generated from the other data that is available from this class. The appropriate behaviour on the part of the caller will depend on the projection type flag.

Specified by:

getProjectionMatrix in interface ViewEnvironmentCullable

Parameters:

matrix - An array of length 16 to put the projection matrix in to The format is row-major

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

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

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

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

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

setProjectionMatrix

public void setProjectionMatrix(float[] matrix)

Set a custom projection matrix for this view environment. This will automatically set the projection type to CUSTOM_PROJECTION.

Parameters:

matrix - A length 16 array of the 4x4 matrix, in row major form

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

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the ApplicationUpdateObserver callback method

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]
If a custom matrix is provided, this will generate all zeroes in the returned array values.

Parameters:

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

generateViewFrustumPlanes

public void generateViewFrustumPlanes(javax.vecmath.Vector4f[] planes)

Convenience method to generate the 6 frustum planes from the current projection information held. Note that these are local to the camera's coordinate system and do not include the viewpoint transformation matrix in the calculation.

Planes are in the order: left, right, top, bottom, near, far

Parameters:

planes - The planes to place the data in

setScissorDimensions

public void setScissorDimensions(int x,
                                 int y,
                                 int width,
                                 int height)

Set the scissor area dimensions to reduce the amount of the parent viewport that is rendered to. Dimesions are relative to the window coordinates, not to the viewport. If width or height are set to zero or negative the scissor is ignored and the entire viewport is rendered. This is the default state.

Parameters:

x - The lower left x coordinate for the view

y - The lower left y coordinate for the view

width - The width of the viewport in pixels

height - The height of the viewport in pixels

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.