NASA World Wind

gov.nasa.worldwind
Interface View

All Superinterfaces:
AVList, EventListener, PropertyChangeListener, WWObject
All Known Implementing Classes:
AbstractView, BasicOrbitView

public interface View
extends WWObject

The View interface provides basic methods for implementations to communicate state and state chages to the caller. Views provide a coordinate transformation from the object coordinates of the model to eye coordinates, which follow the OpenGL convention of a left-handed coordinate system with origin at the eye point and looking down the negative-z axis.

View implementations are free to constrain position and orientation, as well as supply any projection from eye to clip coordinates they see fit. Therefore calls to setFieldOfView(gov.nasa.worldwind.geom.Angle), goToCoordinate(gov.nasa.worldwind.geom.LatLon, double), goToLatLon(gov.nasa.worldwind.geom.LatLon) or goToAltitude(double) are not guaranteed to produce the requested transformation. When exact knowledge of these values in necessary, calling getFieldOfView(), getPosition() or getAltitude() immediately after a call to apply(gov.nasa.worldwind.DrawContext) guarantees the value to be synchronized with data structures used for view transformation (e.g. model-view and projection matrices).

Views contain both fixed state and computed state. The computed state is typically updated during a call to the apply(gov.nasa.worldwind.DrawContext) method. Most accessor methods in this interface return the computed state that was set during the most recent call to apply().

See Also:
Frustum, ViewFrustum

Method Summary
 void apply(DrawContext dc)
          Calculates and applies View's internal state to the graphics context in DrawContext.
 double computeHorizonDistance()
          Returns 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 getAltitude()
          Returns the View eye altitude (in meters) above the last rendered SectorGeometry, or the analytical Globe, depending on the implementation.
 Point getEyePoint()
          Returns the eye position in model coordinates.
 Angle getFieldOfView()
          Returns the horizontal field-of-view angle (the angle of visibility) associated with this View, or null if the View implementation does not support a field-of-view.
 Point getForwardVector()
          Returns the View z-axis orientation in model coordinates.
 Frustum getFrustum()
          Returns the viewing Frustum in eye coordinates, computed in apply().
 Frustum getFrustumInModelCoordinates()
          Returns the viewing Frustum transformed to model coordinates.
 Angle getHeading()
          Returns the View's angle from true North.
 Matrix4 getModelViewMatrix()
          Returns the 'model-view' matrix computed in apply(), which transforms model coordinates to eye coordinates (where the eye is located at the origin, facing down the negative-z axis).
 Angle getPitch()
          Returns the View's angle from the plane tangent to the surface.
 Angle[] getPitchConstraints()
          Returns a two-dimensional array containing the range of angles (inclusive) the View may limit its pitch to, if pitch constraints are enabled.
 Position getPosition()
          Returns the geographic (latitude, longitude, elevation) coordinate of the View's eye point.
 Matrix4 getProjectionMatrix()
          Returns the 'projection' matrix computed in apply(), which transforms eye coordinates to homogeneous clip coordinates (a box of dimension (2, 2, 2) centered at the origin).
 Angle getRoll()
          Returns the View's angle about its local z-axis.
 Point getUpVector()
          Returns the View y-axis orientation in model coordinates.
 Rectangle getViewport()
          Returns a Rectangle representing the window bounds (x, y, width, height) of the viewport, computed in apply().
 double getZoom()
          Returns the View's translation in its forward direction.
 double[] getZoomConstraints()
          Returns a two-dimensional array containing the range of values (inclusive) the View may limit its zoom to, if zoom constraints are enabled.
 void goToAltitude(double newAltitude)
          Moves the View eye point to the new altitude (in meters) above the last rendered SectorGeometry, or the analytical Globe, depending on the implementation.
 void goToCoordinate(LatLon newLatLon, double newAltitude)
          Moves the View eye point to the new polar coordinate (latitude, longitude, elevation).
 void goToLatLon(LatLon newLatLon)
          Moves the View eye point to the new geographic (latitude, longitude) coordinate.
 boolean isEnablePitchConstraints()
          Returns true when pitch constraints are enabled.
 boolean isEnableZoomConstraints()
          Returns true when zoom constraints are enabled.
 void popReferenceCenter(DrawContext dc)
          Removes the model-view matrix on top of the matrix stack, and restores the matrix now on top.
 Point project(Point modelPoint)
          Maps a Point in model (cartesian) coordinates to a Point in screen coordinates.
 void pushReferenceCenter(DrawContext dc, Point referenceCenter)
          Generates a new coordinate system in which the View does not move, and model coordinates are reverse transformed into eye coordinates.
 void setEnablePitchConstraints(boolean enabled)
          Enable or disable pitch constraints.
 void setEnableZoomConstraints(boolean enabled)
          Enable or disable zoom constraints.
 void setFieldOfView(Angle newFov)
          Sets the horiziontal field-of-view angle (the angle of visibillity) associated with this View.
 void setHeading(Angle newHeading)
          Sets the View's angle to true North.
 void setPitch(Angle newPitch)
          Sets the View's angle to the plane tangent to the surface.
 void setPitchConstraints(Angle newMinPitch, Angle newMaxPitch)
          Sets the range of angles (inclusive) the View may limit its pitch to, if pitch constraints are enabled.
 void setRoll(Angle newRoll)
          Sets the View's angle about its local z-axis.
 void setZoom(double newZoom)
          Sets the View's translation in its forward direction.
 void setZoomConstraints(double newMinZoom, double newMaxZoom)
          Sets the range of values (inclusive) the View may limit its zoom to, if zoom constraints are enabled.
 Point unProject(Point windowPoint)
          Maps a Point in screen coordinates to a Point in model coordinates.
 
Methods inherited from interface gov.nasa.worldwind.AVList
addPropertyChangeListener, addPropertyChangeListener, copy, firePropertyChange, firePropertyChange, getStringValue, getValue, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue
 
Methods inherited from interface java.beans.PropertyChangeListener
propertyChange
 

Method Detail

apply

void apply(DrawContext dc)
Calculates and applies View's internal state to the graphics context in DrawContext. 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 model-view matrix and Frustum.

Parameters:
dc - the current World Wind drawing context on which View's state will apply.
Throws:
IllegalArgumentException - if dc is null, or if the Globe or GL contained in dc is null.

computeHorizonDistance

double computeHorizonDistance()
Returns 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 (in meters).

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.

getAltitude

double getAltitude()
Returns the View eye altitude (in meters) above the last rendered SectorGeometry, or the analytical Globe, depending on the implementation.

Returns:
the View's altitude (in meters) above the surface.

getEyePoint

Point getEyePoint()
Returns the eye position in model coordinates.

Returns:
the eye position in model coordinates.

getFieldOfView

Angle getFieldOfView()
Returns the horizontal field-of-view angle (the angle of visibility) associated with this View, or null if the View implementation does not support a field-of-view.

Returns:
horizontal field-of-view angle, or null if none exists.

getForwardVector

Point getForwardVector()
Returns the View z-axis orientation in model coordinates.

Returns:
the z-axis vector in model coordinates.

getFrustum

Frustum getFrustum()
Returns the viewing Frustum in eye coordinates, computed in apply(). The Frustum is the portion of viewable space defined by three sets of parallel 'clipping' planes. The method getFrustumInModelCoordinates() maintains the shape of this Frustum, but it has been translated and aligned with the eye in model space.

Returns:
the current viewing frustum in eye coordinates.

getFrustumInModelCoordinates

Frustum getFrustumInModelCoordinates()
Returns the viewing Frustum transformed to model coordinates. Model coordinate frustums are useful for performing multiple intersection tests in model coordinates.

Returns:
the current viewing frustum in model coordinates.

getHeading

Angle getHeading()
Returns the View's angle from true North.

Returns:
the angle from true North.

getModelViewMatrix

Matrix4 getModelViewMatrix()
Returns the 'model-view' matrix computed in apply(), which transforms model coordinates to eye coordinates (where the eye is located at the origin, facing down the negative-z axis). This matrix is constructed using the model space translation and orientation specific to each implementation of View.

Returns:
the current model-view matrix.

getPitch

Angle getPitch()
Returns the View's angle from the plane tangent to the surface.

Returns:
the angle from the surface tangent plane.

getPitchConstraints

Angle[] getPitchConstraints()
Returns a two-dimensional array containing the range of angles (inclusive) the View may limit its pitch to, if pitch constraints are enabled.

Returns:
a two-dimensional array, with the minimum and maximum pitch angles.

getPosition

Position getPosition()
Returns the geographic (latitude, longitude, elevation) coordinate of the View's eye point. Latitude and longitude represent the coordinate directly beneath (or above) the View, while elevation represents the View altitude above the analytical Globe radius.

Returns:
the latitude and longitude coordinates of the eye point.

getProjectionMatrix

Matrix4 getProjectionMatrix()
Returns the 'projection' matrix computed in apply(), which transforms eye coordinates to homogeneous clip coordinates (a box of dimension (2, 2, 2) centered at the origin). This matrix is constructed using the projection parameters specific to each implementation of View (e.g. field-of-view, clipping plane distances). The getFrustum() method returns the planes corresponding to this matrix.

Returns:
the current projection matrix.

getRoll

Angle getRoll()
Returns the View's angle about its local z-axis.

Returns:
the angle about the local z-axis.

getUpVector

Point getUpVector()
Returns the View y-axis orientation in model coordinates.

Returns:
the y-axis vector in model coordinates.

getViewport

Rectangle getViewport()
Returns a Rectangle representing the window bounds (x, y, width, height) of the viewport, computed in apply(). Implementations of View will configure themselves to render in this viewport.

Returns:
the current window bounds of the viewport, or null if none exists.

getZoom

double getZoom()
Returns the View's translation in its forward direction.

Returns:
translation along the forward direction.

getZoomConstraints

double[] getZoomConstraints()
Returns a two-dimensional array containing the range of values (inclusive) the View may limit its zoom to, if zoom constraints are enabled.

Returns:
two-dimensional array, with the minimum and maximum zoom values.

goToAltitude

void goToAltitude(double newAltitude)
Moves the View eye point to the new altitude (in meters) above the last rendered SectorGeometry, or the analytical Globe, depending on the implementation.

Parameters:
newAltitude - the new eye altitude (in meters) above the surface,

goToCoordinate

void goToCoordinate(LatLon newLatLon,
                    double newAltitude)
Moves the View eye point to the new polar coordinate (latitude, longitude, elevation).

Parameters:
newLatLon - the new latitude and longitude of the eye point.
newAltitude - the new eye altitude (in meters) above the surface,
Throws:
IllegalArgumentException - if newLatlon is null.

goToLatLon

void goToLatLon(LatLon newLatLon)
Moves the View eye point to the new geographic (latitude, longitude) coordinate. Altitude is left unchanged.

Parameters:
newLatLon - the new latitude and longitude of the eye point.
Throws:
IllegalArgumentException - if newLatlon is null.

isEnablePitchConstraints

boolean isEnablePitchConstraints()
Returns true when pitch constraints are enabled.

Returns:
true when pitch constraints are enabled.

isEnableZoomConstraints

boolean isEnableZoomConstraints()
Returns true when zoom constraints are enabled.

Returns:
true when zoom constraints are enabled, false otherwise.

popReferenceCenter

void popReferenceCenter(DrawContext dc)
Removes the model-view matrix on top of the matrix stack, and restores the matrix now on top. This has the effect of immediately replacing the current OpenGL model-view matrix with the matrix below the top. When the stack size is one, therefore containing the original model-view matrix computed by apply(), this method will throw an exception.

Parameters:
dc - the current World Wind drawing context on which View's state will apply.
Throws:
IllegalStateException - if the the refernce matrix stack is empty.

project

Point project(Point 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

void pushReferenceCenter(DrawContext dc,
                         Point referenceCenter)
Generates a new coordinate system in which the View does not move, and model coordinates are reverse transformed into eye coordinates. The origin for these coordinates will be referenceCenter, therefore all objects drawn after a call to pushReferenceCenter should be with respect to this Point, rather than the customary origin (0, 0, 0). This creates a new model-view matrix, which is placed on the top of a matrix stack, and immediately applied to the current OpenGL context. In order to return to the original coordinate space, callers should invoke popReferenceCenter(gov.nasa.worldwind.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 View's state will apply.
referenceCenter - the Point to become the new model space origin.
Throws:
IllegalArgumentException - if referenceCenter is null.

setEnablePitchConstraints

void setEnablePitchConstraints(boolean enabled)
Enable or disable pitch constraints.

Parameters:
enabled - true when pitch constraints should be enabled, false otherwise.

setEnableZoomConstraints

void setEnableZoomConstraints(boolean enabled)
Enable or disable zoom constraints.

Parameters:
enabled - trhe when zoom constraints should be enabled, false otherwise.

setFieldOfView

void setFieldOfView(Angle newFov)
Sets the horiziontal field-of-view angle (the angle of visibillity) associated with this View. This call may be ignored by implementations that do not support a field-of-view.

Parameters:
newFov - the new horizontal field-of-view angle.
Throws:
IllegalArgumentException - if newFov is null.

setHeading

void setHeading(Angle newHeading)
Sets the View's angle to true North.

Parameters:
newHeading - the new angle to true North.
Throws:
IllegalArgumentException - if newHeading is null.

setPitch

void setPitch(Angle newPitch)
Sets the View's angle to the plane tangent to the surface.

Parameters:
newPitch - the new angle to the surface tangent plane.
Throws:
IllegalArgumentException - if newPitch is null.

setPitchConstraints

void setPitchConstraints(Angle newMinPitch,
                         Angle newMaxPitch)
Sets the range of angles (inclusive) the View may limit its pitch to, if pitch constraints are enabled.

Parameters:
newMinPitch - the minimum pitch angle.
newMaxPitch - the maximum pitch angle.

setRoll

void setRoll(Angle newRoll)
Sets the View's angle about its local z-axis.

Parameters:
newRoll - the new angle about the local z-axis.
Throws:
IllegalArgumentException - if newRoll is null.

setZoom

void setZoom(double newZoom)
Sets the View's translation in its forward direction.

Parameters:
newZoom - translation along the forward direction.

setZoomConstraints

void setZoomConstraints(double newMinZoom,
                        double newMaxZoom)
Sets the range of values (inclusive) the View may limit its zoom to, if zoom constraints are enabled.

Parameters:
newMinZoom - the minimum zoom value.
newMaxZoom - the maximum zoom value.

unProject

Point unProject(Point 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