fix: preserve native sky sprite screen depth

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/reference/environment-effects.md b/docs/reference/environment-effects.md
index 8045d68..fdc29f0 100644
--- a/docs/reference/environment-effects.md
+++ b/docs/reference/environment-effects.md
@@ -207,6 +207,35 @@ packed: [key.colors[10], key.colors[14]],
 `AtmosphereFrame` пока не несёт этот бит обновления, поэтому sampler
 выдаёт интерполированный цвет при каждом запросе.
 
+## Экранная геометрия солнца и луны
+
+`CSun::Render` сначала переводит направление небесного тела в пиксели текущего
+viewport, затем собирает quad с native XYZRHW-позицией. При положительной высоте
+viewport Vulkan пиксели переводятся в clip-space так:
+
+```rust
+position = [
+    pixel[0] * (2.0 / width) - 1.0,
+    pixel[1] * (2.0 / height) - 1.0,
+    0.999,
+];
+```
+
+Vertex shader пропускает `clip_from_world` для строк солнца и луны. CPU каждый
+кадр пересчитывает центр и размер quad по текущему viewport; старые пиксельные
+координаты не переносятся на новый размер. World-space billboards бликов
+остаются отдельным путём. Материал экранного quad не освещается, vertex fog
+отключён, а sky far-depth bit к нему не применяется.
+
+Native `z = 0.999` не означает, что спрайт гарантированно лежит за любой
+поверхностью. Vulkan использует `LESS_OR_EQUAL` и не записывает depth для
+прозрачного ряда. При near `0.5`, far `700` мировая поверхность на расстоянии
+`320` получает depth
+`700 / (700 - 0.5) * (1 - 0.5 / 320) ≈ 0.999151`; поэтому экранный `0.999`
+чуть ближе этой поверхности и проходит depth test перед ней. Это фиксированное
+native значение сохраняется для совместимости, но само по себе не обещает
+окклюзию солнца всей геометрией местности.
+
 ## Что остаётся за владельцем
 
 `EnvironmentSystem` не извлекает камеру из renderer, не разрешает материалы