Spatial: поверхность, свет, alpha и глубина

Spatial-шейдер задаёт поверхность 3D-меша. Назначьте Shader в ShaderMaterial, затем материал поверхности MeshInstance3D или его MaterialOverride. vertex() изменяет геометрию/атрибуты, fragment() задаёт свойства материала, light() при необходимости заменяет расчёт прямого света.

Первый материал и место назначения

Полный непрозрачный материал использует текстуру и tint. source_color отмечает цветовые данные, а hint_default_white позволяет получить цвет tint без отдельной текстуры:

shader_type spatial;
uniform sampler2D albedo_texture : source_color, hint_default_white;
uniform vec4 tint : source_color = vec4(1.0);
void fragment() {
    ALBEDO = texture(albedo_texture, UV).rgb * tint.rgb;
    METALLIC = 0.0;
    ROUGHNESS = 0.7;
}

ALBEDO — базовый цвет, не гарантированный итоговый RGB: освещение, белый блик неметалла, отражения, туман и тональная обработка меняют пиксель. Красный ALBEDO может дать ненулевые G/B из-за блика. Для просмотра только базового цвета используйте unshaded как диагностический режим.

Полный C#-помощник создаёт QuadMesh с материалом:

using Reckfell;

public static class SpatialSetup
{
    public static MeshInstance3D Create(Shader shader)
    {
        return new MeshInstance3D
        {
            Mesh = new QuadMesh { Size = new Vector2(1, 1) },
            MaterialOverride = new ShaderMaterial { Shader = shader },
        };
    }
}

Загрузите Shader через ResourceLoader.Load<Shader>("asset://PbrSurface.reckfellshader"), вызовите SpatialSetup.Create(shader) и добавьте результат в дерево. Камера у (0,0,5), смотрящая вдоль −Z, видит лицевую сторону этого quad. Для освещённого материала нужен свет или подходящее окружение.

Порядок выбора материала: MaterialOverride объекта → override конкретной поверхности → материал поверхности ресурса Mesh. GetSurfaceOverrideMaterial возвращает сохранённый override, который может быть неактивен из-за MaterialOverride. GetActiveMaterial помогает проверить фактически выбранный базовый материал. GetSurfaceOverrideMaterialCount считает слоты поверхностей, не число непустых override.

MaterialOverlay добавляет проход, подчинённый своей очереди, смешиванию и глубине; это не безусловный слой поверх. В проверке непрозрачный overlay на той же глубине не оказался сверху, а прозрачный корректно смешался с базой. Не рассчитывайте исправить порядок прозрачности одним названием overlay.

Координаты вершин и нормалей

По умолчанию VERTEX, NORMAL, TANGENT и BINORMAL входят в vertex() в локальном пространстве меша. MODEL_MATRIX переводит позицию в мир, VIEW_MATRIX — в пространство камеры, PROJECTION_MATRIX — в clip. В fragment() VERTEX и обычная NORMAL уже в пространстве вида. Матрица активного прохода тени может относиться к свету; MAIN_CAM_INV_VIEW_MATRIX относится к основной камере viewport.

Нормаль при неравномерном масштабе преобразуется обратной транспонированной матрицей. Умножение на обычную MODELVIEW_MATRIX как направления даёт неверный угол. Полный диагностический пример ручного пути:

shader_type spatial;
render_mode unshaded, skip_vertex_transform;
void vertex() {
    VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
    NORMAL = normalize(MODELVIEW_NORMAL_MATRIX * NORMAL);
    TANGENT = normalize(mat3(MODELVIEW_MATRIX) * TANGENT);
    BINORMAL = normalize(mat3(MODELVIEW_MATRIX) * BINORMAL);
}
void fragment() {
    ALBEDO = normalize(NORMAL) * 0.5 + 0.5;
}

skip_vertex_transform отключает автоматический model→view для позиции и базиса; проекция остаётся. Здесь NORMAL использует MODELVIEW_NORMAL_MATRIX, а касательные — линейную часть MODELVIEW_MATRIX. При сложных деформациях/неортогональном TBN дополнительно восстановите согласованный касательный базис. Не используйте эту запись как универсальное исправление любого normal-mapped/skinned меша.

В world_vertex_coords пользовательский vertex() получает мировые атрибуты; не применяйте MODEL_MATRIX второй раз. Если пишете POSITION, задавайте полный clip-space vec4 на всех ветках: автоматическая проекция позиции заменяется, но fragment VERTEX всё ещё формируется из VERTEX. Нельзя считать эти два выхода одним пространством. Нормализованный UV, SCREEN_UV viewport и пиксельный FRAGCOORD — также разные координаты.

Прозрачность и вырезание

У пространственного материала blend_mix является исходным режимом смешивания, но непрозрачность определяется и использованием ALPHA. В PbrSurface tint.a не используется: установка alpha цвета в 0 не делает поверхность прозрачной. Чтение/запись ALPHA может перевести материал в прозрачную очередь даже при значении 1; это меняет сортировку и участие в других эффектах.

Для плавной прозрачности запишите ALPHA. Для вырезанной формы можно сохранить жёсткую границу через ALPHA_SCISSOR_THRESHOLD. Полный пример оставляет правую половину quad непрозрачной:

shader_type spatial;
render_mode unshaded;
void fragment() {
    ALBEDO = vec3(1.0, 0.0, 0.0);
    ALPHA = UV.x;
    ALPHA_SCISSOR_THRESHOLD = 0.5;
}

Alpha hash использует ALPHA_HASH_SCALE для стохастического покрытия. Alpha-to-coverage требует соответствующего MSAA и настроек сглаживания; это не замена разрешению текстуры. Прозрачные поверхности сортируются с ограничениями и не ведут себя как набор попиксельно упорядоченных слоёв. depth_prepass_alpha помогает некоторым случаям, но не решает произвольную взаимную прозрачность.

NORMAL_MAP принимает карту нормалей в её кодировке, NORMAL — вектор нормали пространства вида. Не присваивайте NORMAL необработанный RGB текстуры. Цветовые текстуры/параметры помечайте source_color, карты данных — по их назначению; не переносите sRGB-преобразование на векторы, маски и физические параметры.

Собственный light()

Если light() не задан, движок использует готовое освещение. Пользовательская функция работает для источника, в пространстве вида. LIGHT — направление к нему, ATTENUATION учитывает ослабление/тени, LIGHT_COLOR — энергию и цвет. Для сложения источников накапливайте вклад через +=.

Полный простой диффузный расчёт:

shader_type spatial;
uniform vec3 base_color : source_color = vec3(1.0);
void fragment() {
    ALBEDO = base_color;
    ROUGHNESS = 1.0;
}
void light() {
    float ndotl = max(dot(NORMAL, LIGHT), 0.0);
    DIFFUSE_LIGHT += ndotl * ATTENUATION * LIGHT_COLOR / PI;
}

В текущем Forward+ итоговый diffuse ещё умножается на ALBEDO. Поэтому повторное умножение на ALBEDO в примере light() затемнило бы цвет дважды. Проверка подтверждает однократное применение. source_color также переводит введённый цвет в линейное пространство: значение 0.5 в цветовом параметре нельзя автоматически считать линейной интенсивностью 0.5.

Пример рассчитан на обычный прямой диффузный свет, не на полную PBR-модель. Для area light учитывайте специальные данные/множители, а для блика задавайте SPECULAR_LIGHT. unshaded обходит освещение; vertex_lighting может обходить пользовательский попиксельный light(). Сначала проверьте требуемый путь, затем усложняйте BRDF.

Глубина: учитывайте проход, а не только число

В проверенном Forward+/Vulkan используется reverse-Z: DEPTH=0 — далеко, DEPTH=1 — близко. CLIP_SPACE_FAR описывает дальнюю clip-координату рендерера; это не готовое мировое расстояние. Для восстановления позиции по экранной глубине используйте подходящую INV_PROJECTION_MATRIX и деление на w; см. экранные шейдеры.

Если DEPTH записывается на одной ветке, задайте его осмысленно на всех ветках. Отдельно проверьте depth-prepass и тени: они не обязаны повторять произвольный фрагментный алгоритм.

В установленном Forward+ воспроизведён конкретный дефект: простой opaque-материал с пользовательским DEPTH может использовать общий prepass, где эта запись не учитывается. Геометрия закрывает задний объект в prepass, а затем её цвет не проходит проверку новой глубины — появляется чёрный участок. В исходнике выбор общего материала prepass не проверяет запись DEPTH. Это ограничение данной конфигурации, не признак того, что reverse-Z равен обычному Z. Отдельная проверка прозрачного пути без записи глубины подтвердила 0/1 относительно задней непрозрачной поверхности. Не используйте пользовательский DEPTH как универсальный трюк перекрытия без проверки всех нужных проходов.

Stencil: запись и чтение маски

Текущий синтаксис использует stencil_mode, значение 0–255 и режимы write/read/write_depth_fail. Правильное имя — write_depth_fail, не write_if_depth_fail. Чтение должно идти через прозрачную очередь. Эти примеры дают синюю поверхность-записыватель и красного читателя внутри её маски:

shader_type spatial;
render_mode unshaded;
stencil_mode write, 1;
void fragment() {
    ALBEDO = vec3(0.0, 0.0, 1.0);
}

shader_type spatial;
render_mode unshaded, depth_test_disabled;
stencil_mode read, compare_equal, 1;
void fragment() {
    ALBEDO = vec3(1.0, 0.0, 0.0);
    ALPHA = 1.0;
}

Назначьте их двум мешам; читатель может быть крупнее записывателя. В проверке красный виден только внутри маски, а движение записывателя обновляет её. Читатель специально пишет ALPHA=1 и отключает depth test. Это минимальная проверка маски, не готовый портал или outline-эффект.

Для сравнения доступны compare_always, compare_equal, compare_not_equal, compare_less, compare_less_or_equal, compare_greater и compare_greater_or_equal. Сравнивается reference с содержимым stencil. Не считайте stencil обычной цветовой текстурой: в spatial нет встроенного sampler этого буфера. Поддержку конкретного рендерера/прохода проверяйте отдельно.

Полный реестр встроенных значений

G — глобально; V — vertex(); F — fragment(); L — light(). Звёздочка после этапа означает, что значение допускает запись. Имена без неё доступны только для чтения. Начальные значения и назначение результата зависят от поля; при условной записи выходов задавайте их на всех нужных ветках.

Режимы отрисовки

Выбирайте согласованные режимы, а не все одновременно. Политика записи depth не отменяет тест глубины и ограничения очереди.

TIME сбрасывается по rendering/limits/time/time_rollover_secs, по умолчанию через 3600 секунд. Для паузируемой игровой анимации передавайте собственное время uniform.

При выключенном ambient стандартное specular occlusion может обнулить зеркальный вклад даже при корректном RADIANCE или ReflectionProbe. В текущих Forward+ и Mobile ветка без bent-normal карты использует яркость ambient как приближение видимости отражения. Для изолированной проверки используйте specular_occlusion_disabled; в StandardMaterial3D — DisableSpecularOcclusion. Это не отключение прямых теней или diffuse AO. Настройка и проверенные условия.

Диагностика

В установленном Windows Forward+/Vulkan проверены шесть полных шейдеров и C#-помощник: базовая поверхность, нормали, culling, ALPHA/scissor, прямой свет, DEPTH, stencil и приоритет материалов. Реестр 95 имён и остальные режимы сверены с исходниками. Это не полная проверка всех BRDF, SSS, area light, MSAA, деформаций/скелета, стриминга, XR, теней и платформ. Функциональные пиксельные чтения не публикуются как художественные иллюстрации; дефект пользовательского DEPTH зафиксирован в проверке.