osmgl 0.7.0 → 0.7.2

package/dist/osmgl.d.cts

@@ -1780,25 +1780,43 @@ interface ErrorResponse {
 }
 type WorkerResponse = LoadedResponse | ErrorResponse;
 
-/**
- * Пул воркеров с round-robin раздачей.
- *
- * Если бандл воркера недоступен (dev из исходников, запрет Blob-воркеров политикой
- * CSP), пул честно работает в главном потоке: карта тормозит на разборе, но не падает.
- */
 declare class WorkerPool {
     private workers;
     private blobUrl;
     private pending;
+    private queue;
+    /** Сколько задач сейчас у каждого воркера. */
+    private busy;
     private nextId;
-    private cursor;
     private mainThreadAborts;
     private destroyed;
     readonly usingWorkers: boolean;
     constructor(size?: number);
     get size(): number;
-    /** Ставит тайл в очередь. Возвращает id — им же и отменяют. */
-    load(req: Omit<LoadRequest, 'type' | 'id'>, onDone: (res: WorkerResponse) => void): number;
+    /**
+     * Ставит тайл в очередь. Возвращает id — им же и отменяют.
+     *
+     * `priority` — чем меньше, тем раньше. Порядок постановки значения не имеет: очередь разбирается
+     * по важности, а не по времени (см. [[pump]]).
+     */
+    load(req: Omit<LoadRequest, 'type' | 'id'>, onDone: (res: WorkerResponse) => void, priority?: number): number;
+    /**
+     * Раздаёт задачи наименее загруженному воркеру, пока у него меньше PER_WORKER задач.
+     *
+     * Почему НЕ по одной. Освобождает воркера главный поток — он получает ответ и отправляет
+     * следующую задачу. Значит при одной задаче на воркера пропускная способность упирается в
+     * главный поток: пока он занят кадром (или притормаживается в скрытой вкладке), воркеры стоят.
+     * Второй задачи в запасе хватает, чтобы работа не прерывалась, и при этом неотменяемыми
+     * оказываются лишь единицы задач вместо трёхсот.
+     *
+     * ПОРЯДОК — ПО ВАЖНОСТИ, А НЕ ПО ОЧЕРЕДИ. На широком экране одно движение камеры ставит триста
+     * с лишним тайлов на семь источников, и в порядке поступления полсотни тайлов самой карты
+     * оказывались перемешаны с двумя с половиной сотнями пробок, точек и размещений: карта под
+     * курсором ждала, пока разберут декор на другом краю кадра. Важность считает источник — она
+     * складывается из его ранга и расстояния до камеры, так что первой приезжает основа в середине
+     * экрана. Выбор минимума перебором: очередь живёт сотнями записей, куча тут не окупается.
+     */
+    private pump;
     abort(id: number): void;
     private onMessage;
     private disposeWorkers;
@@ -1968,6 +1986,14 @@ interface TileSourceOptions extends CoverOptions {
     plan: LayerPlan[];
     /** Сколько тайлов держать в кеше сверх видимых. */
     cacheSize?: number;
+    /**
+     * Важность источника в общей очереди воркеров: 0 — основа карты, дальше по убыванию.
+     *
+     * Пул один на все источники, и на широком экране пробки с размещениями ставят в него вчетверо
+     * больше тайлов, чем сама карта. Ранг решает, кого разбирать первым. По умолчанию 1 — «поверх
+     * основы».
+     */
+    rank?: number;
 }
 interface TileSourceEvents extends Record<string, unknown> {
     /** Пришли новые данные — надо перерисовать кадр. */
@@ -1984,8 +2010,6 @@ declare class TileSource extends Evented<TileSourceEvents> {
     private pool;
     private cache;
     private visible;
-    /** Момент, с которого держим прежний набор вместо нового. 0 — не держим. */
-    private holdSince;
     /** Показывали ли уже готовую картину. См. [[warm]]. */
     private warmed;
     /**
@@ -2022,6 +2046,34 @@ declare class TileSource extends Evented<TileSourceEvents> {
     get pendingCount(): number;
     /** Пересчитывает видимый набор под текущую камеру и запускает недостающие загрузки. */
     update(tr: Transform): void;
+    /**
+     * Покрытие из ГОТОВЫХ тайлов: где нужного ещё нет, его место занимает загруженный предок.
+     *
+     * Предок покрывает весь свой квадрат, поэтому подменять им один тайл, оставив рядом второй,
+     * значит закрасить это место дважды — полупрозрачный слой там лёг бы вдвое плотнее. Значит
+     * квадрат берётся целиком, и отсюда главное ограничение: предок годится, только если под ним
+     * НЕТ НИ ОДНОЙ уже готовой цели. Иначе подмена не добавляла бы картинку, а стирала — грубый
+     * предок уносил с собой всю подробность на своей площади, и дальний план пустел. Проверено.
+     */
+    private coverFor;
+    /**
+     * Готовые потомки целей — по одному проходу ПО КЕШУ, а не перебором дерева вниз.
+     *
+     * Перебор вниз стоит четыре тайла на уровень, шестнадцать на два, шестьдесят четыре на три — и
+     * всё равно упирается в свою глубину: после отдаления на пять зумов загруженное лежит ещё ниже,
+     * и до него так не достать. Проход по кешу дешевле (в нём сотни тайлов, а не тысячи гипотез) и
+     * глубиной не ограничен вовсе.
+     *
+     * Потомки безопасны без оговорок: они лежат ВНУТРИ своей цели, рисовать которую всё равно нечем,
+     * и не пересекаются между собой.
+     */
+    private descendantsOf;
+    /**
+     * Есть ли в наборе хоть один готовый тайл.
+     *
+     * Порог для «ждать надоело»: показывать набор, где не приехало НИЧЕГО, значит показать пустоту.
+     */
+    private anyReady;
     /** Готов ли набор целиком: у каждого тайла есть ответ — с геометрией, пустой или с ошибкой. */
     private readyFor;
     /**
@@ -2032,6 +2084,16 @@ declare class TileSource extends Evented<TileSourceEvents> {
      * нельзя: за краем кадра его просто не существует, и мы показали бы пустоту вместо загрузки.
      */
     private covers;
+    /**
+     * Источник никто не рисует: снять загрузки и очистить видимый набор.
+     *
+     * Набор считался и качался всегда, даже когда ни один его слой на этом зуме не показывают. На
+     * широком экране это давало полторы сотни тайлов размещений на зуме, где 3D-объектов ещё нет
+     * вовсе, и столько же выключенных пробок — и всё это стояло в очереди перед самой картой.
+     * Загруженное остаётся в кеше: вернуться в свой диапазон зума источник должен без повторной
+     * загрузки.
+     */
+    deactivate(): void;
     private loadTile;
     /**
      * Готовый предок для тайла, который ещё грузится — чтобы на его месте не зияла
@@ -5507,6 +5569,14 @@ declare class Map$1 extends Evented<MapEvents> {
      * при смене темы, — и забытое место означало бы «объекты пропали после
      * переключения темы».
      */
+    /**
+     * Рисует ли этот набор хоть кто-нибудь на текущем зуме.
+     *
+     * Считаем по СТИЛЮ, а не по плану воркера: план нарочно не знает ни зумов слоя, ни тумблеров
+     * видимости — тайл кешируется один раз и обязан оставаться пригодным на любом зуме. А вот
+     * КАЧАТЬ его, пока ни один слой набора не показывают, смысла нет.
+     */
+    private sourceDrawn;
     private planFor;
     /**
      * Пересчёт детальных 3D-объектов по текущей камере.

package/dist/osmgl.d.ts

@@ -1780,25 +1780,43 @@ interface ErrorResponse {
 }
 type WorkerResponse = LoadedResponse | ErrorResponse;
 
-/**
- * Пул воркеров с round-robin раздачей.
- *
- * Если бандл воркера недоступен (dev из исходников, запрет Blob-воркеров политикой
- * CSP), пул честно работает в главном потоке: карта тормозит на разборе, но не падает.
- */
 declare class WorkerPool {
     private workers;
     private blobUrl;
     private pending;
+    private queue;
+    /** Сколько задач сейчас у каждого воркера. */
+    private busy;
     private nextId;
-    private cursor;
     private mainThreadAborts;
     private destroyed;
     readonly usingWorkers: boolean;
     constructor(size?: number);
     get size(): number;
-    /** Ставит тайл в очередь. Возвращает id — им же и отменяют. */
-    load(req: Omit<LoadRequest, 'type' | 'id'>, onDone: (res: WorkerResponse) => void): number;
+    /**
+     * Ставит тайл в очередь. Возвращает id — им же и отменяют.
+     *
+     * `priority` — чем меньше, тем раньше. Порядок постановки значения не имеет: очередь разбирается
+     * по важности, а не по времени (см. [[pump]]).
+     */
+    load(req: Omit<LoadRequest, 'type' | 'id'>, onDone: (res: WorkerResponse) => void, priority?: number): number;
+    /**
+     * Раздаёт задачи наименее загруженному воркеру, пока у него меньше PER_WORKER задач.
+     *
+     * Почему НЕ по одной. Освобождает воркера главный поток — он получает ответ и отправляет
+     * следующую задачу. Значит при одной задаче на воркера пропускная способность упирается в
+     * главный поток: пока он занят кадром (или притормаживается в скрытой вкладке), воркеры стоят.
+     * Второй задачи в запасе хватает, чтобы работа не прерывалась, и при этом неотменяемыми
+     * оказываются лишь единицы задач вместо трёхсот.
+     *
+     * ПОРЯДОК — ПО ВАЖНОСТИ, А НЕ ПО ОЧЕРЕДИ. На широком экране одно движение камеры ставит триста
+     * с лишним тайлов на семь источников, и в порядке поступления полсотни тайлов самой карты
+     * оказывались перемешаны с двумя с половиной сотнями пробок, точек и размещений: карта под
+     * курсором ждала, пока разберут декор на другом краю кадра. Важность считает источник — она
+     * складывается из его ранга и расстояния до камеры, так что первой приезжает основа в середине
+     * экрана. Выбор минимума перебором: очередь живёт сотнями записей, куча тут не окупается.
+     */
+    private pump;
     abort(id: number): void;
     private onMessage;
     private disposeWorkers;
@@ -1968,6 +1986,14 @@ interface TileSourceOptions extends CoverOptions {
     plan: LayerPlan[];
     /** Сколько тайлов держать в кеше сверх видимых. */
     cacheSize?: number;
+    /**
+     * Важность источника в общей очереди воркеров: 0 — основа карты, дальше по убыванию.
+     *
+     * Пул один на все источники, и на широком экране пробки с размещениями ставят в него вчетверо
+     * больше тайлов, чем сама карта. Ранг решает, кого разбирать первым. По умолчанию 1 — «поверх
+     * основы».
+     */
+    rank?: number;
 }
 interface TileSourceEvents extends Record<string, unknown> {
     /** Пришли новые данные — надо перерисовать кадр. */
@@ -1984,8 +2010,6 @@ declare class TileSource extends Evented<TileSourceEvents> {
     private pool;
     private cache;
     private visible;
-    /** Момент, с которого держим прежний набор вместо нового. 0 — не держим. */
-    private holdSince;
     /** Показывали ли уже готовую картину. См. [[warm]]. */
     private warmed;
     /**
@@ -2022,6 +2046,34 @@ declare class TileSource extends Evented<TileSourceEvents> {
     get pendingCount(): number;
     /** Пересчитывает видимый набор под текущую камеру и запускает недостающие загрузки. */
     update(tr: Transform): void;
+    /**
+     * Покрытие из ГОТОВЫХ тайлов: где нужного ещё нет, его место занимает загруженный предок.
+     *
+     * Предок покрывает весь свой квадрат, поэтому подменять им один тайл, оставив рядом второй,
+     * значит закрасить это место дважды — полупрозрачный слой там лёг бы вдвое плотнее. Значит
+     * квадрат берётся целиком, и отсюда главное ограничение: предок годится, только если под ним
+     * НЕТ НИ ОДНОЙ уже готовой цели. Иначе подмена не добавляла бы картинку, а стирала — грубый
+     * предок уносил с собой всю подробность на своей площади, и дальний план пустел. Проверено.
+     */
+    private coverFor;
+    /**
+     * Готовые потомки целей — по одному проходу ПО КЕШУ, а не перебором дерева вниз.
+     *
+     * Перебор вниз стоит четыре тайла на уровень, шестнадцать на два, шестьдесят четыре на три — и
+     * всё равно упирается в свою глубину: после отдаления на пять зумов загруженное лежит ещё ниже,
+     * и до него так не достать. Проход по кешу дешевле (в нём сотни тайлов, а не тысячи гипотез) и
+     * глубиной не ограничен вовсе.
+     *
+     * Потомки безопасны без оговорок: они лежат ВНУТРИ своей цели, рисовать которую всё равно нечем,
+     * и не пересекаются между собой.
+     */
+    private descendantsOf;
+    /**
+     * Есть ли в наборе хоть один готовый тайл.
+     *
+     * Порог для «ждать надоело»: показывать набор, где не приехало НИЧЕГО, значит показать пустоту.
+     */
+    private anyReady;
     /** Готов ли набор целиком: у каждого тайла есть ответ — с геометрией, пустой или с ошибкой. */
     private readyFor;
     /**
@@ -2032,6 +2084,16 @@ declare class TileSource extends Evented<TileSourceEvents> {
      * нельзя: за краем кадра его просто не существует, и мы показали бы пустоту вместо загрузки.
      */
     private covers;
+    /**
+     * Источник никто не рисует: снять загрузки и очистить видимый набор.
+     *
+     * Набор считался и качался всегда, даже когда ни один его слой на этом зуме не показывают. На
+     * широком экране это давало полторы сотни тайлов размещений на зуме, где 3D-объектов ещё нет
+     * вовсе, и столько же выключенных пробок — и всё это стояло в очереди перед самой картой.
+     * Загруженное остаётся в кеше: вернуться в свой диапазон зума источник должен без повторной
+     * загрузки.
+     */
+    deactivate(): void;
     private loadTile;
     /**
      * Готовый предок для тайла, который ещё грузится — чтобы на его месте не зияла
@@ -5507,6 +5569,14 @@ declare class Map$1 extends Evented<MapEvents> {
      * при смене темы, — и забытое место означало бы «объекты пропали после
      * переключения темы».
      */
+    /**
+     * Рисует ли этот набор хоть кто-нибудь на текущем зуме.
+     *
+     * Считаем по СТИЛЮ, а не по плану воркера: план нарочно не знает ни зумов слоя, ни тумблеров
+     * видимости — тайл кешируется один раз и обязан оставаться пригодным на любом зуме. А вот
+     * КАЧАТЬ его, пока ни один слой набора не показывают, смысла нет.
+     */
+    private sourceDrawn;
     private planFor;
     /**
      * Пересчёт детальных 3D-объектов по текущей камере.