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> interface provides basic methods for implementations to communicate state and state chages to
  12  * the caller. <code>Views</code> provide a coordinate transformation from the object coordinates of the model to eye
  13  * coordinates, which follow the OpenGL convention of a left-handed coordinate system with origin at the eye point and
  14  * looking down the negative-z axis.
  15  * <p/>
  16  * View implementations are free to constrain position and orientation, as well as supply any projection from eye to
  17  * clip coordinates they see fit. Therefore calls to {@link #setFieldOfView}, {@link #goToCoordinate}, {@link
  18  * #goToLatLon} or {@link #goToAltitude} are not guaranteed to produce the requested transformation. When exact
  19  * knowledge of these values in necessary, calling {@link #getFieldOfView}, {@link #getPosition} or {@link #getAltitude}
  20  * immediately after a call to {@link #apply} guarantees the value to be synchronized with data structures used for view
  21  * transformation (e.g. model-view and projection matrices).
  22  * <p/>
  23  * Views contain both fixed state and computed state. The computed state is typically updated during a call to the
  24  * {@link #apply} method. Most accessor methods in this interface return the computed state that was set during the most
  25  * recent call to <code>apply()</code>.
  26  *
  27  * @author Paul Collins
  28  * @version $Id: View.java 1795 2007-05-08 22:08:29Z dcollins $
  29  * @see gov.nasa.worldwind.geom.Frustum
  30  * @see gov.nasa.worldwind.geom.ViewFrustum
  31  */
  32 public interface View extends WWObject
  33 {
  34     /**
  35      * Calculates and applies <code>View's</code> internal state to the graphics context in <code>DrawContext</code>.
  36      * All subsequently rendered objects use this new state. Upon return, the OpenGL graphics context reflects the
  37      * values of this view, as do any computed values of the view, such as the model-view matrix and
  38      * <code>Frustum</code>.
  39      *
  40      * @param dc the current World Wind drawing context on which <code>View's</code> state will apply.
  41      * @throws IllegalArgumentException if <code>dc</code> is null, or if the <code>Globe</code> or <code>GL</code>
  42      *                                  contained in <code>dc</code> is null.
  43      */
  44     void apply(DrawContext dc);
  45
  46     /**
  47      * Returns the 'model-view' matrix computed in <code>apply()</code>, which transforms model coordinates to eye
  48      * coordinates (where the eye is located at the origin, facing down the negative-z axis). This matrix is constructed
  49      * using the model space translation and orientation specific to each implementation of <code>View</code>.
  50      *
  51      * @return the current model-view matrix.
  52      */
  53     Matrix4 getModelViewMatrix();
  54
  55     /**
  56      * Returns the 'projection' matrix computed in <code>apply()</code>, which transforms eye coordinates to homogeneous
  57      * clip coordinates (a box of dimension (2, 2, 2) centered at the origin). This matrix is constructed using the
  58      * projection parameters specific to each implementation of <code>View</code> (e.g. field-of-view, clipping plane
  59      * distances). The {@link #getFrustum} method returns the planes corresponding to this matrix.
  60      *
  61      * @return the current projection matrix.
  62      */
  63     Matrix4 getProjectionMatrix();
  64
  65     /**
  66      * Returns a Rectangle representing the window bounds (x, y, width, height) of the viewport, computed in
  67      * <code>apply()</code>. Implementations of <code>View</code> will configure themselves to render in this viewport.
  68      *
  69      * @return the current window bounds of the viewport, or null if none exists.
  70      */
  71     java.awt.Rectangle getViewport();
  72
  73     /**
  74      * Returns the viewing <code>Frustum</code> in eye coordinates, computed in <code>apply()</code>. The
  75      * <code>Frustum</code> is the portion of viewable space defined by three sets of parallel 'clipping' planes. The
  76      * method {@link #getFrustumInModelCoordinates} maintains the shape of this <code>Frustum</code>, but it has been
  77      * translated and aligned with the eye in model space.
  78      *
  79      * @return the current viewing frustum in eye coordinates.
  80      */
  81     Frustum getFrustum();
  82
  83     /**
  84      * Returns the viewing <code>Frustum</code> transformed to model coordinates. Model coordinate frustums are useful
  85      * for performing multiple intersection tests in model coordinates.
  86      *
  87      * @return the current viewing frustum in model coordinates.
  88      */
  89     Frustum getFrustumInModelCoordinates();
  90
  91     /**
  92      * Returns the horizontal field-of-view angle (the angle of visibility) associated with this <code>View</code>, or
  93      * null if the <code>View</code> implementation does not support a field-of-view.
  94      *
  95      * @return horizontal field-of-view angle, or null if none exists.
  96      */
  97     Angle getFieldOfView();
  98
  99     /**
 100      * Sets the horiziontal field-of-view angle (the angle of visibillity) associated with this <code>View</code>. This
 101      * call may be ignored by implementations that do not support a field-of-view.
 102      *
 103      * @param newFov the new horizontal field-of-view angle.
 104      * @throws IllegalArgumentException if <code>newFov</code> is null.
 105      */
 106     void setFieldOfView(Angle newFov);
 107
 108     /**
 109      * Generates a new coordinate system in which the <code>View</code> does not move, and model coordinates are reverse
 110      * transformed into eye coordinates. The origin for these coordinates will be <code>referenceCenter</code>,
 111      * therefore all objects drawn after a call to <code>pushReferenceCenter</code> should be with respect to this
 112      * <code>Point</code>, rather than the customary origin (0, 0, 0). This creates a new model-view matrix, which is
 113      * placed on the top of a matrix stack, and immediately applied to the current OpenGL context. In order to return to
 114      * the original coordinate space, callers should invoke {@link #popReferenceCenter} after rendering is complete.
 115      * Note that calls to {@link #getModelViewMatrix} will not return reference-center model-view matrix, but the
 116      * original matrix.
 117      *
 118      * @param dc              the current World Wind drawing context on which <code>View's</code> state will apply.
 119      * @param referenceCenter the <code>Point</code> to become the new model space origin.
 120      * @throws IllegalArgumentException if <code>referenceCenter</code> is null.
 121      */
 122     void pushReferenceCenter(DrawContext dc, Point referenceCenter);
 123
 124     /**
 125      * Removes the model-view matrix on top of the matrix stack, and restores the matrix now on top. This has the effect
 126      * of immediately replacing the current OpenGL model-view matrix with the matrix below the top. When the stack size
 127      * is one, therefore containing the original model-view matrix computed by <code>apply()</code>, this method will
 128      * throw an exception.
 129      *
 130      * @param dc the current World Wind drawing context on which <code>View's</code> state will apply.
 131      * @throws IllegalStateException if the the refernce matrix stack is empty.
 132      */
 133     void popReferenceCenter(DrawContext dc);
 134
 135     /**
 136      * Returns the eye position in model coordinates.
 137      *
 138      * @return the eye position in model coordinates.
 139      */
 140     Point getEyePoint();
 141
 142     /**
 143      * Returns the <code>View</code> y-axis orientation in model coordinates.
 144      *
 145      * @return the y-axis vector in model coordinates.
 146      */
 147     Point getUpVector();
 148
 149     /**
 150      * Returns the <code>View</code> z-axis orientation in model coordinates.
 151      *
 152      * @return the z-axis vector in model coordinates.
 153      */
 154     Point getForwardVector();
 155
 156     /**
 157      * Moves the <code>View</code> eye point to the new polar coordinate (latitude, longitude, elevation).
 158      *
 159      * @param newLatLon   the new latitude and longitude of the eye point.
 160      * @param newAltitude the new eye altitude (in meters) above the surface,
 161      * @throws IllegalArgumentException if <code>newLatlon</code> is null.
 162      */
 163     void goToCoordinate(LatLon newLatLon, double newAltitude);
 164
 165     /**
 166      * Returns the geographic (latitude, longitude, elevation) coordinate of the <code>View's</code> eye point. Latitude
 167      * and longitude represent the coordinate directly beneath (or above) the <code>View</code>, while elevation
 168      * represents the <code>View</code> altitude above the analytical <code>Globe</code> radius.
 169      *
 170      * @return the latitude and longitude coordinates of the eye point.
 171      */
 172     Position getPosition();
 173
 174     /**
 175      * Moves the <code>View</code> eye point to the new geographic (latitude, longitude) coordinate. Altitude is left
 176      * unchanged.
 177      *
 178      * @param newLatLon the new latitude and longitude of the eye point.
 179      * @throws IllegalArgumentException if <code>newLatlon</code> is null.
 180      */
 181     void goToLatLon(LatLon newLatLon);
 182
 183     /**
 184      * Returns the <code>View</code> eye altitude (in meters) above the last rendered <code>SectorGeometry</code>, or
 185      * the analytical <code>Globe</code>, depending on the implementation.
 186      *
 187      * @return the <code>View's</code> altitude (in meters) above the surface.
 188      */
 189     double getAltitude();
 190
 191     /**
 192      * Moves the <code>View</code> eye point to the new altitude (in meters) above the last rendered
 193      * <code>SectorGeometry</code>, or the analytical <code>Globe</code>, depending on the implementation.
 194      *
 195      * @param newAltitude the new eye altitude (in meters) above the surface,
 196      */
 197     void goToAltitude(double newAltitude);
 198
 199     /**
 200      * Returns the <code>View's</code> angle from true North.
 201      *
 202      * @return the angle from true North.
 203      */
 204     Angle getHeading();
 205
 206     /**
 207      * Sets the <code>View's</code> angle to true North.
 208      *
 209      * @param newHeading the new angle to true North.
 210      * @throws IllegalArgumentException if <code>newHeading</code> is null.
 211      */
 212     void setHeading(Angle newHeading);
 213
 214     /**
 215      * Returns the <code>View's</code> angle from the plane tangent to the surface.
 216      *
 217      * @return the angle from the surface tangent plane.
 218      */
 219     Angle getPitch();
 220
 221     /**
 222      * Sets the <code>View's</code> angle to the plane tangent to the surface.
 223      *
 224      * @param newPitch the new angle to the surface tangent plane.
 225      * @throws IllegalArgumentException if <code>newPitch</code> is null.
 226      */
 227     void setPitch(Angle newPitch);
 228
 229     /**
 230      * Returns a two-dimensional array containing the range of angles (inclusive) the <code>View</code> may limit
 231      * its pitch to, if pitch constraints are enabled.
 232      *
 233      * @return a two-dimensional array, with the minimum and maximum pitch angles.
 234      */
 235     Angle[] getPitchConstraints();
 236
 237     /**
 238      * Sets the range of angles (inclusive) the <code>View</code> may limit its pitch to, if pitch constraints are
 239      * enabled.
 240      *
 241      * @param newMinPitch the minimum pitch angle.
 242      * @param newMaxPitch the maximum pitch angle.
 243      */
 244     void setPitchConstraints(Angle newMinPitch, Angle newMaxPitch);
 245
 246     /**
 247      * Returns true when pitch constraints are enabled.
 248      *
 249      * @return true when pitch constraints are enabled.
 250      */
 251     boolean isEnablePitchConstraints();
 252
 253     /**
 254      * Enable or disable pitch constraints.
 255      *
 256      * @param enabled true when pitch constraints should be enabled, false otherwise.
 257      */
 258     void setEnablePitchConstraints(boolean enabled);
 259
 260     /**
 261      * Returns the <code>View's</code> angle about its local z-axis.
 262      *
 263      * @return the angle about the local z-axis.
 264      */
 265     Angle getRoll();
 266
 267     /**
 268      * Sets the <code>View's</code> angle about its local z-axis.
 269      *
 270      * @param newRoll the new angle about the local z-axis.
 271      * @throws IllegalArgumentException if <code>newRoll</code> is null.
 272      */
 273     void setRoll(Angle newRoll);
 274
 275     /**
 276      * Returns the <code>View's</code> translation in its forward direction.
 277      *
 278      * @return translation along the forward direction.
 279      */
 280     double getZoom();
 281
 282     /**
 283      * Sets the <code>View's</code> translation in its forward direction.
 284      *
 285      * @param newZoom translation along the forward direction.
 286      */
 287     void setZoom(double newZoom);
 288
 289     /**
 290      * Returns a two-dimensional array containing the range of values (inclusive) the <code>View</code> may limit
 291      * its zoom to, if zoom constraints are enabled.
 292      *
 293      * @return two-dimensional array, with the minimum and maximum zoom values.
 294      */
 295     double[] getZoomConstraints();
 296
 297     /**
 298      * Sets the range of values (inclusive) the <code>View</code> may limit its zoom to, if zoom constraints are
 299      * enabled.
 300      *
 301      * @param newMinZoom the minimum zoom value.
 302      * @param newMaxZoom the maximum zoom value.
 303      */
 304     void setZoomConstraints(double newMinZoom, double newMaxZoom);
 305
 306     /**
 307      * Returns true when zoom constraints are enabled.
 308      *
 309      * @return true when zoom constraints are enabled, false otherwise.
 310      */
 311     boolean isEnableZoomConstraints();
 312
 313     /**
 314      * Enable or disable zoom constraints.
 315      *
 316      * @param enabled trhe when zoom constraints should be enabled, false otherwise.
 317      */
 318     void setEnableZoomConstraints(boolean enabled);
 319
 320     /**
 321      * Computes a line, in model coordinates, originating from the eye point, and passing throught the point contained
 322      * by (x, y) on the <code>View's</code> projection plane (or after projection into model space).
 323      *
 324      * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
 325      * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
 326      * @return a line beginning at the <code>View's</code> eye point and passing throught (x, y) transformed into model
 327      *         space.
 328      */
 329     Line computeRayFromScreenPoint(double x, double y);
 330
 331     /**
 332      * Computes the intersection of a line originating from the eye point (passing throught (x, y)) with the last
 333      * rendered <code>SectorGeometry</code>, or the last analytical <code>Globe</code> if no rendered geometry exists.
 334      *
 335      * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
 336      * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
 337      * @return the point on the surface in polar coordiantes.
 338      */
 339     Position computePositionFromScreenPoint(double x, double y);
 340
 341     /**
 342      * Computes the screen-aligned dimension (in meters) that a screen pixel would cover at a given distance (also in
 343      * meters). This computation assumes that pixels dimensions are square, and therefore returns a single dimension.
 344      *
 345      * @param distance the distance from the eye point, in eye coordinates, along the z-axis. This value must be
 346      *                 positive but is otherwise unbounded.
 347      * @return the dimension of a pixel (in meters) at the given distance.
 348      * @throws IllegalArgumentException if <code>distance</code> is negative.
 349      */
 350     double computePixelSizeAtDistance(double distance);
 351
 352     /**
 353      * Returns the distance from the <code>View's</code> eye point to the horizon point on the last rendered
 354      * <code>Globe</code>.
 355      *
 356      * @return the distance from the eye point to the horizon (in meters).
 357      */
 358     double computeHorizonDistance();
 359
 360     /**
 361      * Maps a <code>Point</code> in model (cartesian) coordinates to a <code>Point</code> in screen coordinates. The
 362      * returned x and y are relative to the lower left hand screen corner, while z is the screen depth-coordinate. If
 363      * the model point cannot be sucessfully mapped, this will return null.
 364      *
 365      * @param modelPoint the model coordinate <code>Point</code> to project.
 366      * @return the mapped screen coordinate <code>Point</code>.
 367      * @throws IllegalArgumentException if <code>modelPoint</code> is null.
 368      */
 369     Point project(Point modelPoint);
 370
 371     /**
 372      * Maps a <code>Point</code> in screen coordinates to a <code>Point</code> in model coordinates. The input x and y
 373      * are  relative to the lower left hand screen corner, while z is the screen depth-coordinate.  If the screen point
 374      * cannot be sucessfully mapped, this will return null.
 375      *
 376      * @param windowPoint the window coordinate <code>Point</code> to project.
 377      * @return the mapped screen coordinate <code>Point</code>.
 378      * @throws IllegalArgumentException if <code>windowPoint</code> is null.
 379      */
 380     Point unProject(Point windowPoint);
 381 }