Архитектура рендеринга: путь кадра и подсистемы
Entity, ресурсы, RenderingServer, драйверы, буферы, расширения и диагностика по исходникам.
Этот раздел показывает путь данных рендеринга в Reckfell 1.0.0 и помогает выбрать место для диагностики или доработки. Описанная архитектура сверена с текущими исходниками. Исполнение проверено в отдельных сценариях Windows/Vulkan Forward+ и Mobile; это не проверка всех эффектов, драйверов или качества изображения.
Путь от Entity до кадра
Entity / Resource
|
RenderingServer / RID
|
RendererSceneCull + RendererCanvasCull + RendererViewport
|
+-- Forward+ / Mobile --> RenderingDevice --> graphics driver --> GPU
|
+-- Compatibility ------> GLES3 renderer --> OpenGL driver --> GPUMeshInstance3D использует Mesh и материалы как ресурсы. VisualInstance3D создаёт серверный instance, передаёт базовый ресурс и обновляет трансформ через RenderingServer. Несколько Entity могут ссылаться на один Mesh; размещение объекта и геометрия ресурса — разные данные. Число Entity не равно числу draw calls: поверхности, материалы, проходы и тени влияют на работу рендера.
RenderingServer предоставляет API ресурсов и операций рендера через RID. RendererSceneCull собирает видимую 3D-сцену, RendererCanvasCull обрабатывает canvas, RendererViewport организует вывод камер и целевых текстур. Это позволяет работать с серверными ресурсами напрямую, но тогда их настройка и жизненный цикл становятся обязанностью вызывающего кода.
RenderingDevice — более низкий уровень: текстуры, буферы, шейдеры, pipeline, uniform sets и списки draw/compute-команд. Он не создаёт автоматически Material, камеру, коллизии или правила видимости. Его граф команд обслуживает зависимости GPU-работы; игровая иерархия остаётся в EntityTree.
Метод рендеринга и драйвер
| Метод | Серверная реализация | Графический путь |
|---|---|---|
| forward_plus | RenderForwardClustered | RenderingDevice |
| mobile | RenderForwardMobile | RenderingDevice |
| gl_compatibility | GLES3 | OpenGL-семейство |
| dummy | Диагностический путь без нормального GPU-вывода | Не подтверждает работу GPU |
Метод задаёт организацию рендера; драйвер реализует графический API. В коде запуска для Forward+/Mobile перечислены Vulkan, Direct3D 12 и Metal под соответствующими флагами сборки. Для Compatibility перечислены opengl3/opengl3_angle/opengl3_es. Наличие исходника драйвера не означает, что он включён в конкретную поставку или проверен на вашей платформе.
Сохраняйте вместе RenderingServer.GetCurrentRenderingMethod(), RenderingServer.GetCurrentRenderingDriverName(), модель GPU и журнал запуска. Одной настройки rendering/renderer/rendering_method недостаточно для диагностики всех fallback-сценариев. Например, RendererCompositorRD содержит переход с clustered-пути на Mobile при лимите менее 48 текстур на shader stage; это условие исходника, а не отдельная проверка такого GPU здесь.
Forward+ использует ClusterBuilderRD для подготовки кластерных данных, применяемых при освещении. Mobile имеет отдельную организацию проходов и буферов; общая база RenderingDevice не делает их набор эффектов одинаковым. Compatibility использует отдельную GLES3-реализацию. Выбирайте метод по нужным функциям и измерениям целевой сцены: название Mobile само по себе не гарантирует скорость, а Forward+ — качество готовой картинки.
Что происходит при отрисовке
В RenderingServerDefault::_draw видны следующие крупные этапы:
- Начало кадра и подготовка XR, когда он включён.
- Обновление scene/canvas и данных частиц.
- Подготовка отражающих проб.
- Отрисовка viewport.
- Завершение кадра и уведомления видимости.
Внутри 3D-пути RendererSceneCull готовит камеру, видимые instance и связанные данные освещения, GI, decal, lightmap и fog. Затем выбранная реализация получает render_scene. Порядок конкретных GPU-проходов зависит от метода и включённых функций; этот список не является неизменным списком render passes.
Viewport определяет целевой размер, камеру и конфигурацию вывода. RenderSceneBuffersRD хранит промежуточные RD-текстуры и данные проходов. Размер, число представлений, MSAA и форматы буферов влияют на память и доступность чтения. Не предполагайте, что любой эффект всегда получает одинаковые color/depth-текстуры или что приватное имя внутреннего буфера — публичный контракт SDK.
Свойство Visible — только одно условие участия объекта: дополнительно учитываются камера, слои, расстояние, culling и готовность ресурсов. Для пропавшего объекта сначала проверьте путь до нужного viewport, затем материал и геометрию; не начинайте с правки драйвера.
Шейдеры проекта и шейдеры движка
Shader передаёт подготовленный код в RenderingServer.shader_set_code. Material передаёт параметры и ссылки на ресурсы; BaseMaterial3D генерирует код по своим функциям. Поэтому смена параметра материала и смена набора его функций могут иметь разную стоимость подготовки.
Во внутренних RD/GLES3-шейдерах реализованы этапы рендера. Их исходники и генерируемые заголовки входят в сборку движка. Изменение такого GLSL-файла в репозитории само по себе не меняет уже установленный бинарник; для применения правки нужна соответствующая сборка. Шейдер проекта хранится и компилируется другим путём. Для прикладного эффекта начинайте с языка шейдеров, а не с изменения общего material shader движка.
Первый показ нового варианта может включать подготовку шейдера/pipeline. Это отдельная причина задержки от постоянной стоимости каждого кадра. Измеряйте первый запуск и установившуюся сцену отдельно; этот раздел не устанавливает их длительность на вашем устройстве.
Где находятся подсистемы
Все пути ниже относительны локальному дереву Source; это навигация по исходникам, не архивы для скачивания.
| Задача | Начните с |
|---|---|
| Mesh instance и серверный RID | scene/3d/mesh_instance_3d.cpp; scene/3d/visual_instance_3d.cpp |
| Обновление/диспетчеризация кадра | servers/rendering/rendering_server_default.cpp |
| Камера, видимость и данные сцены | servers/rendering/renderer_scene_cull.cpp |
| Viewport и canvas | servers/rendering/renderer_viewport.cpp; renderer_canvas_cull.cpp в той же папке |
| Выбор RD-реализации | servers/rendering/renderer_rd/renderer_compositor_rd.cpp |
| Forward+ и кластеризация | servers/rendering/renderer_rd/forward_clustered/; cluster_builder_rd.cpp |
| Mobile | servers/rendering/renderer_rd/forward_mobile/ |
| Compatibility | drivers/gles3/ |
| GPU-буферы сцены | servers/rendering/renderer_rd/storage_rd/render_scene_buffers_rd.cpp |
| GI, небо и объёмный туман | servers/rendering/renderer_rd/environment/gi.cpp, sky.cpp, fog.cpp |
| TAA, FSR2, DOF, screen-space эффекты | servers/rendering/renderer_rd/effects/ |
| Низкоуровневый GPU API | servers/rendering/rendering_device.cpp и rendering_device.h |
| CPU occlusion culling | modules/raycast/raycast_occlusion_cull.cpp |
| Генерация LOD при импорте | scene/resources/3d/importer_mesh.cpp |
Наличие модуля эффекта не означает поддержку во всех методах. За настройками и ограничениями конкретного эффекта переходите в его руководство: объёмный туман, VRS. Генерация mesh LOD при импорте, выбор LOD для камеры и отбрасывание occluded-объекта решают разные задачи; не заменяйте одно другим при поиске причины исчезновения геометрии.
Расширение через Compositor
CompositorEffect получает RenderData в выбранной стадии рендера. Этот путь позволяет использовать подготовленные буферы сцены; он требует корректного этапа, формата, размеров и времени жизни данных.
| Метод | Наблюдавшиеся стадии |
|---|---|
| Forward+ | PreOpaque, PostOpaque, PostSky, PreTransparent, PostTransparent |
| Mobile | PreOpaque, PreTransparent, PostTransparent |
В сохранённом Mobile-прогоне PostOpaque выдавал предупреждение, PostSky не вызывался. Нельзя переносить эффект между методами, ориентируясь только на наличие enum. Camera.Compositor заменяет мировой compositor; даже пустой compositor камеры перекрывает мировой список. Это поведение выполнено в движке.
PostTransparent в проверенном RD-пути находится до постобработки и tonemap. Не считайте его автоматически финальным изображением на экране. Буферы и RenderData считывайте в callback; не сохраняйте заимствованные данные кадра как долгоживущие ресурсы. Контракты и пример: CompositorEffect.
Потоки, RID и чтение GPU
RenderingServerDefault имеет очередь команд и вариант с отдельным render thread. Вызов на CPU и завершение работы GPU — разные события. Для main RenderingDevice выполняйте операции в подходящем render-thread контексте, например callback CompositorEffect; не переносите scene-tree операции туда без проверки их потокового контракта.
GetRenderingDevice возвращает общий device движка. CreateLocalRenderingDevice требует доступного основного RD и создаёт отдельный device; он не делает отсутствующий RD доступным в Compatibility. RID принадлежат создавшей их подсистеме/device. RenderingServer.FreeRid и RenderingDevice.FreeRid не взаимозаменяемы. Заимствованные RID буферов viewport не освобождайте как свои.
Rid.IsValid проверяет ненулевой идентификатор, а не существование ресурса у владельца. После освобождения сохранённая копия RID не превращается автоматически в ноль. Поддерживайте владение явно, особенно при освобождении callback-ресурсов.
Синхронный texture_get_data в RD может принудительно завершать ожидающую GPU-работу. Не добавляйте постоянное чтение изображения на CPU в обычный путь кадра без измерения; отдельная проверка содержимого текстуры и производительный эффект — разные сценарии.
Диагностика по симптому
| Симптом | Первая проверка |
|---|---|
| Эффект работает только в одном методе | Фактические method/driver, стадия callback и нужные буферы |
| Чёрный или неправильный результат custom pass | Format/usage/размеры, MSAA/view count, зависимости и стадия до/после tonemap |
| Краткая задержка при первом появлении материала | Подготовка нового shader/pipeline; сравните с повторным показом |
| Низкий FPS постоянно | Разделите CPU и GPU frame time, число поверхностей/проходов, тени и разрешение |
| Объект исчезает | Камера/viewport, слои, visibility range, culling и mesh LOD |
| Ошибка RID или ресурс пропал | Владелец, device, lifetime и освобождение; IsValid недостаточно |
| Headless-проверка прошла | Уточните, использовался ли настоящий GPU renderer; dummy этого не доказывает |
Охват проверки
Использованы 40 ранее выполненных наблюдений Windows/Vulkan Forward+/Mobile: стадии Compositor, override камеры, доступ к color/depth/view count и выделение VRS attachment. Runtime, SDK и файлы тех тестов повторно сверены; GPU-сцены заново не запускались. Проверка идентичности включает запуск console --version.
Исходные отчёты содержат предупреждение Vulkan loader и предупреждение неподдерживаемой стадии Mobile. Их отрицательный статус не заменён положительным. Это доказательства ограниченных сценариев и структуры, не приёмка всей графики. D3D12, Metal, Compatibility, GI/TAA/DOF-качество, FPS, MSAA, stereo, экспорт и визуальное качество этим разделом не проверены. Код движка, SDK и установленный Runtime не менялись.