src.gov.nasa.worldwind.View Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of worldwindx Show documentation
Show all versions of worldwindx Show documentation
World Wind is a collection of components that interactively display 3D geographic information within Java applications or applets.
/*
* Copyright (C) 2012 United States Government as represented by the Administrator of the
* National Aeronautics and Space Administration.
* All Rights Reserved.
*/
package gov.nasa.worldwind;
import gov.nasa.worldwind.animation.Animator;
import gov.nasa.worldwind.awt.ViewInputHandler;
import gov.nasa.worldwind.geom.*;
import gov.nasa.worldwind.globes.Globe;
import gov.nasa.worldwind.render.DrawContext;
import gov.nasa.worldwind.view.ViewPropertyLimits;
/**
* 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
* {@link #apply(gov.nasa.worldwind.render.DrawContext) 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
*
*
* @author Paul Collins
* @version $Id: View.java 1171 2013-02-11 21:45:02Z dcollins $
* @see gov.nasa.worldwind.view.orbit.OrbitView
*/
public interface View extends WWObject, Restorable
{
final String VIEW_STOPPED = "gov.nasa.worldwind.View.ViewStopped";
/** Stops any movement associated with this View. */
void stopMovement();
/**
* 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 {@link #setEyePosition(gov.nasa.worldwind.geom.Position)}
* but is the eye position corresponding to this view's most recently applied state.
*
* @return the position of the eye corresponding to the most recent application of this view, or null if the view
* has not yet been applied.
*/
Position getEyePosition();
/**
* Sets the geographic position of the eye.
*
* @param eyePosition the eye position.
*
* @throws IllegalArgumentException If eyePosition is null.
*/
void setEyePosition(Position eyePosition);
/**
* 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 {@link #setEyePosition(gov.nasa.worldwind.geom.Position)}
* but is the eye position corresponding to this view's current parameters.
*
* @return the position of the eye corresponding to the current parameters of this view.
*/
Position getCurrentEyePosition();
/**
* 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.
*
* @param eyePosition Position of they eye.
* @param centerPosition Position of the screen center.
*/
void setOrientation(Position eyePosition, Position centerPosition);
/**
* Sets the heading of the view. The implementation may interpret this command in whatever way it chooses.
*
* @param heading The direction to aim the view in degrees
*/
void setHeading(Angle heading);
/**
* Sets the pitch of the view. The implementation may interpret pitch as it chooses
*
* @param pitch The pitch of the view.
*/
void setPitch(Angle pitch);
/**
* Returns the view's current heading.
*
* @return Angle of the view's heading.
*/
Angle getHeading();
/**
* Returns the view's current pitch.
*
* @return Angle of the view's pitch.
*/
Angle getPitch();
/**
* Returns this View's current roll.
*
* @return Angle of the view's roll.
*/
Angle getRoll();
/**
* Set the roll of the view. The implementation may interpret roll as it chooses.
*
* @param roll New roll. May not be null.
*/
void setRoll(Angle roll);
/**
* Returns the location of the eye in cartesian coordinates. This value is computed in the most recent call to
* apply.
*
* @return Vec4 of the eye.
*/
Vec4 getEyePoint();
/**
* Returns the most up-to-date location of the eye in cartesian coordinates. Unlike {@link #getEyePosition} and
* {@link #getEyePoint}, getCurrentEyePoint will return the View's immediate position.
*
* @return Vec4 of the eye.
*/
Vec4 getCurrentEyePoint();
/**
* Returns the up axis in cartesian coordinates. This value is computed in the most recent call to
* apply.
*
* @return Vec4 of the up axis.
*/
Vec4 getUpVector();
/**
* Returns the forward axis in cartesian coordinates. This value is computed in the most recent call to
* apply.
*
* @return Vec4 of the forward axis.
*/
Vec4 getForwardVector();
/**
* 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.
*
* @return the current model-view matrix.
*/
Matrix getModelviewMatrix();
/**
* 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.
*
* @return an identifier for the current modelview matrix state.
*/
long getViewStateID();
/**
* Returns the horizontal field-of-view angle (the angle of visibility), or null if the implementation does not
* support a field-of-view.
*
* @return Angle of the horizontal field-of-view, or null if none exists.
*/
Angle getFieldOfView();
/**
* 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.
*
* @param fieldOfView the horizontal field-of-view angle.
*
* @throws IllegalArgumentException If the implementation supports field-of-view, and fieldOfView is
* null.
*/
void setFieldOfView(Angle fieldOfView);
/**
* 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.
*
* @return the Rectangle of the viewport.
*/
java.awt.Rectangle getViewport();
/**
* 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 {@link gov.nasa.worldwind.view.orbit.BasicOrbitView} or {@link
* gov.nasa.worldwind.view.firstperson.BasicFlyView}
*
* @return near clipping plane distance, in eye coordinates.
*/
double getNearClipDistance();
/**
* 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 {@link gov.nasa.worldwind.view.orbit.BasicOrbitView} or {@link
* gov.nasa.worldwind.view.firstperson.BasicFlyView}
*
* @return far clipping plane distance, in eye coordinates.
*/
double getFarClipDistance();
/**
* 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.
*
* @return viewing Frustum in eye coordinates.
*/
Frustum getFrustum();
/**
* 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.
*
* @return viewing Frustum in model coordinates.
*/
Frustum getFrustumInModelCoordinates();
/**
* 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
* {@link #getFrustum} returns the geometry corresponding to this matrix. This value is computed in the most recent
* call to apply.
*
* @return the current projection matrix.
*/
Matrix getProjectionMatrix();
/**
* 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.
*
* @param 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.
*/
void apply(DrawContext dc);
/**
* 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.
*
* @param modelPoint the model coordinate Point to project.
*
* @return the mapped screen coordinate Point.
*
* @throws IllegalArgumentException if modelPoint is null.
*/
Vec4 project(Vec4 modelPoint);
/**
* 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.
*
* @param windowPoint the window coordinate Point to project.
*
* @return the mapped screen coordinate Point.
*
* @throws IllegalArgumentException if windowPoint is null.
*/
Vec4 unProject(Vec4 windowPoint);
/**
* 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 {@link #popReferenceCenter(gov.nasa.worldwind.render.DrawContext)
* popReferenceCenter} after rendering is complete. Note that calls to {@link #getModelviewMatrix} will not return
* reference-center model-view matrix, but the original matrix.
*
* @param dc the current World Wind drawing context on which new model-view state will be applied.
* @param referenceCenter the location to become the new world origin.
*
* @return 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.
*/
Matrix pushReferenceCenter(DrawContext dc, Vec4 referenceCenter);
/**
* Removes the model-view matrix on top of the matrix stack, and restores the original matrix.
*
* @param 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.
*/
void popReferenceCenter(DrawContext dc);
/**
* Sets the reference center matrix without pushing the stack.
*
* @param dc the drawing context.
* @param referenceCenter the new reference center
*
* @return 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.
* @see #pushReferenceCenter(gov.nasa.worldwind.render.DrawContext, gov.nasa.worldwind.geom.Vec4)
*/
Matrix setReferenceCenter(DrawContext dc, Vec4 referenceCenter);
/**
* 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).
*
* @param x the horizontal coordinate originating from the left side of View's projection plane.
* @param y the vertical coordinate originating from the top of View's projection plane.
*
* @return a line beginning at the View's eye point and passing through (x, y) transformed into model
* space.
*/
Line computeRayFromScreenPoint(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.
*
* @param x the horizontal coordinate originating from the left side of View's projection plane.
* @param y the vertical coordinate originating from the top of View's projection plane.
*
* @return the point on the surface in polar coordinates.
*/
Position computePositionFromScreenPoint(double x, double y);
/**
* 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.
*
* @param distance the distance in meters from the eye point. This value must be positive but is otherwise
* unbounded.
*
* @return the dimension of a pixel in meters at the given distance.
*
* @throws IllegalArgumentException if distance is negative.
*/
double computePixelSizeAtDistance(double distance);
/**
* Gets the center point of the view.
*
* @return the center point of the view if that point is on the globe, otherwise, return null
*/
Vec4 getCenterPoint();
/**
* 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().
*
* @return the globe being rendered by this view, or null before the first invocation of View.apply().
*/
Globe getGlobe();
/**
* Gets the ViewInputHandler being used to map input events to View controls.
*
* @return the ViewInputHandler being used to map input events to View controls.
*/
ViewInputHandler getViewInputHandler();
/** Stops any animations that are active in this View */
void stopAnimations();
/**
* Animate to the specified position. The implementation is expected to animate the View to look at
* the given position from the given elevation.
*
* @param position The position to animate to.
* @param elevation The elevation to look at the position from.
*/
void goTo(Position position, double elevation);
/**
* Determine if there are any animations active in the View.
*
* @return true if there are active animations, false otherwise.
*/
boolean isAnimating();
/**
* Get the {@link ViewPropertyLimits} for this view.
*
* @return the {@link ViewPropertyLimits} for this view.
*/
ViewPropertyLimits getViewPropertyLimits();
/**
* Copy the state of the given View.
*
* @param view The View whose state is to be copied.
*/
void copyViewState(View view);
/**
* Add an animator to the View. This method does not start the {@link
* gov.nasa.worldwind.animation.Animator}. Starting the {@link gov.nasa.worldwind.animation.Animator} is the
* responsibility of the application.
*
* @param animator the {@link gov.nasa.worldwind.animation.Animator} to be added
*/
void addAnimator(Animator animator);
/**
* 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.
*
* @return the horizon position, in meters, or 0 if this view has not yet been applied.
*/
double getHorizonDistance();
}