fix(render): use native shifted water reflection camera

1 files changed, 25 insertions, 10 deletions

diff --git a/docs/tomes/05-render.md b/docs/tomes/05-render.md
index a7a1396..53667c8 100644
--- a/docs/tomes/05-render.md
+++ b/docs/tomes/05-render.md
@@ -1147,13 +1147,27 @@ lightmap state передаются в `VulkanStaticMaterial`, а shader пос�
 В [эталонной сборке](../reference/original-binaries.md) выбор грани находится
 в Terrain.dll RVA `0x28A50`, а подготовка EMBM-пакета — в RVA `0x1B540`.
 
-Первый Vulkan-проход строит плоское зеркало. Для горизонтальной воды на
-высоте `h` отражённая координата точки равна `z′ = 2h − z`. Это преобразование
-применяется перед обычной проекцией. Оно меняет порядок вершин треугольника,
-поэтому проход меняет сторону отсечения и отбрасывает геометрию ниже воды.
+Для горизонтальной воды на высоте `h` камера отражения находится в точке
+`[eye_x, eye_y, 2h − eye_z]`. Но она не повторяет наклон основной камеры:
+смотрит вертикально вверх, а её окно лежит на прямоугольнике водоёма. Поэтому
+текстура отражения привязана к местности, а не к экрану игрока. В плоскости
+воды координаты изображения равны `U = 1 − Ynorm`, `V = 1 − Xnorm`.
+
+Terrain.dll RVA `0x4EFF0` передаёт shifted-проекции пять значений:
+`[min_y − eye_y, min_x − eye_x, span_y, span_x, eye_z − h]`. Например,
+для наблюдателя `[1200, 800, 185]`, воды `150` и границ
+`[1000, 500, 1500, 1200]` это `[-300, -200, 700, 500, 35]`.
+Матрица камеры и эти аргументы проверены исполнением оригинальной функции
+при двух положениях и разных поворотах основной камеры. Оракул подменяет
+ввод-вывод очереди, ландшафта и камеры; сам renderer и матрица глубины в эту
+проверку не входят. Vulkan-проекция сохраняет near/far основного вида;
+Rust-тест отдельно проверяет углы водоёма и границы глубины.
+
+Отражённый вид меняет сторону отсечения и отбрасывает геометрию ниже воды.
 Небо и оставшаяся сцена попадают в отдельную цветовую текстуру с собственной
-глубиной. В основном проходе водные треугольники читают её в экранной
-координате: точки самой плоскости не сдвигаются при отражении.
+глубиной. В основном проходе водные треугольники читают её по координатам
+водоёма с добавленным смещением волн. Для неперспективной камеры API остаётся
+обычное зеркало с экранными координатами.
 
 Цветовой target переходит из attachment layout в shader-read layout после
 записи. Следующий зеркальный проход ждёт предыдущего чтения этой текстуры;
@@ -1182,10 +1196,11 @@ lightmap state передаются в `VulkanStaticMaterial`, а shader пос�
 В Vulkan карта хранится в двух каналах несжатой текстуры и возвращается к
 знаковым значениям перед вычислением смещения.
 
-Обычное зеркало ещё не повторяет shifted-камеру оригинала: смещения Du/Dv
-сейчас переводятся из координат водоёма в текущую зеркальную проекцию.
-Это приближение учитывается в `planar_reflection_shifted_camera_unsupported`;
-совпадение генератора волн не доказывает совпадения итогового отражения.
+Матрица положения камеры, её окно и координаты волн восстановлены, но весь
+контекст отражённого вида ещё не повторён. Диапазон глубины, небо, туман и FX
+заимствуются из основного вида, а размер target совпадает со swapchain.
+Эти ограничения учитываются в `planar_reflection_render_context_approx`;
+совпадение генератора волн и окна не доказывает совпадения итогового отражения.
 Один target обслуживает ближайшую
 активную высоту воды; другие высоты и негоризонтальные поверхности явно
 считаются как неподдержанные. Это промежуточный водный проход, а не полная