Translucent Sorting

Apps/Sandcastle/gallery/Picking.html

@@ -94,6 +94,7 @@
 
     function cleanup() {
         widget.scene.getPrimitives().removeAll();
+        widget.scene.getPrimitives().sortPrimitives = true;
         handler = handler && handler.destroy();
     }
 
@@ -256,6 +257,8 @@
         addOverlappingPolygons(scene, ellipsoid);
 
         var primitives = scene.getPrimitives();
+        primitives.sortPrimitives = false;
+
         // Move the primitive that the mouse is over to the top.
         handler = new Cesium.ScreenSpaceEventHandler(scene.getCanvas());
             handler.setInputAction(function(movement) {
@@ -272,6 +275,8 @@
         addOverlappingPolygons(scene, ellipsoid);
 
         var primitives = scene.getPrimitives();
+        primitives.sortPrimitives = false;
+
         // Move the primitive that the mouse is over to the top.
         handler = new Cesium.ScreenSpaceEventHandler(scene.getCanvas());
             handler.setInputAction(function(movement) {

CHANGES.md

@@ -6,7 +6,8 @@ Beta Releases
 
 ### b25 - 2014-02-03
 * Breaking changes:
-  * The `Viewer` constructor argument `options.fullscreenElement` now matches the `FullscreenButton` default of `document.body`, it was previously the `Viewer` container itself. 
+  * The `Viewer` constructor argument `options.fullscreenElement` now matches the `FullscreenButton` default of `document.body`, it was previously the `Viewer` container itself.
+* Improved visual quality of overlapping tranlucent objects.
 
 ### b24 - 2014-01-06
 

Source/Core/BoundingSphere.js

@@ -733,6 +733,37 @@ define([
         return result;
     };
 
+    var distanceSquaredToScratch = new Cartesian3();
+
+    /**
+     * Computes the estimated distance squared from the closest point on a bounding sphere to a point.
+     * @memberof BoundingSphere
+     *
+     * @param {BoundingSphere} sphere The sphere.
+     * @param {Cartesian3} cartesian The point
+     * @returns {Number} The estimated distance squared from the bounding sphere to the point.
+     *
+     * @exception {DeveloperError} sphere is required.
+     * @exception {DeveloperError} cartesian is required.
+     *
+     * @example
+     * // Sort bounding spheres from back to front
+     * spheres.sort(function(a, b) {
+     *     return BoundingSphere.distanceSquaredTo(b, camera.positionWC) - BoundingSphere.distanceSquaredTo(a, camera.positionWC);
+     * });
+     */
+    BoundingSphere.distanceSquaredTo = function(sphere, cartesian) {
+        if (!defined(sphere)) {
+            throw new DeveloperError('sphere is required.');
+        }
+        if (!defined(cartesian)) {
+            throw new DeveloperError('cartesian is required.');
+        }
+
+        var diff = Cartesian3.subtract(sphere.center, cartesian, distanceSquaredToScratch);
+        return Cartesian3.magnitudeSquared(diff) - sphere.radius * sphere.radius;
+    };
+
     /**
      * Applies a 4x4 affine transformation matrix to a bounding sphere where there is no scale
      * The transformation matrix is not verified to have a uniform scale of 1.
@@ -1007,6 +1038,19 @@ define([
         return BoundingSphere.intersect(this, plane);
     };
 
+    /**
+     * Computes the estimated distance squared from the closest point on a bounding sphere to a point.
+     * @memberof BoundingSphere
+     *
+     * @param {Cartesian3} cartesian The point
+     * @returns {Number} The estimated distance squared from the bounding sphere to the point.
+     *
+     * @exception {DeveloperError} cartesian is required.
+     */
+    BoundingSphere.prototype.distanceSquaredTo = function(cartesian) {
+        return BoundingSphere.distanceSquaredTo(this, cartesian);
+    };
+
     /**
      * The distances calculated by the vector from the center of the bounding sphere to position projected onto direction
      * plus/minus the radius of the bounding sphere.

Source/Renderer/DrawCommand.js

@@ -178,4 +178,4 @@ define(function() {
     };
 
     return DrawCommand;
-});
+});

Source/Renderer/Pass.js

@@ -33,4 +33,4 @@ define(function() {
     };
 
     return Pass;
-});
+});

Source/Scene/BillboardCollection.js

@@ -1439,4 +1439,4 @@ define([
     };
 
     return BillboardCollection;
-});
+});

Source/Scene/CompositePrimitive.js

@@ -74,8 +74,19 @@ define([
          * Determines if primitives in this composite will be shown.
          *
          * @type Boolean
+         * @default true
          */
         this.show = true;
+
+        /**
+         * Determines if the primitives in this composite should be sorted. If set to <code>true</code>,
+         * an attempt will be made to sort the primitives; otherwise, the primitives are assumed to be sorted
+         * in the correct drawing order.
+         *
+         * @type Boolean
+         * @default true
+         */
+        this.sortPrimitives = true;
     };
 
     /**
@@ -392,6 +403,8 @@ define([
         return this._primitives.length;
     };
 
+    var scratchCommandList = [];
+
     /**
      * @private
      */
@@ -406,8 +419,25 @@ define([
 
         var primitives = this._primitives;
         var length = primitives.length;
-        for (var i = 0; i < length; ++i) {
-            primitives[i].update(context, frameState, commandList);
+        var i;
+
+        if (this.sortPrimitives) {
+            for (i = 0; i < length; ++i) {
+                primitives[i].update(context, frameState, commandList);
+            }
+        } else {
+            for (i = 0; i < length; ++i) {
+                scratchCommandList.length = 0;
+                primitives[i].update(context, frameState, scratchCommandList);
+
+                var tempCommandListLength = scratchCommandList.length;
+                var commandListLength = commandList.length;
+                for (var j = 0; j < tempCommandListLength; ++j) {
+                    var command = scratchCommandList[j];
+                    command.index = tempCommandListLength + j;
+                    commandList.push(command);
+                }
+            }
         }
     };
 

Source/Scene/CustomSensorVolume.js

@@ -572,4 +572,4 @@ define([
     };
 
     return CustomSensorVolume;
-});
+});

Source/Scene/EllipsoidPrimitive.js

@@ -457,4 +457,4 @@ define([
     };
 
     return EllipsoidPrimitive;
-});
+});

Source/Scene/FrameState.js

@@ -111,4 +111,4 @@ define([
     };
 
     return FrameState;
-});
+});

Source/Scene/FrustumCommands.js

@@ -38,4 +38,4 @@ define(['../Core/defaultValue'], function(defaultValue) {
     };
 
     return FrustumCommands;
-});
+});

Source/Scene/PolylineCollection.js

@@ -1485,4 +1485,4 @@ define([
     };
 
     return PolylineCollection;
-});
+});

Source/Scene/Primitive.js

@@ -1091,4 +1091,4 @@ define([
     };
 
     return Primitive;
-});
+});

Source/Scene/Scene.js

@@ -720,6 +720,61 @@ define([
                    (!defined(occluder) || occluder.isBoundingSphereVisible(boundingVolume)))));
     }
 
+    function createTranslucentCompareFunction(position) {
+        return function(a, b) {
+            if (defined(a.index) && defined(b.index)) {
+                return a.index - b.index;
+            }
+            return b.boundingVolume.distanceSquaredTo(position) - a.boundingVolume.distanceSquaredTo(position);
+        };
+    }
+
+    function merge(array, compare, start, middle, end) {
+        var leftLength = middle - start + 1;
+        var rightLength = end - middle;
+        var left = new Array(leftLength);
+        var right = new Array(rightLength);
+
+        var i;
+        var j;
+
+        for (i = 0; i < leftLength; ++i) {
+            left[i] = array[start + i];
+        }
+
+        for (j = 0; j < rightLength; ++j) {
+            right[j] = array[middle + j + 1];
+        }
+
+        i = 0;
+        j = 0;
+        for (var k = start; k <= end; ++k) {
+            var leftElement = left[i];
+            var rightElement = right[j];
+            if (defined(leftElement) && (!defined(rightElement) || compare(leftElement, rightElement) <= 0)) {
+                array[k] = leftElement;
+                ++i;
+            } else {
+                array[k] = rightElement;
+                ++j;
+            }
+        }
+    }
+
+    function sort(array, compare, start, end) {
+        start = defaultValue(start, 0);
+        end = defaultValue(end, array.length - 1);
+
+        if (start >= end) {
+            return;
+        }
+
+        var middle = Math.floor((start + end) * 0.5);
+        sort(array, compare, start, middle);
+        sort(array, compare, middle + 1, end);
+        merge(array, compare, start, middle, end);
+    }
+
     var scratchPerspectiveFrustum = new PerspectiveFrustum();
     var scratchPerspectiveOffCenterFrustum = new PerspectiveOffCenterFrustum();
     var scratchOrthographicFrustum = new OrthographicFrustum();
@@ -793,6 +848,7 @@ define([
         }
 
         var clearDepthStencil = scene._clearDepthStencilCommand;
+        var translucentCompare = createTranslucentCompareFunction(camera.positionWC);
 
         var frustumCommandsList = scene._frustumCommandsList;
         var numFrustums = frustumCommandsList.length;
@@ -815,6 +871,7 @@ define([
 
             commands = frustumCommands.translucentCommands;
             length = commands.length = frustumCommands.translucentIndex;
+            sort(commands, translucentCompare);
             for (j = 0; j < length; ++j) {
                 executeCommand(commands[j], scene, context, passState);
             }

Source/Scene/SkyAtmosphere.js

@@ -231,4 +231,4 @@ define([
     };
 
     return SkyAtmosphere;
-});
+});

Source/Scene/SkyBox.js

@@ -227,4 +227,4 @@ define([
     };
 
     return SkyBox;
-});
+});

Source/Scene/Sun.js

@@ -381,4 +381,4 @@ define([
     };
 
     return Sun;
-});
+});

Source/Scene/ViewportQuad.js

@@ -251,4 +251,4 @@ define([
     };
 
     return ViewportQuad;
-});
+});

Specs/Core/BoundingSphereSpec.js

@@ -427,6 +427,13 @@ defineSuite([
         expect(bs.getPlaneDistances(position, direction)).toEqual(expected);
     });
 
+    it('estimated distance squared to point', function() {
+        var bs = new BoundingSphere(Cartesian3.ZERO, 1.0);
+        var position = new Cartesian3(-2.0, 1.0, 0.0);
+        var expected = Cartesian3.magnitudeSquared(position) - 1.0;
+        expect(bs.distanceSquaredTo(position)).toEqual(expected);
+    });
+
     it('projectTo2D', function() {
         var positions = getPositions();
         var projection = new GeographicProjection();
@@ -534,6 +541,18 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
+    it('static distanceSquaredTo throws without a sphere', function() {
+        expect(function() {
+            BoundingSphere.distanceSquaredTo();
+        }).toThrow();
+    });
+
+    it('static distanceSquaredTo throws without a cartesian', function() {
+        expect(function() {
+            BoundingSphere.distanceSquaredTo(new BoundingSphere());
+        }).toThrow();
+    });
+
     it('static transformWithoutScale throws without a sphere', function() {
         expect(function() {
             BoundingSphere.transformWithoutScale();

Specs/Scene/CentralBodySurfaceSpec.js

@@ -591,4 +591,4 @@ defineSuite([
             });
         });
     });
-}, 'WebGL');
+}, 'WebGL');

Specs/Scene/LabelCollectionSpec.js

@@ -1559,4 +1559,4 @@ defineSuite([
         expect(textureAtlas.isDestroyed()).toBe(true);
     });
 
-}, 'WebGL');
+}, 'WebGL');

Specs/Scene/PrimitiveSpec.js

@@ -741,4 +741,4 @@ defineSuite([
         primitive.destroy();
         expect(primitive.isDestroyed()).toEqual(true);
     });
-}, 'WebGL');
+}, 'WebGL');

Specs/Scene/SceneSpec.js

@@ -297,4 +297,4 @@ defineSuite([
         destroyScene(s);
         expect(s.isDestroyed()).toEqual(true);
     });
-}, 'WebGL');
+}, 'WebGL');

Specs/Scene/SkyAtmosphereSpec.js

@@ -123,4 +123,4 @@ defineSuite([
         s.destroy();
         expect(s.isDestroyed()).toEqual(true);
     });
-}, 'WebGL');
+}, 'WebGL');

Specs/Scene/SkyBoxSpec.js

@@ -381,4 +381,4 @@ defineSuite([
             return skyBox.update(context, frameState);
         }).toThrow();
     });
-}, 'WebGL');
+}, 'WebGL');