Billboard transparency

CHANGES.md

@@ -34,6 +34,8 @@ Change Log
 * `TerrainProvider` now optionally exposes an `availability` property that can be used to query the terrain level that is available at a location or in a rectangle.  Currently only `CesiumTerrainProvider` exposes this property.
 * Added `sampleTerrainMostDetailed` to sample the height of an array of positions using the best available terrain data at each point.  This requires a `TerrainProvider` with the `availability` property.
 * Added 2D and Columbus View support for models using the RTC extension or whose vertices are in WGS84 coordinates. [#4922](https://github.com/AnalyticalGraphicsInc/cesium/pull/4922)
+* Transparent parts of billboards, labels, and points no longer overwrite parts of the scene behind them. [#4886](https://github.com/AnalyticalGraphicsInc/cesium/pull/4886)
+    * Added `blendOption` property to `BillboardCollection`, `LabelCollection`, and `PointPrimitiveCollection`. The default is `BlendOption.OPAQUE_AND_TRANSLUCENT`; however, if all billboards, labels, or points are either completely opaque or completely translucent, `blendOption` can be changed to `BlendOption.OPAQUE` or `BlendOption.TRANSLUCENT`, respectively, to increase performance by up to 2x.
 
 ### 1.29 - 2017-01-02
 

Source/Scene/BlendOption.js

@@ -0,0 +1,37 @@
+/*global define*/
+define([
+    '../Core/freezeObject'
+], function(
+    freezeObject) {
+    'use strict';
+
+    /**
+     * Determines how opaque and translucent parts of billboards, points, and labels are blended with the scene.
+     *
+     * @exports BlendOption
+     */
+    var BlendOption = {
+        /**
+         * The billboards, points, or labels in the collection are completely opaque.
+         * @type {Number}
+         * @constant
+         */
+        OPAQUE : 0,
+
+        /**
+         * The billboards, points, or labels in the collection are completely translucent.
+         * @type {Number}
+         * @constant
+         */
+        TRANSLUCENT : 1,
+
+        /**
+         * The billboards, points, or labels in the collection are both opaque and translucent.
+         * @type {Number}
+         * @constant
+         */
+        OPAQUE_AND_TRANSLUCENT : 2
+    };
+
+    return freezeObject(BlendOption);
+});

Source/Scene/LabelCollection.js

@@ -11,6 +11,7 @@ define([
         '../Core/Matrix4',
         '../Core/writeTextToCanvas',
         './BillboardCollection',
+        './BlendOption',
         './HorizontalOrigin',
         './Label',
         './LabelStyle',
@@ -28,6 +29,7 @@ define([
         Matrix4,
         writeTextToCanvas,
         BillboardCollection,
+        BlendOption,
         HorizontalOrigin,
         Label,
         LabelStyle,
@@ -440,6 +442,9 @@ define([
      * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] The 4x4 transformation matrix that transforms each label from model to world coordinates.
      * @param {Boolean} [options.debugShowBoundingVolume=false] For debugging only. Determines if this primitive's commands' bounding spheres are shown.
      * @param {Scene} [options.scene] Must be passed in for labels that use the height reference property or will be depth tested against the globe.
+     * @param {BlendOption} [options.blendOption=BlendOption.OPAQUE_AND_TRANSLUCENT] The label blending option. The default
+     * is used for rendering both opaque and translucent labels. However, if either all of the labels are completely opaque or all are completely translucent,
+     * setting the technique to BillboardRenderTechnique.OPAQUE or BillboardRenderTechnique.TRANSLUCENT can improve performance by up to 2x.
      *
      * @performance For best performance, prefer a few collections, each with many labels, to
      * many collections with only a few labels each.  Avoid having collections where some
@@ -533,6 +538,16 @@ define([
          * @default false
          */
         this.debugShowBoundingVolume = defaultValue(options.debugShowBoundingVolume, false);
+
+        /**
+         * The label blending option. The default is used for rendering both opaque and translucent labels.
+         * However, if either all of the labels are completely opaque or all are completely translucent,
+         * setting the technique to BillboardRenderTechnique.OPAQUE or BillboardRenderTechnique.TRANSLUCENT can improve
+         * performance by up to 2x.
+         * @type {BlendOption}
+         * @default BlendOption.OPAQUE_AND_TRANSLUCENT
+         */
+        this.blendOption = defaultValue(options.blendOption, BlendOption.OPAQUE_AND_TRANSLUCENT);
     }
 
     defineProperties(LabelCollection.prototype, {
@@ -732,8 +747,10 @@ define([
 
         billboardCollection.modelMatrix = this.modelMatrix;
         billboardCollection.debugShowBoundingVolume = this.debugShowBoundingVolume;
+        billboardCollection.blendOption = this.blendOption;
         backgroundBillboardCollection.modelMatrix = this.modelMatrix;
         backgroundBillboardCollection.debugShowBoundingVolume = this.debugShowBoundingVolume;
+        backgroundBillboardCollection.blendOption = this.blendOption;
 
         var context = frameState.context;