Merge pull request #1791 from AnalyticalGraphicsInc/requireResultCart…

…esian Require result parameter: Cartesian2, Cartesian3, Cartesian4
CesiumGS · Jun 11, 2014 · 94cd80c · 94cd80c
2 parents 80e16dc + f08a1c8
commit 94cd80c
Show file tree

Hide file tree

Showing 86 changed files with 1,634 additions and 1,494 deletions.
diff --git a/Apps/Sandcastle/gallery/Terrain.html b/Apps/Sandcastle/gallery/Terrain.html
@@ -47,12 +47,12 @@
 
             if (scene.mode === Cesium.SceneMode.SCENE3D) {
                 eye = new Cesium.Cartesian3(294572.0645397696, 5637826.573008351, 2978624.6868285);
-                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(0.9028130862217908, -0.42449297750082904, -0.06880583840911567));
+                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(0.9028130862217908, -0.42449297750082904, -0.06880583840911567), new Cesium.Cartesian3());
                 up = new Cesium.Cartesian3(0.40668971896562117, 0.790807045510862, 0.45741413322152297);
                 scene.camera.lookAt(eye, target, up);
             } else if (scene.mode === Cesium.SceneMode.COLUMBUS_VIEW) {
                 eye = new Cesium.Cartesian3(9684590.891310014, 3114799.076252769, 9849.375792522824);
-                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(-0.8929328433855669, -0.00005779973945286486, -0.45018988645076763));
+                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(-0.8929328433855669, -0.00005779973945286486, -0.45018988645076763), new Cesium.Cartesian3());
                 up = new Cesium.Cartesian3(-0.4501898855076042, -0.0000291369789812141, 0.8929328452557279);
                 scene.camera.lookAt(eye, target, up);
             } else {
@@ -65,12 +65,12 @@
 
             if (scene.mode === Cesium.SceneMode.SCENE3D) {
                 eye = new Cesium.Cartesian3(-2496304.1498512086, -4391818.97382059, 3884176.4503971986);
-                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(0.9279518715011381, -0.29488412129953234, -0.22792252890604328));
+                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(0.9279518715011381, -0.29488412129953234, -0.22792252890604328), new Cesium.Cartesian3());
                 up = new Cesium.Cartesian3(-0.11836693744723503, -0.8130611584421428, 0.5700182635106171);
                 scene.camera.lookAt(eye, target, up);
             } else if (scene.mode === Cesium.SceneMode.COLUMBUS_VIEW) {
                 eye = new Cesium.Cartesian3(-13314946.646404704, 4200941.442507448, 2468.225945515426);
-                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(0.9624895834866811, 0.04124314776883213, -0.26816562874787864));
+                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(0.9624895834866811, 0.04124314776883213, -0.26816562874787864), new Cesium.Cartesian3());
                 up = new Cesium.Cartesian3(0.2679197697914868, 0.011480478929947842, 0.9633728227203466);
                 scene.camera.lookAt(eye, target, up);
             } else {
@@ -83,12 +83,12 @@
 
             if (scene.mode === Cesium.SceneMode.SCENE3D) {
                 eye = new Cesium.Cartesian3(-2674718.9291375633, -4332137.224608461, 3888180.6614196445);
-                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(-0.40034097132786534, 0.9155843741828319, 0.03784653786617176));
+                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(-0.40034097132786534, 0.9155843741828319, 0.03784653786617176), new Cesium.Cartesian3());
                 up = new Cesium.Cartesian3(-0.6502679490649945, -0.3129458646313862, 0.6922546353438556);
                 scene.camera.lookAt(eye, target, up);
             } else if (scene.mode === Cesium.SceneMode.COLUMBUS_VIEW) {
                 eye = new Cesium.Cartesian3(-13562569.113918452, 4176598.9965795614, 37656.37201701476);
-                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(-0.8108519561707095, 0.4023795334200999, -0.42498213639958615));
+                target = Cesium.Cartesian3.add(eye, new Cesium.Cartesian3(-0.8108519561707095, 0.4023795334200999, -0.42498213639958615), new Cesium.Cartesian3());
                 up = new Cesium.Cartesian3(-0.3806859699462094, 0.18891270085627615, 0.905201736488051);
                 scene.camera.lookAt(eye, target, up);
             } else {

diff --git a/CHANGES.md b/CHANGES.md
@@ -27,6 +27,7 @@ Beta Releases
    * CZML property references now use a `#` symbol to separate identifier from property path. `objectId.position` should now be `objectId#position`. 
    * `CesiumWidget.showErrorPanel` now takes a `message` parameter in between the previous `title` and `error` parameters.
    * `Event.removeEventListener` no longer throws `DeveloperError` if the `listener` does not exist; it now returns `false`.
+   * All `Cartesain2`, `Cartesian3` and `Cartesian4` functions that take a `result` parameter now require the parameter (except for functions starting with `from`).
 * `DynamicObject.id` can now include period characters.
 * `ReferenceProperty` can now handle sub-properties, for example, `myObject#billboard.scale`.
 * Added `Cesium.VERSION` to the combined `Cesium.js` file.

diff --git a/Source/Core/AxisAlignedBoundingBox.js b/Source/Core/AxisAlignedBoundingBox.js
@@ -42,7 +42,7 @@ define([
 
         //If center was not defined, compute it.
         if (!defined(center)) {
-            center = Cartesian3.add(this.minimum, this.maximum);
+            center = Cartesian3.add(this.minimum, this.maximum, new Cartesian3());
             Cartesian3.multiplyByScalar(center, 0.5, center);
         } else {
             center = Cartesian3.clone(center);

diff --git a/Source/Core/BoxGeometry.js b/Source/Core/BoxGeometry.js
@@ -101,8 +101,8 @@ define([
         }
         //>>includeEnd('debug');
 
-        var corner = Cartesian3.multiplyByScalar(dimensions, 0.5);
-        var min = Cartesian3.negate(corner);
+        var corner = Cartesian3.multiplyByScalar(dimensions, 0.5, new Cartesian3());
+        var min = Cartesian3.negate(corner, new Cartesian3());
         var max = corner;
 
         var newOptions = {

diff --git a/Source/Core/BoxOutlineGeometry.js b/Source/Core/BoxOutlineGeometry.js
@@ -92,8 +92,8 @@ define([
         }
         //>>includeEnd('debug');
 
-        var corner = Cartesian3.multiplyByScalar(dimensions, 0.5);
-        var min = Cartesian3.negate(corner);
+        var corner = Cartesian3.multiplyByScalar(dimensions, 0.5, new Cartesian3());
+        var min = Cartesian3.negate(corner, new Cartesian3());
         var max = corner;
 
         var newOptions = {

diff --git a/Source/Core/Cartesian2.js b/Source/Core/Cartesian2.js
@@ -70,7 +70,6 @@ define([
         if (!defined(cartesian)) {
             return undefined;
         }
-
         if (!defined(result)) {
             return new Cartesian2(cartesian.x, cartesian.y);
         }
@@ -120,7 +119,6 @@ define([
         if (!defined(value)) {
             throw new DeveloperError('value is required');
         }
-
         if (!defined(array)) {
             throw new DeveloperError('array is required');
         }
@@ -213,7 +211,7 @@ define([
      *
      * @param {Cartesian2} first A cartesian to compare.
      * @param {Cartesian2} second A cartesian to compare.
-     * @param {Cartesian2} [result] The object into which to store the result.
+     * @param {Cartesian2} result The object into which to store the result.
      * @returns {Cartesian2} A cartesian with the minimum components.
      */
     Cartesian2.getMinimumByComponent = function(first, second, result) {
@@ -224,11 +222,11 @@ define([
         if (!defined(second)) {
             throw new DeveloperError('second is required.');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            result = new Cartesian2();
+            throw new DeveloperError('result is required.');
         }
+        //>>includeEnd('debug');
+
 
         result.x = Math.min(first.x, second.x);
         result.y = Math.min(first.y, second.y);
@@ -241,7 +239,7 @@ define([
      *
      * @param {Cartesian2} first A cartesian to compare.
      * @param {Cartesian2} second A cartesian to compare.
-     * @param {Cartesian2} [result] The object into which to store the result.
+     * @param {Cartesian2} result The object into which to store the result.
      * @returns {Cartesian2} A cartesian with the maximum components.
      */
     Cartesian2.getMaximumByComponent = function(first, second, result) {
@@ -252,11 +250,10 @@ define([
         if (!defined(second)) {
             throw new DeveloperError('second is required.');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            result = new Cartesian2();
+            throw new DeveloperError('result is required.');
         }
+        //>>includeEnd('debug');
 
         result.x = Math.max(first.x, second.x);
         result.y = Math.max(first.y, second.y);
@@ -317,20 +314,21 @@ define([
      * Computes the normalized form of the supplied Cartesian.
      *
      * @param {Cartesian2} cartesian The Cartesian to be normalized.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.normalize = function(cartesian, result) {
         //>>includeStart('debug', pragmas.debug);
         if (!defined(cartesian)) {
             throw new DeveloperError('cartesian is required');
         }
+        if (!defined(result)) {
+            throw new DeveloperError('result is required');
+        }
         //>>includeEnd('debug');
 
         var magnitude = Cartesian2.magnitude(cartesian);
-        if (!defined(result)) {
-            return new Cartesian2(cartesian.x / magnitude, cartesian.y / magnitude);
-        }
+
         result.x = cartesian.x / magnitude;
         result.y = cartesian.y / magnitude;
         return result;
@@ -361,8 +359,8 @@ define([
      *
      * @param {Cartesian2} left The first Cartesian.
      * @param {Cartesian2} right The second Cartesian.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.multiplyComponents = function(left, right, result) {
         //>>includeStart('debug', pragmas.debug);
@@ -372,11 +370,11 @@ define([
         if (!defined(right)) {
             throw new DeveloperError('right is required');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            return new Cartesian2(left.x * right.x, left.y * right.y);
+            throw new DeveloperError('result is required');
         }
+        //>>includeEnd('debug');
+
         result.x = left.x * right.x;
         result.y = left.y * right.y;
         return result;
@@ -387,8 +385,8 @@ define([
      *
      * @param {Cartesian2} left The first Cartesian.
      * @param {Cartesian2} right The second Cartesian.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.add = function(left, right, result) {
         //>>includeStart('debug', pragmas.debug);
@@ -398,11 +396,11 @@ define([
         if (!defined(right)) {
             throw new DeveloperError('right is required');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            return new Cartesian2(left.x + right.x, left.y + right.y);
+            throw new DeveloperError('result is required');
         }
+        //>>includeEnd('debug');
+
         result.x = left.x + right.x;
         result.y = left.y + right.y;
         return result;
@@ -413,8 +411,8 @@ define([
      *
      * @param {Cartesian2} left The first Cartesian.
      * @param {Cartesian2} right The second Cartesian.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.subtract = function(left, right, result) {
         //>>includeStart('debug', pragmas.debug);
@@ -424,11 +422,11 @@ define([
         if (!defined(right)) {
             throw new DeveloperError('right is required');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            return new Cartesian2(left.x - right.x, left.y - right.y);
+            throw new DeveloperError('result is required');
         }
+        //>>includeEnd('debug');
+
         result.x = left.x - right.x;
         result.y = left.y - right.y;
         return result;
@@ -439,8 +437,8 @@ define([
      *
      * @param {Cartesian2} cartesian The Cartesian to be scaled.
      * @param {Number} scalar The scalar to multiply with.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.multiplyByScalar = function(cartesian, scalar, result) {
         //>>includeStart('debug', pragmas.debug);
@@ -450,11 +448,11 @@ define([
         if (typeof scalar !== 'number') {
             throw new DeveloperError('scalar is required and must be a number.');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            return new Cartesian2(cartesian.x * scalar, cartesian.y * scalar);
+            throw new DeveloperError('result is required');
         }
+        //>>includeEnd('debug');
+
         result.x = cartesian.x * scalar;
         result.y = cartesian.y * scalar;
         return result;
@@ -465,8 +463,8 @@ define([
      *
      * @param {Cartesian2} cartesian The Cartesian to be divided.
      * @param {Number} scalar The scalar to divide by.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.divideByScalar = function(cartesian, scalar, result) {
         //>>includeStart('debug', pragmas.debug);
@@ -476,11 +474,11 @@ define([
         if (typeof scalar !== 'number') {
             throw new DeveloperError('scalar is required and must be a number.');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            return new Cartesian2(cartesian.x / scalar, cartesian.y / scalar);
+            throw new DeveloperError('result is required');
         }
+        //>>includeEnd('debug');
+
         result.x = cartesian.x / scalar;
         result.y = cartesian.y / scalar;
         return result;
@@ -490,19 +488,19 @@ define([
      * Negates the provided Cartesian.
      *
      * @param {Cartesian2} cartesian The Cartesian to be negated.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.negate = function(cartesian, result) {
         //>>includeStart('debug', pragmas.debug);
         if (!defined(cartesian)) {
             throw new DeveloperError('cartesian is required');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            return new Cartesian2(-cartesian.x, -cartesian.y);
+            throw new DeveloperError('result is required');
         }
+        //>>includeEnd('debug');
+
         result.x = -cartesian.x;
         result.y = -cartesian.y;
         return result;
@@ -512,19 +510,19 @@ define([
      * Computes the absolute value of the provided Cartesian.
      *
      * @param {Cartesian2} cartesian The Cartesian whose absolute value is to be computed.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.abs = function(cartesian, result) {
         //>>includeStart('debug', pragmas.debug);
         if (!defined(cartesian)) {
             throw new DeveloperError('cartesian is required');
         }
-        //>>includeEnd('debug');
-
         if (!defined(result)) {
-            return new Cartesian2(Math.abs(cartesian.x), Math.abs(cartesian.y));
+            throw new DeveloperError('result is required');
         }
+        //>>includeEnd('debug');
+
         result.x = Math.abs(cartesian.x);
         result.y = Math.abs(cartesian.y);
         return result;
@@ -537,8 +535,8 @@ define([
      * @param {Cartesian2} start The value corresponding to t at 0.0.
      * @param {Cartesian2} end The value corresponding to t at 1.0.
      * @param {Number} t The point along t at which to interpolate.
-     * @param {Cartesian2} [result] The object onto which to store the result.
-     * @returns {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     * @param {Cartesian2} result The object onto which to store the result.
+     * @returns {Cartesian2} The modified result parameter.
      */
     Cartesian2.lerp = function(start, end, t, result) {
         //>>includeStart('debug', pragmas.debug);
@@ -551,6 +549,9 @@ define([
         if (typeof t !== 'number') {
             throw new DeveloperError('t is required and must be a number.');
         }
+        if (!defined(result)) {
+            throw new DeveloperError('result is required.');
+        }
         //>>includeEnd('debug');
 
         Cartesian2.multiplyByScalar(end, t, lerpScratch);
@@ -587,14 +588,17 @@ define([
      * Returns the axis that is most orthogonal to the provided Cartesian.
      *
      * @param {Cartesian2} cartesian The Cartesian on which to find the most orthogonal axis.
-     * @param {Cartesian2} [result] The object onto which to store the result.
+     * @param {Cartesian2} result The object onto which to store the result.
      * @returns {Cartesian2} The most orthogonal axis.
      */
     Cartesian2.mostOrthogonalAxis = function(cartesian, result) {
         //>>includeStart('debug', pragmas.debug);
         if (!defined(cartesian)) {
             throw new DeveloperError('cartesian is required.');
         }
+        if (!defined(result)) {
+            throw new DeveloperError('result is required.');
+        }
         //>>includeEnd('debug');
 
         var f = Cartesian2.normalize(cartesian, mostOrthogonalAxisScratch);