Ensure Cesium is fast by default

CHANGES.md

@@ -8,6 +8,19 @@ Change Log
 
 ##### Additions :tada:
 
+* `useBrowserRecommendedResolution` flag in `Viewer` and `CesiumWidget` now defaults to `true`. This ensures Cesium rendering is fast and smooth by default across all devices. Set it to `false` to always render at native device resolution instead at the cost of performance on under-powered devices.
+* Cesium now creates a WebGL context with a `powerPreference` value of `high-performance`. Some browsers use this setting to enable a second, more powerful, GPU.  You can set it back to `default`, or opt-in to `low-power` mode, by passing the context option when creating a `Viewer` or `CesiumWidget` instance:
+
+```js
+    var viewer = new Viewer('cesiumContainer', {
+        contextOptions : {
+            webgl : {
+                powerPreference: 'default'
+            }
+        }
+    });
+```
+
 * Add more customization to Cesium's lighting system [#8493](https://github.com/AnalyticalGraphicsInc/cesium/pull/8493)
     * Added `Light`, `DirectionalLight`, and `SunLight` classes for creating custom light sources.
     * Added `Scene.light` for setting the scene's light source, which defaults to a `SunLight`.

Source/Scene/Scene.js

@@ -4,6 +4,7 @@ import BoxGeometry from '../Core/BoxGeometry.js';
 import Cartesian3 from '../Core/Cartesian3.js';
 import Cartesian4 from '../Core/Cartesian4.js';
 import Cartographic from '../Core/Cartographic.js';
+import clone from '../Core/clone.js';
 import Color from '../Core/Color.js';
 import ColorGeometryInstanceAttribute from '../Core/ColorGeometryInstanceAttribute.js';
 import createGuid from '../Core/createGuid.js';
@@ -97,6 +98,7 @@ import View from './View.js';
      *     depth : true,
      *     stencil : false,
      *     antialias : true,
+     *     powerPreference: 'high-performance',
      *     premultipliedAlpha : true,
      *     preserveDrawingBuffer : false,
      *     failIfMajorPerformanceCaveat : false
@@ -156,10 +158,18 @@ import View from './View.js';
     function Scene(options) {
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
         var canvas = options.canvas;
-        var contextOptions = options.contextOptions;
         var creditContainer = options.creditContainer;
         var creditViewport = options.creditViewport;
 
+        var contextOptions = clone(options.contextOptions);
+        if (!defined(contextOptions)) {
+            contextOptions = {};
+        }
+        if (!defined(contextOptions.webgl)) {
+            contextOptions.webgl = {};
+        }
+        contextOptions.webgl.powerPreference = defaultValue(contextOptions.webgl.powerPreference, 'high-performance');
+
         //>>includeStart('debug', pragmas.debug);
         if (!defined(canvas)) {
             throw new DeveloperError('options and options.canvas are required.');

Source/Widgets/CesiumWidget/CesiumWidget.js

@@ -132,7 +132,7 @@ import getElement from '../getElement.js';
      * @param {MapProjection} [options.mapProjection=new GeographicProjection()] The map projection to use in 2D and Columbus View modes.
      * @param {Globe} [options.globe=new Globe(mapProjection.ellipsoid)] The globe to use in the scene.  If set to <code>false</code>, no globe will be added.
      * @param {Boolean} [options.useDefaultRenderLoop=true] True if this widget should control the render loop, false otherwise.
-     * @param {Boolean} [options.useBrowserRecommendedResolution=false] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
+     * @param {Boolean} [options.useBrowserRecommendedResolution=true] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
      * @param {Number} [options.targetFrameRate] The target frame rate when using the default render loop.
      * @param {Boolean} [options.showRenderLoopErrors=true] If true, this widget will automatically display an HTML panel to the user containing the error, if a render loop error occurs.
      * @param {Object} [options.contextOptions] Context and WebGL creation properties corresponding to <code>options</code> passed to {@link Scene}.
@@ -218,7 +218,7 @@ import getElement from '../getElement.js';
 
         var showRenderLoopErrors = defaultValue(options.showRenderLoopErrors, true);
 
-        var useBrowserRecommendedResolution = defaultValue(options.useBrowserRecommendedResolution, false);
+        var useBrowserRecommendedResolution = defaultValue(options.useBrowserRecommendedResolution, true);
 
         this._element = element;
         this._container = container;

Source/Widgets/Viewer/Viewer.js

@@ -231,7 +231,7 @@ import VRButton from '../VRButton/VRButton.js';
      * @param {Boolean} [options.useDefaultRenderLoop=true] True if this widget should control the render loop, false otherwise.
      * @param {Number} [options.targetFrameRate] The target frame rate when using the default render loop.
      * @param {Boolean} [options.showRenderLoopErrors=true] If true, this widget will automatically display an HTML panel to the user containing the error, if a render loop error occurs.
-     * @param {Boolean} [options.useBrowserRecommendedResolution=false] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
+     * @param {Boolean} [options.useBrowserRecommendedResolution=true] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
      * @param {Boolean} [options.automaticallyTrackDataSourceClocks=true] If true, this widget will automatically track the clock settings of newly added DataSources, updating if the DataSource's clock changes.  Set this to false if you want to configure the clock independently.
      * @param {Object} [options.contextOptions] Context and WebGL creation properties corresponding to <code>options</code> passed to {@link Scene}.
      * @param {SceneMode} [options.sceneMode=SceneMode.SCENE3D] The initial scene mode.

Specs/Widgets/CesiumWidget/CesiumWidgetSpec.js

@@ -59,6 +59,7 @@ describe('Widgets/CesiumWidget/CesiumWidget', function() {
         expect(widget.camera).toBeInstanceOf(Camera);
         expect(widget.clock).toBeInstanceOf(Clock);
         expect(widget.screenSpaceEventHandler).toBeInstanceOf(ScreenSpaceEventHandler);
+        expect(widget.useBrowserRecommendedResolution).toBe(true);
         widget.render();
         widget.destroy();
         expect(widget.isDestroyed()).toEqual(true);
@@ -190,7 +191,8 @@ describe('Widgets/CesiumWidget/CesiumWidget', function() {
             stencil : true,
             antialias : false,
             premultipliedAlpha : true, // Workaround IE 11.0.8, which does not honor false.
-            preserveDrawingBuffer : true
+            preserveDrawingBuffer : true,
+            powerPreference: 'low-power'
         };
         var contextOptions = {
             allowTextureFilterAnisotropic : false,
@@ -210,6 +212,7 @@ describe('Widgets/CesiumWidget/CesiumWidget', function() {
         expect(contextAttributes.stencil).toEqual(webglOptions.stencil);
         expect(contextAttributes.antialias).toEqual(webglOptions.antialias);
         expect(contextAttributes.premultipliedAlpha).toEqual(webglOptions.premultipliedAlpha);
+        expect(contextAttributes.powerPreference).toEqual(webglOptions.powerPreference);
         expect(contextAttributes.preserveDrawingBuffer).toEqual(webglOptions.preserveDrawingBuffer);
     });
 

Specs/Widgets/Viewer/ViewerSpec.js

@@ -102,6 +102,7 @@ describe('Widgets/Viewer/Viewer', function() {
         expect(viewer.canvas).toBe(viewer.cesiumWidget.canvas);
         expect(viewer.cesiumLogo).toBe(viewer.cesiumWidget.cesiumLogo);
         expect(viewer.screenSpaceEventHandler).toBe(viewer.cesiumWidget.screenSpaceEventHandler);
+        expect(viewer.useBrowserRecommendedResolution).toBe(true);
         expect(viewer.isDestroyed()).toEqual(false);
         viewer.destroy();
         expect(viewer.isDestroyed()).toEqual(true);
@@ -432,6 +433,7 @@ describe('Widgets/Viewer/Viewer', function() {
             depth : true, //TODO Change to false when https://bugzilla.mozilla.org/show_bug.cgi?id=745912 is fixed.
             stencil : true,
             antialias : false,
+            powerPreference: 'low-power',
             premultipliedAlpha : true, // Workaround IE 11.0.8, which does not honor false.
             preserveDrawingBuffer : true
         };
@@ -452,6 +454,7 @@ describe('Widgets/Viewer/Viewer', function() {
         expect(contextAttributes.depth).toEqual(webglOptions.depth);
         expect(contextAttributes.stencil).toEqual(webglOptions.stencil);
         expect(contextAttributes.antialias).toEqual(webglOptions.antialias);
+        expect(contextAttributes.powerPreference).toEqual(webglOptions.powerPreference);
         expect(contextAttributes.premultipliedAlpha).toEqual(webglOptions.premultipliedAlpha);
         expect(contextAttributes.preserveDrawingBuffer).toEqual(webglOptions.preserveDrawingBuffer);
     });