Merge pull request #5969 from AnalyticalGraphicsInc/imagery-nearest-update

Improve doc and tests for imagery layer texture filtering

Author: pjcozzi

Source/Renderer/TextureMagnificationFilter.js

@@ -7,24 +7,22 @@ define([
     'use strict';
 
     /**
-     * Enumerates all possible filters used when magnifying WebGL textures, which takes places when zooming
-     * into imagery. Provides the possible values for the {@link ImageryLayer#magnificationFilter} property.
+     * Enumerates all possible filters used when magnifying WebGL textures.
      *
      * @exports TextureMagnificationFilter
      *
      * @see TextureMinificationFilter
-     * @see ImageryLayer#magnificationFilter
      */
     var TextureMagnificationFilter = {
         /**
-         * Nearest neighbor sampling of image pixels to texture.
+         * Samples the texture by returning the closest pixel.
          *
          * @type {Number}
          * @constant
          */
         NEAREST : WebGLConstants.NEAREST,
         /**
-         * Bi-linear interpolation of image pixels to texture.
+         * Samples the texture through bi-linear interpolation of the four nearest pixels. This produces smoother results than <code>NEAREST</code> filtering.
          *
          * @type {Number}
          * @constant

Source/Renderer/TextureMinificationFilter.js

@@ -7,53 +7,68 @@ define([
     'use strict';
 
     /**
-     * Enumerates all possible filters used when minifying WebGL textures, which takes places when zooming
-     * out of imagery. Provides the possible values for the {@link ImageryLayer#minificationFilter} property.
+     * Enumerates all possible filters used when minifying WebGL textures.
      *
      * @exports TextureMinificationFilter
      *
      * @see TextureMagnificationFilter
-     * @see ImageryLayer#minificationFilter
      */
     var TextureMinificationFilter = {
         /**
-         * Nearest neighbor sampling of image pixels to texture.
+         * Samples the texture by returning the closest pixel.
          *
          * @type {Number}
          * @constant
          */
         NEAREST : WebGLConstants.NEAREST,
         /**
-         * Bi-linear interpolation of image pixels to texture.
+         * Samples the texture through bi-linear interpolation of the four nearest pixels. This produces smoother results than <code>NEAREST</code> filtering.
          *
          * @type {Number}
          * @constant
          */
         LINEAR : WebGLConstants.LINEAR,
         /**
-         * WebGL <code>NEAREST_MIPMAP_NEAREST</code> interpolation of image pixels to texture.
+         * Selects the nearest mip level and applies nearest sampling within that level.
+         * <p>
+         * Requires that the texture has a mipmap. The mip level is chosen by the view angle and screen-space size of the texture.
+         * </p>
          *
          * @type {Number}
          * @constant
          */
         NEAREST_MIPMAP_NEAREST : WebGLConstants.NEAREST_MIPMAP_NEAREST,
         /**
-         * WebGL <code>LINEAR_MIPMAP_NEAREST</code> interpolation of image pixels to texture.
+         * Selects the nearest mip level and applies linear sampling within that level.
+         * <p>
+         * Requires that the texture has a mipmap. The mip level is chosen by the view angle and screen-space size of the texture.
+         * </p>
          *
          * @type {Number}
          * @constant
          */
         LINEAR_MIPMAP_NEAREST : WebGLConstants.LINEAR_MIPMAP_NEAREST,
         /**
-         * WebGL <code>NEAREST_MIPMAP_LINEAR</code> interpolation of image pixels to texture.
+         * Read texture values with nearest sampling from two adjacent mip levels and linearly interpolate the results.
+         * <p>
+         * This option provides a good balance of visual quality and speed when sampling from a mipmapped texture.
+         * </p>
+         * <p>
+         * Requires that the texture has a mipmap. The mip level is chosen by the view angle and screen-space size of the texture.
+         * </p>
          *
          * @type {Number}
          * @constant
          */
         NEAREST_MIPMAP_LINEAR : WebGLConstants.NEAREST_MIPMAP_LINEAR,
         /**
-         * WebGL <code>LINEAR_MIPMAP_LINEAR</code> interpolation of image pixels to texture.
-         *
+         * Read texture values with linear sampling from two adjacent mip levels and linearly interpolate the results.
+         * <p>
+         * This option provides a good balance of visual quality and speed when sampling from a mipmapped texture.
+         * </p>
+         * <p>
+         * Requires that the texture has a mipmap. The mip level is chosen by the view angle and screen-space size of the texture.
+         * </p>
          * @type {Number}
          * @constant
          */

Source/Scene/ImageryLayer.js

@@ -5,6 +5,7 @@ define([
         '../Core/defined',
         '../Core/defineProperties',
         '../Core/destroyObject',
+        '../Core/DeveloperError',
         '../Core/FeatureDetection',
         '../Core/GeographicTilingScheme',
         '../Core/IndexDatatype',
@@ -45,6 +46,7 @@ define([
         defined,
         defineProperties,
         destroyObject,
+        DeveloperError,
         FeatureDetection,
         GeographicTilingScheme,
         IndexDatatype,
@@ -814,6 +816,13 @@ define([
             }
         }
 
+        //>>includeStart('debug', pragmas.debug);
+        if (this.minificationFilter !== TextureMinificationFilter.NEAREST &&
+            this.minificationFilter !== TextureMinificationFilter.LINEAR) {
+            throw new DeveloperError('ImageryLayer minification filter must be NEAREST or LINEAR');
+        }
+        //>>includeEnd('debug');
+
         var sampler = new Sampler({
             minificationFilter : this.minificationFilter,
             magnificationFilter : this.magnificationFilter

Specs/Scene/ImageryLayerSpec.js

@@ -398,7 +398,26 @@ defineSuite([
         });
         expect(layer.minificationFilter).toEqual(TextureMinificationFilter.NEAREST);
         expect(layer.magnificationFilter).toEqual(TextureMagnificationFilter.NEAREST);
-        layer.destroy();
+
+        return pollToPromise(function() {
+            return provider.ready;
+        }).then(function() {
+            var imagery = new Imagery(layer, 0, 0, 0);
+            imagery.addReference();
+            layer._requestImagery(imagery);
+            RequestScheduler.update();
+
+            return pollToPromise(function() {
+                return imagery.state === ImageryState.RECEIVED;
+            }).then(function() {
+                layer._createTexture(scene.context, imagery);
+                var sampler = imagery.texture.sampler;
+                expect(sampler.minificationFilter).toEqual(TextureMinificationFilter.NEAREST);
+                expect(sampler.magnificationFilter).toEqual(TextureMinificationFilter.NEAREST);
+                imagery.releaseReference();
+                layer.destroy();
+            });
+        });
     });
 
     it('uses default texture filter properties of ImageryProvider', function() {