Rename frustum plane properties

docs/api-reference/viewport.md

@@ -122,7 +122,7 @@ Note:
 
 ##### `projectPosition`
 
-Projects latitude, longitude (and altitude) to coordinates in the WebMercator world.
+Projects latitude, longitude (and altitude) to coordinates in the [common space](/docs/shader-modules/project.md).
 
 Parameters:
 
@@ -135,7 +135,7 @@ Returns:
 
 ##### `unprojectPosition`
 
-Projects a coordinate from the WebMercator world to latitude, longitude and altitude.
+Projects a coordinate from the [common space](/docs/shader-modules/project.md) to latitude, longitude and altitude.
 
 Parameters:
 
@@ -148,12 +148,12 @@ Returns:
 
 ##### `getFrustumPlanes`
 
-Extract view frustum planes in common space. Each plane is defined by its normal `n` and distance from
-the origin `d` (such that point `x` is on the plane if `dot(n, x) === d`).
+Extract view frustum planes of the current camera. Each plane is defined by its normal `normal` and distance from
+the origin `distance` (such that point `x` is on the plane if `dot(normal, x) === distance`) in the [common space](/docs/shader-modules/project.md).
 
 Returns:
 
-* `{near: {n, d}, far: {n, d}, left: {n, d}, right: {n, d}, top: {n, d}, bottom: {n, d}}`
+* `{near: {normal, distance}, far: {normal, distance}, left: {normal, distance}, right: {normal, distance}, top: {normal, distance}, bottom: {normal, distance}}`
 
 
 ## Remarks

modules/core/src/utils/math-utils.js

@@ -55,17 +55,17 @@ export function getFrustumPlanes({aspect, near, far, fovyRadians, position, dire
     .scale(far * nearFarScale)
     .add(cameraPosition);
 
-  let n = cameraDirection.clone().negate();
-  let d = n.dot(nearCenter);
+  let normal = cameraDirection.clone().negate();
+  let distance = normal.dot(nearCenter);
 
   const planes = {
     near: {
-      d,
-      n
+      distance,
+      normal
     },
     far: {
-      d: cameraDirection.dot(farCenter),
-      n: cameraDirection.clone()
+      distance: cameraDirection.dot(farCenter),
+      normal: cameraDirection.clone()
     }
   };
 
@@ -74,36 +74,36 @@ export function getFrustumPlanes({aspect, near, far, fovyRadians, position, dire
     .add(nearCenter)
     .subtract(cameraPosition)
     .normalize();
-  n = new Vector3(cameraUp).cross(a);
-  d = cameraPosition.dot(n);
-  planes.right = {n, d};
+  normal = new Vector3(cameraUp).cross(a);
+  distance = cameraPosition.dot(normal);
+  planes.right = {normal, distance};
 
   a.copy(cameraRight)
     .scale(-nearWidth * 0.5)
     .add(nearCenter)
     .subtract(cameraPosition)
     .normalize();
-  n = new Vector3(a).cross(cameraUp);
-  d = cameraPosition.dot(n);
-  planes.left = {n, d};
+  normal = new Vector3(a).cross(cameraUp);
+  distance = cameraPosition.dot(normal);
+  planes.left = {normal, distance};
 
   a.copy(cameraUp)
     .scale(nearHeight * 0.5)
     .add(nearCenter)
     .subtract(cameraPosition)
     .normalize();
-  n = new Vector3(a).cross(cameraRight);
-  d = cameraPosition.dot(n);
-  planes.top = {n, d};
+  normal = new Vector3(a).cross(cameraRight);
+  distance = cameraPosition.dot(normal);
+  planes.top = {normal, distance};
 
   a.copy(cameraUp)
     .scale(-nearHeight * 0.5)
     .add(nearCenter)
     .subtract(cameraPosition)
     .normalize();
-  n = new Vector3(cameraRight).cross(a);
-  d = cameraPosition.dot(n);
-  planes.bottom = {n, d};
+  normal = new Vector3(cameraRight).cross(a);
+  distance = cameraPosition.dot(normal);
+  planes.bottom = {normal, distance};
 
   return planes;
 }

test/apps/frustum-cull/app.js

@@ -52,7 +52,7 @@ class Root extends Component {
     for (const dir in frustumPlanes) {
       const plane = frustumPlanes[dir];
 
-      if (testPosition.copy(commonPosition).dot(plane.n) > plane.d) {
+      if (testPosition.copy(commonPosition).dot(plane.normal) > plane.distance) {
         out = true;
         outDir = dir;
         break;

test/modules/core/utils/math-utils.spec.js

@@ -6,28 +6,28 @@ const ROOT2 = 0.7071;
 
 const EXPECTED_PLANES = {
   near: {
-    d: 0,
-    n: [0, 0, 1]
+    distance: 0,
+    normal: [0, 0, 1]
   },
   far: {
-    d: 9,
-    n: [0, 0, -1]
+    distance: 9,
+    normal: [0, 0, -1]
   },
   left: {
-    d: ROOT2,
-    n: [-ROOT2, 0, ROOT2]
+    distance: ROOT2,
+    normal: [-ROOT2, 0, ROOT2]
   },
   right: {
-    d: ROOT2,
-    n: [ROOT2, 0, ROOT2]
+    distance: ROOT2,
+    normal: [ROOT2, 0, ROOT2]
   },
   top: {
-    d: ROOT2,
-    n: [0, -ROOT2, ROOT2]
+    distance: ROOT2,
+    normal: [0, -ROOT2, ROOT2]
   },
   bottom: {
-    d: ROOT2,
-    n: [0, ROOT2, ROOT2]
+    distance: ROOT2,
+    normal: [0, ROOT2, ROOT2]
   }
 };
 
@@ -49,8 +49,8 @@ test('getFrustumPlanes#tests', t => {
   for (const plane in planes) {
     const calculated = planes[plane];
     const expected = EXPECTED_PLANES[plane];
-    t.ok(floatEquals(calculated.d, expected.d), 'd is equal');
-    t.ok(vecEquals(calculated.n, expected.n), 'n is equal');
+    t.ok(floatEquals(calculated.distance, expected.distance), 'distance is equal');
+    t.ok(vecEquals(calculated.normal, expected.normal), 'normal is equal');
   }
 
   t.end();

test/modules/core/viewports/viewport.spec.js

@@ -1,5 +1,5 @@
 import test from 'tape-catch';
-import {vecFinite} from '../../../utils/utils';
+import {vecNormalized} from '../../../utils/utils';
 import {Viewport} from 'deck.gl';
 import * as mat4 from 'gl-matrix/mat4';
 
@@ -102,21 +102,17 @@ test('Viewport.containsPixel', t => {
 });
 
 test('Viewport.getFrustumPlanes', t => {
-  const viewport = new Viewport(TEST_VIEWPORTS[0].mapState);
-  let planes = viewport.getFrustumPlanes();
-
-  for (const side in planes) {
-    const plane = planes[side];
-    t.ok(Number.isFinite(plane.d), 'd is defined');
-    t.ok(vecFinite(plane.n), 'n is defined');
-  }
-
-  planes = viewport.getFrustumPlanes();
+  for (const testCase of TEST_VIEWPORTS) {
+    const viewport = new Viewport(testCase.mapState);
+    const planes = viewport.getFrustumPlanes();
+
+    for (const side in planes) {
+      const plane = planes[side];
+      t.ok(Number.isFinite(plane.distance), 'distance is defined');
+      t.ok(vecNormalized(plane.normal), 'normal is defined');
+    }
 
-  for (const side in planes) {
-    const plane = planes[side];
-    t.ok(Number.isFinite(plane.d), 'cached d is defined');
-    t.ok(vecFinite(plane.n), 'cached n is defined');
+    t.is(viewport.getFrustumPlanes(), planes, 'frustum planes are cached');
   }
 
   t.end();

test/utils/utils.js

@@ -14,12 +14,15 @@ export function vecEquals(v1, v2) {
   return v1.length === v2.length;
 }
 
-export function vecFinite(v) {
+export function vecNormalized(v) {
   for (let i = 0; i < v.length; ++i) {
     if (!Number.isFinite(v[i])) {
       return false;
     }
   }
+  if (!floatEquals(v.len(), 1)) {
+    return false;
+  }
 
   return true;
 }