gov.nasa.worldwind

Interface View

All Superinterfaces:

AVList, java.util.EventListener, MessageListener, java.beans.PropertyChangeListener, Restorable, WWObject

All Known Subinterfaces:

OrbitView

All Known Implementing Classes:

BasicFlyView, BasicOrbitView, BasicView

public interface View
extends WWObject, Restorable

The View interface provides a coordinate transformation from model coordinates to eye coordinates. This follows the OpenGL convention of a right-handed coordinate system with the origin at the eye point and looking down the negative Z axis. View also provides a transformation from eye coordinates to screen coordinates, following the OpenGL convention of an origin in the lower left hand screen corner.

Most of the accessor and computation methods on View will use viewing state computed in the last call to apply.

The following methods return state values updated in the most recent call to apply.

• getEyePosition
• getEyePoint
• getUpVector
• getForwardVector
• getModelviewMatrix
• getViewport
• getFrustum
• getFrustumInModelCoordinates
• getProjectionMatrix

The following methods return computed values using state that was updated in the most recent call to apply.

• project
• unproject
• computeRayFromScreenPoint
• computePositionFromScreenPoint
• computePixelSizeAtDistance
• computeHorizonDistance

See Also:

OrbitView

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VIEW_STOPPED

Method Summary

Modifier and Type	Method and Description
void	addAnimator(Animator animator) Add an animator to the View.
void	apply(DrawContext dc) Calculates and applies this View's internal state to the graphics context in the specified dc.
double	computePixelSizeAtDistance(double distance) Computes the dimension (in meters) that a screen pixel would cover at a given distance from the eye point (also in meters).
Position	computePositionFromScreenPoint(double x, double y) Computes the intersection of a line originating from the eye point and passing through (x, y) with the Globe.
Line	computeRayFromScreenPoint(double x, double y) Computes a line, in model coordinates, originating from the eye point, and passing through the point contained by (x, y) on the View's projection plane (or after projection into model space).
void	copyViewState(View view) Copy the state of the given View.
Vec4	getCenterPoint() Gets the center point of the view.
Vec4	getCurrentEyePoint() Returns the most up-to-date location of the eye in cartesian coordinates.
Position	getCurrentEyePosition() Returns the current geographic coordinates of this view's eye position, as determined from this view's current parameters.
Vec4	getEyePoint() Returns the location of the eye in cartesian coordinates.
Position	getEyePosition() Returns the current geographic coordinates of this view's eye position, as computed for the most recent model traversal.
double	getFarClipDistance() Returns the far clipping plane distance, in eye coordinates.
Angle	getFieldOfView() Returns the horizontal field-of-view angle (the angle of visibility), or null if the implementation does not support a field-of-view.
Vec4	getForwardVector() Returns the forward axis in cartesian coordinates.
Frustum	getFrustum() Returns the viewing Frustum in eye coordinates.
Frustum	getFrustumInModelCoordinates() Returns the viewing Frustum in model coordinates.
Globe	getGlobe() Gets the globe associated with this view.
Angle	getHeading() Returns the view's current heading.
double	getHorizonDistance() Returns the horizon distance for this view's most recently used eye position.
Matrix	getModelviewMatrix() Returns the modelview matrix.
double	getNearClipDistance() Returns the near clipping plane distance, in eye coordinates.
Angle	getPitch() Returns the view's current pitch.
Matrix	getProjectionMatrix() Gets the projection matrix.
Angle	getRoll() Returns this View's current roll.
Vec4	getUpVector() Returns the up axis in cartesian coordinates.
ViewInputHandler	getViewInputHandler() Gets the ViewInputHandler being used to map input events to View controls.
java.awt.Rectangle	getViewport() Returns the bounds (x, y, width, height) of the viewport.
ViewPropertyLimits	getViewPropertyLimits() Get the ViewPropertyLimits for this view.
long	getViewStateID() Get an identifier for the current state of the modelview matrix.
void	goTo(Position position, double elevation) Animate to the specified position.
boolean	isAnimating() Determine if there are any animations active in the View.
void	popReferenceCenter(DrawContext dc) Removes the model-view matrix on top of the matrix stack, and restores the original matrix.
Vec4	project(Vec4 modelPoint) Maps a Point in model (cartesian) coordinates to a Point in screen coordinates.
Matrix	pushReferenceCenter(DrawContext dc, Vec4 referenceCenter) Defines and applies a new model-view matrix in which the world origin is located at referenceCenter.
void	setEyePosition(Position eyePosition) Sets the geographic position of the eye.
void	setFieldOfView(Angle fieldOfView) Sets the horizontal field-of-view angle (the angle of visibility) to the specified fieldOfView.
void	setHeading(Angle heading) Sets the heading of the view.
void	setOrientation(Position eyePosition, Position centerPosition) Sets the location of the eye, and the center of the screen in geographic coordinates.
void	setPitch(Angle pitch) Sets the pitch of the view.
Matrix	setReferenceCenter(DrawContext dc, Vec4 referenceCenter) Sets the reference center matrix without pushing the stack.
void	setRoll(Angle roll) Set the roll of the view.
void	stopAnimations() Stops any animations that are active in this View
void	stopMovement() Stops any movement associated with this View.
Vec4	unProject(Vec4 windowPoint) Maps a Point in screen coordinates to a Point in model coordinates.

Methods inherited from interface gov.nasa.worldwind.avlist.AVList

addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getEntries, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues

Methods inherited from interface java.beans.PropertyChangeListener

propertyChange

Methods inherited from interface gov.nasa.worldwind.event.MessageListener

onMessage

Methods inherited from interface gov.nasa.worldwind.Restorable

getRestorableState, restoreState

Field Detail

VIEW_STOPPED

static final java.lang.String VIEW_STOPPED

See Also:

Constant Field Values

Method Detail

addAnimator

void addAnimator(Animator animator)

Add an animator to the View. This method does not start the Animator. Starting the Animator is the responsibility of the application.

Parameters:

animator - the Animator to be added

apply

void apply(DrawContext dc)

Calculates and applies this View's internal state to the graphics context in the specified dc. All subsequently rendered objects use this new state. Upon return, the OpenGL graphics context reflects the values of this view, as do any computed values of the view, such as the modelview matrix, projection matrix and viewing frustum.

Parameters:

dc - the current WorldWind DrawContext on which View will apply its state.

Throws:

java.lang.IllegalArgumentException - If dc is null, or if the Globe or GL instances in dc are null.

computePixelSizeAtDistance

double computePixelSizeAtDistance(double distance)

Computes the dimension (in meters) that a screen pixel would cover at a given distance from the eye point (also in meters). The distance is interpreted as the linear distance between the eye point and the world point in question. This computation assumes that pixels dimensions are square, and therefore returns a single dimension.

Parameters:

distance - the distance in meters from the eye point. This value must be positive but is otherwise unbounded.

Returns:

the dimension of a pixel in meters at the given distance.

Throws:

java.lang.IllegalArgumentException - if distance is negative.

computePositionFromScreenPoint

Position computePositionFromScreenPoint(double x,
                                        double y)

Computes the intersection of a line originating from the eye point and passing through (x, y) with the Globe. Only the ellipsoid itself is considered; terrain elevations are not incorporated.

Parameters:

x - the horizontal coordinate originating from the left side of View's projection plane.

y - the vertical coordinate originating from the top of View's projection plane.

Returns:

the point on the surface in polar coordinates.

computeRayFromScreenPoint

Line computeRayFromScreenPoint(double x,
                               double y)

Computes a line, in model coordinates, originating from the eye point, and passing through the point contained by (x, y) on the View's projection plane (or after projection into model space).

Parameters:

x - the horizontal coordinate originating from the left side of View's projection plane.

y - the vertical coordinate originating from the top of View's projection plane.

Returns:

a line beginning at the View's eye point and passing through (x, y) transformed into model space.

copyViewState

void copyViewState(View view)

Copy the state of the given View.

Parameters:

view - The View whose state is to be copied.

getCenterPoint

Vec4 getCenterPoint()

Gets the center point of the view.

Returns:

the center point of the view if that point is on the globe, otherwise, return null

getCurrentEyePoint

Vec4 getCurrentEyePoint()

Returns the most up-to-date location of the eye in cartesian coordinates. Unlike getEyePosition() and getEyePoint(), getCurrentEyePoint will return the View's immediate position.

Returns:

Vec4 of the eye.

getCurrentEyePosition

Position getCurrentEyePosition()

Returns the current geographic coordinates of this view's eye position, as determined from this view's current parameters.

Note: The value returned is not necessarily the value specified to setEyePosition(gov.nasa.worldwind.geom.Position) but is the eye position corresponding to this view's current parameters.

Returns:

the position of the eye corresponding to the current parameters of this view.

getEyePoint

Vec4 getEyePoint()

Returns the location of the eye in cartesian coordinates. This value is computed in the most recent call to apply.

Returns:

Vec4 of the eye.

getEyePosition

Position getEyePosition()

Returns the current geographic coordinates of this view's eye position, as computed for the most recent model traversal.

Note: The value returned is not necessarily the value specified to setEyePosition(gov.nasa.worldwind.geom.Position) but is the eye position corresponding to this view's most recently applied state.

Returns:

the position of the eye corresponding to the most recent application of this view, or null if the view has not yet been applied.

getFarClipDistance

double getFarClipDistance()

Returns the far clipping plane distance, in eye coordinates. Implementations of the View interface are not required to have a method for setting the near and far distance. Applications that need to control the near and far clipping distances can derive from BasicOrbitView or BasicFlyView

Returns:

far clipping plane distance, in eye coordinates.

getFieldOfView

Angle getFieldOfView()

Returns the horizontal field-of-view angle (the angle of visibility), or null if the implementation does not support a field-of-view.

Returns:

Angle of the horizontal field-of-view, or null if none exists.

getForwardVector

Vec4 getForwardVector()

Returns the forward axis in cartesian coordinates. This value is computed in the most recent call to apply.

Returns:

Vec4 of the forward axis.

getFrustum

Frustum getFrustum()

Returns the viewing Frustum in eye coordinates. The Frustum is the portion of viewable space defined by three sets of parallel 'clipping' planes. This value is computed in the most recent call to apply.

Returns:

viewing Frustum in eye coordinates.

getFrustumInModelCoordinates

Frustum getFrustumInModelCoordinates()

Returns the viewing Frustum in model coordinates. Model coordinate frustums are useful for performing visibility tests against world geometry. This frustum has the same shape as the frustum returned in getFrustum, but it has been transformed into model space. This value is computed in the most recent call to apply.

Returns:

viewing Frustum in model coordinates.

getGlobe

Globe getGlobe()

Gets the globe associated with this view. The Globe is updated at the beginning of each frame, during View.apply(). View.getGlobe() returns null if called before the first invocation of View.apply().

Returns:

the globe being rendered by this view, or null before the first invocation of View.apply().

getHeading

Angle getHeading()

Returns the view's current heading.

Returns:

Angle of the view's heading.

getHorizonDistance

double getHorizonDistance()

Returns the horizon distance for this view's most recently used eye position. The eye position changes when this view changes, so the horizon distance also changes when this view changes. The value returned is the value used during the most recent model traversal.

Returns:

the horizon position, in meters, or 0 if this view has not yet been applied.

getModelviewMatrix

Matrix getModelviewMatrix()

Returns the modelview matrix. The modelview matrix transforms model coordinates to eye coordinates. This matrix is constructed using the model space translation and orientation specific to each the implementation. This value is computed in the most recent call to apply.

Returns:

the current model-view matrix.

getNearClipDistance

double getNearClipDistance()

Returns the near clipping plane distance, in eye coordinates. Implementations of the View interface are not required to have a method for setting the near and far distance. Applications that need to control the near and far clipping distances can derive from BasicOrbitView or BasicFlyView

Returns:

near clipping plane distance, in eye coordinates.

getPitch

Angle getPitch()

Returns the view's current pitch.

Returns:

Angle of the view's pitch.

getProjectionMatrix

Matrix getProjectionMatrix()

Gets the projection matrix. The projection matrix transforms eye coordinates to screen coordinates. This matrix is constructed using the projection parameters specific to each implementation of View. The method getFrustum() returns the geometry corresponding to this matrix. This value is computed in the most recent call to apply.

Returns:

the current projection matrix.

getRoll

Angle getRoll()

Returns this View's current roll.

Returns:

Angle of the view's roll.

getUpVector

Vec4 getUpVector()

Returns the up axis in cartesian coordinates. This value is computed in the most recent call to apply.

Returns:

Vec4 of the up axis.

getViewInputHandler

ViewInputHandler getViewInputHandler()

Gets the ViewInputHandler being used to map input events to View controls.

Returns:

the ViewInputHandler being used to map input events to View controls.

getViewport

java.awt.Rectangle getViewport()

Returns the bounds (x, y, width, height) of the viewport. The implementation will configure itself to render in this viewport. This value is computed in the most recent call to apply.

Returns:

the Rectangle of the viewport.

getViewPropertyLimits

ViewPropertyLimits getViewPropertyLimits()

Get the ViewPropertyLimits for this view.

Returns:

the ViewPropertyLimits for this view.

getViewStateID

long getViewStateID()

Get an identifier for the current state of the modelview matrix. The modelview matrix transforms model coordinates to eye coordinates. This identifier can be used to determine if the view has changed state since a previous frame.

Returns:

an identifier for the current modelview matrix state.

goTo

void goTo(Position position,
          double elevation)

Animate to the specified position. The implementation is expected to animate the View to look at the given position from the given elevation.

Parameters:

position - The position to animate to.

elevation - The elevation to look at the position from.

isAnimating

boolean isAnimating()

Determine if there are any animations active in the View.

Returns:

true if there are active animations, false otherwise.

popReferenceCenter

void popReferenceCenter(DrawContext dc)

Removes the model-view matrix on top of the matrix stack, and restores the original matrix.

Parameters:

dc - the current WorldWind drawing context on which the original matrix will be restored.

Throws:

java.lang.IllegalArgumentException - if dc is null, or if the Globe or GL instances in dc are null.

project

Vec4 project(Vec4 modelPoint)

Maps a Point in model (cartesian) coordinates to a Point in screen coordinates. The returned x and y are relative to the lower left hand screen corner, while z is the screen depth-coordinate. If the model point cannot be successfully mapped, this will return null.

Parameters:

modelPoint - the model coordinate Point to project.

Returns:

the mapped screen coordinate Point.

Throws:

java.lang.IllegalArgumentException - if modelPoint is null.

pushReferenceCenter

Matrix pushReferenceCenter(DrawContext dc,
                           Vec4 referenceCenter)

Defines and applies a new model-view matrix in which the world origin is located at referenceCenter. Geometry rendered after a call to pushReferenceCenter should be transformed with respect to referenceCenter, rather than the canonical origin (0, 0, 0). Calls to pushReferenceCenter must be followed by popReferenceCenter after rendering is complete. Note that calls to getModelviewMatrix() will not return reference-center model-view matrix, but the original matrix.

Parameters:

dc - the current WorldWind drawing context on which new model-view state will be applied.

referenceCenter - the location to become the new world origin.

Returns:

a new model-view matrix with origin is at referenceCenter, or null if this method failed.

Throws:

java.lang.IllegalArgumentException - if referenceCenter is null, if dc is null, or if the Globe or GL instances in dc are null.

setEyePosition

void setEyePosition(Position eyePosition)

Sets the geographic position of the eye.

Parameters:

eyePosition - the eye position.

Throws:

java.lang.IllegalArgumentException - If eyePosition is null.

setFieldOfView

void setFieldOfView(Angle fieldOfView)

Sets the horizontal field-of-view angle (the angle of visibility) to the specified fieldOfView. This may be ignored if the implementation that do not support a field-of-view.

Parameters:

fieldOfView - the horizontal field-of-view angle.

Throws:

java.lang.IllegalArgumentException - If the implementation supports field-of-view, and fieldOfView is null.

setHeading

void setHeading(Angle heading)

Sets the heading of the view. The implementation may interpret this command in whatever way it chooses.

Parameters:

heading - The direction to aim the view in degrees

setOrientation

void setOrientation(Position eyePosition,
                    Position centerPosition)

Sets the location of the eye, and the center of the screen in geographic coordinates. The implementation may interpret this command in whatever way it chooses, so long as the eye is placed at the specified eyePosition, and the center of the screen is the specified centerPosition. Specifically, implementations must determine what the up direction will be given these parameters, and apply these parameters in a meaningful way.

Parameters:

eyePosition - Position of they eye.

centerPosition - Position of the screen center.

setPitch

void setPitch(Angle pitch)

Sets the pitch of the view. The implementation may interpret pitch as it chooses

Parameters:

pitch - The pitch of the view.

setReferenceCenter

Matrix setReferenceCenter(DrawContext dc,
                          Vec4 referenceCenter)

Sets the reference center matrix without pushing the stack.

Parameters:

dc - the drawing context.

referenceCenter - the new reference center

Returns:

a new model-view matrix with origin is at referenceCenter, or null if this method failed.

Throws:

java.lang.IllegalArgumentException - if referenceCenter is null, if dc is null, or if the Globe or GL instances in dc are null.

See Also:

pushReferenceCenter(gov.nasa.worldwind.render.DrawContext, gov.nasa.worldwind.geom.Vec4)

setRoll

void setRoll(Angle roll)

Set the roll of the view. The implementation may interpret roll as it chooses.

Parameters:

roll - New roll. May not be null.

stopAnimations

void stopAnimations()

Stops any animations that are active in this View

stopMovement

void stopMovement()

Stops any movement associated with this View.

unProject

Vec4 unProject(Vec4 windowPoint)

Maps a Point in screen coordinates to a Point in model coordinates. The input x and y are relative to the lower left hand screen corner, while z is the screen depth-coordinate. If the screen point cannot be successfully mapped, this will return null.

Parameters:

windowPoint - the window coordinate Point to project.

Returns:

the mapped screen coordinate Point.

Throws:

java.lang.IllegalArgumentException - if windowPoint is null.