Merge remote-tracking branch 'agi/master' into frustum-debug

.travis.yml

@@ -15,8 +15,8 @@ script:
   - npm run jsHint -- --failTaskOnError
   - echo -en 'travis_fold:end:script.jsHint\\r'
 
-  - echo 'test non-webgl' && echo -en 'travis_fold:start:script.test\\r'
-  - npm run test -- --exclude WebGL --browsers Electron --failTaskOnError --suppressPassed
+  - echo 'test webgl-stub' && echo -en 'travis_fold:start:script.test\\r'
+  - npm run test -- --browsers Electron --webgl-stub --failTaskOnError --suppressPassed
   - echo -en 'travis_fold:end:script.test\\r'
 
   - echo 'makeZipFile' && echo -en 'travis_fold:start:script.makeZipFile\\r'
@@ -30,8 +30,8 @@ script:
   - npm run deploy-status -- --status success --message Deployed
   - echo -en 'travis_fold:end:script.deploy\\r'
 
-  - echo 'test non-webgl release' && echo -en 'travis_fold:start:script test.release\\r'
-  - npm run test -- --exclude WebGL --browsers Electron --failTaskOnError --release --suppressPassed
+  - echo 'test webgl-stub release' && echo -en 'travis_fold:start:script test.release\\r'
+  - npm run test -- --browsers Electron --failTaskOnError --webgl-stub --release --suppressPassed
   - echo -en 'travis_fold:end:script test.release\\r'
 
   - echo 'cloc' && echo -en 'travis_fold:start:script.cloc\\r'

CHANGES.md

@@ -36,7 +36,11 @@ Change Log
 * 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.
+<<<<<<< HEAD
 * Added support to `DebugCameraPrimitive` to draw multifrustum planes. `CesiumInspector` also displays this toggle.
+=======
+* Added the ability to run the unit tests with a [WebGL Stub](https://github.com/AnalyticalGraphicsInc/cesium/tree/master/Documentation/Contributors/TestingGuide#run-with-webgl-stub), which makes all WebGL calls a noop and ignores test expectations that rely on reading back from WebGL.  Use the web link from the main index.html or run with `npm run test-webgl-stub`.
+>>>>>>> agi/master
 
 ### 1.29 - 2017-01-02
 

Documentation/Contributors/BuildGuide/README.md

@@ -112,10 +112,11 @@ Here's the full set of scripts and what they do.
    * **Testing scripts** -- build and run the unit tests
       * `test` - Runs all tests with [Karma](http://karma-runner.github.io/0.13/index.html) using the default browser specified in the Karma config file.
       * `test-all` - Runs all tests with Karma using all browsers installed on the current system.
-      * `test-non-webgl` - Runs only non-WebGL tests with Karma.
-      * `test-webgl` - Runs only WebGL tests with Karma.
+      * `test-non-webgl` - Runs only non-WebGL tests.
+      * `test-webgl` - Runs only WebGL tests.
+      * `test-webgl-stub` - Runs all tests using the WebGL stub, which WebGL calls a noop and ignores related test expectations.
       * `test-webgl-validation` - Runs all tests with Karma and enables low-level WebGL validation.
-      * `test-release` - Runs all tests with Karma on the minified release version of built Cesium.
+      * `test-release` - Runs all tests on the minified release version of built Cesium.
    * **Deployment scripts**
       * `deploy-s3` - Deploys the built cesium files, the npm package, and the zip file to Amazon S3. This requires having credentials set up for the S3 bucket to which you are deploying.
       * `deploy-status` - Set the deployment statuses in GitHub, for use with Travis.

Documentation/Contributors/TestingGuide/README.md

@@ -7,13 +7,15 @@ As of Cesium 1.15, Cesium has over 7,000 tests with 93% code coverage.  Cesium h
 All new code should have 100% code coverage and should pass all tests.  Always run the tests before opening a pull request.
 
 * [Running the Tests](#running-the-tests)
-   * [Run All Tests (Run with WebGL Validation)](#run-all-tests-run-with-webgl-validation)
+   * [Run All Tests](#run-all-tests)
+      * [Run with WebGL validation](#run-with-webgl-validation)
+      * [Run with WebGL stub](#run-with-webgl-stub)
    * [Select a Test to Run](#select-a-test-to-run)
    * [Run Only WebGL Tests](#run-only-webgl-tests)
    * [Run Only Non-WebGL Tests](#run-only-non-webgl-tests)
    * [Run All Tests against Combined File (Run All Tests against Combined File with Debug Code Removed)]()
    * [Run All Tests with Code Coverage (Build 'instrumentForCoverage' First)](#run-all-tests-against-combined-file-run-all-tests-against-combined-file-with-debug-code-removed)
-   * [Run All Tests on the Command Line with Karma](#run-all-tests-on-the-command-line-with-karma)
+   * [Running Tests on the Command Line with Karma](#run-all-tests-on-the-command-line-with-karma)
 * [Testing Previous Versions of Cesium](#testing-previous-versions-of-cesium)
 * [`testfailure` Label for Issues](#testfailure-label-for-issues)
 * [Writing Tests](#writing-tests)
@@ -44,7 +46,7 @@ The Cesium tests are written in JavaScript and use [Jasmine](http://jasmine.gith
 
 When running Cesium locally, browse to [http://localhost:8080/](http://localhost:8080/) and there are several test options:
 
-### Run All Tests (Run with WebGL Validation)
+### Run All Tests
 
 Runs all the tests.  As of Cesium 1.15, on a decent laptop, they run in about a minute in Chrome.  It is important that the tests run quickly so we run them often.
 
@@ -62,8 +64,14 @@ In this case, the number of failing tests is listed at the top, and details on e
 ```
 Click on the failed test to rerun just that test.  This is useful for saving time when fixing an issue as it avoids rerunning all the tests.  Always rerun _all_ the tests before opening a pull request.
 
+#### Run with WebGL validation
+
 The link to **Run with WebGL validation** passes a query parameter to the tests to enable extra low-level WebGL validation such as calling `gl.getError()` after each WebGL call.  We use this when doing the monthly Cesium release and when making changes to Cesium's renderer.
 
+#### Run with WebGL stub
+
+The **Run with WebGL stub** link passes a query parameter to the tests to use Cesium's WebGL stub.  This makes all WebGL calls a noop and ignores test expectations that rely on reading back from WebGL.  This allows running the tests on CI where a reasonable WebGL implementation is not available and still getting full code coverage albeit not all verification.
+
 ### Select a Test to Run
 
 This option loads the test page without running any tests.
@@ -140,7 +148,7 @@ It is possible to have 100% code coverage with two tests: one test where `a` and
 
 The number of linearly independent paths (four in this case) is called the **cyclomatic complexity**.  Be mindful of this when writing tests.  On one extreme, 100% code coverage is the least amount of testing, on the other extreme is covering the cyclomatic complexity, which quickly becomes unreasonable.  Use your knowledge of the implementation to devise the best strategy.
 
-### Run All Tests on the Command Line with Karma
+### Running Tests on the Command Line with Karma
 
 [Karma](http://karma-runner.github.io/0.13/index.html) is a tool which spawns a browser window, runs tests against that browser, and displays the results on the command line.
 
@@ -166,6 +174,10 @@ It is also possible for Karma to run all tests against each browser installed on
 
 `npm run test-webgl-validation`
 
+#### Run All Tests with WebGL Stub
+
+`npm run test-webgl-stub`
+
 #### Run Only WebGL Tests with Karma
 
 `npm run test-webgl`
@@ -317,7 +329,7 @@ Above, `scene` is scoped at the suite-level, so all tests in the file have acces
 ```javascript
 it('renders', function() {
     var p = scene.primitives.add(new DebugModelMatrixPrimitive());
-    expect(scene.renderForSpecs()).not.toEqual([0, 0, 0, 255]);
+    expect(scene).notToRender([0, 0, 0, 255]);
 });
 ```
 
@@ -331,40 +343,119 @@ The tests in the `'WebGL'` category do not strictly follow this pattern.  Creati
 
 Unlike the `Cartesian3` tests we first saw, many tests need to construct the main Cesium `Viewer` widget or one of its major components.  Low-level renderer tests construct just `Context` (which, itself, has a canvas and WebGL context), and primitive tests construct a `Scene` (which contains a `Context`).
 
-As shown above, these tests use Cesium test utility functions: `createViewer`, `createScene`, or `createContext`.  These functions honor query parameters passed to the tests (e.g., enabling WebGL validation) and add extra test functions to the returned object.
+As shown above, these tests use Cesium test utility functions: `createViewer`, `createScene`, or `createContext`.  These functions honor query parameters passed to the tests (e.g., enabling WebGL validation or the WebGL stub) and add a few utility functions to the returned object.  For example, `createScene` creates a 1x1 pixel canvas with a Cesium Scene and adds `renderForSpecs` (to initialize and render a frame) and `destroyForSpecs` to the returned `Scene` object.
 
-For example, `createScene` creates a 1x1 pixel canvas with a Cesium Scene and adds `renderForSpecs` and `pickForSpecs` to the returned `Scene` object:
+> Most Cesium apps do not render the scene directly; instead, the `Viewer` object's default render loop renders the scene implicit to the user.  The tests are an exception; most tests explicitly render the scene.
+
+Cesium adds several custom Jasmine matchers to make the rendering tests more concise and to support running tests with the WebGL stub.  When using the WebGL stub, the WebGL implementation is a noop, and test expectations that rely on reading back from WebGL are ignored.  The rendering custom matchers are:
+
+* `toRender`
+* `notToRender`
+* `toRenderAndCall`
+* `toPickPrimitive`
+* `notToPick`
+* `toPickAndCall`
+* `toDrillPickAndCall`
+* `toReadPixels`
+* `notToReadPixels`
+* `contextToRender`
+* `notContextToRender`
+
+`toRender` and `notToRender` clear a 1x1 viewport to black, renders the scene into it, and verifies the RGBA value of the pixel, e.g.:
 
 ```javascript
 it('renders', function() {
     var p = scene.primitives.add(new DebugModelMatrixPrimitive());
-    expect(scene.renderForSpecs()).not.toEqual([0, 0, 0, 255]);
+    expect(scene).notToRender([0, 0, 0, 255]);
 });
 
 it('does not render when show is false', function() {
     scene.primitives.add(new DebugModelMatrixPrimitive({
         show : false
     }));
-    expect(scene.renderForSpecs()).toEqual([0, 0, 0, 255]);
+    expect(scene).toRender([0, 0, 0, 255]);
 });
+```
 
-it('is picked', function() {
-    var p = scene.primitives.add(new DebugModelMatrixPrimitive({
-        id : 'id'
-    }));
+Like most rendering tests, the first example uses a coarse-grained expectation to check that the pixel is not the default value of black.  Although an expectation this coarse-grained may not catch all subtle errors, it is reliable across platforms, and we rarely have bugs a more fine-grained test would have caught, especially with some manual testing (see below).
 
-    var pick = scene.pickForSpecs();
-    expect(pick.primitive).toEqual(p);
-    expect(pick.id).toEqual('id');
+The second test verifies that the pixel value is the same as the default background color since the primitive's `show` property is `false`.
+
+`toRender` and `notToRender` can also render the scene at a given Cesium simulation time, e.g.,:
+
+```javascript
+expect({
+    scene : scene,
+    time : t
+}).toRender([0, 0, 0, 255]);
+```
+
+For more complicated expectations, which will still be ignored with the WebGL stub, `toRenderAndCall` takes a callback function:
+
+```javascript
+expect(scene).toRenderAndCall(function(rgba) {
+    expect(rgba[0]).not.toEqual(0);
+    expect(rgba[1]).toBeGreaterThanOrEqualTo(0);
+    expect(rgba[2]).toBeGreaterThanOrEqualTo(0);
+    expect(rgba[3]).toEqual(255);
 });
 ```
-In the first test, `renderForSpecs` initializes the frame, renders the scene into the 1x1 canvas, and then returns the RGBA value of the rendered pixel.  Like most rendering tests, this uses a coarse-grained expectation to check that the pixel is not the default value of black.  Although an expectation this coarse-grained may not catch all subtle errors, it is reliable across platforms, and we rarely have bugs a more fine-grained test would have caught, especially with some manual testing (see below).
 
-In the second test, `renderForSpecs` is used again, but this time it is to verify that the pixel value is the same as the default background color since the primitive's `show` property is `false`.
+For reliability across WebGL implementations, use complex expectations in `toRenderAndCall` sparingly.
 
-> Most Cesium apps do not render the scene directly; instead, the `Viewer` object's default render loop renders the scene implicit to the user.  The tests are an exception; most tests explicitly render the scene.
+Similar custom matchers are used for picking tests:
+
+```javascript
+var b = billboards.add(/* ... */);
+expect(scene).toPickPrimitive(b);  // Can also use toPickAndCall() and toDrillPickAndCall()
+
+b.show = false;
+expect(scene).notToPick();
+```
+
+For tests that render the scene themselves, `toReadPixels` and `notToReadPixels` are used to verify the RGBA value.  In the simplest case, pass an RGBA array, e.g.:
+
+```javascript
+expect(context).toReadPixels([0, 0, 0, 255]);
+
+expect(context).notToReadPixels([0, 0, 0, 255]);
+```
+
+`toReadPixels` can also read from a given framebuffer and use an epsilon for the RGBA comparison test, e.g.:
+
+```javascript
+expect({
+    context : context,
+    framebuffer : framebuffer,
+    epsilon : 1
+}).toReadPixels([0, 0, 0, 255]);
+```
+
+Low-level Cesium renderer tests use just a `Context` without a Cesium `Scene`, and use the `contextToRender` and `notContextToRender` custom matchers to render a WebGL point primitive to the context's 1x1 viewport and verify the RGBA value, e.g.:
 
-In the final test, `pickForSpecs` executes a `Scene.pick` for the one-pixel canvas.  A typical follow-up expectation verifies that the primitive of interest was picked and its `id` is the expected value.
+```javascript
+expect({
+    context : context,
+    shaderProgram : sp,
+}).contextToRender(expected);
+
+expect(/* ... */).notContextToRender();
+```
+
+Uniforms, the model matrix, and various depth options can be provided.  In addition, instead of providing a full shader program, just the fragment shader's source can be provided, e.g.,
+
+```javascript
+it('can declare automatic uniforms', function() {
+    var fs =
+        'void main() { ' +
+        '  gl_FragColor = vec4((czm_viewport.x == 0.0) && (czm_viewport.y == 0.0) && (czm_viewport.z == 1.0) && (czm_viewport.w == 1.0)); ' +
+        '}';
+    expect({
+        context : context,
+        fragmentShader : fs
+    }).contextToRender();
+});
+```
 
 ### GLSL
 

Source/Core/WebGLConstants.js

@@ -589,7 +589,10 @@ define([
         COMPRESSED_SRGB8_ALPHA8_ETC2_EAC : 0x9279,
         TEXTURE_IMMUTABLE_FORMAT : 0x912F,
         MAX_ELEMENT_INDEX : 0x8D6B,
-        TEXTURE_IMMUTABLE_LEVELS : 0x82DF
+        TEXTURE_IMMUTABLE_LEVELS : 0x82DF,
+
+        // Extensions
+        MAX_TEXTURE_MAX_ANISOTROPY_EXT : 0x84FF
     };
 
     return freezeObject(WebGLConstants);