gov/nasa/worldwind/view/View.java

   1 /*
   2 Copyright (C) 2001, 2006 United States Government as represented by
   3 the Administrator of the National Aeronautics and Space Administration.
   4 All Rights Reserved.
   5 */
   6 package gov.nasa.worldwind.view;
   7
   8 import gov.nasa.worldwind.WWObject;
   9 import gov.nasa.worldwind.geom.*;
  10 import gov.nasa.worldwind.render.DrawContext;
  11
  12 /**
  13  * <code>View</code> provides a coordinate transformation from <code>Model</code> coordinates to eye coordinates,
  14  * following the OpenGL convention of a left-handed coordinate system with the origin at the eye point and looking down
  15  * the negative Z axis. <code>View</code> also provides a transformation from eye coordinates to screen coordinates,
  16  * following the OpenGL convention of an origin in the lower left hand screen corner.
  17  * </p>
  18  * <code>View</code> contains both fixed state and computed state. The computed state is typically updated during a call
  19  * to the {@link #apply} method. Most accessor methods in this interface return the computed state that was set during
  20  * the most recent call to <code>apply()</code>.
  21  *
  22  * @author Paul Collins
  23  * @version $Id: View.java 2491 2007-08-02 18:48:00Z dcollins $
  24  * @see ViewStateIterator
  25  * @see gov.nasa.worldwind.view.OrbitView
  26  */
  27 public interface View extends WWObject
  28 {
  29     /**
  30      * Calculates and applies <code>View's</code> internal state to the graphics context in <code>DrawContext</code>.
  31      * All subsequently rendered objects use this new state. Upon return, the OpenGL graphics context reflects the
  32      * values of this view, as do any computed values of the view, such as the model-view matrix, projection matrix and
  33      * <code>Frustum</code>.
  34      *
  35      * @param dc the current World Wind drawing context on which <code>View's</code> state will apply.
  36      * @throws IllegalArgumentException if <code>dc</code> is null, or if the <code>Globe</code> or <code>GL</code>
  37      *                                  instances in <code>dc</code> are null.
  38      */
  39     void apply(DrawContext dc);
  40
  41     /**
  42      * Maps a <code>Point</code> in model (cartesian) coordinates to a <code>Point</code> in screen coordinates. The
  43      * returned x and y are relative to the lower left hand screen corner, while z is the screen depth-coordinate. If
  44      * the model point cannot be sucessfully mapped, this will return null.
  45      *
  46      * @param modelPoint the model coordinate <code>Point</code> to project.
  47      * @return the mapped screen coordinate <code>Point</code>.
  48      * @throws IllegalArgumentException if <code>modelPoint</code> is null.
  49      */
  50     Vec4 project(Vec4 modelPoint);
  51
  52     /**
  53      * Maps a <code>Point</code> in screen coordinates to a <code>Point</code> in model coordinates. The input x and y
  54      * are  relative to the lower left hand screen corner, while z is the screen depth-coordinate.  If the screen point
  55      * cannot be sucessfully mapped, this will return null.
  56      *
  57      * @param windowPoint the window coordinate <code>Point</code> to project.
  58      * @return the mapped screen coordinate <code>Point</code>.
  59      * @throws IllegalArgumentException if <code>windowPoint</code> is null.
  60      */
  61     Vec4 unProject(Vec4 windowPoint);
  62
  63     /**
  64      * Defines and applies a new model-view matrix in which the world origin is located at <code>referenceCenter</code>.
  65      * Geometry rendered after a call to <code>pushReferenceCenter</code> should be transformed with respect to
  66      * <code>referenceCenter</code>, rather than the canonical origin (0, 0, 0). Calls to
  67      * <code>pushReferenceCenter</code> must be followed by {@link #popReferenceCenter} after rendering is complete.
  68      * Note that calls to {@link #getModelViewMatrix} will not return reference-center model-view matrix, but the
  69      * original matrix.
  70      *
  71      * @param dc              the current World Wind drawing context on which new model-view state will be applied.
  72      * @param referenceCenter the location to become the new world origin.
  73      * @return a new model-view matrix with origin is at <code>referenceCenter</code>, or null if this method failed.
  74      * @throws IllegalArgumentException if <code>referenceCenter</code> is null, if <code>dc</code> is null, or if the
  75      *                                  <code>Globe</code> or <code>GL</code> instances in <code>dc</code> are null.
  76      */
  77     Matrix pushReferenceCenter(DrawContext dc, Vec4 referenceCenter);
  78
  79     /**
  80      * Removes the model-view matrix on top of the matrix stack, and restores the original matrix.
  81      *
  82      * @param dc the current World Wind drawing context on which the original matrix will be restored.
  83      * @throws IllegalArgumentException if <code>dc</code> is null, or if the <code>Globe</code> or <code>GL</code>
  84      *                                  instances in <code>dc</code> are null.
  85      */
  86     void popReferenceCenter(DrawContext dc);
  87
  88     /**
  89      * Gets the 'model-view' matrix computed in <code>apply()</code>, which transforms model coordinates to eye
  90      * coordinates (where the eye is located at the origin, facing down the negative-z axis). This matrix is constructed
  91      * using the model space translation and orientation specific to each implementation of <code>View</code>.
  92      *
  93      * @return the current model-view matrix.
  94      */
  95     Matrix getModelViewMatrix();
  96
  97     /**
  98      * Gets the 'projection' matrix computed in <code>apply()</code>, which transforms eye coordinates to screen
  99      * coordinates. This matrix is constructed using the projection parameters specific to each implementation of
 100      * <code>View</code> (e.g. field-of-view). The {@link #getFrustum} method returns the geometry corresponding to this
 101      * matrix.
 102      *
 103      * @return the current projection matrix.
 104      */
 105     Matrix getProjectionMatrix();
 106
 107     /**
 108      * Gets a Rectangle representing the window bounds (x, y, width, height) of the viewport, computed in
 109      * <code>apply()</code>. Implementations of <code>View</code> will configure themselves to render in this viewport.
 110      *
 111      * @return the current window bounds of the viewport.
 112      */
 113     java.awt.Rectangle getViewport();
 114
 115     /**
 116      * Gets the viewing <code>Frustum</code> in eye coordinates, computed in <code>apply()</code>. The
 117      * <code>Frustum</code> is the portion of viewable space defined by three sets of parallel 'clipping' planes. The
 118      * method {@link #getFrustumInModelCoordinates} maintains the shape of this <code>Frustum</code>, but it has been
 119      * translated and aligned with the eye in model space.
 120      *
 121      * @return the current viewing frustum in eye coordinates.
 122      */
 123     Frustum getFrustum();
 124
 125     /**
 126      * Gets the viewing <code>Frustum</code> transformed to model coordinates. Model coordinate frustums are useful for
 127      * performing visibility tests against world geometry.
 128      *
 129      * @return the current viewing frustum in model coordinates.
 130      */
 131     Frustum getFrustumInModelCoordinates();
 132
 133     /**
 134      * Gets the horizontal field-of-view angle (the angle of visibility) associated with this <code>View</code>, or null
 135      * if the <code>View</code> implementation does not support a field-of-view.
 136      *
 137      * @return horizontal field-of-view angle, or null if none exists.
 138      */
 139     Angle getFieldOfView();
 140
 141     /**
 142      * Sets the horiziontal field-of-view angle (the angle of visibillity) associated with this <code>View</code>. This
 143      * call may be ignored by implementations that do not support a field-of-view.
 144      *
 145      * @param newFov the new horizontal field-of-view angle.
 146      * @throws IllegalArgumentException if <code>newFov</code> is null.
 147      */
 148     void setFieldOfView(Angle newFov);
 149
 150     /**
 151      * Gets the <code>View</code> eye position in model coordinates.
 152      *
 153      * @return the eye position in model coordinates.
 154      */
 155     Vec4 getEyePoint();
 156
 157     /**
 158      * Gets the position of the <code>View</code> eye point in geographic coordinates.
 159      *
 160      * @return the geographic coordinates of the eye point.
 161      */
 162     Position getEyePosition();
 163
 164     /**
 165      * Gets the <code>View</code> y-axis orientation in model coordinates.
 166      *
 167      * @return the y-axis vector in model coordinates.
 168      */
 169     Vec4 getUpVector();
 170
 171     /**
 172      * Gets the <code>View</code> z-axis orientation in model coordinates.
 173      *
 174      * @return the z-axis vector in model coordinates.
 175      */
 176     Vec4 getForwardVector();
 177
 178     /**
 179      * Computes a line, in model coordinates, originating from the eye point, and passing throught the point contained
 180      * by (x, y) on the <code>View's</code> projection plane (or after projection into model space).
 181      *
 182      * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
 183      * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
 184      * @return a line beginning at the <code>View's</code> eye point and passing throught (x, y) transformed into model
 185      *         space.
 186      */
 187     Line computeRayFromScreenPoint(double x, double y);
 188
 189     /**
 190      * Computes the intersection of a line originating from the eye point (passing throught (x, y)) with the last
 191      * rendered <code>SectorGeometry</code>, or the last analytical <code>Globe</code> if no rendered geometry exists.
 192      *
 193      * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
 194      * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
 195      * @return the point on the surface in polar coordiantes.
 196      */
 197     Position computePositionFromScreenPoint(double x, double y);
 198
 199     /**
 200      * Computes the screen-aligned dimension (in meters) that a screen pixel would cover at a given distance (also in
 201      * meters). This computation assumes that pixels dimensions are square, and therefore returns a single dimension.
 202      *
 203      * @param distance the distance from the eye point, in eye coordinates, along the z-axis. This value must be
 204      *                 positive but is otherwise unbounded.
 205      * @return the dimension of a pixel (in meters) at the given distance.
 206      * @throws IllegalArgumentException if <code>distance</code> is negative.
 207      */
 208     double computePixelSizeAtDistance(double distance);
 209
 210     /**
 211      * Gets the distance from the <code>View's</code> eye point to the horizon point on the last rendered
 212      * <code>Globe</code>.
 213      *
 214      * @return the distance from the eye point to the horizon (in meters).
 215      */
 216     double computeHorizonDistance();
 217
 218     /**
 219      * Iterates over <code>View</code> state changes in <code>ViewStateIterator</code> and applies them to the
 220      * <code>View</code>. The <code>View</code> will automatically refresh and request state from
 221      * <code>viewStateIterator</code> until the iteration is complete, or <code>View</code> has been stopped by invoking
 222      * {@link #stopStateIterators}.
 223      *
 224      * @param viewStateIterator the <code>ViewStateIterator</code> to iterate over.
 225      */
 226     void applyStateIterator(ViewStateIterator viewStateIterator);
 227
 228     /**
 229      * Returns true when <code>View</code> is actively iterating over an instance of <code>ViewStateIterator</code>.
 230      *
 231      * @return true when iterating over <code>ViewStateIterator</code>; false otherwise.
 232      */
 233     boolean hasStateIterator();
 234
 235     /**
 236      * Immediately stops all active iteration over <code>ViewStateIterator</code>.
 237      */
 238     void stopStateIterators();
 239 }