gov/nasa/worldwind/geom/Frustum.java

   1 /*
   2 Copyright (C) 2001, 2006 United States Government
   3 as represented by the Administrator of the
   4 National Aeronautics and Space Administration.
   5 All Rights Reserved.
   6 */
   7 package gov.nasa.worldwind.geom;
   8
   9 import gov.nasa.worldwind.util.Logging;
  10
  11 //todo: check javadoc accuracy,
  12
  13 /**
  14  * Instances of <code>Frustum</code> are immutable. </p>
  15  *
  16  * @author Tom Gaskins
  17  * @version $Id: Frustum.java 2471 2007-07-31 21:50:57Z tgaskins $
  18  */
  19 public class Frustum
  20 {
  21     private final Plane left;
  22     private final Plane right;
  23     private final Plane bottom;
  24     private final Plane top;
  25     private final Plane near;
  26     private final Plane far;
  27
  28     /**
  29      * Create a default frustum with six <code>Plane</code>s. This defines a box of dimension (2, 2, 2) centered at the
  30      * origin.
  31      */
  32     public Frustum()
  33     {
  34         this(
  35             new Plane(1, 0, 0, 1),  // Left
  36             new Plane(-1, 0, 0, 1),  // Right
  37             new Plane(0, 1, 0, 1),  // Bottom
  38             new Plane(0, -1, 0, 1),  // Top
  39             new Plane(0, 0, 1, 1),  // Near
  40             new Plane(0, 0, -1, 1)); // Far
  41     }
  42
  43     /**
  44      * Create a frustum from six <code>Plane</code>s, which define its boundaries. Does not except null arguments.
  45      *
  46      * @param near   the near plane
  47      * @param far    the far plane
  48      * @param left   the left side of the view frustum
  49      * @param right  the right side of the view frustm
  50      * @param top    the top of the view frustum
  51      * @param bottom the bottom of the view frustum
  52      * @throws IllegalArgumentException if any argument is null
  53      */
  54     public Frustum(Plane left, Plane right, Plane bottom, Plane top, Plane near, Plane far)
  55     {
  56         if (left == null || right == null || bottom == null || top == null || near == null || far == null)
  57         {
  58             String message = Logging.getMessage("nullValue.PlaneIsNull");
  59             Logging.logger().severe(message);
  60             throw new IllegalArgumentException(message);
  61         }
  62         this.left = left;
  63         this.right = right;
  64         this.bottom = bottom;
  65         this.top = top;
  66         this.near = near;
  67         this.far = far;
  68     }
  69
  70     public boolean equals(Object obj)
  71     {
  72         if (this == obj)
  73             return true;
  74         if (obj == null || getClass() != obj.getClass())
  75             return false;
  76
  77         Frustum that = (Frustum) obj;
  78         return this.left.equals(that.left)
  79             && this.right.equals(that.right)
  80             && this.bottom.equals(that.bottom)
  81             && this.top.equals(that.top)
  82             && this.near.equals(that.near)
  83             && this.far.equals(that.far);
  84     }
  85
  86     public final Plane getLeft()
  87     {
  88         return this.left;
  89     }
  90
  91     public final Plane getRight()
  92     {
  93         return this.right;
  94     }
  95
  96     public final Plane getBottom()
  97     {
  98         return this.bottom;
  99     }
 100
 101     public final Plane getTop()
 102     {
 103         return this.top;
 104     }
 105
 106     public final Plane getNear()
 107     {
 108         return this.near;
 109     }
 110
 111     public final Plane getFar()
 112     {
 113         return this.far;
 114     }
 115
 116     public int hashCode()
 117     {
 118         int result;
 119         result = this.left.hashCode();
 120         result = 31 * result + this.right.hashCode();
 121         result = 19 * result + this.bottom.hashCode();
 122         result = 23 * result + this.top.hashCode();
 123         result = 17 * result + this.near.hashCode();
 124         result = 19 * result + this.far.hashCode();
 125
 126         return result;
 127     }
 128
 129     public String toString()
 130     {
 131         StringBuilder sb = new StringBuilder();
 132         sb.append("(");
 133         sb.append("left=").append(this.near);
 134         sb.append(", right=").append(this.near);
 135         sb.append(", bottom=").append(this.near);
 136         sb.append(", top=").append(this.near);
 137         sb.append(", near=").append(this.near);
 138         sb.append(", far=").append(this.near);
 139         sb.append(")");
 140         return sb.toString();
 141     }
 142
 143     // ============== Factory Functions ======================= //
 144     // ============== Factory Functions ======================= //
 145     // ============== Factory Functions ======================= //
 146
 147     public static Frustum fromProjectionMatrix(Matrix projectionMatrix)
 148     {
 149         //noinspection UnnecessaryLocalVariable
 150         Matrix m = projectionMatrix;
 151         if (m == null)
 152         {
 153             String message = Logging.getMessage("nullValue.MatrixIsNull");
 154             Logging.logger().severe(message);
 155             throw new IllegalArgumentException(message);
 156         }
 157
 158         // Extract the left clipping plane from the projectionMatrix-matrix.
 159         double leftMag = Math.sqrt((m.m41 + m.m11) * (m.m41 + m.m11) + (m.m42 + m.m12) * (m.m42 + m.m12)
 160             + (m.m43 + m.m13) * (m.m43 + m.m13));
 161         Plane leftPlane = new Plane((m.m41 + m.m11) / leftMag, (m.m42 + m.m12) / leftMag, (m.m43 + m.m13) / leftMag,
 162             m.m44 + m.m14);
 163         // Extract the right clipping plane from the projectionMatrix-matrix.
 164         double rightMag = Math.sqrt((m.m41 - m.m11) * (m.m41 - m.m11) + (m.m42 - m.m12) * (m.m42 - m.m12)
 165             + (m.m43 - m.m13) * (m.m43 - m.m13));
 166         Plane rightPlane = new Plane((m.m41 - m.m11) / rightMag, (m.m42 - m.m12) / rightMag, (m.m43 - m.m13) / rightMag,
 167             m.m44 - m.m14);
 168         // Extract the bottom clipping plane from the projectionMatrix-matrix.
 169         double bottomMag = Math.sqrt((m.m41 + m.m21) * (m.m41 + m.m21) + (m.m42 + m.m22) * (m.m42 + m.m22)
 170             + (m.m43 + m.m23) * (m.m43 + m.m23));
 171         Plane bottomPlane = new Plane((m.m41 + m.m21) / bottomMag, (m.m42 + m.m22) / bottomMag,
 172             (m.m43 + m.m23) / bottomMag,
 173             m.m44 + m.m24);
 174         // Extract the top clipping plane from the projectionMatrix-matrix.
 175         double topMag = Math.sqrt((m.m41 - m.m21) * (m.m41 - m.m21) + (m.m42 - m.m22) * (m.m42 - m.m22)
 176             + (m.m43 - m.m23) * (m.m43 - m.m23));
 177         Plane topPlane = new Plane((m.m41 - m.m21) / topMag, (m.m42 - m.m22) / topMag, (m.m43 - m.m23) / topMag,
 178             m.m44 - m.m24);
 179         // Extract the near clipping plane from the projectionMatrix-matrix.
 180         double nearMag = Math.sqrt((m.m41 + m.m31) * (m.m41 + m.m31) + (m.m42 + m.m32) * (m.m42 + m.m32)
 181             + (m.m43 + m.m33) * (m.m43 + m.m33));
 182         Plane nearPlane = new Plane((m.m41 + m.m31) / nearMag, (m.m42 + m.m32) / nearMag, (m.m43 + m.m33) / nearMag,
 183             m.m44 + m.m34);
 184         // Extract the far clipping plane from the projectionMatrix-matrix.
 185         double farMag = Math.sqrt((m.m41 - m.m31) * (m.m41 - m.m31) + (m.m42 - m.m32) * (m.m42 - m.m32)
 186             + (m.m43 - m.m33) * (m.m43 - m.m33));
 187         Plane farPlane = new Plane((m.m41 - m.m31) / farMag, (m.m42 - m.m32) / farMag, (m.m43 - m.m33) / farMag,
 188             m.m44 - m.m34);
 189         return new Frustum(leftPlane, rightPlane, bottomPlane, topPlane, nearPlane, farPlane);
 190     }
 191
 192     /**
 193      * Creates a <code>Frustum</code> from a horizontal field-of-view, viewport aspect ratio and distance to near and
 194      * far depth clipping planes. The near plane must be closer than the far plane, and both planes must be a positive
 195      * distance away.
 196      *
 197      * @param horizontalFieldOfView horizontal field-of-view angle in the range (0, 180)
 198      * @param viewportWidth         the width of the viewport in screen pixels
 199      * @param viewportHeight        the height of the viewport in screen pixels
 200      * @param near                  distance to the near depth clipping plane
 201      * @param far                   distance to far depth clipping plane
 202      * @throws IllegalArgumentException if fov is not in the range (0, 180), if either near or far are negative, or near
 203      *                                  is greater than or equal to far
 204      */
 205     public static Frustum fromPerspective(Angle horizontalFieldOfView, int viewportWidth, int viewportHeight,
 206         double near, double far)
 207     {
 208         if (horizontalFieldOfView == null)
 209         {
 210             String message = Logging.getMessage("Geom.ViewFrustum.FieldOfViewIsNull");
 211             Logging.logger().fine(message);
 212             throw new IllegalArgumentException(message);
 213         }
 214         double fov = horizontalFieldOfView.getDegrees();
 215         double farMinusNear = far - near;
 216         String message = null;
 217         if (fov <= 0 || fov > 180)
 218             message = Logging.getMessage("Geom.ViewFrustum.FieldOfViewOutOfRange", fov);
 219         if (near <= 0 || farMinusNear <= 0)
 220             message = Logging.getMessage("Geom.ViewFrusutm.ClippingDistanceOutOfRange");
 221         if (message != null)
 222         {
 223             Logging.logger().severe(message);
 224             throw new IllegalArgumentException(message);
 225         }
 226
 227         double focalLength = 1d / horizontalFieldOfView.tanHalfAngle();
 228         double aspect = viewportHeight / (double) viewportWidth;
 229         double lrLen = Math.sqrt(focalLength * focalLength + 1);
 230         double btLen = Math.sqrt(focalLength * focalLength + aspect * aspect);
 231         Plane leftPlane = new Plane(focalLength / lrLen, 0d, 0d - 1d / lrLen, 0);
 232         Plane rightPlane = new Plane(0d - focalLength / lrLen, 0d, 0d - 1d / lrLen, 0d);
 233         Plane bottomPlane = new Plane(0d, focalLength / btLen, 0d - aspect / btLen, 0d);
 234         Plane topPlane = new Plane(0d, 0d - focalLength / btLen, 0d - aspect / btLen, 0d);
 235         Plane nearPlane = new Plane(0d, 0d, 0d - 1d, 0d - near);
 236         Plane farPlane = new Plane(0d, 0d, 1d, far);
 237         return new Frustum(leftPlane, rightPlane, bottomPlane, topPlane, nearPlane, farPlane);
 238     }
 239
 240     /**
 241      * Creates a <code>Frustum</code> from three sets of parallel clipping planes (a parallel projectionMatrix). In this
 242      * case, the near and far depth clipping planes may be a negative distance away.
 243      *
 244      * @param near   distance to the near depth clipping plane
 245      * @param far    distance to far depth clipping plane
 246      * @param width  horizontal dimension of the near clipping plane
 247      * @param height vertical dimension of the near clipping plane
 248      * @throws IllegalArgumentException if the difference of any plane set (lright - left, top - bottom, far - near) is
 249      *                                  less than or equal to zero.
 250      */
 251     public static Frustum fromPerspective(double width, double height, double near, double far)
 252     {
 253         double farMinusNear = far - near;
 254         if (farMinusNear <= 0.0 || width <= 0.0 || height <= 0.0)
 255         {
 256             String message = Logging.getMessage("Geom.ViewFrusutm.ClippingDistanceOutOfRange");
 257             Logging.logger().fine(message);
 258             throw new IllegalArgumentException(message);
 259         }
 260
 261         double width_over_2 = width / 2.0;
 262         double height_over_2 = height / 2.0;
 263         Plane leftPlane = new Plane(1.0, 0.0, 0.0, width_over_2);
 264         Plane rightPlane = new Plane(-1.0, 0.0, 0.0, width_over_2);
 265         Plane bottomPlane = new Plane(0.0, 1.0, 0.0, height_over_2);
 266         Plane topPlane = new Plane(0.0, -1.0, 0.0, height_over_2);
 267         Plane nearPlane = new Plane(0.0, 0.0, -1.0, (near < 0.0) ? near : -near);
 268         Plane farPlane = new Plane(0.0, 0.0, 1.0, (far < 0.0) ? -far : far);
 269         return new Frustum(leftPlane, rightPlane, bottomPlane, topPlane, nearPlane, farPlane);
 270     }
 271
 272     // ============== Intersection Functions ======================= //
 273     // ============== Intersection Functions ======================= //
 274     // ============== Intersection Functions ======================= //
 275
 276     /**
 277      * @param extent
 278      * @return
 279      * @throws IllegalArgumentException if <code>extent</code> is null
 280      */
 281     public final boolean intersects(Extent extent)
 282     {
 283         if (extent == null)
 284         {
 285             String msg = Logging.getMessage("nullValue.ExtentIsNull");
 286             Logging.logger().fine(msg);
 287             throw new IllegalArgumentException(msg);
 288         }
 289
 290         // See if the extent's bounding sphere is within or intersects the frustum.
 291         Vec4 c = extent.getCenter();
 292         double nr = -extent.getRadius();
 293
 294         if (this.far.dot(c) <= nr)
 295             return false;
 296         if (this.left.dot(c) <= nr)
 297             return false;
 298         if (this.right.dot(c) <= nr)
 299             return false;
 300         if (this.top.dot(c) <= nr)
 301             return false;
 302         if (this.bottom.dot(c) <= nr)
 303             return false;
 304         //noinspection RedundantIfStatement
 305         if (this.near.dot(c) <= nr)
 306             return false;
 307
 308         return true;
 309     }
 310
 311     /**
 312      * @param point
 313      * @return
 314      * @throws IllegalArgumentException if <code>point</code> is null
 315      */
 316     public final boolean contains(Vec4 point)
 317     {
 318         if (point == null)
 319         {
 320             String msg = Logging.getMessage("nullValue.PointIsNull");
 321             Logging.logger().fine(msg);
 322             throw new IllegalArgumentException(msg);
 323         }
 324
 325         if (this.far.dot(point) < 0)
 326             return false;
 327         if (this.left.dot(point) < 0)
 328             return false;
 329         if (this.right.dot(point) < 0)
 330             return false;
 331         if (this.top.dot(point) < 0)
 332             return false;
 333         if (this.bottom.dot(point) < 0)
 334             return false;
 335         //noinspection RedundantIfStatement
 336         if (this.near.dot(point) < 0)
 337             return false;
 338
 339         return true;
 340     }
 341
 342     // ============== Geometric Functions ======================= //
 343     // ============== Geometric Functions ======================= //
 344     // ============== Geometric Functions ======================= //
 345
 346     /**
 347      * @param matrix
 348      * @return
 349      * @throws IllegalArgumentException if <code>matrix</code> is null
 350      */
 351     public Frustum transformBy(Matrix matrix)
 352     {
 353         ensureNonNull(matrix);
 354         Plane left = new Plane(this.left.getVector().transformBy4(matrix));
 355         Plane right = new Plane(this.right.getVector().transformBy4(matrix));
 356         Plane bottom = new Plane(this.bottom.getVector().transformBy4(matrix));
 357         Plane top = new Plane(this.top.getVector().transformBy4(matrix));
 358         Plane near = new Plane(this.near.getVector().transformBy4(matrix));
 359         Plane far = new Plane(this.far.getVector().transformBy4(matrix));
 360         return new Frustum(left, right, bottom, top, near, far);
 361     }
 362
 363     // ============== Helper Functions ======================= //
 364     // ============== Helper Functions ======================= //
 365     // ============== Helper Functions ======================= //
 366
 367     private static void ensureNonNull(Matrix matrix)
 368     {
 369         if (matrix == null)
 370         {
 371             String msg = Logging.getMessage("nullValue.MatrixIsNull");
 372             Logging.logger().fine(msg);
 373             throw new IllegalArgumentException(msg);
 374         }
 375     }
 376 }