osmgl 0.4.0 → 0.6.0

package/dist/osmgl.d.cts

@@ -432,6 +432,20 @@ declare class Transform {
      * Порядок: левый верх, правый верх, левый низ, правый низ.
      */
     localRayCorners(): Vec3[];
+    /**
+     * Базис камеры в МИРОВЫХ осях движка (X восток, Y юг, Z вверх) и фокус в пикселях вида.
+     *
+     * По ним из пикселя восстанавливается луч: dir = normalize(fwd*focal + right*dx + up*dy). Небу
+     * этого хватает, чтобы считаться от УГЛА ЛУЧА, а не от экранной высоты, — только так у горизонта
+     * получается настоящая воздушная масса, а не нарисованная полоса.
+     */
+    cameraRay(): {
+        right: Vec3;
+        up: Vec3;
+        fwd: Vec3;
+        focal: number;
+        axisElev: number;
+    };
     /** Направление на центр планеты и её угловой радиус — для каймы атмосферы. */
     globeDisc(): {
         dir: Vec3;
@@ -751,14 +765,19 @@ interface LayerBase {
      */
     splitBy?: string;
     /**
-     * Рисовать ПОВЕРХ объёма, без теста глубины.
+     * Накладка: слой рисуется вне общей очереди, без теста глубины. Значение говорит, ГДЕ.
      *
-     * Нужно планам этажей: они лежат внутри здания, и в обычном порядке их
-     * закрыла бы его крыша. План этажа и есть накладка — «мы внутри», — а
-     * покрывает он ровно контур своего здания, поэтому соседние дома остаются
+     * `'volume'` (и `true` — прежнее написание) — поверх объёма. Нужно планам этажей: они лежат
+     * внутри здания, и в обычном порядке их закрыла бы его крыша. План этажа и есть накладка —
+     * «мы внутри», — а покрывает он ровно контур своего здания, поэтому соседние дома остаются
      * видимыми.
+     *
+     * `'roads'` — сразу после дорог и ДО объёма. Это место разметки: зебры, перекрытия, всё, что
+     * лежит на асфальте. Дороги рисуются позже поверхностей, поэтому в общую очередь такая
+     * разметка не встаёт, но и поверх объёма ей делать нечего — зебра, висящая на стене дома,
+     * первой бросается в глаза.
      */
-    overlay?: boolean;
+    overlay?: boolean | 'roads' | 'volume';
     /** Выключить слой, не удаляя из стиля. */
     visible?: boolean;
     /**
@@ -979,6 +998,21 @@ interface FillExtrusionLayerSpec extends LayerBase {
         windowGlow?: Interpolated<number>;
         /** Высота этажа в метрах: шаг сетки окон. */
         floorHeight?: Interpolated<number>;
+        /**
+         * На сколько метров стекло утоплено от плоскости стены (по умолчанию 0.18).
+         * Край проёма кладёт на утопленное стекло тень со стороны, где нет солнца, —
+         * именно она и читается как глубина. Ноль возвращает плоское окно.
+         */
+        windowRecess?: Interpolated<number>;
+        /** Глубина тени откоса, 0..1. */
+        windowRecessShade?: Interpolated<number>;
+        /**
+         * Высота в метрах, на которой цокольное затемнение сходит на нет (по умолчанию 4).
+         * Затемнение считается для ВСЕЙ стены, включая скруглённые углы и фронтоны.
+         */
+        plinthHeight?: Interpolated<number>;
+        /** Сила цокольного затемнения у самой земли, 0..1. */
+        plinthShade?: Interpolated<number>;
         /**
          * Разброс цвета СКАТНЫХ кровель, 0..1. Тон берётся из хеша здания, яркость
          * остаётся от темы — иначе терракота всплыла бы посреди ночной карты.
@@ -1305,8 +1339,15 @@ interface LightSpec {
 interface SkySpec {
     /** Рисовать небо и дымку. */
     enabled: boolean;
-    /** Цвет в зените. */
+    /** Цвет открытого неба над полосой мглы. */
     skyColor: string;
+    /**
+     * Цвет ВЕРХНЕЙ АТМОСФЕРЫ — выше по кадру, где воздуха меньше и синь глубже.
+     *
+     * Третья остановка градиента. Двух цветов на небо не хватает: получается ровная заливка, по
+     * которой не читается ни толща воздуха, ни высота. Так же устроено небо у Mapbox (`high-color`).
+     */
+    highColor?: string;
     /** Цвет у горизонта. В него же уходит дальняя земля — отсюда бесшовный стык. */
     horizonColor: string;
     /**
@@ -1317,6 +1358,14 @@ interface SkySpec {
     fogRange: [number, number];
     /** Предел силы дымки: 1 — дальний план сливается с горизонтом полностью. */
     fogIntensity: number;
+    /**
+     * Вертикальный диапазон дымки в МЕТРАХ: с какой высоты она начинает отпускать геометрию и на
+     * какой отпускает совсем. Мгла лежит слоем у земли, и башня из неё выходит — низ теряется,
+     * верх остаётся чистым. Ровно выцветшая по всей высоте башня выдаёт нарисованную дымку первой.
+     *
+     * Равные значения выключают учёт высоты. Аналог `fog.vertical-range` у Mapbox.
+     */
+    fogVerticalRange: [number, number];
     /** Цвет космоса за пределами атмосферы. Виден только на глобусе. */
     spaceColor: string;
     /** Цвет атмосферной каймы вокруг планеты. */
@@ -1324,12 +1373,15 @@ interface SkySpec {
     /** Яркость звёзд, 0 — выключить. Звёзды закреплены в мире, а не на экране. */
     starIntensity: number;
     /**
-     * Доля ВИДИМОЙ полосы неба, на которой цвет переходит от горизонта к зениту.
+     * Толщина полосы МГЛЫ над горизонтом — в синусе угла подъёма луча, как `fog.horizon-blend`
+     * у Mapbox. Значение 0.14 это примерно восемь градусов.
      *
-     * Именно видимой, а не высоты экрана: при поле зрения 37° над горизонтом
-     * помещается всего несколько градусов, и полоса неба в кадре — это десятки
-     * пикселей. Привязка к высоте экрана давала бы переход длиной в сотни
-     * пикселей, то есть ровный цвет вместо градиента.
+     * Величина угловая, а не доля кадра: толщина мглы от кадрирования не зависит. Доля видимого
+     * неба схлопывается в ноль, когда горизонт подходит к кромке кадра (большой зум с наклоном), и
+     * синее небо упирается в мглу стыком.
+     *
+     * Этой же полосой дымка отпускает геометрию по мере подъёма луча — небо и дальний дом обязаны
+     * приходить у горизонта в один цвет.
      */
     horizonBlend: number;
 }
@@ -3498,6 +3550,10 @@ declare class LayerRenderer {
      * перелёт через город.
      */
     private patternScale;
+    /** Камера в метрах от мирового нуля — считается раз на кадр (см. render). */
+    private cameraMeters;
+    /** Пикселей буфера на пиксель вида — считается раз на кадр (см. render). */
+    private dpr;
     /**
      * Множитель процедурной детализации (фасады, материалы) — из профиля
      * качества. Ноль не ставим даже на слабых устройствах: без окон и ряби карта
@@ -3656,6 +3712,23 @@ declare class LayerRenderer {
      * отсекли изнанку. Подробности, почему не годится сам шар, — в GLOBE_CLIP_VERT.
      */
     private drawGlobeClip;
+    /**
+     * Горизонт и ширина его полосы в пикселях буфера — ОДНО число на небо и на дымку.
+     *
+     * Полоса меряется по ВИДИМОМУ небу, а не по высоте экрана: при наклоне 75° и поле зрения 37°
+     * над горизонтом помещается несколько градусов, и небо в кадре — это десятки пикселей. Привязка
+     * к высоте экрана дала бы переход длиной в сотни пикселей, то есть ровную заливку вместо
+     * градиента.
+     */
+    /**
+     * Луч и полоса мглы — ОДНИ И ТЕ ЖЕ числа небу и дымке.
+     *
+     * Небо и дальняя геометрия сходятся у горизонта, и считать их надо от одной величины: угла
+     * подъёма луча. Отсюда наклон оси камеры, фокус и центр кадра — по ним шейдер восстанавливает
+     * луч из пикселя (см. Transform.cameraRay).
+     */
+    private applyAtmosphere;
+    private skyBand;
     /** Небо: вертикальный градиент во весь экран. Геометрии у него нет. */
     private drawSky;
     /**
@@ -3779,6 +3852,14 @@ declare class LayerRenderer {
      * И масштаб, И начало — тогда координата остаётся непрерывной, а размеры
      * прежними.
      */
+    /**
+     * Накладка — слои вне общей очереди, без теста глубины.
+     *
+     * Позиций две, и они не взаимозаменяемы. `roads` идёт до объёма: разметка лежит на асфальте, и
+     * дом обязан её закрывать. `volume` идёт после: план этажа лежит ВНУТРИ здания, и в обычном
+     * порядке его закрыла бы крыша.
+     */
+    private drawOverlay;
     private applyTileScale;
     private applyMaterial;
     private drawFill;
@@ -4946,6 +5027,11 @@ declare const SURFACE_LEVEL_SCALE = 64;
 interface SurfaceOptions {
     /** Метров в единице тайла — все размеры ниже задаются в МЕТРАХ. */
     metersPerUnit: number;
+    /**
+     * Предел длины ребра в единицах тайла: длиннее — верхняя плоскость дробится. Нужно ГЛОБУСУ,
+     * где сфера гнёт вершины, а не рёбра. Ноль (плоская карта) выключает дробление.
+     */
+    maxSegment?: number;
     /** Уровень верхней плоскости, метры. Отрицательный — ниже земли. */
     elevation: number;
     /**

package/dist/osmgl.d.ts

@@ -432,6 +432,20 @@ declare class Transform {
      * Порядок: левый верх, правый верх, левый низ, правый низ.
      */
     localRayCorners(): Vec3[];
+    /**
+     * Базис камеры в МИРОВЫХ осях движка (X восток, Y юг, Z вверх) и фокус в пикселях вида.
+     *
+     * По ним из пикселя восстанавливается луч: dir = normalize(fwd*focal + right*dx + up*dy). Небу
+     * этого хватает, чтобы считаться от УГЛА ЛУЧА, а не от экранной высоты, — только так у горизонта
+     * получается настоящая воздушная масса, а не нарисованная полоса.
+     */
+    cameraRay(): {
+        right: Vec3;
+        up: Vec3;
+        fwd: Vec3;
+        focal: number;
+        axisElev: number;
+    };
     /** Направление на центр планеты и её угловой радиус — для каймы атмосферы. */
     globeDisc(): {
         dir: Vec3;
@@ -751,14 +765,19 @@ interface LayerBase {
      */
     splitBy?: string;
     /**
-     * Рисовать ПОВЕРХ объёма, без теста глубины.
+     * Накладка: слой рисуется вне общей очереди, без теста глубины. Значение говорит, ГДЕ.
      *
-     * Нужно планам этажей: они лежат внутри здания, и в обычном порядке их
-     * закрыла бы его крыша. План этажа и есть накладка — «мы внутри», — а
-     * покрывает он ровно контур своего здания, поэтому соседние дома остаются
+     * `'volume'` (и `true` — прежнее написание) — поверх объёма. Нужно планам этажей: они лежат
+     * внутри здания, и в обычном порядке их закрыла бы его крыша. План этажа и есть накладка —
+     * «мы внутри», — а покрывает он ровно контур своего здания, поэтому соседние дома остаются
      * видимыми.
+     *
+     * `'roads'` — сразу после дорог и ДО объёма. Это место разметки: зебры, перекрытия, всё, что
+     * лежит на асфальте. Дороги рисуются позже поверхностей, поэтому в общую очередь такая
+     * разметка не встаёт, но и поверх объёма ей делать нечего — зебра, висящая на стене дома,
+     * первой бросается в глаза.
      */
-    overlay?: boolean;
+    overlay?: boolean | 'roads' | 'volume';
     /** Выключить слой, не удаляя из стиля. */
     visible?: boolean;
     /**
@@ -979,6 +998,21 @@ interface FillExtrusionLayerSpec extends LayerBase {
         windowGlow?: Interpolated<number>;
         /** Высота этажа в метрах: шаг сетки окон. */
         floorHeight?: Interpolated<number>;
+        /**
+         * На сколько метров стекло утоплено от плоскости стены (по умолчанию 0.18).
+         * Край проёма кладёт на утопленное стекло тень со стороны, где нет солнца, —
+         * именно она и читается как глубина. Ноль возвращает плоское окно.
+         */
+        windowRecess?: Interpolated<number>;
+        /** Глубина тени откоса, 0..1. */
+        windowRecessShade?: Interpolated<number>;
+        /**
+         * Высота в метрах, на которой цокольное затемнение сходит на нет (по умолчанию 4).
+         * Затемнение считается для ВСЕЙ стены, включая скруглённые углы и фронтоны.
+         */
+        plinthHeight?: Interpolated<number>;
+        /** Сила цокольного затемнения у самой земли, 0..1. */
+        plinthShade?: Interpolated<number>;
         /**
          * Разброс цвета СКАТНЫХ кровель, 0..1. Тон берётся из хеша здания, яркость
          * остаётся от темы — иначе терракота всплыла бы посреди ночной карты.
@@ -1305,8 +1339,15 @@ interface LightSpec {
 interface SkySpec {
     /** Рисовать небо и дымку. */
     enabled: boolean;
-    /** Цвет в зените. */
+    /** Цвет открытого неба над полосой мглы. */
     skyColor: string;
+    /**
+     * Цвет ВЕРХНЕЙ АТМОСФЕРЫ — выше по кадру, где воздуха меньше и синь глубже.
+     *
+     * Третья остановка градиента. Двух цветов на небо не хватает: получается ровная заливка, по
+     * которой не читается ни толща воздуха, ни высота. Так же устроено небо у Mapbox (`high-color`).
+     */
+    highColor?: string;
     /** Цвет у горизонта. В него же уходит дальняя земля — отсюда бесшовный стык. */
     horizonColor: string;
     /**
@@ -1317,6 +1358,14 @@ interface SkySpec {
     fogRange: [number, number];
     /** Предел силы дымки: 1 — дальний план сливается с горизонтом полностью. */
     fogIntensity: number;
+    /**
+     * Вертикальный диапазон дымки в МЕТРАХ: с какой высоты она начинает отпускать геометрию и на
+     * какой отпускает совсем. Мгла лежит слоем у земли, и башня из неё выходит — низ теряется,
+     * верх остаётся чистым. Ровно выцветшая по всей высоте башня выдаёт нарисованную дымку первой.
+     *
+     * Равные значения выключают учёт высоты. Аналог `fog.vertical-range` у Mapbox.
+     */
+    fogVerticalRange: [number, number];
     /** Цвет космоса за пределами атмосферы. Виден только на глобусе. */
     spaceColor: string;
     /** Цвет атмосферной каймы вокруг планеты. */
@@ -1324,12 +1373,15 @@ interface SkySpec {
     /** Яркость звёзд, 0 — выключить. Звёзды закреплены в мире, а не на экране. */
     starIntensity: number;
     /**
-     * Доля ВИДИМОЙ полосы неба, на которой цвет переходит от горизонта к зениту.
+     * Толщина полосы МГЛЫ над горизонтом — в синусе угла подъёма луча, как `fog.horizon-blend`
+     * у Mapbox. Значение 0.14 это примерно восемь градусов.
      *
-     * Именно видимой, а не высоты экрана: при поле зрения 37° над горизонтом
-     * помещается всего несколько градусов, и полоса неба в кадре — это десятки
-     * пикселей. Привязка к высоте экрана давала бы переход длиной в сотни
-     * пикселей, то есть ровный цвет вместо градиента.
+     * Величина угловая, а не доля кадра: толщина мглы от кадрирования не зависит. Доля видимого
+     * неба схлопывается в ноль, когда горизонт подходит к кромке кадра (большой зум с наклоном), и
+     * синее небо упирается в мглу стыком.
+     *
+     * Этой же полосой дымка отпускает геометрию по мере подъёма луча — небо и дальний дом обязаны
+     * приходить у горизонта в один цвет.
      */
     horizonBlend: number;
 }
@@ -3498,6 +3550,10 @@ declare class LayerRenderer {
      * перелёт через город.
      */
     private patternScale;
+    /** Камера в метрах от мирового нуля — считается раз на кадр (см. render). */
+    private cameraMeters;
+    /** Пикселей буфера на пиксель вида — считается раз на кадр (см. render). */
+    private dpr;
     /**
      * Множитель процедурной детализации (фасады, материалы) — из профиля
      * качества. Ноль не ставим даже на слабых устройствах: без окон и ряби карта
@@ -3656,6 +3712,23 @@ declare class LayerRenderer {
      * отсекли изнанку. Подробности, почему не годится сам шар, — в GLOBE_CLIP_VERT.
      */
     private drawGlobeClip;
+    /**
+     * Горизонт и ширина его полосы в пикселях буфера — ОДНО число на небо и на дымку.
+     *
+     * Полоса меряется по ВИДИМОМУ небу, а не по высоте экрана: при наклоне 75° и поле зрения 37°
+     * над горизонтом помещается несколько градусов, и небо в кадре — это десятки пикселей. Привязка
+     * к высоте экрана дала бы переход длиной в сотни пикселей, то есть ровную заливку вместо
+     * градиента.
+     */
+    /**
+     * Луч и полоса мглы — ОДНИ И ТЕ ЖЕ числа небу и дымке.
+     *
+     * Небо и дальняя геометрия сходятся у горизонта, и считать их надо от одной величины: угла
+     * подъёма луча. Отсюда наклон оси камеры, фокус и центр кадра — по ним шейдер восстанавливает
+     * луч из пикселя (см. Transform.cameraRay).
+     */
+    private applyAtmosphere;
+    private skyBand;
     /** Небо: вертикальный градиент во весь экран. Геометрии у него нет. */
     private drawSky;
     /**
@@ -3779,6 +3852,14 @@ declare class LayerRenderer {
      * И масштаб, И начало — тогда координата остаётся непрерывной, а размеры
      * прежними.
      */
+    /**
+     * Накладка — слои вне общей очереди, без теста глубины.
+     *
+     * Позиций две, и они не взаимозаменяемы. `roads` идёт до объёма: разметка лежит на асфальте, и
+     * дом обязан её закрывать. `volume` идёт после: план этажа лежит ВНУТРИ здания, и в обычном
+     * порядке его закрыла бы крыша.
+     */
+    private drawOverlay;
     private applyTileScale;
     private applyMaterial;
     private drawFill;
@@ -4946,6 +5027,11 @@ declare const SURFACE_LEVEL_SCALE = 64;
 interface SurfaceOptions {
     /** Метров в единице тайла — все размеры ниже задаются в МЕТРАХ. */
     metersPerUnit: number;
+    /**
+     * Предел длины ребра в единицах тайла: длиннее — верхняя плоскость дробится. Нужно ГЛОБУСУ,
+     * где сфера гнёт вершины, а не рёбра. Ноль (плоская карта) выключает дробление.
+     */
+    maxSegment?: number;
     /** Уровень верхней плоскости, метры. Отрицательный — ниже земли. */
     elevation: number;
     /**