NASA World Wind

gov.nasa.worldwind
Interface View

All Superinterfaces:
AVList, EventListener, PropertyChangeListener, Restorable, WWObject
All Known Subinterfaces:
OrbitView
All Known Implementing Classes:
AbstractView, BasicOrbitView, FlatOrbitView

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 left-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(gov.nasa.worldwind.render.DrawContext).

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

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

See Also:
ViewStateIterator, OrbitView

Field Summary
static String VIEW_STOPPED
           
 
Method Summary
 void apply(DrawContext dc)
          Calculates and applies this View's internal state to the graphics context in the specified dc.
 void applyStateIterator(ViewStateIterator viewStateIterator)
          Iterates over View state changes in ViewStateIterator and applies them to the View.
 double computeHorizonDistance()
          Gets the distance from the View's eye point to the horizon point on the last rendered Globe.
 double computePixelSizeAtDistance(double distance)
          Computes the screen-aligned dimension (in meters) that a screen pixel would cover at a given distance (also in meters).
 Position computePositionFromScreenPoint(double x, double y)
          Computes the intersection of a line originating from the eye point (passing throught (x, y)) with the last rendered SectorGeometry, or the last analytical Globe if no rendered geometry exists.
 Line computeRayFromScreenPoint(double x, double y)
          Computes a line, in model coordinates, originating from the eye point, and passing throught the point contained by (x, y) on the View's projection plane (or after projection into model space).
 double getAutoFarClipDistance()
          Returns the auto-configured far clipping plane distance, in eye coordinates.
 double getAutoNearClipDistance()
          Returns the auto-configured near clipping plane distance, in eye coordinates.
 Vec4 getCurrentEyePoint()
          Returns the most up-to-date location of the eye in cartesian coordinates.
 Position getCurrentEyePosition()
          Returns the most up-to-date location of the eye in geographic coordintes.
 Vec4 getEyePoint()
          Returns the location of the eye in cartesian coordinates.
 Position getEyePosition()
          Returns the location of the eye in geographic coordinates.
 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.
 Matrix getModelviewMatrix()
          Returns the modelview matrix.
 double getNearClipDistance()
          Returns the near clipping plane distance, in eye coordinates.
 Matrix getProjectionMatrix()
          Gets the projection matrix.
 Vec4 getUpVector()
          Returns the up axis in cartesian coordinates.
 Rectangle getViewport()
          Returns the bounds (x, y, width, height) of the viewport.
 boolean hadCollisions()
          Returns whether or not a collision has occurred since the last call to hadCollisions.
 boolean hasStateIterator()
          Returns true when View is actively iterating over an instance of ViewStateIterator.
 boolean isDetectCollisions()
          Returns whether the this View will detect collisions with other objects, such as the surface geometry.
 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 setDetectCollisions(boolean detectCollisions)
          Sets whether or not this View will detect collisions with other objects, such as the surface geometry.
 void setEyePosition(Position eyePosition)
          Sets the location of the eye in geographic coordinates.
 void setFarClipDistance(double distance)
          Sets the far clipping plane distance, in eye coordinates.
 void setFieldOfView(Angle fieldOfView)
          Sets the horiziontal field-of-view angle (the angle of visibillity) to the specified fieldOfView.
 void setNearClipDistance(double distance)
          Sets the near clipping plane distance, in eye coordinates.
 void setOrientation(Position eyePosition, Position centerPosition)
          Sets the location of the eye, and the center of the screen in geographic coordinates.
 void stopMovement()
          Stops any movement associated with this View.
 void stopStateIterators()
          Immediately stops all active iteration over ViewStateIterator.
 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.Restorable
getRestorableState, restoreState
 

Field Detail

VIEW_STOPPED

static final String VIEW_STOPPED
See Also:
Constant Field Values
Method Detail

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 World Wind DrawContext on which View will apply its state.
Throws:
IllegalArgumentException - If dc is null, or if the Globe or GL instances in dc are null.

applyStateIterator

void applyStateIterator(ViewStateIterator viewStateIterator)
Iterates over View state changes in ViewStateIterator and applies them to the View. The View will automatically refresh and request state from viewStateIterator until the iteration is complete, or View has been stopped by invoking stopStateIterators().

Parameters:
viewStateIterator - the ViewStateIterator to iterate over.

computeHorizonDistance

double computeHorizonDistance()
Gets the distance from the View's eye point to the horizon point on the last rendered Globe.

Returns:
the distance from the eye point to the horizon.

computePixelSizeAtDistance

double computePixelSizeAtDistance(double distance)
Computes the screen-aligned dimension (in meters) that a screen pixel would cover at a given distance (also in meters). This computation assumes that pixels dimensions are square, and therefore returns a single dimension.

Parameters:
distance - the distance from the eye point, in eye coordinates, along the z-axis. This value must be positive but is otherwise unbounded.
Returns:
the dimension of a pixel (in meters) at the given distance.
Throws:
IllegalArgumentException - if distance is negative.

computePositionFromScreenPoint

Position computePositionFromScreenPoint(double x,
                                        double y)
Computes the intersection of a line originating from the eye point (passing throught (x, y)) with the last rendered SectorGeometry, or the last analytical Globe if no rendered geometry exists.

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 coordiantes.

computeRayFromScreenPoint

Line computeRayFromScreenPoint(double x,
                               double y)
Computes a line, in model coordinates, originating from the eye point, and passing throught 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 throught (x, y) transformed into model space.

getAutoFarClipDistance

double getAutoFarClipDistance()
Returns the auto-configured far clipping plane distance, in eye coordinates. The distance is implementation dependent, and should be based on the View's current position and orientation.

Returns:
auto-configured far clipping plane distance.

getAutoNearClipDistance

double getAutoNearClipDistance()
Returns the auto-configured near clipping plane distance, in eye coordinates. The distance is implementation dependent, and should be based on the View's current position and orientation.

Returns:
auto-configured near clipping plane distance.

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 most up-to-date location of the eye in geographic coordintes. Unlike getEyePosition() and getEyePoint(), getCurrentEyePosition will return the View's immediate position.

Returns:
Position of the eye.

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 location of the eye in geographic coordinates. This value is computed in the most recent call to apply.

Returns:
Position of the eye.

getFarClipDistance

double getFarClipDistance()
Returns the far clipping plane distance, in eye coordinates. If the far clipping plane is auto-configured by the View, this will still return the value last specified by the caller. To get the auto-configured value, see getAutoFarClipDistance()

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.

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. If the near clipping plane is auto-configured by the View, this will still return the value last specified by the caller. To get the auto-configured value, see getAutoNearClipDistance().

Returns:
near clipping plane distance, in eye coordinates.

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.

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.

getViewport

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.

hadCollisions

boolean hadCollisions()
Returns whether or not a collision has occurred since the last call to hadCollisions. If isDetectCollisions() is false, collisions will not be detected and hadCollisions will always return false.

Returns:
true if a collision has occurred since the last call; false otherwise.

hasStateIterator

boolean hasStateIterator()
Returns true when View is actively iterating over an instance of ViewStateIterator.

Returns:
true when iterating over ViewStateIterator; false otherwise.

isDetectCollisions

boolean isDetectCollisions()
Returns whether the this View will detect collisions with other objects, such as the surface geometry. If true, implementations may also automatically resolve any detected collisions.

Returns:
true If this View will detect collisions; 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 World Wind drawing context on which the original matrix will be restored.
Throws:
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 sucessfully mapped, this will return null.

Parameters:
modelPoint - the model coordinate Point to project.
Returns:
the mapped screen coordinate Point.
Throws:
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(gov.nasa.worldwind.render.DrawContext) 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 World Wind 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:
IllegalArgumentException - if referenceCenter is null, if dc is null, or if the Globe or GL instances in dc are null.

setDetectCollisions

void setDetectCollisions(boolean detectCollisions)
Sets whether or not this View will detect collisions with other objects, such as the surface geometry. If detectCollisions is true, implementations may also automatically resolve any detected collisions.

Parameters:
detectCollisions - If true, this View will resolve collisions; otherwise this View will ignore collisions.

setEyePosition

void setEyePosition(Position eyePosition)
Sets the location of the eye 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.

Parameters:
eyePosition - Position of the eye.
Throws:
IllegalArgumentException - If eyePosition is null.

setFarClipDistance

void setFarClipDistance(double distance)
Sets the far clipping plane distance, in eye coordinates. Implementations may restrict the range of valid distances. When the caller specifies an invalid distance, implementations may interpret this as an indicator to auto-configure the far clipping distance. Otherwise, specifying an invalid distance will cause an IllegalArgumentException to be thrown.

Parameters:
distance - the far clipping plane distance.
Throws:
IllegalArgumentException - if distance is not valid, and the implementation does not specially treat invalid values.

setFieldOfView

void setFieldOfView(Angle fieldOfView)
Sets the horiziontal field-of-view angle (the angle of visibillity) 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:
IllegalArgumentException - If the implementation supports field-of-view, and fieldOfView is null.

setNearClipDistance

void setNearClipDistance(double distance)
Sets the near clipping plane distance, in eye coordinates. Implementations may restrict the range of valid distances. When the caller specifies an invalid distance, implementations may interpret this as an indicator to auto-configure the near clipping distance. Otherwise, specifying an invalid distance will cause an IllegalArgumentException to be thrown.

Parameters:
distance - the near clipping plane distance.
Throws:
IllegalArgumentException - if distance is not valid, and the implementation does not specially treat invalid values.

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 choooses, so long as the eye is placed at the specified eyePosition, and the center of the screen is the specified centerPositoin. 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.

stopMovement

void stopMovement()
Stops any movement associated with this View. This will stop any currently active ViewStateIterators on this View.


stopStateIterators

void stopStateIterators()
Immediately stops all active iteration over ViewStateIterator.


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 sucessfully mapped, this will return null.

Parameters:
windowPoint - the window coordinate Point to project.
Returns:
the mapped screen coordinate Point.
Throws:
IllegalArgumentException - if windowPoint is null.

NASA World Wind