gov/nasa/worldwind/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;
   7
   8 import gov.nasa.worldwind.geom.*;
   9
  10 /**
  11  * The <code>View</code> provides an interface for communicating current viewing state and viewing state chages. For
  12  * example calling {@link #getLatitude} and {@link #setLatitude} will get and set the View latitude coordinate.
  13  * <p/>
  14  * <code>Views</code> contain both fixed state and computed state. The computed state is typically updated during a call
  15  * to the {@link #apply} method. Most accessor methods in this interface return the computed state that was set during
  16  * the most recent call to <code>apply()</code>.
  17  * <p/>
  18  * Implementations may impose constraints on any state variable. Following the above example, simple constraints on View
  19  * latitude coordinates may be queried by calling {@link #normalizeLatitude}. However additional environmental factors
  20  * may constrain View state variables in a manner that cannot be easliy predicted. For this reason, setting a state
  21  * variable does not guarantee the specified state change will occur. When exact knowledge of viewing state is required,
  22  * calling {@link #getLatitude}, immediately after a call to {@link #apply} will return the correct latitude
  23  * coordiante.
  24  * <p/>
  25  * <code>View</code> provides a coordinate transformation from <code>Model</code> coordinates to eye coordinates,
  26  * following the OpenGL convention of a left-handed coordinate system with origin at the eye point and looking down the
  27  * negative Z axis. <code>View</code> also provides a transformation from eye coordinates to screen coordinates,
  28  * following the OpenGL convention of an origin in the lower left hand screen corner.
  29  *
  30  * @author Paul Collins
  31  * @version $Id: View.java 2060 2007-06-14 22:41:20Z dcollins $
  32  * @see gov.nasa.worldwind.ViewStateIterator
  33  * @see gov.nasa.worldwind.geom.Frustum
  34  */
  35 public interface View extends WWObject
  36 {
  37     /**
  38      * Calculates and applies <code>View's</code> internal state to the graphics context in <code>DrawContext</code>.
  39      * All subsequently rendered objects use this new state. Upon return, the OpenGL graphics context reflects the
  40      * values of this view, as do any computed values of the view, such as the model-view matrix, projection matrix and
  41      * <code>Frustum</code>.
  42      *
  43      * @param dc the current World Wind drawing context on which <code>View's</code> state will apply.
  44      * @throws IllegalArgumentException if <code>dc</code> is null, or if the <code>Globe</code> or <code>GL</code>
  45      *                                  instances in <code>dc</code> are null.
  46      */
  47     void apply(DrawContext dc);
  48
  49     /**
  50      * Gets the 'model-view' matrix computed in <code>apply()</code>, which transforms model coordinates to eye
  51      * coordinates (where the eye is located at the origin, facing down the negative-z axis). This matrix is constructed
  52      * using the model space translation and orientation specific to each implementation of <code>View</code>.
  53      *
  54      * @return the current model-view matrix.
  55      */
  56     Matrix getModelViewMatrix();
  57
  58     /**
  59      * Gets the 'projection' matrix computed in <code>apply()</code>, which transforms eye coordinates to screen
  60      * coordinates. This matrix is constructed using the projection parameters specific to each implementation of
  61      * <code>View</code> (e.g. field-of-view). The {@link #getFrustum} method returns the geometry corresponding to this
  62      * matrix.
  63      *
  64      * @return the current projection matrix.
  65      */
  66     Matrix getProjectionMatrix();
  67
  68     /**
  69      * Gets a Rectangle representing the window bounds (x, y, width, height) of the viewport, computed in
  70      * <code>apply()</code>. Implementations of <code>View</code> will configure themselves to render in this viewport.
  71      *
  72      * @return the current window bounds of the viewport.
  73      */
  74     java.awt.Rectangle getViewport();
  75
  76     /**
  77      * Gets the viewing <code>Frustum</code> in eye coordinates, computed in <code>apply()</code>. The
  78      * <code>Frustum</code> is the portion of viewable space defined by three sets of parallel 'clipping' planes. The
  79      * method {@link #getFrustumInModelCoordinates} maintains the shape of this <code>Frustum</code>, but it has been
  80      * translated and aligned with the eye in model space.
  81      *
  82      * @return the current viewing frustum in eye coordinates.
  83      */
  84     Frustum getFrustum();
  85
  86     /**
  87      * Gets the viewing <code>Frustum</code> transformed to model coordinates. Model coordinate frustums are useful for
  88      * performing visibility tests against world geometry.
  89      *
  90      * @return the current viewing frustum in model coordinates.
  91      */
  92     Frustum getFrustumInModelCoordinates();
  93
  94     /**
  95      * Gets the horizontal field-of-view angle (the angle of visibility) associated with this <code>View</code>, or null
  96      * if the <code>View</code> implementation does not support a field-of-view.
  97      *
  98      * @return horizontal field-of-view angle, or null if none exists.
  99      */
 100     Angle getFieldOfView();
 101
 102     /**
 103      * Sets the horiziontal field-of-view angle (the angle of visibillity) associated with this <code>View</code>. This
 104      * call may be ignored by implementations that do not support a field-of-view.
 105      *
 106      * @param newFov the new horizontal field-of-view angle.
 107      * @throws IllegalArgumentException if <code>newFov</code> is null.
 108      */
 109     void setFieldOfView(Angle newFov);
 110
 111     /**
 112      * Defines and applies a new model-view matrix in which the world origin is located at <code>referenceCenter</code>.
 113      * Geometry rendered after a call to <code>pushReferenceCenter</code> should be transformed with respect to
 114      * <code>referenceCenter</code>, rather than the canonical origin (0, 0, 0). Calls to
 115      * <code>pushReferenceCenter</code> must be followed by {@link #popReferenceCenter} after rendering is complete.
 116      * Note that calls to {@link #getModelViewMatrix} will not return reference-center model-view matrix, but the
 117      * original matrix.
 118      *
 119      * @param dc              the current World Wind drawing context on which new model-view state will be applied.
 120      * @param referenceCenter the location to become the new world origin.
 121      * @return a new model-view matrix with origin is at <code>referenceCenter</code>, or null if this method failed.
 122      * @throws IllegalArgumentException if <code>referenceCenter</code> is null, if <code>dc</code> is null, or if the
 123      *                                  <code>Globe</code> or <code>GL</code> instances in <code>dc</code> are null.
 124      */
 125     Matrix pushReferenceCenter(DrawContext dc, Vec4 referenceCenter);
 126
 127     /**
 128      * Removes the model-view matrix on top of the matrix stack, and restores the original matrix.
 129      *
 130      * @param dc the current World Wind drawing context on which the original matrix will be restored.
 131      * @throws IllegalArgumentException if <code>dc</code> is null, or if the <code>Globe</code> or <code>GL</code>
 132      *                                  instances in <code>dc</code> are null.
 133      */
 134     void popReferenceCenter(DrawContext dc);
 135
 136     /**
 137      * Gets the <code>View</code> eye position in model coordinates.
 138      *
 139      * @return the eye position in model coordinates.
 140      */
 141     Vec4 getEyePoint();
 142
 143     /**
 144      * Gets the <code>View</code> y-axis orientation in model coordinates.
 145      *
 146      * @return the y-axis vector in model coordinates.
 147      */
 148     Vec4 getUpVector();
 149
 150     /**
 151      * Gets the <code>View</code> z-axis orientation in model coordinates.
 152      *
 153      * @return the z-axis vector in model coordinates.
 154      */
 155     Vec4 getForwardVector();
 156
 157     /**
 158      * Gets the <code>View</code> latitude position.
 159      *
 160      * @return the current latitude positon.
 161      */
 162     Angle getLatitude();
 163
 164     /**
 165      * Sets the <code>View</code> eye point to the new latitude coordinate.
 166      *
 167      * @param newLatitude the new latitude position.
 168      * @throws IllegalArgumentException if <code>newLatitude</code> is null.
 169      */
 170     void setLatitude(Angle newLatitude);
 171
 172     /**
 173      * Gets the <code>View</code> longitude position.
 174      *
 175      * @return the current longitude positon.
 176      */
 177     Angle getLongitude();
 178
 179     /**
 180      * Sets the <code>View</code> eye point to the new longitude coordinate.
 181      *
 182      * @param newLongitude the new longitude position.
 183      * @throws IllegalArgumentException if <code>newLongitude</code> is null.
 184      */
 185     void setLongitude(Angle newLongitude);
 186
 187     /**
 188      * Gets the <code>View</code> eye altitude above the analytical globe radius.
 189      *
 190      * @return the <code>View's</code> altitude above the globe radius.
 191      */
 192     double getAltitude();
 193
 194     /**
 195      * Sets the <code>View</code> eye point to the new altitude above the analytical globe radius.
 196      *
 197      * @param newAltitude the new eye altitude above the globe radius.
 198      */
 199     void setAltitude(double newAltitude);
 200
 201     /**
 202      * Sets the <code>View</code> eye point to the new (latitude, longitude) coordinate. This has the effect of calling
 203      * {@link #setLatitude} and {@link #setLongitude}.
 204      *
 205      * @param newLatLon the latitude and longitude coordinate of the eye point.
 206      */
 207     void setLatLon(LatLon newLatLon);
 208
 209 //    /**
 210 //     * Gets the geographic (latitude, longitude, elevation) coordinate of the <code>View's</code> eye point.
 211 //     *
 212 //     * @return the latitude and longitude coordinates of the eye point.
 213 //     */
 214 //    Position getLatLonAltitude();
 215
 216     /**
 217      * Sets the <code>View</code> eye point to the new (latitude, longitude, elevation) coordinate. This has the effect
 218      * of calling {@link #setLatitude}, {@link #setLongitude} and {@link #setAltitude}.
 219      *
 220      * @param newPosition the latitude, longitude and elevation coordinate of the eye point.
 221      */
 222     void setLatLonAltitude(Position newPosition);
 223
 224     /**
 225      * Gets the <code>View's</code> angle from true North.
 226      *
 227      * @return the angle from true North.
 228      */
 229     Angle getHeading();
 230
 231     /**
 232      * Sets the <code>View's</code> angle to true North.
 233      *
 234      * @param newHeading the new angle to true North.
 235      * @throws IllegalArgumentException if <code>newHeading</code> is null.
 236      */
 237     void setHeading(Angle newHeading);
 238
 239     /**
 240      * Gets the <code>View's</code> angle from the plane tangent to the surface.
 241      *
 242      * @return the angle from the surface tangent plane.
 243      */
 244     Angle getPitch();
 245
 246     /**
 247      * Sets the <code>View's</code> angle to the plane tangent to the surface.
 248      *
 249      * @param newPitch the new angle to the surface tangent plane.
 250      * @throws IllegalArgumentException if <code>newPitch</code> is null.
 251      */
 252     void setPitch(Angle newPitch);
 253
 254     /**
 255      * Gets the <code>View's</code> angle about its local z-axis.
 256      *
 257      * @return the angle about the local z-axis.
 258      */
 259     Angle getRoll();
 260
 261     /**
 262      * Sets the <code>View's</code> angle about its local z-axis.
 263      *
 264      * @param newRoll the new angle about the local z-axis.
 265      * @throws IllegalArgumentException if <code>newRoll</code> is null.
 266      */
 267     void setRoll(Angle newRoll);
 268
 269     /**
 270      * Gets the <code>View's</code> translation in its forward direction.
 271      *
 272      * @return translation along the forward direction.
 273      */
 274     double getZoom();
 275
 276     /**
 277      * Sets the <code>View's</code> translation in its forward direction.
 278      *
 279      * @param newZoom translation along the forward direction.
 280      */
 281     void setZoom(double newZoom);
 282
 283     /**
 284      * Normalizes latitude coordinates to values acceptable to this <code>View</code> implementation.
 285      *
 286      * @param latitude the latitude to normalize.
 287      * @return the (possibly) normalized latitude.
 288      */
 289     Angle normalizeLatitude(Angle latitude);
 290
 291     /**
 292      * Normalizes longitude coordinates to values acceptable to this <code>View</code> implementation.
 293      *
 294      * @param longitude the longitude to normalize.
 295      * @return the (possibly) normalized longitude.
 296      */
 297     Angle normalizeLongitude(Angle longitude);
 298
 299     /**
 300      * Normalizes altitude coordinates to values acceptable to this <code>View</code> implementation.
 301      *
 302      * @param altitude the altitude to normalize.
 303      * @return the (possibly) normalized altitude.
 304      */
 305     double normalizeAltitude(double altitude);
 306
 307     /**
 308      * Normalizes heading coordinates to values acceptable to this <code>View</code> implementation.
 309      *
 310      * @param heading the altitude to normalize.
 311      * @return the (possibly) normalized heading.
 312      */
 313     Angle normalizeHeading(Angle heading);
 314
 315     /**
 316      * Normalizes pitch coordinates to values acceptable to this <code>View</code> implementation.
 317      *
 318      * @param pitch the altitude to normalize.
 319      * @return the (possibly) normalized pitch.
 320      */
 321     Angle normalizePitch(Angle pitch);
 322
 323     /**
 324      * Normalizes roll coordinates to values acceptable to this <code>View</code> implementation.
 325      *
 326      * @param roll the altitude to normalize.
 327      * @return the (possibly) normalized roll.
 328      */
 329     Angle normalizeRoll(Angle roll);
 330
 331     /**
 332      * Normalizes zoom coordinates to values acceptable to this <code>View</code> implementation.
 333      *
 334      * @param zoom the altitude to normalize.
 335      * @return the (possibly) normalized zoom.
 336      */
 337     double normalizeZoom(double zoom);
 338
 339     /**
 340      * Iterates over <code>View</code> state changes in <code>ViewStateIterator</code> and applies them to the
 341      * <code>View</code>. The <code>View</code> will automatically refresh and request state from
 342      * <code>viewStateIterator</code> until the iteration is complete, or <code>View</code> has been stopped by invoking
 343      * {@link #stopIterating}.
 344      *
 345      * @param viewStateIterator the <code>ViewStateIterator</code> to iterate over.
 346      */
 347     void iterateOver(ViewStateIterator viewStateIterator);
 348
 349     /**
 350      * Returns true when <code>View</code> is actively iterating over an instance of <code>ViewStateIterator</code>.
 351      *
 352      * @return true when iterating over <code>ViewStateIterator</code>; false otherwise.
 353      */
 354     boolean isIterating();
 355
 356     /**
 357      * Immediately stops all active iteration over <code>ViewStateIterator</code>.
 358      */
 359     void stopIterating();
 360
 361     /**
 362      * Computes a line, in model coordinates, originating from the eye point, and passing throught the point contained
 363      * by (x, y) on the <code>View's</code> projection plane (or after projection into model space).
 364      *
 365      * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
 366      * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
 367      * @return a line beginning at the <code>View's</code> eye point and passing throught (x, y) transformed into model
 368      *         space.
 369      */
 370     Line computeRayFromScreenPoint(double x, double y);
 371
 372     /**
 373      * Computes the intersection of a line originating from the eye point (passing throught (x, y)) with the last
 374      * rendered <code>SectorGeometry</code>, or the last analytical <code>Globe</code> if no rendered geometry exists.
 375      *
 376      * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
 377      * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
 378      * @return the point on the surface in polar coordiantes.
 379      */
 380     Position computePositionFromScreenPoint(double x, double y);
 381
 382     /**
 383      * Computes the screen-aligned dimension (in meters) that a screen pixel would cover at a given distance (also in
 384      * meters). This computation assumes that pixels dimensions are square, and therefore returns a single dimension.
 385      *
 386      * @param distance the distance from the eye point, in eye coordinates, along the z-axis. This value must be
 387      *                 positive but is otherwise unbounded.
 388      * @return the dimension of a pixel (in meters) at the given distance.
 389      * @throws IllegalArgumentException if <code>distance</code> is negative.
 390      */
 391     double computePixelSizeAtDistance(double distance);
 392
 393     /**
 394      * Gets the distance from the <code>View's</code> eye point to the horizon point on the last rendered
 395      * <code>Globe</code>.
 396      *
 397      * @return the distance from the eye point to the horizon (in meters).
 398      */
 399     double computeHorizonDistance();
 400
 401     /**
 402      * Maps a <code>Point</code> in model (cartesian) coordinates to a <code>Point</code> in screen coordinates. The
 403      * returned x and y are relative to the lower left hand screen corner, while z is the screen depth-coordinate. If
 404      * the model point cannot be sucessfully mapped, this will return null.
 405      *
 406      * @param modelPoint the model coordinate <code>Point</code> to project.
 407      * @return the mapped screen coordinate <code>Point</code>.
 408      * @throws IllegalArgumentException if <code>modelPoint</code> is null.
 409      */
 410     Vec4 project(Vec4 modelPoint);
 411
 412     /**
 413      * Maps a <code>Point</code> in screen coordinates to a <code>Point</code> in model coordinates. The input x and y
 414      * are  relative to the lower left hand screen corner, while z is the screen depth-coordinate.  If the screen point
 415      * cannot be sucessfully mapped, this will return null.
 416      *
 417      * @param windowPoint the window coordinate <code>Point</code> to project.
 418      * @return the mapped screen coordinate <code>Point</code>.
 419      * @throws IllegalArgumentException if <code>windowPoint</code> is null.
 420      */
 421     Vec4 unProject(Vec4 windowPoint);
 422 }