Merge remote-tracking branch 'origin/master' into resolutionScaleFactor

Conflicts:
	Source/Widgets/CesiumWidget/CesiumWidget.js

CHANGES.md

@@ -10,6 +10,7 @@ Beta Releases
   * Removed `CesiumWidget.onRenderLoopError` and `Viewer.renderLoopError`.  They have been replaced by `Scene.renderError`.
 * Improved terrain and imagery rendering performance when very close to the surface.
 * Added `preRender` and `postRender` events to `Scene`.
+* Added `Viewer.targetFrameRate` and `CesiumWidget.targetFrameRate` to allow for throttling of the requestAnimationFrame rate.
 
 ### b28 - 2014-05-01
 

Source/Widgets/CesiumWidget/CesiumWidget.js

@@ -11,6 +11,7 @@ define([
         '../../Core/Ellipsoid',
         '../../Core/Event',
         '../../Core/formatError',
+        '../../Core/getTimestamp',
         '../../Core/requestAnimationFrame',
         '../../Core/ScreenSpaceEventHandler',
         '../../Scene/BingMapsImageryProvider',
@@ -35,6 +36,7 @@ define([
         Ellipsoid,
         Event,
         formatError,
+        getTimestamp,
         requestAnimationFrame,
         ScreenSpaceEventHandler,
         BingMapsImageryProvider,
@@ -55,16 +57,32 @@ define([
 
     function startRenderLoop(widget) {
         widget._renderLoopRunning = true;
+        widget._lastFrameTime = getTimestamp();
 
         function render() {
             if (widget.isDestroyed()) {
                 return;
             }
 
             if (widget._useDefaultRenderLoop) {
-                widget.resize();
-                widget.render();
-                requestAnimationFrame(render);
+                var targetFrameRate = widget._targetFrameRate;
+                if (!defined(targetFrameRate)) {
+                    widget.resize();
+                    widget.render();
+                    requestAnimationFrame(render);
+                } else {
+                    var lastFrameTime = widget._lastFrameTime;
+                    var interval = 1000.0 / targetFrameRate;
+                    var now = getTimestamp();
+                    var delta = now - lastFrameTime;
+
+                    if (delta > interval) {
+                        widget.resize();
+                        widget.render();
+                        widget._lastFrameTime = now - (delta % interval);
+                    }
+                    requestAnimationFrame(render);
+                }
             } else {
                 widget._renderLoopRunning = false;
             }
@@ -89,6 +107,7 @@ define([
      * @param {SkyBox} [options.skyBox] The skybox used to render the stars.  When <code>undefined</code>, the default stars are used.
      * @param {SceneMode} [options.sceneMode=SceneMode.SCENE3D] The initial scene mode.
      * @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 {Object} [options.contextOptions=undefined] Context and WebGL creation properties corresponding to {@link Context#options}.
      *
@@ -216,6 +235,8 @@ define([
             this._canRender = false;
             this._showRenderLoopErrors = defaultValue(options.showRenderLoopErrors, true);
             this._forceResize = false;
+            this._lastFrameTime = undefined;
+            this._targetFrameRate = undefined;
 
             if (options.sceneMode) {
                 if (options.sceneMode === SceneMode.SCENE2D) {
@@ -227,6 +248,7 @@ define([
             }
 
             this.useDefaultRenderLoop = defaultValue(options.useDefaultRenderLoop, true);
+            this.targetFrameRate = options.targetFrameRate;
 
             var that = this;
             scene.renderError.addEventListener(function(scene, error) {
@@ -319,6 +341,27 @@ define([
             }
         },
 
+        /**
+         * Gets or sets the target frame rate of the widget when <code>useDefaultRenderLoop</code>
+         * is true. If undefined, the browser's {@link requestAnimationFrame} implementation
+         * determines the frame rate.  This value must be greater than 0 and a value higher than
+         * the underlying requestAnimationFrame implementatin will have no affect.
+         * @memberof CesiumWidget.prototype
+         *
+         * @type {Number}
+         */
+        targetFrameRate : {
+            get : function() {
+                return this._targetFrameRate;
+            },
+            set : function(value) {
+                if (value <= 0) {
+                    throw new DeveloperError('targetFrameRate must be greater than 0.');
+                }
+                this._targetFrameRate = value;
+            }
+        },
+
         /**
          * Gets or sets whether or not this widget should control the render loop.
          * If set to true the widget will use {@link requestAnimationFrame} to

Source/Widgets/Viewer/Viewer.js

@@ -96,6 +96,7 @@ define([
      * @param {SkyBox} [options.skyBox] The skybox used to render the stars.  When <code>undefined</code>, the default stars are used.
      * @param {Element} [options.fullscreenElement=document.body] The element to make full screen when the full screen button is pressed.
      * @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.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=undefined] Context and WebGL creation properties corresponding to {@link Context#options}.
@@ -211,6 +212,7 @@ Either specify options.terrainProvider instead or set options.baseLayerPicker to
             sceneMode : options.sceneMode,
             contextOptions : options.contextOptions,
             useDefaultRenderLoop : options.useDefaultRenderLoop,
+            targetFrameRate : options.targetFrameRate,
             showRenderLoopErrors : options.showRenderLoopErrors
         });
 
@@ -643,6 +645,24 @@ Either specify options.terrainProvider instead or set options.baseLayerPicker to
             }
         },
 
+        /**
+         * Gets or sets the target frame rate of the widget when <code>useDefaultRenderLoop</code>
+         * is true. If undefined, the browser's {@link requestAnimationFrame} implementation
+         * determines the frame rate.  This value must be greater than 0 and a value higher than
+         * the underlying requestAnimationFrame implementatin will have no effect.
+         * @memberof Viewer.prototype
+         *
+         * @type {Number}
+         */
+        targetFrameRate : {
+            get : function() {
+                return this._cesiumWidget.targetFrameRate;
+            },
+            set : function(value) {
+                this._cesiumWidget.targetFrameRate = value;
+            }
+        },
+
         /**
          * Gets or sets whether or not this widget should control the render loop.
          * If set to true the widget will use {@link requestAnimationFrame} to

Specs/Widgets/CesiumWidget/CesiumWidgetSpec.js

@@ -90,6 +90,13 @@ defineSuite([
         expect(widget.useDefaultRenderLoop).toBe(false);
     });
 
+    it('can set target frame rate', function() {
+        widget = new CesiumWidget(container, {
+            targetFrameRate : 23
+        });
+        expect(widget.targetFrameRate).toBe(23);
+    });
+
     it('sets expected options imageryProvider', function() {
         var options = {
             imageryProvider : new TileCoordinatesImageryProvider()
@@ -169,6 +176,13 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
+    it('throws if targetFrameRate less than 0', function() {
+        widget = new CesiumWidget(container);
+        expect(function() {
+            widget.targetFrameRate = -1;
+        }).toThrowDeveloperError();
+    });
+
     it('throws if no container id does not exist', function() {
         expect(function() {
             return new CesiumWidget('doesnotexist');

Specs/Widgets/Viewer/ViewerSpec.js

@@ -355,6 +355,20 @@ defineSuite([
         expect(viewer.useDefaultRenderLoop).toBe(false);
     });
 
+    it('can set target frame rate', function() {
+        viewer = new Viewer(container, {
+            targetFrameRate : 23
+        });
+        expect(viewer.targetFrameRate).toBe(23);
+    });
+
+    it('throws if targetFrameRate less than 0', function() {
+        viewer = new Viewer(container);
+        expect(function() {
+            viewer.targetFrameRate = -1;
+        }).toThrowDeveloperError();
+    });
+
     it('constructor throws with undefined container', function() {
         expect(function() {
             return new Viewer(undefined);

build.xml

@@ -297,11 +297,47 @@
 		</condition>
 	</target>
 
-	<target name="setNodePathLocation" if="nodePathValue">
-		<property name="nodePath" location="${nodePathValue}" />
-	</target>
+	<target name="setNodePath">
+		<exec executable="node" failonerror="false" failifexecutionfails="false" resultproperty="node.exec.result">
+			<arg value="--version" />
+		</exec>
+
+		<!-- use node from path if return code is zero -->
+		<condition property="nodePath" value="node">
+			<equals arg1="${node.exec.result}" arg2="0" />
+		</condition>
+
+		<!-- otherwise on windows use the windows binary -->
+		<condition property="nodePath" value="${toolsDirectory}/nodejs-0.6.17/windows/node.exe">
+			<and>
+				<os family="windows" />
+				<not>
+					<isset property="nodePath" />
+				</not>
+			</and>
+		</condition>
+
+		<!-- otherwise on mac use the mac binary -->
+		<condition property="nodePath" value="${toolsDirectory}/nodejs-0.6.17/mac/node">
+			<and>
+				<os family="mac" />
+				<not>
+					<isset property="nodePath" />
+				</not>
+			</and>
+		</condition>
+
+		<!-- otherwise on linux use the linux binary -->
+		<condition property="nodePath" value="${toolsDirectory}/nodejs-0.6.17/linux/node">
+			<and>
+				<os family="unix" />
+				<not>
+					<isset property="nodePath" />
+				</not>
+			</and>
+		</condition>
 
-	<target name="setNodePath" depends="setNodePathValue,setNodePathLocation">
+		<!-- otherwise use node from path -->
 		<condition property="nodePath" value="node">
 			<not>
 				<isset property="nodePath" />