osmgl 0.14.1 → 0.16.0

package/README.md

@@ -158,6 +158,43 @@ nginx отдаёт его двумя путями — `/maps/osmgl.global.js` (
 выключенным depth-тестом (всё лежит на z=0, тест дал бы только z-fighting), затем
 объёмные слои с честной глубиной.
 
+### Линия, уступающая подробному слою (`yieldTo`)
+
+Пара «линия дороги — асфальт» живёт в разных наборах тайлов: линия приходит с основой, асфальт
+(полотно по графу) — своим набором с z15. Гасить линию `maxzoom` по зуму камеры нельзя, и это
+измерено, а не придумано:
+
+- пока тайл асфальта едет, улицы нет вовсе — ни линии, ни полотна (замер с задержкой ответов
+  полотна на 4 с: с `maxzoom` проезжая часть пуста, с уступкой видна вся сеть);
+- у наклонённой карты дальние тайлы рисуются с меньшей подробностью (`Transform.detailZoom`), и
+  асфальт с `minzoom: 15` гаснет вдали сам. На z15.6 при наклоне 75° дорог не было в дальней
+  трети кадра — подписи улиц висели над пустой землёй.
+
+Поэтому линия объявляет `"yieldTo": "<id поверхности>"` и рисуется везде, КРОМЕ квадратов тайлов,
+в которых эта поверхность в кадре уже легла. Квадраты ставятся битом трафарета (`PAINTED_BIT`) перед
+проходом поднятых линий и снимаются после него. Это «грубое сразу, подробное кусками» у Baidu
+(`useThumbData`).
+
+Уступка идёт ПО КВАДРАТУ ТАЙЛА, а не по пикселю асфальта: линия дороги шире полотна (ширина линии —
+приём картографии в пикселях), и маска по самому асфальту оставила бы вдоль кромки полоску старой
+линии. Квадрат, чья геометрия отложена бюджетом загрузки, не ставится — иначе в нём на кадр не было
+бы ни того, ни другого. Там, где асфальт уже загружен, кадр совпадает с прежним до пикселя.
+
+ГОЧА: на слабом профиле поверхность рисуется ЗАЛИВКОЙ (`flattened`), поэтому квадраты пишет и
+`drawFill`. Без этого на телефоне линии лежали поверх асфальта, а на компьютере — нет.
+
+### Линия под настилом (`depthTest`)
+
+Поднятые линии рисуются без теста глубины: краска лежит на своём асфальте в сантиметрах, и такой
+зазор буфер глубины не различает. Поэтому краска улицы под эстакадой проступала сквозь настил.
+
+Слой с `"depthTest": true` проходит тест глубины (без записи), а его глубина сдвинута к камере на
+долю расстояния (`DEPTH_NUDGE` = 0.4 %). Своё полотно в сантиметрах ниже её не закрывает, настил в
+5–8 м над ней — закрывает. Сдвиг — одна постоянная в z клипа на кадр: `B·k/(1−k)`, где `B` — элемент
+[14] перспективы (`Transform.projZOffset`); точка на экране не двигается. Действует только в
+проходе поднятых линий, не на шаре и не в текстуре рельефа. Дальше ~2 км от камеры сдвиг больше
+просвета, и краска под настилом снова видна.
+
 ### Разноцветная линия
 
 Маршрут, раскрашенный по пробкам, — как у Яндекса:
@@ -386,6 +423,27 @@ new OsmGL.Map({ icons: { taxi: '<svg viewBox="0 0 24 24">…</svg>' } })
 Настоящего шейпинга нет: перо двигается по `advance`. Кириллице, латинице и таджикскому
 этого достаточно, арабский и иврит потребуют отдельного прохода.
 
+### Иерархия подписей мест
+
+Во всех пяти стилях места делятся по КЛАССУ, а не по рангу. Ранг в тайлах navigram — порядковый
+номер внутри клетки сетки, о размере места он не говорит ничего: Худжанд с рангом 12 до z10.5 не
+показывался вовсе. Приоритет слоя сильнее любого ранга фичи, поэтому порядок задаётся слоями:
+
+| Слой | Что | С зума | `priority` |
+|------|-----|--------|-----------:|
+| `place-capital` | столица и центры областей: Душанбе, Худжанд, Бохтар, Хорог | 4 | 110 |
+| `place-region` | области (свой источник `regions` в стиле) | 4.5 | 100 |
+| `place-label` | остальные города и страна | 4 | 90 |
+| `place-label-minor` | посёлки (`town`) | 7.5 | 70 |
+| `place-label-local` | сёла, кварталы, острова | 10.5 | 55 |
+
+Верхнего зума у областей нет. Центры стоят ВЫШЕ областей: крупное название области иначе
+накрывает на мелком зуме свой же областной центр. Признака столицы (`capital`) в тайлах navigram
+нет, поэтому центры выбираются по имени, в обоих написаниях (`Хуҷанд`/`Худжанд`, `Хоруғ`/`Хорог`).
+Обычные города исключают их тем же списком (`!in`), иначе одна подпись встала бы дважды. Точек
+областей в данных navigram нет совсем, поэтому они едут в стиле встроенным geojson-источником.
+Проверяется `tests/places.test.mjs`.
+
 ## Планы этажей
 
 Помещения ТЦ, вокзалов и рынков. Схема тайлов — [indoorequal](https://github.com/indoorequal/indoorequal)
@@ -667,6 +725,11 @@ CPU в экранных координатах — поэтому пережив
 перенесённые сюда скриптом, чтобы карта на своём движке выглядела так же, как
 везде в продукте:
 
+Ледяная модель света у зданий (`ice: 1`: свет прибавляется, тёмных сторон нет, швов нет) стоит не
+только у `ice`: её кодом получают светлая `3d`, тёмная `night` и пара «Атлас» (`atlas-day`,
+`atlas-night`). У тёмного «Атласа» кровля — цветом стены: своей у палитры нет, и движок брал ей
+светлую по умолчанию.
+
 `ice` — отдельная тема со СВОЕЙ палитрой целиком, а не правка светлой. Цвета сняты
 с растровых тайлов Baidu Maps (Луцзяцзуй, z17, 25 тайлов): земля `#f5f3f0`,
 дороги белые с серой обводкой `#dbdbdd`, магистрали `#ffd86b`, вода `#90ddf6`,
@@ -994,6 +1057,12 @@ map.getQuality()                     // { auto, profile, pixelRatio }
 | `balanced` | ≤1.75 | ≤2560×2160 | да | ≤4 | 1024 | 0.85 |
 | `low` | ≤1.25 | ≤1920×1350 | нет | ≤2 | 512 | 0.5 |
 
+На `low` и `minimal` геометрия упрощается (`simpleGeometry`): объёмные поверхности становятся
+плоскими заливками. Исключение — полотно дорог с настилом (`deck`): его объём даёт и высоту
+эстакады, и глубину, которой настил закрывает разметку под собой (`depthTest`). Пока оно
+упрощалось, режим «Эстакады с высотой» на слабом телефоне не делал ничего, а эмулятор Android
+(он определяется как `minimal`) показывал эстакады плоскими.
+
 Телефон отличается от десктопа не столько силой GPU, сколько **плотностью
 экрана**: при `devicePixelRatio` 3 кадр 412×892 CSS — это 3,3 миллиона
 пикселей, вдвое больше типичного окна на ноутбуке, и рисует их вчетверо более
@@ -1482,6 +1551,14 @@ node scripts/smoke.mjs         # рендер в headless-браузере, 4 р
 
 ## Грабли, на которые уже наступили
 
+- **Перенос кадра подписей на Android и iOS (KMP) усыплял проявление.** Подпись встаёт в
+  начале проявления, почти прозрачной. Следующие ~300 мс кадр подписей переносится на камеру
+  (`reproject`) вместе с прозрачностью на момент раскладки и продолжения не просит. На
+  неподвижной карте цикл кадров засыпал, и подписи оставались невидимыми до первого касания.
+  Чаще всего это видно на мелком зуме: шрифт приезжает позже тайлов. Теперь проход подписей
+  просит кадр, пока кадр `fading`, и на переносе тоже (`labelsFading` в `layers/Renderer.kt`).
+  В вебе переноса нет, поэтому там этого не было. Проверяется
+  `SymbolFrameTest.lateGlyphsArePlacedWithoutCameraMove`.
 - **`ELEMENT_ARRAY_BUFFER` — состояние VAO, а не глобальное.** Создание индексного буфера
   соседнего тайла, пока привязан VAO предыдущего, молча переписывало тому привязку: тайл
   начинал рисовать чужими индексами по своим вершинам. Ошибок GL нет, кадр не падает — тайл