From fcc850e217e3f907c3951e077da52cec9dab1e40 Mon Sep 17 00:00:00 2001
From: Tim Deubler <tim.deubler@here.com>
Date: Wed, 13 Sep 2023 12:17:55 +0200
Subject: [PATCH] added(display): LayerStyles backgroundColor now supports
 dynamic colors taking zoom level into account.

updated docs

Signed-off-by: Tim Deubler <tim.deubler@here.com>
---
 packages/core/src/styles/BoxStyle.ts          | 16 ++-----
 packages/core/src/styles/CircleStyle.ts       | 16 ++-----
 packages/core/src/styles/GenericStyle.ts      | 16 ++-----
 packages/core/src/styles/LayerStyle.ts        | 26 +++++-----
 packages/core/src/styles/LineStyle.ts         |  9 ++--
 packages/core/src/styles/PolygonStyle.ts      | 16 ++-----
 packages/core/src/styles/RectStyle.ts         | 16 ++-----
 packages/core/src/styles/SphereStyle.ts       |  9 ++--
 packages/core/src/styles/TextStyle.ts         | 16 ++-----
 packages/core/src/styles/VerticalLineStyle.ts |  9 ++--
 packages/display/src/displays/BasicDisplay.ts | 48 ++++++++++++++-----
 packages/display/src/displays/styleTools.ts   | 19 ++++----
 .../display/src/displays/webgl/Display.ts     |  2 +-
 13 files changed, 99 insertions(+), 119 deletions(-)

diff --git a/packages/core/src/styles/BoxStyle.ts b/packages/core/src/styles/BoxStyle.ts
index 237e06009..e5b6bdf0d 100644
--- a/packages/core/src/styles/BoxStyle.ts
+++ b/packages/core/src/styles/BoxStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 
 /**
@@ -49,22 +49,16 @@ export interface BoxStyle {
     /**
      * Sets the color to fill the Box.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    fill?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    fill?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the stroke color of the Box.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the width of the stroke.
diff --git a/packages/core/src/styles/CircleStyle.ts b/packages/core/src/styles/CircleStyle.ts
index f2e6fdba3..ec0cceed2 100644
--- a/packages/core/src/styles/CircleStyle.ts
+++ b/packages/core/src/styles/CircleStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 /**
  * Interface for configuring the visual appearance of Circles.
@@ -48,22 +48,16 @@ export interface CircleStyle {
     /**
      * Sets the color to fill the Circle.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    fill?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    fill?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the stroke color of the Circle.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the width of the stroke.
diff --git a/packages/core/src/styles/GenericStyle.ts b/packages/core/src/styles/GenericStyle.ts
index a75db214d..5c23e3075 100644
--- a/packages/core/src/styles/GenericStyle.ts
+++ b/packages/core/src/styles/GenericStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 import {LinearGradient} from '@here/xyz-maps-core';
 
 /**
@@ -95,23 +95,17 @@ export interface Style {
      * Sets the color to fill the shape.
      * This attribute is valid for Circle, Rect, Text and Polygon.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    fill?: string | StyleValueFunction<string> | StyleZoomRange<string> | LinearGradient;
+    fill?: Color | StyleValueFunction<Color> | StyleZoomRange<Color> | LinearGradient;
 
     /**
      * Sets the stroke color of the shape.
      * This attribute is valid for Circle, Rect, Line, Text and Polygon.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the width of the stroke.
diff --git a/packages/core/src/styles/LayerStyle.ts b/packages/core/src/styles/LayerStyle.ts
index 7d604c5e3..816633c4d 100644
--- a/packages/core/src/styles/LayerStyle.ts
+++ b/packages/core/src/styles/LayerStyle.ts
@@ -19,18 +19,6 @@
 
 import {Feature} from '../features/Feature';
 import {Style} from './GenericStyle';
-import {ModelStyle} from '@here/xyz-maps-core';
-import Model from '@here/xyz-maps-display/src/displays/webgl/program/Model';
-import {LineStyle} from './LineStyle';
-import {VerticalLineStyle} from './VerticalLineStyle';
-import {Line} from '@here/xyz-maps-editor';
-import {PolygonStyle} from './PolygonStyle';
-import {RectStyle} from './RectStyle';
-import {CircleStyle} from './CircleStyle';
-import {ImageStyle} from './ImageStyle';
-import {BoxStyle} from './BoxStyle';
-import {SphereStyle} from './SphereStyle';
-import {TextStyle} from './TextStyle';
 
 
 /**
@@ -89,6 +77,18 @@ export type StyleGroup = Array<Style>;
 
 // (<LineStyle>testStyle[0]).stroke;
 
+/**
+ * The Color is an RGBA color value representing RED, GREEN, and BLUE light sources with an optional alpha channel.
+ * Colors can be specified in the following ways:
+ * - CSS color names: "red"
+ * - RGB colors: "rgb(255,0,0)"
+ * - RGBA colors: "rgba(255,0,0,1.0)"
+ * - Hexadecimal colors: "#ff0000" | "#f00"
+ * - Hexadecimal colors with transparency: "#ff0000ff"
+ * - hexadecimal numbers: 0xff0000
+ * - RGBA Color Array: [1.0, 0.0, 0.0, 1.0]
+ */
+export type Color = string | number | [number, number, number, number];
 
 /**
  * This is an interface to describe how certain features should be rendered within a layer.
@@ -119,7 +119,7 @@ export interface LayerStyle {
     /**
      * the color for the background of the layer
      */
-    backgroundColor?: string;
+    backgroundColor?: Color | StyleZoomRange<Color> | ((zoomlevel: number) => Color);
 
     /**
      *  This object contains key/styleGroup pairs.
diff --git a/packages/core/src/styles/LineStyle.ts b/packages/core/src/styles/LineStyle.ts
index ba5fab374..52c28b6d2 100644
--- a/packages/core/src/styles/LineStyle.ts
+++ b/packages/core/src/styles/LineStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 /**
  * Interface for configuring the visual appearance of Lines.
@@ -50,12 +50,9 @@ export interface LineStyle {
     /**
      * Sets the stroke color of the Line.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the width of the line.
diff --git a/packages/core/src/styles/PolygonStyle.ts b/packages/core/src/styles/PolygonStyle.ts
index bc8bbcb86..3c0c8cd1c 100644
--- a/packages/core/src/styles/PolygonStyle.ts
+++ b/packages/core/src/styles/PolygonStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 /**
  * Interface for configuring the visual appearance of Polygons.
@@ -48,22 +48,16 @@ export interface PolygonStyle {
     /**
      * Sets the color to fill the polygon.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    fill?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    fill?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the stroke color of the polygon.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the width of the stroke of the polygon (outline).
diff --git a/packages/core/src/styles/RectStyle.ts b/packages/core/src/styles/RectStyle.ts
index 047a1bf39..b0d0cfd83 100644
--- a/packages/core/src/styles/RectStyle.ts
+++ b/packages/core/src/styles/RectStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 export interface RectStyle {
     /**
@@ -45,22 +45,16 @@ export interface RectStyle {
     /**
      * Sets the color to fill the Rectangle.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    fill?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    fill?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the stroke color of the Rectangle.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the width of the Rectangle.
diff --git a/packages/core/src/styles/SphereStyle.ts b/packages/core/src/styles/SphereStyle.ts
index c099f0f78..d889a579c 100644
--- a/packages/core/src/styles/SphereStyle.ts
+++ b/packages/core/src/styles/SphereStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 /**
  * Interface for configuring the visual appearance of Rectangles.
@@ -49,12 +49,9 @@ export interface SphereStyle {
      * Sets the color to fill the Sphere.
      * This attribute is valid for Circle, Rect, Text and Polygon.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    fill?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    fill?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Defines the opacity of the style.
diff --git a/packages/core/src/styles/TextStyle.ts b/packages/core/src/styles/TextStyle.ts
index 272065765..0ce064dd9 100644
--- a/packages/core/src/styles/TextStyle.ts
+++ b/packages/core/src/styles/TextStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 /**
  * Interface for configuring the visual appearance of Text.
@@ -48,22 +48,16 @@ export interface TextStyle {
     /**
      * Sets the color to fill the text.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    fill?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    fill?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the stroke color of the text (outline).
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Sets the width of the stroke (outline) to display the text with.
diff --git a/packages/core/src/styles/VerticalLineStyle.ts b/packages/core/src/styles/VerticalLineStyle.ts
index 3a39ea30a..c6098b86c 100644
--- a/packages/core/src/styles/VerticalLineStyle.ts
+++ b/packages/core/src/styles/VerticalLineStyle.ts
@@ -16,7 +16,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * License-Filename: LICENSE
  */
-import {StyleValueFunction, StyleZoomRange} from './LayerStyle';
+import {Color, StyleValueFunction, StyleZoomRange} from './LayerStyle';
 
 
 /**
@@ -49,12 +49,9 @@ export interface VerticalLineStyle {
     /**
      * Sets the stroke color of the shape.
      *
-     * The color can be specified in the following ways:
-     * - CSS color names: "red"
-     * - RGB(A) values: "rgba(255,0,0,1.0)"
-     * - hexadecimal values: "#ff0000"
+     * @see {@link Color} for a detailed list of possible supported formats.
      */
-    stroke?: string | StyleValueFunction<string> | StyleZoomRange<string>;
+    stroke?: Color | StyleValueFunction<Color> | StyleZoomRange<Color>;
 
     /**
      * Defines the opacity of the style.
diff --git a/packages/display/src/displays/BasicDisplay.ts b/packages/display/src/displays/BasicDisplay.ts
index a43e7e28f..2b4f6ef83 100644
--- a/packages/display/src/displays/BasicDisplay.ts
+++ b/packages/display/src/displays/BasicDisplay.ts
@@ -28,6 +28,8 @@ import BasicBucket from './BasicBucket';
 import Preview from './Preview';
 import LayerClusterer from './LayerClusterer';
 import Grid, {ViewportTile} from '../Grid';
+import {createZoomRangeFunction, parseColorMap} from './styleTools';
+import {RGBA} from './webgl/color';
 
 const CREATE_IF_NOT_EXISTS = true;
 const MAX_PITCH_GRID = 60 / 180 * Math.PI;
@@ -47,14 +49,6 @@ const exclusiveTimeMS = 4;
 let UNDEF;
 
 abstract class Display {
-    static getPixelRatio(dpr: string | number | any) {
-        dpr = dpr == 'auto'
-            ? Math.min(2, global.devicePixelRatio || 1)
-            : dpr || 1;
-
-        return dpr < 1 ? 1 : dpr;
-    }
-
     private previewer: Preview;
     private updating: boolean = false;
     private ti: number; // tile index
@@ -63,8 +57,12 @@ abstract class Display {
     protected sx: number; // grid/screen offset x (includes scale offset)
     protected sy: number; // grid/screen offset y (includes scale offset)
     protected dirty: boolean = false;
+
     private centerWorld: number[]; // absolute world center xy0
 
+    protected bgColor: RGBA;
+    globalBgc: boolean | string | [number, number, number, number?] = false;
+
     tileSize: number;
     layers: Layers;
     dpr: number;
@@ -148,6 +146,14 @@ abstract class Display {
         };
     }
 
+    static getPixelRatio(dpr: string | number | any) {
+        dpr = dpr == 'auto'
+            ? Math.min(2, global.devicePixelRatio || 1)
+            : dpr || 1;
+
+        return dpr < 1 ? 1 : dpr;
+    }
+
     addLayer(layer: TileLayer | CustomLayer, styles, index: number): boolean {
         const display = this;
         const layers = display.layers;
@@ -271,14 +277,29 @@ abstract class Display {
     abstract project(x: number, y: number, z?: number): number[];
 
     private setLayerBgColor(style, dLayer: Layer) {
-        const {backgroundColor} = style;
-        const display = this;
+        let {backgroundColor} = style;
 
         if (backgroundColor) {
-            dLayer.bgColor = display.render.convertColor(backgroundColor);
+            if (typeof backgroundColor == 'object' && !Array.isArray(backgroundColor)) {
+                backgroundColor = createZoomRangeFunction(parseColorMap(backgroundColor));
+            }
+            dLayer.bgColor = typeof backgroundColor == 'function'
+                ? backgroundColor
+                : this.render.convertColor(backgroundColor);
         }
     }
 
+    private processLayerBackgroundColor(zoomlevel?: number) {
+        const display = this;
+        const layers = display.layers;
+        let bgColor = layers[0]?.bgColor;
+
+        if (typeof bgColor == 'function') {
+            bgColor = display.render.convertColor(bgColor(zoomlevel));
+        }
+        this.bgColor = bgColor || display.globalBgc;
+    }
+
     private isVisible(tile: Tile, dLayer: Layer): boolean {
         const qk = tile.quadkey;
         for (let screen of dLayer.tiles) {
@@ -289,6 +310,7 @@ abstract class Display {
         return false;
     }
 
+
     getContext() {
         return this.render.getContext();
     }
@@ -448,6 +470,8 @@ abstract class Display {
         const tileGridZoom = zoomlevel ^ 0;
         // const worldSize = Math.pow(2, zoomlevel) * this.tileSize;
 
+        this.processLayerBackgroundColor(zoomlevel);
+
         this.viewChange = true;
         this.sx = screenOffsetX;
         this.sy = screenOffsetY;
@@ -536,8 +560,6 @@ abstract class Display {
         }
     }
 
-    globalBgc: boolean | string | [number, number, number, number?] = false;
-
     setBGColor(color?: string) {
         const displ = this;
         const {render} = displ;
diff --git a/packages/display/src/displays/styleTools.ts b/packages/display/src/displays/styleTools.ts
index b43ee5afe..fc1f72f90 100644
--- a/packages/display/src/displays/styleTools.ts
+++ b/packages/display/src/displays/styleTools.ts
@@ -19,7 +19,7 @@
 
 import {wrapText} from './textUtils';
 import {Feature, StyleZoomRange} from '@here/xyz-maps-core';
-import {toRGB} from './webgl/color';
+import {RGBA, toRGB} from './webgl/color';
 import {getRotatedBBox} from '../geometry';
 import {webMercator, Style, StyleGroup} from '@here/xyz-maps-core';
 
@@ -469,16 +469,18 @@ const fillMap = (map, searchMap, parseSizeValue: boolean) => {
 };
 
 
-const parseColors = (map) => {
+export const parseColorMap = (map: { [zoom: string]: RGBA }) => {
     for (let z in map) {
         map[z] = toRGB(map[z]);
     }
+    return map;
 };
 
-const createZoomRangeFunction = (map) => {
-    // const range = new Function('f,zoom', `return (${JSON.stringify(map)})[zoom];`);
+export const createZoomRangeFunction = (map: StyleZoomRange<RGBA>, /* isFeatureContext?:boolean,*/ parseSizeValue?: boolean) => {
+    map = fillMap({}, map, parseSizeValue);
+    // return new Function('f,zoom', `return (${JSON.stringify(map)})[zoom];`);
     const range = (feature, zoom: number) => {
-        return map[zoom];
+        return map[zoom ?? feature];
     };
     range.map = map; // dbg
 
@@ -501,13 +503,14 @@ const parseStyleGroup = (styleGroup: Style[]) => {
                         // "zoomrange" value detected
                         if (name == 'stroke' || name == 'fill') {
                             // convert to [r,g,b,a]
-                            parseColors(value);
+                            parseColorMap(value);
                         }
 
                         const parseSizeValue = !allowedFloatProperties[name];
 
-                        let map = fillMap({}, value, parseSizeValue);
-                        style[name] = createZoomRangeFunction(map);
+                        style[name] = createZoomRangeFunction(value, parseSizeValue);
+                        // let map = fillMap({}, value, parseSizeValue);
+                        // style[name] = createZoomRangeFunction(map);
                     }
                 }
             }
diff --git a/packages/display/src/displays/webgl/Display.ts b/packages/display/src/displays/webgl/Display.ts
index daa243e61..46c419cee 100644
--- a/packages/display/src/displays/webgl/Display.ts
+++ b/packages/display/src/displays/webgl/Display.ts
@@ -485,7 +485,7 @@ class WebGlDisplay extends BasicDisplay {
             );
         }
 
-        render.clear((layerLength && layers[0].bgColor) || display.globalBgc);
+        render.clear(display.bgColor);
 
         render.fixedView = Number(!this.viewChange);