Set texture sampler properties of ImageryLayer

CHANGES.md

@@ -1,5 +1,15 @@
 Change Log
 ==========
+
+### 1.39 - 2017-11-??
+
+* Added two new properties to `ImageryLayer` that allow for adjusting the texture sampler used for up- and down-sampling
+  of image tiles, namely `minificationFilter` and `magnificationFilter` with possible values `LINEAR`
+  (the default) and `NEAREST` defined in `TextureMinificationFilter` and `TextureMagnificationFilter`.
+  [#5846](https://github.com/AnalyticalGraphicsInc/cesium/issues/5846)
+  Hence, the enums `TextureMagnificationFilter` and `TextureMinificationFilter` have been made public. 
+
+
 ### 1.38 - 2017-10-02
 
 * Breaking changes

Source/Renderer/TextureMagnificationFilter.js

@@ -7,12 +7,30 @@ define([
     'use strict';
 
     /**
-     * @private
+     * 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.
+     *
+     * @alias TextureMagnificationFilter
+     *
+     * @see TextureMinificationFilter
+     * @see ImageryLayer#magnificationFilter
      */
     var TextureMagnificationFilter = {
+        /**
+         * Nearest neighbor sampling of image pixels to texture.
+         */
         NEAREST : WebGLConstants.NEAREST,
+        /**
+         * Bi-linear interpolation of image pixels to texture.
+         */
         LINEAR : WebGLConstants.LINEAR,
 
+        /**
+         * Validates the given <code>textureMinificationFilter</code> with respect to the possible enum values.
+         *
+         * @param textureMagnificationFilter
+         * @returns {boolean} <code>true</code> if <code>textureMagnificationFilter</code> is valid.
+         */
         validate : function(textureMagnificationFilter) {
             return ((textureMagnificationFilter === TextureMagnificationFilter.NEAREST) ||
                     (textureMagnificationFilter === TextureMagnificationFilter.LINEAR));

Source/Renderer/TextureMinificationFilter.js

@@ -7,16 +7,46 @@ define([
     'use strict';
 
     /**
-     * @private
+     * 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.
+     *
+     * @alias TextureMinificationFilter
+     *
+     * @see TextureMagnificationFilter
+     * @see ImageryLayer#minificationFilter
      */
     var TextureMinificationFilter = {
+        /**
+         * Nearest neighbor sampling of image pixels to texture.
+         */
         NEAREST : WebGLConstants.NEAREST,
+        /**
+         * Bi-linear interpolation of image pixels to texture.
+         */
         LINEAR : WebGLConstants.LINEAR,
+        /**
+         * WebGL <code>NEAREST_MIPMAP_NEAREST</code> interpolation of image pixels to texture.
+         */
         NEAREST_MIPMAP_NEAREST : WebGLConstants.NEAREST_MIPMAP_NEAREST,
+        /**
+         * WebGL <code>LINEAR_MIPMAP_NEAREST</code> interpolation of image pixels to texture.
+         */
         LINEAR_MIPMAP_NEAREST : WebGLConstants.LINEAR_MIPMAP_NEAREST,
+        /**
+         * WebGL <code>NEAREST_MIPMAP_LINEAR</code> interpolation of image pixels to texture.
+         */
         NEAREST_MIPMAP_LINEAR : WebGLConstants.NEAREST_MIPMAP_LINEAR,
+        /**
+         * WebGL <code>LINEAR_MIPMAP_LINEAR</code> interpolation of image pixels to texture.
+         */
         LINEAR_MIPMAP_LINEAR : WebGLConstants.LINEAR_MIPMAP_LINEAR,
 
+        /**
+         * Validates the given <code>textureMinificationFilter</code> with respect to the possible enum values.
+         *
+         * @param textureMinificationFilter
+         * @returns {boolean} <code>true</code> if <code>textureMinificationFilter</code> is valid.
+         */
         validate : function(textureMinificationFilter) {
             return ((textureMinificationFilter === TextureMinificationFilter.NEAREST) ||
                     (textureMinificationFilter === TextureMinificationFilter.LINEAR) ||

Source/Scene/ImageryLayer.js

@@ -136,6 +136,14 @@ define([
      *                          the gamma value to use for the tile.  The function is executed for every
      *                          frame and for every tile, so it must be fast.
      * @param {ImagerySplitDirection|Function} [options.splitDirection=ImagerySplitDirection.NONE] The {@link ImagerySplitDirection} split to apply to this layer.
+     * @param {TextureMinificationFilter} [options.minificationFilter=TextureMinificationFilter.LINEAR] The
+     *                                    texture minification filter to apply to this layer. Possible values
+     *                                    are <code>TextureMinificationFilter.LINEAR</code> and
+     *                                    <code>TextureMinificationFilter.NEAREST</code>.
+     * @param {TextureMagnificationFilter} [options.magnificationFilter=TextureMagnificationFilter.LINEAR] The
+     *                                     texture minification filter to apply to this layer. Possible values
+     *                                     are <code>TextureMagnificationFilter.LINEAR</code> and
+     *                                     <code>TextureMagnificationFilter.NEAREST</code>.
      * @param {Boolean} [options.show=true] True if the layer is shown; otherwise, false.
      * @param {Number} [options.maximumAnisotropy=maximum supported] The maximum anisotropy level to use
      *        for texture filtering.  If this parameter is not specified, the maximum anisotropy supported
@@ -211,6 +219,26 @@ define([
          */
         this.splitDirection = defaultValue(options.splitDirection, defaultValue(imageryProvider.defaultSplit, ImageryLayer.DEFAULT_SPLIT));
 
+        /**
+         * The {@link TextureMinificationFilter} to apply to this layer.
+         * Possible values are {@link TextureMinificationFilter.LINEAR} (the default)
+         * and {@link TextureMinificationFilter.NEAREST}.
+         *
+         * @type {TextureMinificationFilter}
+         * @default {@link ImageryLayer.DEFAULT_MINIFICATION_FILTER}
+         */
+        this.minificationFilter = defaultValue(options.minificationFilter, defaultValue(imageryProvider.defaultMinificationFilter, ImageryLayer.DEFAULT_MINIFICATION_FILTER));
+
+        /**
+         * The {@link TextureMagnificationFilter} to apply to this layer.
+         * Possible values are {@link TextureMagnificationFilter.LINEAR} (the default)
+         * and {@link TextureMagnificationFilter.NEAREST}.
+         *
+         * @type {TextureMagnificationFilter}
+         * @default {@link ImageryLayer.DEFAULT_MAGNIFICATION_FILTER}
+         */
+        this.magnificationFilter = defaultValue(options.magnificationFilter, defaultValue(imageryProvider.defaultMagnificationFilter, ImageryLayer.DEFAULT_MAGNIFICATION_FILTER));
+
         /**
          * Determines if this layer is shown.
          *
@@ -309,13 +337,29 @@ define([
     ImageryLayer.DEFAULT_GAMMA = 1.0;
 
     /**
-     * This value is used as the default spliat for the imagery layer if one is not provided during construction
+     * This value is used as the default split for the imagery layer if one is not provided during construction
      * or by the imagery provider.
      * @type {ImagerySplitDirection}
      * @default ImagerySplitDirection.NONE
      */
     ImageryLayer.DEFAULT_SPLIT = ImagerySplitDirection.NONE;
 
+    /**
+     * This value is used as the default texture magnification filter for the imagery layer if one is not provided
+     * during construction or by the imagery provider.
+     * @type {TextureMagnificationFilter}
+     * @default TextureMagnificationFilter.LINEAR
+     */
+    ImageryLayer.DEFAULT_MAGNIFICATION_FILTER = TextureMagnificationFilter.LINEAR;
+
+    /**
+     * This value is used as the default texture minification filter for the imagery layer if one is not provided
+     * during construction or by the imagery provider.
+     * @type {TextureMinificationFilter}
+     * @default TextureMinificationFilter.LINEAR
+     */
+    ImageryLayer.DEFAULT_MINIFICATION_FILTER = TextureMinificationFilter.LINEAR;
+
     /**
      * Gets a value indicating whether this layer is the base layer in the
      * {@link ImageryLayerCollection}.  The base layer is the one that underlies all
@@ -764,6 +808,11 @@ define([
             }
         }
 
+        var sampler = new Sampler({
+            minificationFilter : this.minificationFilter,
+            magnificationFilter : this.magnificationFilter
+        });
+
         // Imagery does not need to be discarded, so upload it to WebGL.
         var texture;
         if (defined(image.internalFormat)) {
@@ -774,13 +823,15 @@ define([
                 height : image.height,
                 source : {
                     arrayBufferView : image.bufferView
-                }
+                },
+                sampler: sampler
             });
         } else {
             texture = new Texture({
                 context : context,
                 source : image,
-                pixelFormat : imageryProvider.hasAlphaChannel ? PixelFormat.RGBA : PixelFormat.RGB
+                pixelFormat : imageryProvider.hasAlphaChannel ? PixelFormat.RGBA : PixelFormat.RGB,
+                sampler: sampler
             });
         }
 
@@ -799,11 +850,17 @@ define([
             var mipmapSampler = context.cache.imageryLayer_mipmapSampler;
             if (!defined(mipmapSampler)) {
                 var maximumSupportedAnisotropy = ContextLimits.maximumTextureFilterAnisotropy;
+                var mipmapMinificationFilter = imageryLayer.minificationFilter;
+                if (imageryLayer.minificationFilter === TextureMinificationFilter.NEAREST) {
+                    mipmapMinificationFilter = TextureMinificationFilter.NEAREST_MIPMAP_NEAREST;
+                } else if (imageryLayer.minificationFilter === TextureMinificationFilter.LINEAR) {
+                    mipmapMinificationFilter = TextureMinificationFilter.LINEAR_MIPMAP_LINEAR;
+                }
                 mipmapSampler = context.cache.imageryLayer_mipmapSampler = new Sampler({
                     wrapS : TextureWrap.CLAMP_TO_EDGE,
                     wrapT : TextureWrap.CLAMP_TO_EDGE,
-                    minificationFilter : TextureMinificationFilter.LINEAR_MIPMAP_LINEAR,
-                    magnificationFilter : TextureMagnificationFilter.LINEAR,
+                    minificationFilter : mipmapMinificationFilter,
+                    magnificationFilter : imageryLayer.magnificationFilter,
                     maximumAnisotropy : Math.min(maximumSupportedAnisotropy, defaultValue(imageryLayer._maximumAnisotropy, maximumSupportedAnisotropy))
                 });
             }
@@ -815,8 +872,8 @@ define([
                 nonMipmapSampler = context.cache.imageryLayer_nonMipmapSampler = new Sampler({
                     wrapS : TextureWrap.CLAMP_TO_EDGE,
                     wrapT : TextureWrap.CLAMP_TO_EDGE,
-                    minificationFilter : TextureMinificationFilter.LINEAR,
-                    magnificationFilter : TextureMagnificationFilter.LINEAR
+                    minificationFilter : imageryLayer.minificationFilter,
+                    magnificationFilter : imageryLayer.magnificationFilter
                 });
             }
             texture.sampler = nonMipmapSampler;

Specs/Scene/ImageryLayerSpec.js

@@ -7,6 +7,8 @@ defineSuite([
         'Core/Rectangle',
         'Core/RequestScheduler',
         'Renderer/ComputeEngine',
+        'Renderer/TextureMagnificationFilter',
+        'Renderer/TextureMinificationFilter',
         'Scene/ArcGisMapServerImageryProvider',
         'Scene/BingMapsImageryProvider',
         'Scene/createTileMapServiceImageryProvider',
@@ -30,6 +32,8 @@ defineSuite([
         Rectangle,
         RequestScheduler,
         ComputeEngine,
+        TextureMagnificationFilter,
+        TextureMinificationFilter,
         ArcGisMapServerImageryProvider,
         BingMapsImageryProvider,
         createTileMapServiceImageryProvider,
@@ -367,6 +371,25 @@ defineSuite([
         expect(layer.isDestroyed()).toEqual(true);
     });
 
+    it('texture filter properties work as expected', function() {
+        var provider = new SingleTileImageryProvider({
+            url : 'Data/Images/Red16x16.png'
+        });
+
+        var layer = new ImageryLayer(provider, {});
+        expect(layer.magnificationFilter).toEqual(TextureMagnificationFilter.LINEAR);
+        expect(layer.minificationFilter).toEqual(TextureMinificationFilter.LINEAR);
+        layer.destroy();
+
+        layer = new ImageryLayer(provider, {
+            magnificationFilter: TextureMagnificationFilter.NEAREST,
+            minificationFilter: TextureMinificationFilter.NEAREST
+        });
+        expect(layer.magnificationFilter).toEqual(TextureMagnificationFilter.NEAREST);
+        expect(layer.minificationFilter).toEqual(TextureMinificationFilter.NEAREST);
+        layer.destroy();
+    });
+
     it('returns HTTP status code information in TileProviderError', function() {
         // Web browsers unfortunately provide very little information about what went wrong when an Image fails
         // to load.  But when an imagery provider is configured to use a TileDiscardPolicy, Cesium downloads the image