@tomtom-org/maps-sdk-plugin-landmarks-3d 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,203 +1,139 @@
-import { KnobConfigOf, KnobEntry, KnobRange, KnobValueOf, TomTomMap } from "@tomtom-org/maps-sdk/map";
+import { _ as Buildings3DKnobValueOf, c as LandmarkTextureUse, d as Landmarks3DKnobValueOf, g as Buildings3DKnobId, n as GLSurfacesKnobId, r as GLSurfacesKnobValueOf, u as Landmarks3DKnobId, w as PaletteMode } from "./surfacesKnobCatalogue-B1prY4bG.js";
+import { BeforeLayerConfig, CustomLayer, EventState, KnobConfigOf, TomTomMap } from "@tomtom-org/maps-sdk/map";
+import { AmbientLight, Camera, DataTexture, DirectionalLight, Group, IUniform, Mesh, Object3D, Scene, ShaderMaterial, Texture, Vector3, Vector4, WebGLRenderer } from "three";
 import { CustomLayerInterface, CustomRenderMethodInput, Map } from "maplibre-gl";
-import { AmbientLight, Camera, DirectionalLight, Group, IUniform, Mesh, Object3D, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
-//#region src/buildings/buildingsKnobCatalogue.d.ts
+//#region src/highlights.d.ts
+type HighlightLooks = Readonly<Record<`${'hover' | 'click'}.color`, string> & Record<`${'hover' | 'click'}.intensity`, number>>;
 /**
- * How the windows of a facade are laid out. `mixed` picks one per building, by its height: punched
- * windows on low ones, office bands from about six storeys and glass curtain walls on towers.
+ * A building of a {@link Buildings3D} or a landmark of a {@link Landmarks3D}, as their user events report it.
  *
- * @group Buildings 3D
- */
-export declare const facadePatterns: readonly ["mixed", "residential", "office", "glass", "plain"];
-/**
- * One of {@link facadePatterns}.
+ * @example
+ * ```typescript
+ * buildings.events.on('click', (building: BuildingHit) => console.log(building.id, building.properties.height));
+ * ```
  *
  * @group Buildings 3D
  */
-type FacadePattern = (typeof facadePatterns)[number];
+type BuildingHit = {
+  /**
+   * A building's feature id in the map's vector tiles, the same in every tile and zoom level that
+   * holds it. The tiles split a building of several heights into parts, which the plugin draws,
+   * colours and lights up as one, under the id of the building's whole outline. A landmark's id is a
+   * number taken from its position, the same in every session.
+   */
+  id: number | string;
+  /**
+   * A building's feature properties, such as `height` and `group`, its whole outline's when it comes in
+   * parts. A landmark's `position`, as `[longitude, latitude]`.
+   */
+  properties: Record<string, unknown>;
+};
 /**
- * The looks the unset knobs take: one per standard style, or `auto`, which follows the map's style.
- *
- * @group Buildings 3D
+ * The uniforms {@link HIGHLIGHT_GLSL} reads, which the materials of one layer share by reference.
+ * @ignore
  */
-export declare const buildingsPresets: readonly ["auto", "streetLight", "streetDark", "streetLightDriving", "streetDarkDriving", "monoLight", "monoDark", "streetSatellite"];
+type HighlightUniforms = Record<'objectColors', IUniform<DataTexture>> & Record<'hoveredObject' | 'clickedObject', IUniform<number>> & Record<'hoverHighlight' | 'clickHighlight', IUniform<Vector4>>;
 /**
- * One of {@link buildingsPresets}.
- *
- * @group Buildings 3D
+ * The buildings or landmarks of one layer as its shaders highlight them: a compact index for each, by the
+ * id it has in the map's data, the colour an app gives it, and which one is hovered and which clicked.
+ * @ignore
  */
-type BuildingsPreset = (typeof buildingsPresets)[number];
-declare const buildingsKnobDefinitions: {
-  readonly visible: {
-    readonly kind: "toggle";
-    readonly description: "The 3D buildings.";
-    readonly default: true;
-  };
-  readonly preset: {
-    readonly kind: "enum";
-    readonly description: "Look every unset knob takes: a standard style's, or auto, which follows the map's standard style.";
-    readonly options: readonly ["auto", "streetLight", "streetDark", "streetLightDriving", "streetDarkDriving", "monoLight", "monoDark", "streetSatellite"];
-    readonly default: "auto";
-  };
-  readonly opacity: {
-    readonly kind: "number";
-    readonly description: "Opacity of the buildings, and of the landmarks left unset among them, 0 to 1.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly minZoom: {
-    readonly kind: "number";
-    readonly description: "Lowest zoom the buildings are drawn at, and the landmarks left unset among them.";
-    readonly range: {
-      readonly min: 13;
-      readonly max: 22;
-      readonly step: 1;
-      readonly bounds: "hard";
-    };
-  };
-  readonly 'facade.pattern': {
-    readonly kind: "enum";
-    readonly description: "How windows are laid out: mixed (by building height), residential, office, glass (curtain walls) or plain (no windows).";
-    readonly options: readonly ["mixed", "residential", "office", "glass", "plain"];
-  };
-  readonly 'facade.intensity': {
-    readonly kind: "number";
-    readonly description: "How strongly the windows show on the walls, and the landmarks' own texture among the buildings while their texture is detail, 0 (plain walls) to 1.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly 'facade.floorHeightMeters': {
-    readonly kind: "number";
-    readonly description: "Height of one storey, which spaces the rows of windows. The ground floor is a third taller.";
-    readonly range: {
-      readonly min: 2.5;
-      readonly max: 6;
-      readonly step: 0.1;
-      readonly bounds: "hard-min";
-    };
-  };
-  readonly 'walls.color': {
-    readonly kind: "color";
-    readonly description: "Colour of the walls. Unset: the map style's 3D building colour of each kind of building, following the map colours that restyle them, and the colour of the buildings of no named kind is the one reported. Landmarks left unset among the buildings take it too.";
-  };
-  readonly 'roofs.color': {
-    readonly kind: "color";
-    readonly description: "Colour of the roofs. Unset: a shade darker than the walls of each building, and the colour reported is the walls' one.";
-  };
-  readonly 'windows.color': {
-    readonly kind: "color";
-    readonly description: "Colour of the window glass.";
-  };
-  readonly 'reflections.intensity': {
-    readonly kind: "number";
-    readonly description: "How much the window glass mirrors the street, the facades across it and the sky, and catches the sun, 0 (matte) to 1. Glass curtain walls reflect the most, landmarks a little; the sky's colour is the ambient light's.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly 'litWindows.color': {
-    readonly kind: "color";
-    readonly description: "Colour of the windows lit from inside.";
-  };
-  readonly 'litWindows.fraction': {
-    readonly kind: "number";
-    readonly description: "Share of the windows lit from inside, 0 to 1. The dark presets light some.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly 'litWindows.intensity': {
-    readonly kind: "number";
-    readonly description: "Brightness of the lit windows, 0 to 1. Pair it with the map effects bloom for a night glow.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly 'light.direction': {
-    readonly kind: "number";
-    readonly description: "Direction the light comes from, in degrees clockwise from north. Shadows fall the opposite way.";
-    readonly range: {
-      readonly min: 0;
-      readonly max: 359;
-      readonly step: 1;
-      readonly bounds: "hard";
-    };
-  };
-  readonly 'light.altitude': {
-    readonly kind: "number";
-    readonly description: "Height of the light above the horizon, in degrees (90 = overhead); lower casts longer shadows.";
-    readonly range: {
-      readonly min: 5;
-      readonly max: 90;
-      readonly step: 1;
-      readonly bounds: "hard";
-    };
-  };
-  readonly 'light.color': {
-    readonly kind: "color";
-    readonly description: "Colour of the light: the sun on light presets, the moon on dark ones.";
-  };
-  readonly 'light.intensity': {
-    readonly kind: "number";
-    readonly description: "Strength of the light, 0 to 1.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly 'ambientLight.color': {
-    readonly kind: "color";
-    readonly description: "Colour of the light from the sky, which also tints the reflections in the glass.";
-  };
-  readonly 'ambientLight.intensity': {
-    readonly kind: "number";
-    readonly description: "Strength of the light from the sky, 0 to 1, which lights the walls in shade.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly 'shadows.visible': {
-    readonly kind: "toggle";
-    readonly description: "Shadows the buildings and the landmarks among them cast, on each other and on the ground.";
-  };
-  readonly 'shadows.intensity': {
-    readonly kind: "number";
-    readonly description: "Darkness of the shadows, 0 to 1.";
-    readonly range: import("@tomtom-org/maps-sdk/map").KnobRange;
-  };
-  readonly 'roadLabels.occluded': {
-    readonly kind: "toggle";
-    readonly description: "Road names draw under the buildings: hidden wherever a building covers them, they give way to the labels above them.";
-  };
-  readonly 'pois.occluded': {
-    readonly kind: "toggle";
-    readonly description: "The style's POIs draw under the buildings: hidden wherever a building covers them, still keeping other labels off, they give way to the labels above them.";
-  };
-};
+declare class ObjectHighlights {
+  readonly uniforms: HighlightUniforms;
+  private readonly indices;
+  private readonly objects;
+  private readonly states;
+  private colors;
+  /** The index of the object with this id, registered on first sight; later properties replace earlier ones. */
+  indexOf(id: number | string, properties?: Record<string, unknown>): number;
+  /** The object at an index, as user events report it. */
+  objectAt(index: number): BuildingHit | undefined;
+  /** Gives the objects with these ids their colour, and every other one its own back. */
+  setColors(colors: Readonly<Record<string, string>>): void;
+  /** The colours {@link setColors} gave, by id. */
+  getColors(): Record<string, string>;
+  /** Sets how the hovered and the clicked object show. */
+  setLook(look: HighlightLooks): void;
+  /** Takes an object's event state, as the SDK hands it to a custom layer. */
+  setState(id: number | string, state: EventState | undefined): void;
+  private get table();
+  private indexOfKey;
+  private writeColor;
+  private growTable;
+}
+//#endregion
+//#region src/knobConfigured.d.ts
 /**
- * The id of a buildings knob, as accepted by the SDK's `setKnob` and as a path into {@link Buildings3DConfig}.
+ * A feature configured by knobs, as {@link Buildings3D} and {@link GLSurfaces} are: it holds the
+ * knobs set, hands them out as a copy, merges a partial set into them, unsets them, and reads and
+ * writes them by id for the SDK's `getKnob`, `setKnobs` and `resetKnob`. The feature supplies
+ * {@link applyConfig}, which puts a whole configuration into effect, and {@link _knobValue}.
  *
- * @group Buildings 3D
+ * It mirrors the SDK's own `AbstractMapModule`, which gives the map's modules this same shape.
+ * @ignore
  */
-type Buildings3DKnobId = keyof typeof buildingsKnobDefinitions;
-type KindOf<ID extends Buildings3DKnobId> = (typeof buildingsKnobDefinitions)[ID]['kind'];
+declare abstract class KnobConfigured<CONFIG extends {
+  visible?: boolean;
+}> {
+  protected config: CONFIG;
+  protected constructor(config: CONFIG);
+  /** Puts a whole configuration into effect, the feature's own way. */
+  abstract applyConfig(config: CONFIG): void;
+  /** @ignore */
+  abstract _knobValue(id: string): unknown;
+  /** Returns the knobs set, as a plain serializable copy. */
+  getConfig(): CONFIG;
+  /** Changes the given knobs and keeps the others, one level deep. */
+  updateConfig(partial: CONFIG): void;
+  /** Unsets every knob. */
+  resetConfig(): void;
+  /** Whether the feature is set to be shown: the `visible` knob, `true` unless set. */
+  isVisible(): boolean;
+  /** Shows or hides the feature. Stored as `visible` in the configuration. */
+  setVisible(visible: boolean): void;
+  /** @ignore */
+  _setKnobValues(values: Readonly<Record<string, unknown>>): void;
+  /** @ignore */
+  _resetKnobValue(id: string): void;
+  /**
+   * A knob's value from a resolved look. The map's light turns with the bearing by fractions of a
+   * degree, which the features draw with; the knob reports whole degrees, a value `setKnob` takes back.
+   */
+  protected lookValue(look: Record<string, unknown>, id: string): unknown;
+}
+//#endregion
+//#region src/palette.d.ts
 /**
- * The value type a buildings knob takes.
- *
- * @group Buildings 3D
+ * A palette as the buildings or the landmarks draw with it, every colour resolved.
+ * @ignore
  */
-type Buildings3DKnobValueOf<ID extends Buildings3DKnobId> = ID extends 'preset' ? BuildingsPreset : ID extends 'facade.pattern' ? FacadePattern : KnobValueOf<KindOf<ID>>;
+type PaletteChoice = {
+  colors: readonly string[];
+  mode: PaletteMode;
+  intensity: number;
+};
 /**
- * One entry of {@link buildings3DKnobCatalogue}, with what a UI or a coding agent needs to offer the
- * knob and validate a value for it. The SDK's `getKnob` reads the value in force.
- *
- * @group Buildings 3D
+ * How the buildings or the landmarks vary their colour from one to the next.
+ * @ignore
  */
-type Buildings3DKnob = KnobEntry<Buildings3DKnobId>;
+type PaletteLook = PaletteChoice & {
+  variation: number;
+};
 /**
- * Every buildings knob with its kind, description, range or options and, for `visible` and `preset`,
- * its default. It's static data, readable without a map.
- *
- * @remarks
- * A knob is a plain value in {@link Buildings3DConfig}, at its id's path. Every knob but `visible` and
- * `preset` takes the preset's value while unset, which the SDK's `getKnob` reports.
- *
- * @group Buildings 3D
+ * The uniforms {@link PALETTE_GLSL} reads.
+ * @ignore
  */
-export declare const buildings3DKnobCatalogue: readonly Buildings3DKnob[];
+type PaletteUniforms = Record<'paletteColors', IUniform<Vector3[]>> & Record<'paletteCount' | 'paletteBlend' | 'paletteIntensity' | 'colorVariation', IUniform<number>>;
+//#endregion
+//#region src/utils.d.ts
 /**
- * Every buildings knob id, in catalogue order.
- *
- * @group Buildings 3D
+ * Where a plugin's sun stands, by its light knobs, in degrees.
+ * @ignore
  */
-export declare const buildings3DKnobIds: readonly Buildings3DKnobId[];
+type LightKnobs = {
+  'light.direction': number;
+  'light.altitude': number;
+};
 //#endregion
 //#region src/buildings/buildingsLook.d.ts
 /**
@@ -215,12 +151,15 @@ type Buildings3DConfig = KnobConfigOf<{ [ID in Buildings3DKnobId]: Buildings3DKn
 type Values = { [ID in Buildings3DKnobId]: Buildings3DKnobValueOf<ID>; };
 /**
  * Every knob resolved to the value the buildings are drawn with, plus the per-kind wall colours the
- * walls take while `walls.color` is unset.
+ * walls take while `walls.color` is unset, and the wall palette with its map colours read.
  * @ignore
  */
 type Buildings3DLook = Values & {
   wallColorsByGroup: GroupColors;
   roofsFollowWalls: boolean;
+  roofColorSet: boolean;
+  wallPalette: PaletteLook;
+  roofPalette: PaletteChoice;
 };
 //#endregion
 //#region src/buildings/glass.d.ts
@@ -232,6 +171,20 @@ type Buildings3DLook = Values & {
  */
 type GlassUniforms = Record<'eyePosition' | 'sunDirection' | 'sunColor' | 'skyColor', IUniform<Vector3>> & Record<'skyIntensity' | 'reflectivity', IUniform<number>>;
 //#endregion
+//#region src/scenePicking.d.ts
+/**
+ * What lies first under a point of the map: a building, by its highlight index, or a landmark mesh, and
+ * how far along the ray from the eye, in scene metres.
+ * @ignore
+ */
+type ScenePick = {
+  building: number;
+  distance: number;
+} | {
+  landmark: Mesh;
+  distance: number;
+};
+//#endregion
 //#region src/basemapBuildings.d.ts
 /**
  * One colour per kind of {@link BUILDING_GROUPS}, in that order, then the one of every other building.
@@ -294,12 +247,20 @@ declare class BuildingsLayer implements CustomLayerInterface {
     id: string;
     layer: string;
   };
+  /**
+   * The buildings as user events report them, the colours an app gives them, and the hovered and clicked one.
+   * @ignore
+   */
+  readonly highlights: ObjectHighlights;
   private map?;
   private renderer?;
   private look?;
   private filter;
   private origin?;
   private frame;
+  private lastPick?;
+  private shadowsDrawnFrom;
+  private sceneVersion;
   private readonly scene;
   private readonly camera;
   private readonly buildings;
@@ -314,29 +275,50 @@ declare class BuildingsLayer implements CustomLayerInterface {
   private readonly tiles;
   private pending;
   private extrusion;
+  private readonly groundKeys;
+  private readonly shadowFromMercator;
+  private drawn;
   /**
    * @param landmarksOf - The landmarks to draw among the buildings, asked every frame. The buildings
    * they replace stay out in the frames that draw them.
    */
   constructor(id: string, landmarksOf?: () => LandmarksForBuildings | undefined);
+  /** Moves the sun alone, the rest of the look as it was. */
+  setSun(sun: LightKnobs): void;
   /** Draws the buildings with this look, from the next frame. */
   setLook(look: Buildings3DLook): void;
   onAdd(map: Map, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+  onRemove(map: Map): void;
   render(gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+  private enableShadowMap;
+  private draw;
+  private shareShadows;
   private renderTranslucent;
+  private shadowsStale;
   private useBuildingsPass;
   private placeLandmarks;
   private toScene;
   private updateOrigin;
   private carryTiles;
   private updateTiles;
+  private sourceKey;
   private queueTiles;
   private startExtrusion;
+  /**
+   * What the last frame drew first under a point of the map, in CSS pixels from its top left: one of
+   * its buildings, or one of the landmarks it drew among them.
+   * @ignore
+   */
+  pick(point: {
+    x: number;
+    y: number;
+  }): ScenePick | undefined;
   private addTileMesh;
   private removeTileMesh;
   private evictStaleTiles;
   private eyePosition;
   private groundMaterial;
+  private groundCornersInView;
   private updateSun;
 }
 //#endregion
@@ -352,16 +334,25 @@ declare class BuildingsLayer implements CustomLayerInterface {
  * - While it shows, it takes the place of the style's own 3D buildings, which it filters out of the
  *   `3D - Building` layer. It draws whether or not the `buildings3D` group of the `BaseMapModule` shows.
  * - Its look is a set of knobs, listed in {@link buildings3DKnobCatalogue}. Each one you leave unset
- *   takes the preset's value. The `auto` preset follows the map style: the dark street and mono styles
- *   light windows from inside under a moon, the others get a sun and glass that mirrors the street and the sky.
+ *   takes the preset's value, but the hover and click colours, which take the map's accent, else blue,
+ *   and the light's direction and altitude, below. The `auto` preset follows the map style: the dark
+ *   street and mono styles light windows from inside under a moon, the others get a sun and glass that
+ *   mirrors the street and the sky.
  * - Walls take the style's 3D building colour of each kind of building until you set `walls.color`,
- *   following the map colours that restyle them.
+ *   following the map colours that restyle them. `walls.palette`, an array of colours of your own, gives
+ *   each building one of them, and `walls.variation` a shade of its own. Roofs follow the walls, palette
+ *   included, until you set `roofs.color` or a `roofs.palette` of their own.
+ * - Its sun is the map's light once one is placed, such as through the styling module's
+ *   `view.light` knobs: `light.direction` and `light.altitude` each follow it while unset.
+ *   `GLSurfaces` follows the same light, so the shadows and the textured ground agree.
  * - On a map with a {@link Landmarks3D}, it leaves out the buildings a landmark replaces and draws the
  *   landmarks among its buildings, under its sun and in its shadows, which they cast too. They take its
- *   wall colour, opacity and `minZoom` for their unset knobs.
+ *   wall colour, opacity, `minZoom`, palette knobs, `walls.variation` and hover and click looks for their
+ *   unset knobs.
  *   Unless their `texture` knob says otherwise, their own textures show as facade detail, as strong as
- *   `facade.intensity`. They mirror a little of the street and the sky, as much as `reflections.intensity` sets.
- * - It draws at sea level, so on a 3D terrain hills cover the buildings' lower floors.
+ *   `facade.intensity`, and in their own colours over satellite imagery. They mirror a little of the street and the sky, as much as `reflections.intensity` sets.
+ * - On a 3D terrain, each building stands on the lowest ground under it, and the streets' shadows,
+ *   which fall on a flat plane, are left out.
  * - With `roadLabels.occluded` or `pois.occluded`, it moves those style layers under its own, so a
  *   building drawn over a label hides it. A hidden POI still keeps other labels off its place, and
  *   the moved labels give way to the labels above them where they collide.
@@ -376,11 +367,12 @@ declare class BuildingsLayer implements CustomLayerInterface {
  *
  * @group Buildings 3D
  */
-export declare class Buildings3D {
+export declare class Buildings3D extends KnobConfigured<Buildings3DConfig> {
   private readonly map;
   private readonly buildingsLayer;
-  private config;
+  private readonly customLayer;
   private renderedLook;
+  private followedLight;
   private styling;
   private readonly occludedLabels;
   private styleOrder;
@@ -396,153 +388,71 @@ export declare class Buildings3D {
    */
   get layer(): BuildingsLayer;
   /**
-   * Returns the knobs set, as a plain serializable copy. The SDK's `getKnob` reads a knob's value
-   * in force, the preset's one when unset.
-   */
-  getConfig(): Buildings3DConfig;
-  /**
-   * Replaces the whole configuration. An empty object has every knob take the `auto` preset's value.
+   * The user events of the buildings: a handler gets the building under the pointer, with its
+   * feature id and properties.
    *
    * @remarks
-   * Use it, and {@link updateConfig}, for a look your code writes: the type is the check, and the
-   * values are not checked again. For values held as data, the SDK's `setKnobs` checks each against
-   * {@link buildings3DKnobCatalogue} and sets them by id.
-   */
-  applyConfig(config: Buildings3DConfig): void;
-  /**
-   * Changes the given knobs and keeps the others, one level deep: a part you pass, such as `light`,
-   * replaces that part's values.
+   * - While a handler listens, the hovered building turns towards `hover.color` and the clicked one
+   *   towards `click.color`, until the next click lands elsewhere.
+   * - A building takes the pointer only where no landmark stands in front of it, and the reverse.
    *
    * @example
    * ```typescript
-   * buildings.updateConfig({ preset: 'streetDark', litWindows: { fraction: 0.6 } });
+   * buildings.events.on('click', (building) => console.log(building.id, building.properties.height));
    * ```
    */
-  updateConfig(partial: Buildings3DConfig): void;
+  get events(): CustomLayer<BuildingHit>['events'];
   /**
-   * Unsets every knob, so the buildings show with the look of the map's style.
+   * Gives the buildings with these feature ids a colour of their own, in place of their wall
+   * colour, and every other one its own colour back. An empty object clears them.
+   *
+   * @remarks
+   * The ids are the ones {@link events} report, which stay the same across tiles and zoom levels,
+   * so you can colour a building before it loads. Its roof takes the colour too, and so does every
+   * part of a building the map data splits into parts, by the id of its whole outline.
+   *
+   * @example
+   * ```typescript
+   * buildings.setBuildingColors({ 6183703601: '#e4572e', 6183703602: '#29335c' });
+   * ```
    */
-  resetConfig(): void;
+  setBuildingColors(colors: Readonly<Record<string, string>>): void;
   /**
-   * Whether the buildings are set to be shown: the `visible` knob, `true` unless set.
+   * The colours {@link setBuildingColors} gave, by feature id.
    */
-  isVisible(): boolean;
+  getBuildingColors(): Record<string, string>;
   /**
-   * Shows or hides the buildings. Stored as `visible` in the configuration. Hidden, they give the
-   * style's own 3D buildings their place back.
+   * Replaces the whole configuration. An empty object has every knob take the `auto` preset's value.
+   *
+   * @remarks
+   * Use it, and `updateConfig`, for a look your code writes: the type is the check, and the values
+   * are not checked again. For values held as data, the SDK's `setKnobs` checks each against
+   * {@link buildings3DKnobCatalogue} and sets them by id, and its `getKnob` reads a knob's value in
+   * force, the preset's one when unset. `light.direction` and `light.altitude` read the map's light
+   * when unset, once one is placed.
+   *
+   * `updateConfig` merges one level deep: a part you pass, such as `light`, replaces that part's values.
+   *
+   * @example
+   * ```typescript
+   * buildings.updateConfig({ preset: 'streetDark', litWindows: { fraction: 0.6 } });
+   * ```
    */
-  setVisible(visible: boolean): void;
+  applyConfig(config: Buildings3DConfig): void;
   /**
    * @ignore
    */
   _knobValue(id: string): unknown;
-  /**
-   * @ignore
-   */
-  _setKnobValues(values: Readonly<Record<string, unknown>>): void;
-  /**
-   * @ignore
-   */
-  _resetKnobValue(id: string): void;
   private install;
+  private hitsAt;
   private look;
+  private followMapLight;
   private render;
   private placeLabels;
   private restoreLabels;
   private occludeLabels;
 }
 //#endregion
-//#region src/knobCatalogue.d.ts
-/**
- * What a landmark's own texture gives its look, besides carving its silhouette:
- *
- * - `mask`: nothing more; the landmark is shaded in its `color`.
- * - `detail`: its light and shade, over the `color`, as facade detail.
- * - `color`: its colours, in place of the `color`.
- *
- * Whatever the use, the map's light shades the landmark.
- *
- * @group Landmarks 3D
- */
-export declare const landmarkTextureUses: readonly ["mask", "detail", "color"];
-/**
- * One of {@link landmarkTextureUses}.
- *
- * @group Landmarks 3D
- */
-type LandmarkTextureUse = (typeof landmarkTextureUses)[number];
-declare const landmarks3DKnobDefinitions: {
-  readonly visible: {
-    readonly kind: "toggle";
-    readonly description: "The landmark models.";
-    readonly default: true;
-  };
-  readonly color: {
-    readonly kind: "color";
-    readonly description: "Colour the landmarks are shaded in. Unset: the base map's 3D buildings' colour, following the map colours that restyle them.";
-  };
-  readonly texture: {
-    readonly kind: "enum";
-    readonly description: "What the landmarks' textures add to their silhouette: mask (nothing), detail (their light and shade over the color) or color (their own colours, in place of the color). Unset: mask, or detail while a Buildings3D draws.";
-    readonly options: readonly ["mask", "detail", "color"];
-  };
-  readonly opacity: {
-    readonly kind: "number";
-    readonly description: "Opacity of the landmarks, 0 to 1. Unset: the base map's 3D buildings' opacity.";
-    readonly range: KnobRange;
-  };
-  readonly verticalGradient: {
-    readonly kind: "toggle";
-    readonly description: "Whether the landmarks' walls darken towards the ground. Unset: as the base map's 3D buildings do. No effect while a Buildings3D draws, whose walls have no gradient.";
-  };
-  readonly minZoom: {
-    readonly kind: "number";
-    readonly description: "Lowest zoom the landmarks are drawn at. Unset: the base map's 3D buildings' one.";
-    readonly range: KnobRange;
-  };
-  readonly maxZoom: {
-    readonly kind: "number";
-    readonly description: "Highest whole zoom level the landmarks are drawn at, up to the next one. Unset: the base map's 3D buildings' one, or 22 while a Buildings3D draws.";
-    readonly range: KnobRange;
-  };
-};
-/**
- * The id of a landmarks knob, as accepted by the SDK's `setKnob` and as a key of {@link Landmarks3DConfig}.
- *
- * @group Landmarks 3D
- */
-type Landmarks3DKnobId = keyof typeof landmarks3DKnobDefinitions;
-/**
- * The value type a landmarks knob takes.
- *
- * @group Landmarks 3D
- */
-type Landmarks3DKnobValueOf<ID extends Landmarks3DKnobId> = ID extends 'texture' ? LandmarkTextureUse : KnobValueOf<(typeof landmarks3DKnobDefinitions)[ID]['kind']>;
-/**
- * One entry of {@link landmarks3DKnobCatalogue}, with what a UI or a coding agent needs to offer the knob
- * and validate a value for it. The SDK's `getKnob` reads the value in force.
- *
- * @group Landmarks 3D
- */
-type Landmarks3DKnob = KnobEntry<Landmarks3DKnobId>;
-/**
- * Every landmarks knob with its kind, description, range or options and, for `visible`, its default.
- * It's static data, readable without a map.
- *
- * @remarks
- * A knob is a plain value in {@link Landmarks3DConfig}, under its id. Every knob but `visible`
- * follows the base map's 3D buildings while unset, which the SDK's `getKnob` reports.
- *
- * @group Landmarks 3D
- */
-export declare const landmarks3DKnobCatalogue: readonly Landmarks3DKnob[];
-/**
- * Every landmarks knob id, in catalogue order.
- *
- * @group Landmarks 3D
- */
-export declare const landmarks3DKnobIds: readonly Landmarks3DKnobId[];
-//#endregion
 //#region src/FillExtrusionMaterial.d.ts
 /**
  * Alpha mask carried over from a landmark mesh's as-authored texture.
@@ -574,10 +484,16 @@ type FillExtrusionAlphaMask = {
  * @group Landmarks 3D
  */
 declare class FillExtrusionMaterial extends ShaderMaterial {
-  constructor(alphaMask?: FillExtrusionAlphaMask);
+  /**
+   * @param alphaMask - The landmark mesh's authored base colour texture, whose alpha carves its silhouette.
+   * @param highlights - The uniforms of the layer's highlights, which its materials share.
+   * @param palette - The uniforms of the layer's palette, in sRGB, which its materials share.
+   */
+  constructor(alphaMask: FillExtrusionAlphaMask | undefined, highlights: HighlightUniforms, palette: PaletteUniforms);
   /**
    * Copies the shading uniforms (colour, texture use, light, layer opacity, vertical gradient) from
-   * another instance, bringing a freshly created alpha-masked variant up to date with the shared material.
+   * another instance, bringing a freshly created alpha-masked variant up to date with the shared
+   * material. The palette's and the highlights' are shared already.
    */
   copyShadingFrom(source: FillExtrusionMaterial): void;
   /**
@@ -670,8 +586,9 @@ interface ModelsSourceSpecification {
 /**
  * Source of tiled glTF/GLB models for a {@link ModelsLayer}.
  *
- * Tracks the tiles covering the current viewport, fetches each tile's models once
- * and keeps them in a Three.js {@link Group} that the owning layer renders.
+ * Tracks the tiles covering the current viewport, fetches each tile's models once, or again after a failure that
+ * clears on its own or the KTX2 transcoder failed to load, and keeps them in a Three.js {@link Group} that the
+ * owning layer renders.
  *
  * @group Landmarks 3D
  */
@@ -684,7 +601,7 @@ export declare class ModelsSource {
   tiles: Array<string>;
   scene: Group;
   loadedTiles: Set<string>;
-  /** Whether a tile came back 403 for want of Orbis 3D Landmarks access, so the key loads none. */
+  /** Whether a tile came back `401` or `403`, so the key loads none and the source fetches no more. */
   accessDenied: boolean;
   /**
    * EPSG:3857 origin subtracted from all mesh positions, because absolute coordinates (~6·10⁶ m)
@@ -703,12 +620,14 @@ export declare class ModelsSource {
   private readonly specification;
   private readonly withCredentials;
   private coveringTileKeys;
+  private readonly retries;
   constructor(id: string, options: ModelsSourceSpecification);
   onAdd(map: Map, renderer: WebGLRenderer): void;
   updateTiles(): void;
   private showCoveringTilesOnly;
   private coveringTiles;
   private loadTile;
+  private reportTileError;
   private rebaseToSceneOrigin;
   private fetchTile;
 }
@@ -749,6 +668,13 @@ export declare class ModelsLayer implements CustomLayerInterface {
   maxzoom: number;
   visible: boolean;
   diffuseColor: string;
+  /**
+   * The landmarks as user events report them, the colours an app gives them, and the hovered and clicked one.
+   * @ignore
+   */
+  readonly highlights: ObjectHighlights;
+  private readonly fillPalette;
+  private readonly facadePalette;
   private readonly fillExtrusionMaterial;
   private readonly depthPrepassMaterial;
   private readonly maskedFillExtrusionMaterials;
@@ -757,14 +683,30 @@ export declare class ModelsLayer implements CustomLayerInterface {
   private glass;
   private opacity;
   private textureUse;
+  private drawn;
   private readonly tilesMainMatrix;
   private tilesStale;
+  private terrainVersion;
   private readonly markTilesStale;
   constructor(options: ModelsLayerSpecification, source: ModelsSourceSpecification);
   updateProperties(options: ModelsLayerSpecification): void;
   setDirectionalLight(radius: number, phi: number, theta: number): void;
   onAdd(map: Map, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
-  render(_gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+  render(gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+  /**
+   * The landmark the last frame drawn here shows first under a point of the map, in CSS pixels from
+   * its top left. None while a `Buildings3D` draws the landmarks, whose own pick finds them.
+   * @ignore
+   */
+  pick(point: {
+    x: number;
+    y: number;
+  }): ScenePick | undefined;
+  /**
+   * A landmark mesh as user events report it.
+   * @ignore
+   */
+  hitOf(mesh: Mesh): BuildingHit | undefined;
   /**
    * Readies the landmark tiles for a `Buildings3D` to draw in its scene this frame.
    * @returns Where they are, `undefined` while they don't show, the key has no access to them, or no
@@ -785,7 +727,6 @@ export declare class ModelsLayer implements CustomLayerInterface {
   private terrainSamplePoints;
   private alignCameraToMap;
   private get sceneOrigin();
-  private needsTranslucentPrepass;
   setOpacity(value: number): void;
   /**
    * Hands the landmarks to a `Buildings3D`, which draws them in its scene under its sun and in its
@@ -794,6 +735,12 @@ export declare class ModelsLayer implements CustomLayerInterface {
    * @ignore
    */
   setBuildingsLight(light: BuildingsLight | undefined): void;
+  /**
+   * Sets the palette each landmark takes its colour from, over `diffuseColor`, and how much each
+   * one's shade varies, here and under a `Buildings3D`.
+   * @ignore
+   */
+  setPalette(palette: PaletteLook): void;
   /** Mirrors the basemap's fill-extrusion-vertical-gradient on the landmark shading. */
   setVerticalGradient(enabled: boolean): void;
   /**
@@ -807,22 +754,28 @@ export declare class ModelsLayer implements CustomLayerInterface {
   private forEachFillExtrusionMaterial;
   private syncLighting;
   private applyMaterials;
+  private bakeHighlightIndex;
   private facadeMaterialOf;
 }
 //#endregion
 //#region src/Landmarks3D.d.ts
 /**
  * The landmark knobs an app sets, as {@link Landmarks3D.getConfig} returns them. Each knob id is its
- * key in here, and it's plain JSON.
+ * path in here, and it's plain JSON.
  *
- * - Every knob but `visible` follows the base map's 3D buildings while unset.
+ * - `color`, `opacity`, `verticalGradient`, `minZoom` and `maxZoom` follow the base map's 3D buildings
+ *   while unset, and `hover.color` and `click.color` the map's accent, else blue.
  * - While a {@link Buildings3D} draws, the landmarks follow its buildings instead: `texture` is `detail`,
  *   there's no wall gradient, which `verticalGradient` can't turn on, and every zoom up to `maxZoom`.
+ *   Their palette and variation are the walls' ones, the palette only while `color` is unset.
+ * - On `streetSatellite`, `texture` is `color` while unset, with or without a {@link Buildings3D}: the
+ *   landmarks show their own colours over the imagery.
  *
  * @example
  * ```typescript
  * const config: Landmarks3DConfig = { color: '#c8b28a', opacity: 0.9 };
  * const authored: Landmarks3DConfig = { texture: 'color' }; // the landmarks' own colours
+ * const varied: Landmarks3DConfig = { palette: ['#efe4cf', '#cdb07f', '#b96c48'], variation: 0.3 };
  * ```
  *
  * @group Landmarks 3D
@@ -854,11 +807,13 @@ type Landmarks3DOptions = Landmarks3DConfig & Pick<ModelsSourceSpecification, 't
  * across map style changes.
  *
  * @remarks
+ * **[Private Preview](https://docs.tomtom.com/legal/private-preview)** until the plugin's 1.0.0 release.
+ *
  * It requires an API key with Orbis 3D Landmarks entitlements. Its look is a set of knobs, listed in
  * {@link landmarks3DKnobCatalogue}.
  *
- * - Each knob you leave unset follows the base map's 3D buildings, through style changes and
- *   anything that restyles them, falling back to the `streetLight` style's look.
+ * - The colour, opacity, gradient and zoom range you leave unset follow the base map's 3D buildings,
+ *   through style changes and anything that restyles them, falling back to the `streetLight` style's look.
  * - Whether those buildings show is the `buildings3D` group of the `BaseMapModule`, hidden in most
  *   standard styles; the plugin leaves it as it is.
  * - A visible {@link Buildings3D} on the same map takes their place: the landmarks then follow its
@@ -881,8 +836,10 @@ export declare class Landmarks3D {
   private readonly layerID;
   private readonly basemapBuildingLayerID;
   private readonly modelsLayer;
+  private readonly customLayer;
   private config;
   private renderedLook;
+  private styling;
   /**
    * Creates the plugin bound to a TomTom map and starts rendering landmarks
    * as soon as the map is ready.
@@ -895,13 +852,49 @@ export declare class Landmarks3D {
    * The underlying MapLibre custom layer, for advanced use beyond this facade.
    */
   get layer(): ModelsLayer;
+  /**
+   * The user events of the landmarks: a handler gets the landmark under the pointer, with its id and
+   * its `position` as `[longitude, latitude]`.
+   *
+   * @remarks
+   * - While a handler listens, the hovered landmark turns towards `hover.color` and the clicked one
+   *   towards `click.color`, until the next click lands elsewhere.
+   * - Among the buildings of a {@link Buildings3D}, a landmark takes the pointer only where no building
+   *   stands in front of it. Over the style's own 3D buildings, it takes it wherever it shows.
+   *
+   * @example
+   * ```typescript
+   * landmarks.events.on('click', (landmark) => console.log(landmark.id, landmark.properties.position));
+   * ```
+   */
+  get events(): CustomLayer<BuildingHit>['events'];
+  /**
+   * Gives the landmarks with these ids a colour of their own, in place of their `color` and palette
+   * colour, and every other one its own colour back. An empty object clears them.
+   *
+   * @remarks
+   * The ids are the ones {@link events} report, which stay the same in every session, so you can
+   * colour a landmark before it loads. Under `texture: 'color'`, a landmark you colour draws as under
+   * `detail`: your colour, with its texture's light and shade over it.
+   *
+   * @example
+   * ```typescript
+   * landmarks.setLandmarkColors({ [landmark.id]: '#e4572e' });
+   * ```
+   */
+  setLandmarkColors(colors: Readonly<Record<string, string>>): void;
+  /**
+   * The colours {@link setLandmarkColors} gave, by id.
+   */
+  getLandmarkColors(): Record<string, string>;
   /**
    * Returns the knobs set, as a plain serializable copy. The SDK's `getKnob` reads a knob's value
-   * in force, the base map's one when unset.
+   * in force: when unset, the base map's, or the knob's own default.
    */
   getConfig(): Landmarks3DConfig;
   /**
-   * Replaces the whole configuration. An empty object has every knob follow the base map's 3D buildings.
+   * Replaces the whole configuration. An empty object unsets every knob, back to the base map's 3D
+   * buildings or the knob's own default.
    *
    * @remarks
    * Use it, and {@link updateConfig}, for a look your code writes: as on a map module, the type is
@@ -915,7 +908,8 @@ export declare class Landmarks3D {
    */
   applyConfig(config: Landmarks3DConfig): void;
   /**
-   * Changes the given knobs and keeps the others.
+   * Changes the given knobs and keeps the others, one level deep: a part you pass, such as `hover`,
+   * replaces that part's values.
    *
    * @example
    * ```typescript
@@ -924,7 +918,8 @@ export declare class Landmarks3D {
    */
   updateConfig(partial: Landmarks3DConfig): void;
   /**
-   * Unsets every knob, so the landmarks are shown and look like the base map's 3D buildings.
+   * Unsets every knob, so the landmarks are shown and look like the base map's 3D buildings, with each
+   * other knob at its own default.
    */
   resetConfig(): void;
   /**
@@ -949,6 +944,7 @@ export declare class Landmarks3D {
    * @ignore
    */
   _resetKnobValue(id: string): void;
+  private hitsAt;
   private install;
   private excludeLandmarkBuildingsFromBasemap;
   private readBuildingsLook;
@@ -968,4 +964,146 @@ export declare class Landmarks3D {
  */
 export declare const buildLandmarksTileURL: () => string;
 //#endregion
-export type { Buildings3DConfig, Buildings3DKnob, Buildings3DKnobId, Buildings3DKnobValueOf, BuildingsLayer, BuildingsPreset, FacadePattern, LandmarkTextureUse, Landmarks3DConfig, Landmarks3DKnob, Landmarks3DKnobId, Landmarks3DKnobValueOf, Landmarks3DOptions, ModelsLayerSpecification, ModelsSourceSpecification };
+//#region src/surfaces/surfacesLook.d.ts
+/**
+ * The surfaces' configuration: each knob of {@link glSurfacesKnobCatalogue} at its id's path, all
+ * optional, and where the 3D trees go in the layer stack.
+ *
+ * @example
+ * ```typescript
+ * const config: GLSurfacesConfig = {
+ *     surfaces: { water: { glint: { intensity: 0.5 } }, roads: { intensity: 0 } },
+ *     wind: { direction: 270, speedFactor: 2 },
+ *     beforeLayerConfig: 'lowest3D',
+ * };
+ * ```
+ *
+ * @group GL Surfaces
+ */
+type GLSurfacesConfig = KnobConfigOf<{ [ID in GLSurfacesKnobId]: GLSurfacesKnobValueOf<ID>; }> & {
+  /**
+   * Where the 3D trees go in the map's layer stack: below the style layer it names, or on top, as a
+   * map module's `beforeLayerConfig` places its layers, on top where the style lacks that layer and
+   * under the POIs where it lacks `lowest3D`. They also go below every layer a module or your app put
+   * right under that one, so a route or a place drawn there stays over the trees, whichever was added
+   * first. The textures stay right after the layers they texture. Not a knob: it moves layers rather
+   * than restyling them.
+   *
+   * @defaultValue `'lowestLabel'`
+   */
+  beforeLayerConfig?: BeforeLayerConfig;
+};
+//#endregion
+//#region src/surfaces/GLSurfaces.d.ts
+/**
+ * Textures the surfaces of the map's style with WebGL materials, and grows 3D trees on its green:
+ * water that ripples in the wind, mirrors the sky and rolls in onto open shores, glaciers, tree crowns
+ * lit by the sun over forests, lawns, meadows and scrub, field parcels over farmland, dunes, mud
+ * flats, shingle, bare rock, paving, built-up ground and asphalt.
+ *
+ * @remarks
+ * **[Public Preview](https://docs.tomtom.com/legal/public-preview)** until the plugin's 1.0.0 release.
+ *
+ * - It draws inside the style, right after the layers it textures, so labels, bridges, buildings
+ *   and everything your app adds above them stay on top, untouched.
+ * - It textures the standard styles' land cover, land use, water, paved areas and road layers, each
+ *   kind of surface listed in {@link surfaceKinds}, in the style's own colours,
+ *   which every material varies rather than replaces. A restyle or a style switch carries over.
+ *   Over satellite imagery, it textures the water and the roads and grows the trees, in the
+ *   imagery's colours.
+ * - Each surface and the trees are coloured for a season, the `season` knob, from the style's
+ *   colours. A colour knob set for one shade of a surface, such as the cereal fields, replaces it.
+ * - The trees are broadleaf, conifers, bushes, columnar and umbrella trees, in the mix each kind of
+ *   ground and its latitude grow, which a `trees.species.<kind>.shareFactor` knob scales. They keep off the
+ *   roads, paths, railways and streams through a wood, which show over the crowns in front of them.
+ * - Every texture is anchored to the ground and fades its details out before they shrink below
+ *   a few pixels, so it stays still and calm while you pan and zoom.
+ * - Its look is a set of knobs, listed in {@link glSurfacesKnobCatalogue}. The sky the water mirrors
+ *   is the map's own where the style sets one, else a day or a night sky by the style's theme, and a
+ *   day sky over satellite imagery.
+ * - Its sun is the map's light once one is placed, such as through the styling module's
+ *   `view.light` knobs, so it lights the crowns, the trees and the dunes from where the 3D
+ *   buildings are lit. Until then, it is the style's theme's sun, 215°/30° by day and the moon at
+ *   135°/35° by night, and the day sun of the 3D buildings, 215°/35°, over satellite imagery.
+ * - While the water, the grass or the trees show and the wind blows, the map draws a frame every
+ *   display frame. Set `wind.speedFactor` to 0 to hold them still and let the map rest.
+ * - Over a 3D terrain, the textures and the trees follow the ground the terrain raises.
+ * - It needs WebGL2.
+ *
+ * @example
+ * ```typescript
+ * import { GLSurfaces } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
+ *
+ * const surfaces = new GLSurfaces(map);
+ * surfaces.updateConfig({ wind: { direction: 270, speedFactor: 2 } }); // a brisk westerly
+ * ```
+ *
+ * @group GL Surfaces
+ */
+export declare class GLSurfaces extends KnobConfigured<GLSurfacesConfig> {
+  private readonly map;
+  private readonly renderer;
+  private installedLayerIds;
+  private readonly installedMasks;
+  private standIns;
+  private styleColors;
+  private resolvedUniforms?;
+  private readonly removeStyleChangeHandler;
+  private removed;
+  private readonly onStyleData;
+  /**
+   * Creates the surfaces on a map, drawn as soon as the map is ready.
+   *
+   * @param map - The map to texture.
+   * @param config - The knobs to start with.
+   */
+  constructor(map: TomTomMap, config?: GLSurfacesConfig);
+  /**
+   * Replaces the whole configuration. An empty object has every knob take its default.
+   *
+   * @remarks
+   * Use it, and `updateConfig`, for a look your code writes: the type is the check, and the values
+   * are not checked again. For values held as data, the SDK's `setKnobs` checks each against
+   * {@link glSurfacesKnobCatalogue} and sets them by id, and its `getKnob` reads a knob's value in
+   * force, the map's own or the default when unset.
+   *
+   * `updateConfig` merges one level deep, and every surface sits in the one part `surfaces`, so
+   * passing `surfaces` replaces the knobs of every surface:
+   * `updateConfig({ surfaces: { roads: { intensity: 0 } } })` also unsets those of the water, the
+   * forest and the others. To change some knobs and keep the others, use the SDK's `setKnobs`:
+   * `setKnobs(surfaces, glSurfacesKnobCatalogue, { 'surfaces.roads.intensity': 0 })`.
+   *
+   * @example
+   * ```typescript
+   * surfaces.updateConfig({ light: { direction: 260, altitude: 12 } }); // a low evening sun
+   * ```
+   */
+  applyConfig(config: GLSurfacesConfig): void;
+  /**
+   * Takes the surfaces and the trees off the map: removes their layers, with the WebGL resources
+   * they hold, and stops following the map's style. Call it when your app drops the surfaces but
+   * keeps the map. A removed `GLSurfaces` can't be shown again; create a new one instead.
+   */
+  remove(): void;
+  /**
+   * @ignore
+   */
+  _knobValue(id: string): unknown;
+  private get mapLibreMap();
+  private context;
+  private look;
+  private uniforms;
+  private readStyleColors;
+  private install;
+  private treesBeforeOf;
+  private isAddedOnTop;
+  private removeLayers;
+  private installMaterialRuns;
+  private addRun;
+  private originalOf;
+  private syncMasks;
+  private syncRunLayers;
+  private followShape;
+}
+//#endregion
+export type { BuildingHit, Buildings3DConfig, BuildingsLayer, GLSurfacesConfig, Landmarks3DConfig, Landmarks3DOptions, ModelsLayerSpecification, ModelsSourceSpecification };