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

package/dist/index.d.ts

@@ -1,24 +1,554 @@
-import { TomTomMap } from "@tomtom-org/maps-sdk/map";
+import { KnobConfigOf, KnobEntry, KnobRange, KnobValueOf, TomTomMap } from "@tomtom-org/maps-sdk/map";
 import { CustomLayerInterface, CustomRenderMethodInput, Map } from "maplibre-gl";
-import { AmbientLight, Camera, DirectionalLight, Group, Mesh, Scene, ShaderMaterial, Texture, WebGLRenderer } from "three";
-//#region src/displayMode.d.ts
+import { AmbientLight, Camera, DirectionalLight, Group, IUniform, Mesh, Object3D, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
+//#region src/buildings/buildingsKnobCatalogue.d.ts
 /**
- * How 3D landmarks are shaded relative to the base map. Every mode renders the
- * landmarks as maplibre-style fill-extrusion buildings:
- * - `inherited`: mirrors the colour, opacity and vertical gradient of the basemap 3D building layer (default).
- * - `dark`: uses the 3D building look of the SDK's `streetDark` style.
- * - `light`: uses the 3D building look of the SDK's `streetLight` style.
+ * 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.
+ *
+ * @group Buildings 3D
+ */
+export declare const facadePatterns: readonly ["mixed", "residential", "office", "glass", "plain"];
+/**
+ * One of {@link facadePatterns}.
+ *
+ * @group Buildings 3D
+ */
+type FacadePattern = (typeof facadePatterns)[number];
+/**
+ * The looks the unset knobs take: one per standard style, or `auto`, which follows the map's style.
+ *
+ * @group Buildings 3D
+ */
+export declare const buildingsPresets: readonly ["auto", "streetLight", "streetDark", "streetLightDriving", "streetDarkDriving", "monoLight", "monoDark", "streetSatellite"];
+/**
+ * One of {@link buildingsPresets}.
+ *
+ * @group Buildings 3D
+ */
+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.";
+  };
+};
+/**
+ * The id of a buildings knob, as accepted by the SDK's `setKnob` and as a path into {@link Buildings3DConfig}.
+ *
+ * @group Buildings 3D
+ */
+type Buildings3DKnobId = keyof typeof buildingsKnobDefinitions;
+type KindOf<ID extends Buildings3DKnobId> = (typeof buildingsKnobDefinitions)[ID]['kind'];
+/**
+ * The value type a buildings knob takes.
+ *
+ * @group Buildings 3D
+ */
+type Buildings3DKnobValueOf<ID extends Buildings3DKnobId> = ID extends 'preset' ? BuildingsPreset : ID extends 'facade.pattern' ? FacadePattern : KnobValueOf<KindOf<ID>>;
+/**
+ * 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
+ */
+type Buildings3DKnob = KnobEntry<Buildings3DKnobId>;
+/**
+ * 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
+ */
+export declare const buildings3DKnobCatalogue: readonly Buildings3DKnob[];
+/**
+ * Every buildings knob id, in catalogue order.
+ *
+ * @group Buildings 3D
+ */
+export declare const buildings3DKnobIds: readonly Buildings3DKnobId[];
+//#endregion
+//#region src/buildings/buildingsLook.d.ts
+/**
+ * The building knobs an app sets, as {@link Buildings3D.getConfig} returns them. Each knob id is its
+ * path in here, so `light.direction` is `config.light.direction`. It's plain JSON.
+ *
+ * @example
+ * ```typescript
+ * const config: Buildings3DConfig = { facade: { pattern: 'glass' }, shadows: { intensity: 0.6 } };
+ * ```
+ *
+ * @group Buildings 3D
+ */
+type Buildings3DConfig = KnobConfigOf<{ [ID in Buildings3DKnobId]: Buildings3DKnobValueOf<ID>; }>;
+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.
+ * @ignore
+ */
+type Buildings3DLook = Values & {
+  wallColorsByGroup: GroupColors;
+  roofsFollowWalls: boolean;
+};
+//#endregion
+//#region src/buildings/glass.d.ts
+/**
+ * The scene's light as glass mirrors it, shared by the buildings' material and the landmarks' so both
+ * mirror one sky: `eyePosition` in scene metres, the sun's direction and colour, the sky's colour and
+ * intensity, and how much glass reflects.
+ * @ignore
+ */
+type GlassUniforms = Record<'eyePosition' | 'sunDirection' | 'sunColor' | 'skyColor', IUniform<Vector3>> & Record<'skyIntensity' | 'reflectivity', IUniform<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.
+ * @ignore
+ */
+type GroupColors = readonly string[];
+/**
+ * Where the landmark tiles are, for a frame a `Buildings3D` draws them in.
+ * @ignore
+ */
+type LandmarksFrame = {
+  /** The origin of the tiles, in EPSG:3857 metres: they lie in metres east and north of it, z up. */
+  origin: {
+    x: number;
+    y: number;
+  };
+  /** Whether the landmarks are translucent, and need a depth prepass. */
+  translucent: boolean;
+};
+/**
+ * A pass a `Buildings3D` draws the landmarks in: in colour, depth only for a depth prepass, or
+ * casting their shadows and drawing nothing.
+ * @ignore
+ */
+type LandmarksPass = 'color' | 'depth' | 'shadows';
+/**
+ * The landmarks of a `Landmarks3D`, as its map's `Buildings3D` draws them: in its own scene, so one
+ * sun lights both and each casts its shadows on the other.
+ * @ignore
+ */
+type LandmarksForBuildings = {
+  /** The landmark tiles. */
+  readonly tiles: Object3D;
+  /**
+   * Readies the tiles for a frame drawn through `mainMatrix`, mirroring a little of the buildings'
+   * `glass` light; `undefined` while they don't show.
+   */
+  prepareForBuildings(mainMatrix: ArrayLike<number>, glass: GlassUniforms): LandmarksFrame | undefined;
+  /** Gives every landmark the materials of one pass. */
+  useMaterials(pass: LandmarksPass): void;
+};
+//#endregion
+//#region src/buildings/BuildingsLayer.d.ts
+/**
+ * MapLibre custom layer drawing the vector tiles' buildings with Three.js: extruded walls and roofs,
+ * procedural windows, a sun with soft shadows on the buildings and the ground, and sky light.
+ *
+ * It extrudes the buildings of the tiles MapLibre already loaded for the map, so it makes no requests
+ * of its own. After changing one of its fields yourself, call `triggerRepaint()` on the MapLibre map.
+ *
+ * @group Buildings 3D
+ */
+declare class BuildingsLayer implements CustomLayerInterface {
+  private readonly landmarksOf;
+  readonly id: string;
+  readonly type: "custom";
+  readonly renderingMode: "3d";
+  /** The vector source and source layer the buildings come from. */
+  source: {
+    id: string;
+    layer: string;
+  };
+  private map?;
+  private renderer?;
+  private look?;
+  private filter;
+  private origin?;
+  private frame;
+  private readonly scene;
+  private readonly camera;
+  private readonly buildings;
+  private readonly landmarks;
+  private readonly material;
+  private readonly depthOnly;
+  private readonly shadowsOnly;
+  private readonly sun;
+  private readonly sky;
+  private readonly groundReach;
+  private readonly ground;
+  private readonly tiles;
+  private pending;
+  private extrusion;
+  /**
+   * @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);
+  /** Draws the buildings with this look, from the next frame. */
+  setLook(look: Buildings3DLook): void;
+  onAdd(map: Map, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+  render(gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+  private renderTranslucent;
+  private useBuildingsPass;
+  private placeLandmarks;
+  private toScene;
+  private updateOrigin;
+  private carryTiles;
+  private updateTiles;
+  private queueTiles;
+  private startExtrusion;
+  private addTileMesh;
+  private removeTileMesh;
+  private evictStaleTiles;
+  private eyePosition;
+  private groundMaterial;
+  private updateSun;
+}
+//#endregion
+//#region src/buildings/Buildings3D.d.ts
+/**
+ * Draws the base map's buildings in 3D with Three.js, with windows on their facades, a sun or moon
+ * that casts shadows on the buildings and the ground, and a look for every standard style.
+ *
+ * @remarks
+ * **[Public Preview](https://docs.tomtom.com/legal/public-preview)** until the plugin's 1.0.0 release.
+ *
+ * - It extrudes the buildings of the vector tiles the map already loads, and makes no requests of its own.
+ * - 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.
+ * - 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.
+ * - 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.
+ *   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.
+ * - 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.
+ *
+ * @example
+ * ```typescript
+ * import { Buildings3D } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
+ *
+ * const buildings = new Buildings3D(map, { facade: { pattern: 'glass' } });
+ * buildings.updateConfig({ light: { direction: 260, altitude: 15 } }); // a low evening sun
+ * ```
+ *
+ * @group Buildings 3D
+ */
+export declare class Buildings3D {
+  private readonly map;
+  private readonly buildingsLayer;
+  private config;
+  private renderedLook;
+  private styling;
+  private readonly occludedLabels;
+  private styleOrder;
+  /**
+   * Creates the buildings on a map, drawn as soon as the map is ready.
+   *
+   * @param map - The map to draw the buildings on.
+   * @param config - The knobs to start with.
+   */
+  constructor(map: TomTomMap, config?: Buildings3DConfig);
+  /**
+   * The underlying MapLibre custom layer, for advanced use beyond this facade.
+   */
+  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.
+   *
+   * @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.
+   *
+   * @example
+   * ```typescript
+   * buildings.updateConfig({ preset: 'streetDark', litWindows: { fraction: 0.6 } });
+   * ```
+   */
+  updateConfig(partial: Buildings3DConfig): void;
+  /**
+   * Unsets every knob, so the buildings show with the look of the map's style.
+   */
+  resetConfig(): void;
+  /**
+   * Whether the buildings are set to be shown: the `visible` knob, `true` unless set.
+   */
+  isVisible(): boolean;
+  /**
+   * Shows or hides the buildings. Stored as `visible` in the configuration. Hidden, they give the
+   * style's own 3D buildings their place back.
+   */
+  setVisible(visible: boolean): void;
+  /**
+   * @ignore
+   */
+  _knobValue(id: string): unknown;
+  /**
+   * @ignore
+   */
+  _setKnobValues(values: Readonly<Record<string, unknown>>): void;
+  /**
+   * @ignore
+   */
+  _resetKnobValue(id: string): void;
+  private install;
+  private look;
+  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 Landmarks3DDisplayMode = 'inherited' | 'dark' | 'light';
+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.
  *
  * Landmark meshes are coarse hulls (e.g. a wall is one rectangle) whose realistic
- * silhouette is carved out by the texture's alpha channel. Untextured shading must keep
+ * silhouette is carved out by the texture's alpha channel. The shading must keep
  * sampling that alpha and discard the carved-away fragments, otherwise the raw hull
  * shape gets coloured in.
  *
@@ -31,8 +561,9 @@ type FillExtrusionAlphaMask = {
   cutoff: number;
 };
 /**
- * Material that shades untextured landmark meshes exactly like maplibre-gl shades
- * `fill-extrusion` buildings, so they blend in with the basemap building layer.
+ * Material that shades landmark meshes exactly like maplibre-gl shades `fill-extrusion`
+ * buildings, so they blend in with the basemap building layer. A mesh given its texture
+ * can take that texture's detail or colours, as {@link FillExtrusionMaterial.setTextureUse} sets.
  *
  * Colour and opacity premultiply like maplibre's `v_color *= u_opacity`, paired with
  * (ONE, ONE_MINUS_SRC_ALPHA) blending. Backfaces are culled like maplibre's extrusion
@@ -45,10 +576,15 @@ type FillExtrusionAlphaMask = {
 declare class FillExtrusionMaterial extends ShaderMaterial {
   constructor(alphaMask?: FillExtrusionAlphaMask);
   /**
-   * Copies the shading uniforms (colour, light, layer opacity, vertical gradient) from another
-   * instance, bringing a freshly created alpha-masked variant up to date with the shared material.
+   * 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.
    */
   copyShadingFrom(source: FillExtrusionMaterial): void;
+  /**
+   * Sets what the mesh's texture gives its look besides its silhouette. Without a texture, the
+   * mesh takes the diffuse colour whatever the use.
+   */
+  setTextureUse(use: LandmarkTextureUse): void;
   /**
    * Sets the building colour from a CSS colour string, stored as raw sRGB
    * components, because maplibre shades paint colours in sRGB space, not linear.
@@ -115,8 +651,10 @@ interface ModelsSourceSpecification {
   attribution?: string;
   /**
    * Base path of the Basis Universal transcoder (`basis_transcoder.js` and
-   * `basis_transcoder.wasm`) used to decode KTX2 textures. Defaults to the copy
-   * bundled with the plugin. Set it to serve your own copy.
+   * `basis_transcoder.wasm`) that decodes KTX2 textures, ending in `/`, such as `'/basis/'`.
+   * Set it to serve the transcoder from your own host. By default, the plugin loads the two
+   * files it ships beside its bundle, which Vite and webpack 5 emit with your build. A bundler
+   * that doesn't emit the files a `new URL('./file', import.meta.url)` names needs this path.
    */
   transcoderPath?: string;
   /**
@@ -146,6 +684,8 @@ 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. */
+  accessDenied: boolean;
   /**
    * EPSG:3857 origin subtracted from all mesh positions, because absolute coordinates (~6·10⁶ m)
    * exceed float32 precision (~0.5 m), making landmark edges tremble while zooming. `null`
@@ -174,6 +714,12 @@ export declare class ModelsSource {
 }
 //#endregion
 //#region src/ModelsLayer.d.ts
+/**
+ * What the landmarks take from a `Buildings3D` on their map beside its sun and shadows: how strongly
+ * its facades show.
+ * @ignore
+ */
+type BuildingsLight = Pick<Buildings3DLook, 'facade.intensity'>;
 /**
  * MapLibre custom layer that renders tiled glTF/GLB models with Three.js.
  *
@@ -206,6 +752,11 @@ export declare class ModelsLayer implements CustomLayerInterface {
   private readonly fillExtrusionMaterial;
   private readonly depthPrepassMaterial;
   private readonly maskedFillExtrusionMaterials;
+  private readonly facadeMaterials;
+  private buildingsLight;
+  private glass;
+  private opacity;
+  private textureUse;
   private readonly tilesMainMatrix;
   private tilesStale;
   private readonly markTilesStale;
@@ -214,6 +765,20 @@ export declare class ModelsLayer implements CustomLayerInterface {
   setDirectionalLight(radius: number, phi: number, theta: number): void;
   onAdd(map: Map, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
   render(_gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+  /**
+   * 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
+   * `Buildings3D` lights them.
+   * @ignore
+   */
+  prepareForBuildings(mainMatrix: ArrayLike<number>, glass: GlassUniforms): LandmarksFrame | undefined;
+  /**
+   * Gives every landmark the materials of one pass: its colour ones, its depth-only ones for the
+   * depth prepass of translucent shading, or its colour ones drawing nothing, to cast its shadows.
+   * @ignore
+   */
+  useMaterials(pass: LandmarksPass): void;
+  private prepareFrame;
   private updateTilesWhenStale;
   private groundLandmarksOnTerrain;
   private groundMeshOnTerrain;
@@ -221,48 +786,55 @@ export declare class ModelsLayer implements CustomLayerInterface {
   private alignCameraToMap;
   private get sceneOrigin();
   private needsTranslucentPrepass;
-  private renderDepthPrepass;
   setOpacity(value: number): void;
+  /**
+   * Hands the landmarks to a `Buildings3D`, which draws them in its scene under its sun and in its
+   * shadows, their textures used as {@link ModelsLayer.setTextureUse} sets. `undefined` draws them here
+   * again, shaded like the style's 3D buildings.
+   * @ignore
+   */
+  setBuildingsLight(light: BuildingsLight | undefined): void;
   /** Mirrors the basemap's fill-extrusion-vertical-gradient on the landmark shading. */
   setVerticalGradient(enabled: boolean): void;
+  /**
+   * Sets what each landmark's own texture gives its look besides its silhouette, here and under a
+   * `Buildings3D`: nothing, its light and shade over `diffuseColor`, or its colours in place of it.
+   * The light shades it either way.
+   */
+  setTextureUse(use: LandmarkTextureUse): void;
   getMaterial(mesh: Mesh): FillExtrusionMaterial;
   private maskedFillExtrusionVariant;
   private forEachFillExtrusionMaterial;
   private syncLighting;
   private applyMaterials;
+  private facadeMaterialOf;
 }
 //#endregion
 //#region src/Landmarks3D.d.ts
 /**
- * Configuration for the {@link Landmarks3D} plugin.
+ * 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.
+ *
+ * - Every knob but `visible` follows the base map's 3D buildings while unset.
+ * - 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`.
+ *
+ * @example
+ * ```typescript
+ * const config: Landmarks3DConfig = { color: '#c8b28a', opacity: 0.9 };
+ * const authored: Landmarks3DConfig = { texture: 'color' }; // the landmarks' own colours
+ * ```
  *
  * @group Landmarks 3D
  */
-type Landmarks3DOptions = {
-  /**
-   * Initial display mode for the landmarks. To change it at runtime, call
-   * {@link Landmarks3D.setDisplayMode}.
-   * @defaultValue `'inherited'`
-   */
-  displayMode?: Landmarks3DDisplayMode;
-  /**
-   * Whether the landmarks are initially visible. To change it at runtime, call
-   * {@link Landmarks3D.setVisible}.
-   * @defaultValue `true`
-   */
-  visible?: boolean;
-  /**
-   * Minimum zoom at which landmarks are rendered.
-   * @defaultValue The basemap 3D building layer's minimum zoom, so landmarks appear together
-   * with it (falls back to `10` when that layer is absent).
-   */
-  minZoom?: number;
-  /**
-   * Maximum zoom at which landmarks are rendered.
-   * @defaultValue The basemap 3D building layer's maximum zoom, so landmarks disappear together
-   * with it (falls back to `22` when that layer is absent).
-   */
-  maxZoom?: number;
+type Landmarks3DConfig = KnobConfigOf<{ [ID in Landmarks3DKnobId]: Landmarks3DKnobValueOf<ID>; }>;
+/**
+ * What the {@link Landmarks3D} plugin starts with: its knobs, how it requests tiles, and where it
+ * loads the texture transcoder from.
+ *
+ * @group Landmarks 3D
+ */
+type Landmarks3DOptions = Landmarks3DConfig & Pick<ModelsSourceSpecification, 'transcoderPath'> & {
   /**
    * Whether each tile request sends `credentials: 'include'`, so a proxy session
    * cookie travels with it. By default, this tracks the SDK's proxy config,
@@ -282,9 +854,15 @@ type Landmarks3DOptions = {
  * across map style changes.
  *
  * @remarks
- * It requires an API key with Orbis 3D Landmarks entitlements. The exclusion
- * filter and `inherited` mode only have an effect on a map style that shows
- * extruded 3D buildings.
+ * 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.
+ * - 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
+ *   look and its light instead.
  *
  * @example
  * ```typescript
@@ -293,7 +871,7 @@ type Landmarks3DOptions = {
  * // assume `map` is your initialized TomTomMap instance
  * const landmarks = new Landmarks3D(map);
  *
- * await landmarks.setDisplayMode('inherited');
+ * landmarks.updateConfig({ color: '#c8b28a' });
  * ```
  *
  * @group Landmarks 3D
@@ -303,50 +881,79 @@ export declare class Landmarks3D {
   private readonly layerID;
   private readonly basemapBuildingLayerID;
   private readonly modelsLayer;
-  private readonly layerMinZoom?;
-  private readonly layerMaxZoom?;
-  private displayMode;
+  private config;
+  private renderedLook;
   /**
    * Creates the plugin bound to a TomTom map and starts rendering landmarks
    * as soon as the map is ready.
    *
    * @param map - The TomTom map instance to render landmarks on.
+   * @param options - The knobs to start with, how to request tiles, and where to load the texture transcoder from.
    */
-  constructor(map: TomTomMap, options?: Landmarks3DOptions);
-  private installWhenReady;
+  constructor(map: TomTomMap, { withCredentials, transcoderPath, ...config }?: Landmarks3DOptions);
   /**
    * The underlying MapLibre custom layer, for advanced use beyond this facade.
    */
   get layer(): ModelsLayer;
   /**
-   * The currently applied display mode.
+   * 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.
    */
-  getDisplayMode(): Landmarks3DDisplayMode;
+  getConfig(): Landmarks3DConfig;
   /**
-   * Changes how landmarks are rendered relative to the base map.
+   * Replaces the whole configuration. An empty object has every knob follow the base map's 3D buildings.
+   *
+   * @remarks
+   * Use it, and {@link updateConfig}, for a look your code writes: as on a map module, 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 landmarks3DKnobCatalogue} and sets them by id.
    *
-   * @param mode - The display mode to apply.
-   * @returns A promise that resolves once the mode has been applied.
+   * @example
+   * ```typescript
+   * landmarks.applyConfig({ color: '#c8b28a', opacity: 0.9 });
+   * ```
+   */
+  applyConfig(config: Landmarks3DConfig): void;
+  /**
+   * Changes the given knobs and keeps the others.
+   *
+   * @example
+   * ```typescript
+   * landmarks.updateConfig({ opacity: 1 }); // the colour still follows the base map
+   * ```
+   */
+  updateConfig(partial: Landmarks3DConfig): void;
+  /**
+   * Unsets every knob, so the landmarks are shown and look like the base map's 3D buildings.
    */
-  setDisplayMode(mode: Landmarks3DDisplayMode): Promise<void>;
+  resetConfig(): void;
   /**
-   * Whether the landmarks are currently visible.
+   * Whether the landmarks are set to be shown: the `visible` knob, `true` unless set.
    */
   isVisible(): boolean;
   /**
-   * Shows or hides the landmarks layer.
+   * Shows or hides the landmarks. Stored as `visible` in the configuration.
    *
    * @param visible - `true` to show landmarks, `false` to hide them.
-   * @returns A promise that resolves once the visibility has been applied.
    */
-  setVisible(visible: boolean): Promise<void>;
+  setVisible(visible: boolean): void;
+  /**
+   * @ignore
+   */
+  _knobValue(id: string): unknown;
+  /**
+   * @ignore
+   */
+  _setKnobValues(values: Readonly<Record<string, unknown>>): void;
+  /**
+   * @ignore
+   */
+  _resetKnobValue(id: string): void;
   private install;
-  private landmarkInsertBeforeID;
-  private alignZoomRangeWithBasemapBuildings;
   private excludeLandmarkBuildingsFromBasemap;
-  private readBasemapBuildingMaterial;
-  private resolveCurrentMaterialState;
-  private applyDisplayMode;
+  private readBuildingsLook;
+  private look;
+  private render;
 }
 //#endregion
 //#region src/landmarksTileURL.d.ts
@@ -361,4 +968,4 @@ export declare class Landmarks3D {
  */
 export declare const buildLandmarksTileURL: () => string;
 //#endregion
-export type { Landmarks3DDisplayMode, Landmarks3DOptions, ModelsLayerSpecification, ModelsSourceSpecification };
+export type { Buildings3DConfig, Buildings3DKnob, Buildings3DKnobId, Buildings3DKnobValueOf, BuildingsLayer, BuildingsPreset, FacadePattern, LandmarkTextureUse, Landmarks3DConfig, Landmarks3DKnob, Landmarks3DKnobId, Landmarks3DKnobValueOf, Landmarks3DOptions, ModelsLayerSpecification, ModelsSourceSpecification };