diff --git a/PLAN.md b/PLAN.md index ad7a338..79da5d7 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,8 +1,8 @@ # План разработки Faset Engine -Версия 1.2 · 18 сентября 2026 года. +Версия 1.3 · 23 сентября 2026 года. -**Статус:** C++ MVP реализован и принят; первый tag — **v0.1.0-mvp**. Исходники движка проверены на `4cb82556de31268d2bde73948dd1ff1b6c02f162`; финальная публикация добавляет документацию и свидетельства, сохраняя код движка. [Досье M0–M9](docs/validation/mvp-acceptance.md) связывает каждый этап с проверками и точными revisions. Linux проверен на RTX 2080 Ti, Windows — в native CI через SwiftShader; это не сертификация всех GPU/драйверов. Системный IME и физические переходы между мониторами не проверены, native Wayland restore имеет явный skip; XWayland и Windows lifecycle прошли. Текст/DPI проверены на уровне widgets и SDL. Эти границы покрытия сохраняются открыто и не выдаются за пройденные сценарии. Контракты находятся в [ARCHITECTURE.md](docs/ARCHITECTURE.md), история — в [журнале реализации](docs/IMPLEMENTATION.md). +**Статус:** C++ MVP реализован и принят; первый tag — **v0.1.0-mvp**. Его исходники проверены на `4cb82556de31268d2bde73948dd1ff1b6c02f162`; [досье M0–M9](docs/validation/mvp-acceptance.md) связывает этапы с проверками и revisions. После MVP реализованы Lua-модуль и P2 GPU visibility/mesh LOD. Для P2 сохранён direct-эталон; [протокол приёмки](docs/studies/19-p2-gpu-visibility-acceptance.md) и [первое измерение](docs/studies/20-p2-gpu-visibility-benchmark-2026-09-23.md) описывают Linux GPU-проверки и границы производительности. В Debug/validation GPU MainCull пока значительно дороже direct GPU-пути, поэтому P2 не означает готовое ускорение. Windows P2 и дополнительные семейства GPU/драйверов не подтверждены этим протоколом. Для MVP Linux проверен на RTX 2080 Ti, Windows — в native CI через SwiftShader; это не сертификация всех GPU/драйверов. Системный IME и физические переходы между мониторами не проверены, native Wayland restore имеет явный skip; XWayland и Windows lifecycle прошли. Контракты находятся в [ARCHITECTURE.md](docs/ARCHITECTURE.md), история — в [журнале реализации](docs/IMPLEMENTATION.md). ## 1. Результат MVP @@ -179,15 +179,21 @@ Lua, C++ hot reload, Blender live link, встроенное изображен Начальные бюджеты отслеживания для конкретных демо и Linux reference host: frame p95 ≤ 4 мс, GPU/readback p95 ≤ 1 мс, simulation/snapshot p95 ≤ 0,5 мс, явные Vulkan allocations ≤ 20 MiB, startup от `main()` ≤ 500 мс. [Методика и исходные измерения](docs/validation/linux-release-2026-09-18/README.md) ограничивают область этих чисел; для других сцен/ОС нужны отдельные baselines. Это бюджеты P1, а не обещание такой производительности любой игры. -Добавить Lua runtime/editor пакет поверх публичного API, проверяемых handles и схем. Предусмотреть диагностику, отладку, Inspector и явный lifecycle перезагрузки. Сохранение состояния при reload проектируется отдельно. Проверка: C++ и Lua используют одни данные/фазы; C++-only export не включает Lua. +Lua runtime/editor пакет реализован как необязательный модуль поверх публичного API, проверяемых handles и схем. Доступны Inspector, диагностика и явный lifecycle development reload; сохранение состояния при reload проектируется отдельно. [Проверка Lua-модуля](docs/validation/lua-module.md) подтверждает Linux CPU-контракты и отключение модуля для C++-only проекта; Windows и независимый graphical/release профиль модуля остаются отдельными проверками. Таким образом, Lua-часть P1 появилась после MVP, но это не закрывает весь этап скорости итераций. Улучшать schema/build cache, сообщения компилятора, шаблоны проектов, переход к коду, autosave и измеренное время «изменение → результат». Dynamic gameplay loading рассматривать при подтверждённой проблеме линковки. ### P2. GPU-driven visibility и LOD -Сохранить direct renderer как эталон. Порядок: GPU instance IDs → GPU frustum culling → fixed indirect batches → current HZB/debug view → two-pass occlusion с контролем истории → подготовленный mesh LOD с hysteresis. +**Реализовано для opaque static meshes на Linux reference GPU; остальные платформы/устройства требуют отдельной проверки.** Direct renderer остался выбираемым эталоном. Реализованы устойчивые instance IDs с generation, GPU frustum culling, фиксированные indirect bins, current HZB и его редакторский preview, main/post occlusion с проверяемой историей, выбор заранее подготовленного mesh LOD по проецируемому размеру и hysteresis. Прозрачные meshes, спрайты, UI и shadow pass сохраняют свои упорядоченные/независимые пути. Система не генерирует LOD-модели из исходного mesh автоматически. -Проверять пустую сцену, рост/переполнение буферов, массовое удаление, открывающуюся дверь, исчезновение заслона, camera cut, teleport и resize. Не требовать синхронного GPU readback. Сравнивать полный кадр на закрытых и открытых сценах: HZB может быть дороже эталона. Основа — [исследование 15](docs/studies/15-renderer-implementation-notes.md). +- [x] GPU instance records, frustum culling и fixed indirect draws без CPU feedback для решения видимости. +- [x] Current HZB, двухпроходное исправление ошибочной previous-frame occlusion и инвалидация истории при cut, resize, смене view/projection/instance. +- [x] Подготовленные LOD с hysteresis и диагностикой LOD counts; direct reference остаётся доступен. +- [x] Автоматические adversarial-сценарии: пустота, граница ёмкости, дверь/телепорт, тени, near plane, resize, несколько views, lifecycle, прозрачность и открытая сцена. +- [x] Профиль direct/frustum/occlusion на закрытой и открытой сценах с raw samples и без обещания универсального ускорения. + +Основой проектирования было [исследование 15](docs/studies/15-renderer-implementation-notes.md); фактическая проверка и методика — в [P2 acceptance](docs/studies/19-p2-gpu-visibility-acceptance.md), [результаты и raw samples](docs/studies/20-p2-gpu-visibility-benchmark-2026-09-23.md), реализация — в [журнале](docs/IMPLEMENTATION.md). Счётчики GPU и HZB preview включаются только для диагностики; существующий framebuffer capture по-прежнему синхронен, поэтому end-to-end benchmark отражает этот путь. Первое измерение выявило дорогой MainCull в Debug/validation на reference GPU; до выбора GPU-режима по умолчанию нужны разбор затрат и Release-повтор. Открытые сцены и дополнительная стоимость HZB публикуются наравне с закрытыми. ### P3. Освещение, тени и temporal reconstruction diff --git a/README.md b/README.md index 287cb81..c21562d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Faset is an independent engine project for desktop **2D and 3D games on Linux and Windows**. Its priorities are a custom editor that is comfortable to use by hand and through MCP, integration with Blender, and a path toward advanced graphics. -**Current status: the C++ MVP is implemented and accepted for the recorded Linux and Windows test profiles.** It includes the native Editor, shared GUI/MCP authoring, gameplay builds, Vulkan Player, Blender import and standalone export. Both playable games passed Release export and relocated execution on both operating systems. Windows graphics acceptance used software Vulkan; physical Windows GPUs, system IME and mixed-monitor transitions need additional coverage. See the [acceptance dossier](docs/validation/mvp-acceptance.md) for exact revisions, checks and limits, and the [implementation checkpoints](docs/IMPLEMENTATION.md) for the development record. +**Current status: the C++ MVP is accepted for the recorded Linux and Windows test profiles; Lua and P2 GPU visibility were added afterward.** The MVP includes the native Editor, shared GUI/MCP authoring, gameplay builds, Vulkan Player, Blender import and standalone export. Both playable games passed Release export and relocated execution on both operating systems. P2 adds optional GPU frustum and two-pass HZB occlusion modes, fixed indirect mesh bins, prepared mesh LOD selection, and an Editor HZB diagnostic view. The direct renderer remains the default and comparison reference. P2 GPU acceptance and measurements cover the Linux reference device; Windows P2 and additional physical GPUs need separate validation. The first Debug/validation benchmark found GPU culling substantially slower than direct GPU work, so the optional modes are not presented as a performance win. Windows MVP graphics acceptance used software Vulkan. See the [MVP acceptance dossier](docs/validation/mvp-acceptance.md), [P2 acceptance protocol](docs/studies/19-p2-gpu-visibility-acceptance.md), [measured P2 results](docs/studies/20-p2-gpu-visibility-benchmark-2026-09-23.md), and [implementation checkpoints](docs/IMPLEMENTATION.md) for exact scope and limits. ## Start here @@ -39,7 +39,7 @@ This README is in English. The current planning documents, studies, and research - **Editor-only MCP:** authoring, assets, import, builds, export, Play/Stop, and editor diagnostics. MCP is absent from the Player and exported games. - Standard, **unmodified Blender**, glTF/GLB import, and an optional add-on for convenient export and stable IDs. -The MVP provides two small games, one 2D and one 3D, with scene editing, C++ behavior, physics, Play and standalone export. A [Lua-only example](examples/lua) demonstrates the optional scripting module. GPU-driven rendering, HZB, advanced shadows, temporal reconstruction and dynamic global illumination follow this baseline. +The MVP provides two small games, one 2D and one 3D, with scene editing, C++ behavior, physics, Play and standalone export. A [Lua-only example](examples/lua) demonstrates the optional scripting module. P2 GPU visibility applies to opaque static meshes; ordered sprites/UI and the shadow pass keep their separate rendering paths. Its LOD policy chooses among meshes supplied by the project; automatic LOD generation, advanced shadows, temporal reconstruction and dynamic global illumination remain future work. See [profiling guidance](docs/manual/editor/profiling.md) before interpreting full-frame measurements. ## Run the research map diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5d4145a..e42910d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,6 @@ # Faset Engine — архитектура -Редакция 1.1 · 18 сентября 2026 · **принятый проект, реализация MVP в процессе**. +Редакция 1.2 · 23 сентября 2026 · **MVP принят; реализация P2 описана отдельно от исходных решений**. Этот файл фиксирует решения пользователя. **Принято** означает выбранное направление реализации, а не автоматически завершённую возможность движка. Работающий код, выполненные проверки и текущие ограничения перечислены в [журнале реализации](IMPLEMENTATION.md). Этапы до MVP и после него, зависимости работ и критерии готовности находятся в [PLAN.md](../PLAN.md). @@ -83,12 +83,14 @@ Catch-up ограничен числом ticks за проход главног 2D и 3D имеют отдельные миры и spatial-типы. Для динамического тела итоговым transform владеет физика; teleport и кинематическое управление — отдельные операции. Физическое тело связано с entity через проверяемый handle. Миры 2D и 3D не сталкиваются автоматически. Внутренние substeps solver настраиваются отдельно от частоты gameplay ticks; начальная настройка — четыре substeps с проверкой на сценах проекта. -Собственный Vulkan 1.3 renderer получает подготовленный snapshot, не обходит изменяемый EnTT registry с render thread. RenderGraph описывает reads/writes ресурсов, порядок проходов, barriers и lifetimes. Первым нужен проверяемый raster-путь 2D/3D без обязательных RT/mesh shaders; GPU-driven visibility и другие передовые механизмы добавляются по измеримым этапам из [плана](../PLAN.md). +Собственный Vulkan 1.3 renderer получает подготовленный snapshot, не обходит изменяемый EnTT registry с render thread. RenderGraph описывает reads/writes ресурсов, порядок проходов, barriers и lifetimes. MVP создал проверяемый raster-путь 2D/3D без обязательных RT/mesh shaders. P2 добавил выбираемые GPU frustum и GPU occlusion режимы для opaque static meshes; Direct остаётся начальным режимом и эталоном. Scene extraction задаёт устойчивые keys для постоянных объектов; renderer отслеживает generation и консервативные bounds. `DrawItem` может содержать заранее подготовленные LOD meshes. CPU формирует фиксированные совместимые bins, GPU заполняет visible IDs и `instanceCount` для indirect draws. В occlusion-режиме previous HZB даёт предварительное решение, а current HZB и PostCull возвращают объекты, которые открылись в этом кадре. Camera cut, несовместимые view/projection/extent и смена instance generation инвалидируют историю. Тени, прозрачные meshes, спрайты и UI не теряют независимый порядок из-за camera culling. Точная реализованная область и проверка приведены в [P2 acceptance](studies/19-p2-gpu-visibility-acceptance.md). **Vulkan API вызывается напрямую внутри собственного backend Faset.** Он владеет Vulkan handles, созданием GPU-ресурсов и pipelines, записью команд, синхронизацией и отправкой в очереди. Renderer и RenderGraph используют небольшой внутренний интерфейс ресурсов и команд Faset; Vulkan-типы и вызовы `vk*` не входят в gameplay API или команды редактора. SDL3 обеспечивает окно и создание Vulkan surface, но не заменяет графический backend; Slang отвечает за компиляцию шейдеров. Универсальная абстракция нескольких графических API не является задачей MVP. Slang компилирует шейдеры в SPIR-V и выдаёт сведения для согласования CPU/GPU данных. Совместимый HLSL проходит выбранный pipeline; поддержка любого существующего HLSL-кода не обещается. Cook учитывает compiler/version, includes, defines и GPU profile. Nanite/Lumen-подобные системы остаются исследовательскими направлениями, не готовыми возможностями MVP. +P2 не требует синхронного чтения GPU-счётчиков для решения видимости: readback включается редакторской диагностикой. Current HZB preview также читается только по запросу. Существующий путь полного framebuffer capture всё ещё ждёт GPU, поэтому измерения полной длительности кадра включают эту стоимость; `gpu_ms` и времена отдельных проходов не заменяют полную CPU/GPU-профилировку. [Первое измерение](studies/20-p2-gpu-visibility-benchmark-2026-09-23.md) обнаружило дорогой MainCull на Linux reference GPU в Debug/validation, несмотря на сокращение CPU-времени вызова renderer; архитектура не объявляет GPU-режим новым performance default. Mesh LOD выбирается среди заранее подготовленных вариантов с hysteresis; генерация LOD, streaming и cluster geometry пока не реализованы. GPU-режимы дополнительно проверяют необходимые limits/formats устройства и не считаются доступными на любом Vulkan 1.3 GPU без такой проверки. + ## 8. Blender и ассеты — принято Используется **обычный Blender**, без обязательного форка или установленного MCP-плагина. Базовый обмен — **GLB и manifest со стабильными asset/subasset IDs**. Обычный экспорт принимается движком; удобный add-on для публикации, UUID и повторного экспорта остаётся необязательным помощником. Если источник не предоставляет устойчивые subasset IDs, importer не обещает надёжно угадать соответствие после произвольного rename/reparent: сохраняет mapping и показывает конфликты. @@ -111,5 +113,6 @@ Development и release Player содержат runtime, выбранные иг - **18.09.2026:** принят порядок C++ → Lua, затем EnTT, собственный retained UI, SDL3, Vulkan 1.3/RenderGraph/Slang и CMake/Ninja/Clang. - **18.09.2026:** утверждены процессы и linkage, явная metadata registration/schema export, JSON/binary formats, вложенные шаблоны/sparse overrides, lifecycle, фиксированный tick и последовательный scheduler; граница MCP ограничена Editor/headless authoring services. - **18.09.2026:** английский принят основным языком интерфейса, диагностик и публичного API; уточнена граница прямых Vulkan-вызовов внутри собственного backend. +- **23.09.2026:** после принятого MVP выполнен P2 GPU visibility/LOD на Linux reference GPU; direct renderer сохранён как начальный режим и эталон, ограничения и измерения вынесены в отдельный [протокол](studies/19-p2-gpu-visibility-acceptance.md). Реализация идёт по [PLAN.md](../PLAN.md). Последующие изменения принятых контрактов фиксируются здесь с причиной и способом проверки. diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md index 4bd8266..4422007 100644 --- a/docs/IMPLEMENTATION.md +++ b/docs/IMPLEMENTATION.md @@ -338,3 +338,51 @@ GPU/driver families. Widget composition/DPI, SDL text-input boundaries, XWayland Windows window lifecycle have their own passing evidence. The narrow static-mesh, root-level box-physics, one-window/C++ MVP profile remains explicit. Lua and advanced graphics are later work. UI references guide appearance; they do not define behavior. + +## Post-MVP checkpoint — P2 GPU visibility and prepared mesh LOD + +The historical MVP statement above describes the `v0.1.0-mvp` scope. Subsequent +work added the optional Lua module and the P2 visibility path. The P2 renderer keeps +`VisibilityMode::Direct` as its default and reference. Scene extraction supplies +stable per-primitive keys and view metadata. `DrawItem` accepts optional prepared +coarse meshes. The renderer tracks generation-checked temporal identity and previous +rendered transforms, derives conservative bounds, and selects a prepared LOD by +projected size with hysteresis. There is no automatic mesh +decimator or cluster/streaming geometry system. + +For opaque static meshes, `GpuFrustum` groups compatible geometry/material into +fixed bins and fills indirect instance counts/visible IDs on the GPU. `GpuOcclusion` +adds previous-frame HZB classification, Main raster, a current forward-Z furthest-depth +HZB, and Post culling/raster so a newly revealed object can appear in the same final +frame. History resets on camera cut, changed view/extent/projection, and incompatible +instance identity. Shadow casters, transparent meshes, sprites and UI remain on their +independent paths; they are not hidden by the camera's opaque HZB. The GPU modes are +lazy-initialized and require the checked Vulkan capabilities and shader bundle. +Shader reload rebuilds both direct and GPU scene pipelines, preserving the working +pipelines on failure. + +The Editor's ImGui diagnostics can select Direct, GPU frustum or GPU occlusion, +inspect pass timings/counters and request a current-HZB preview. Counter and HZB +readback are opt-in diagnostics; the visibility decision itself stays on the GPU. +The existing framebuffer capture still waits for completion and reads back each +frame. Consequently, full-frame benchmark times include that path and must not be +presented as isolated culling costs. + +At renderer checkpoint `ae537c0`, the Linux reference build's full CTest suite +reported 57 registered tests, zero failures and one existing native-window lifecycle +skip. Fifteen offscreen P2 acceptance cases passed with Vulkan validation active and +zero reported errors, including capacity boundaries, door reveal, camera changes, +multi-view history, LOD hysteresis, shadow independence and transparency. Shader +reflection/export and GPU shader reload have focused tests. The +[P2 acceptance protocol](studies/19-p2-gpu-visibility-acceptance.md) contains the +command, tolerance and scene definitions. The +[three-run benchmark report](studies/20-p2-gpu-visibility-benchmark-2026-09-23.md) +retains all 810 raw frame records, device/build details, p50/p95 values and limits. +In that Debug build with validation and diagnostic counters, GPU `MainCull` took +about 3.9–18.2 ms p50 across the three synthetic scenes, far above the direct +path's 0.24–0.50 ms whole-GPU p50. The GPU route reduced synchronous CPU render-call +time, but this is not evidence of a shipping-frame speedup. Profile the cull pass +and repeat in Release before considering a different default. These checks establish +the tested Linux configuration; they do not +establish P2 behavior on a physical Windows GPU or a broad driver matrix. The +[profiling manual](manual/editor/profiling.md) explains how to interpret the timings. diff --git a/docs/manual/editor/profiling.md b/docs/manual/editor/profiling.md index 33c0fe7..d94439a 100644 --- a/docs/manual/editor/profiling.md +++ b/docs/manual/editor/profiling.md @@ -67,11 +67,49 @@ report. A dirty source checkout is explicitly identified. relocated Release packages and records their Player profiles. Its assertions test correct execution, not a frame-time threshold. +## Compare P2 GPU visibility modes + +The Editor diagnostics panel (**F12**) can switch its current viewport between +**Direct**, **GPU frustum**, and **GPU occlusion**. Direct is the default reference. +The selector is an Editor viewport setting; it does not change the saved scene or +automatically change an exported Player. Check **Path: active** in the panel before +interpreting a GPU-mode measurement: a selected mode alone does not prove that the +GPU path ran. See [Diagnostics](diagnostics.md) for the counters and HZB preview. + +For a repeatable offscreen comparison, build and run the P2 benchmark harness: + +```sh +build/linux-debug/faset_render_gpu_acceptance_tests --benchmark /tmp/faset-p2.csv +``` + +It records 10 warm-up and 30 measured frames for Direct, GPU frustum and GPU +occlusion in fixed frustum-heavy, open and occluded scenes. Run it three times and +compare median/p95 by scene and mode. Keep the raw CSV, hardware/driver, resolution, +shader bundle, validation state and source revision with any published result. The +[P2 acceptance protocol](../../studies/19-p2-gpu-visibility-acceptance.md) +documents the scenes and CSV columns. The +[first measured report](../../studies/20-p2-gpu-visibility-benchmark-2026-09-23.md) +retains three raw runs, p50/p95 and limits. Its Debug/validation profile found +GPU MainCull substantially more expensive than direct GPU work, even though the +GPU route reduced synchronous CPU render-call time. + +The harness enables GPU visibility counters, so diagnostic readback is part of its +timings. In the Editor, opening diagnostics likewise enables these counters, and +**Show HZB** adds an on-demand image copy and preview upload. Close the panel and +disable the HZB preview for ordinary gameplay timing. GPU pass timestamps separate +MainCull, MainRaster, HZB, PostCull and PostRaster when supported; they are not a +measure of CPU extraction/upload. The renderer still waits for frame completion +and reads back the full image, so `cpu_ms` is wall time including waits, not CPU +utilization. An open scene can run slower with HZB; visibility correctness and +full-frame speed are separate findings. + ## Current performance scope -The MVP renderer is intentionally conservative: direct draws, CPU culling, one -graphics queue and synchronous capture/readback. Use the measurements to find the -next bottleneck before introducing parallel jobs or GPU-driven rendering. Neither -an offscreen capture benchmark nor a tiny demo is a promise of a production frame -budget. Observed measurements and follow-up targets belong in the implementation -acceptance report with their source revision and method. +The accepted MVP path uses direct draws and CPU culling; P2 adds optional GPU +visibility for opaque static meshes, with prepared LODs supplied by the project. +Both paths currently use one graphics queue and synchronous full-image +capture/readback. Use measurements to find the next bottleneck before introducing +parallel jobs or expanding GPU-driven rendering. Neither an offscreen capture +benchmark nor a tiny demo is a promise of a production frame budget. Observed +measurements and follow-up targets belong in the implementation acceptance report +with their source revision and method. diff --git a/docs/studies/15-renderer-implementation-notes.md b/docs/studies/15-renderer-implementation-notes.md index d83783d..417d6f1 100644 --- a/docs/studies/15-renderer-implementation-notes.md +++ b/docs/studies/15-renderer-implementation-notes.md @@ -1,12 +1,12 @@ # 15. Первый GPU-driven renderer Faset: данные, порядок проходов и проверка корректности -Исследование от 17 сентября 2026; проектные решения обновлены 18 сентября 2026. Это продолжение [обзора UE](07-unreal-graphics-source-study.md): здесь разобран контракт одного будущего GPU-driven прототипа. **Принято, реализация запланирована:** собственные Vulkan 1.3 backend и Render Graph, Slang → SPIR-V, SDL3, Linux/Windows desktop 2D/3D, базовый путь без обязательного RT. Поддерживаемые модели GPU и проверенная матрица драйверов ещё не определены. Актуальные границы — в [архитектуре](../ARCHITECTURE.md) и [плане до/после MVP](../../PLAN.md). +Исследование от 17 сентября 2026; проектные решения обновлены 18 сентября 2026. Это продолжение [обзора UE](07-unreal-graphics-source-study.md): здесь разобран контракт тогда ещё будущего GPU-driven прототипа. **Исторический проектный материал:** собственные Vulkan 1.3 backend и Render Graph, Slang → SPIR-V, SDL3, Linux/Windows desktop 2D/3D, базовый путь без обязательного RT. Ниже сохранены гипотезы и предложения в том виде, в каком они предшествовали реализации; они не доказывают свойства кода. Фактически реализованный P2 и измерения от 23 сентября 2026 описаны в [отдельной приёмке](19-p2-gpu-visibility-acceptance.md) и [журнале](../IMPLEMENTATION.md). Актуальные границы — в [архитектуре](../ARCHITECTURE.md) и [плане](../../PLAN.md). -**Место в плане:** M2 (базовая графика MVP) использует direct renderer с CPU frustum culling, простым PBR/тенями и отдельным упорядоченным 2D-путём; обе демки должны собираться в самостоятельный Player. GPU culling, indirect draws, HZB и LOD из этого исследования начинаются **после MVP, в P2**, с сохранением direct reference. Сначала fixed indirect bins и frustum, затем two-pass HZB, затем обычный mesh LOD с hysteresis. Кластерный LOD и streaming — дальнейшее исследование. Минимальный Render Graph с одной очередью и корректными barriers/lifetime нужен уже MVP; pass culling, aliasing и async compute не обязательны. +**Место в плане на момент исследования:** M2 (базовая графика MVP) использует direct renderer с CPU frustum culling, простым PBR/тенями и отдельным упорядоченным 2D-путём; обе демки должны собираться в самостоятельный Player. GPU culling, indirect draws, HZB и LOD были намечены **после MVP, в P2**, с сохранением direct reference. Порядок: fixed indirect bins и frustum, затем two-pass HZB, затем обычный mesh LOD с hysteresis. Кластерный LOD и streaming — дальнейшее исследование. Минимальный Render Graph с одной очередью и корректными barriers/lifetime нужен уже MVP; pass culling, aliasing и async compute не обязательны. **Граница инструментов:** MCP работает только в редакторе, включая headless authoring/import/build, Play/Stop и логи редактора. Player — отдельный процесс с отдельным окном, без MCP; чтение/изменение runtime worlds и игровых сессий через MCP исключено. Диагностика renderer и ручной GPU capture не превращаются в канал MCP-доступа к Player. -Источники привязаны к [source-manifest.json](source-manifest.json): UE 5.8.2, commit `16d75d84714512edfb744e1fd0a59e9c74d57873`; Godot 4.8-dev, commit `9c776068d6ed23acd0c78bfe534272d1d2a3a619`. Прочитаны выбранные тела C++ и shader-функций, затем официальные Vulkan/D3D12 документы. Репозитории не изменялись. Движки и GPU-прототип не запускались; ускорения, совместимость конкретных карт и качество culling измерениями не подтверждены. **«Факт»** ниже относится к просмотренному коду/документу; **«предложение»** — к нашему проекту; гипотезы отмечены отдельно. +Источники привязаны к [source-manifest.json](source-manifest.json): UE 5.8.2, commit `16d75d84714512edfb744e1fd0a59e9c74d57873`; Godot 4.8-dev, commit `9c776068d6ed23acd0c78bfe534272d1d2a3a619`. Прочитаны выбранные тела C++ и shader-функций, затем официальные Vulkan/D3D12 документы. Репозитории не изменялись. **На момент исследования** сторонние движки и GPU-прототип Faset не запускались; ускорения, совместимость конкретных карт и качество culling измерениями не подтверждались. **«Факт»** ниже относится к просмотренному коду/документу; **«предложение»** — к нашему проекту; гипотезы отмечены отдельно. ## 1. Полезный результат не требует полного GPU command processor @@ -129,4 +129,8 @@ D3D12 подтверждает переносимость самой идеи, Главное дополнение к 07: фиксированные CPU draw templates совместимы с GPU instance visibility; velocity target не требуется для первого HZB; history extraction — output/lifetime контракт; camera reset заменяет весь previous-view набор; indirect и vertex reads требуют разных зависимостей; неполный Main HZB может быть начальным вариантом истории с измеряемой ценой в эффективности. -Прочитаны тела UE `FInstanceCullingContext` создания buffers/submission, `InstanceCullBuildInstanceIdBufferCS`, `ClearIndirectArgInstanceCountCS`, Nanite `FBoxCull::HZB`, `WriteOccludedInstance` и main/HZB/post orchestration; `BuildHZB`, `HZBBuildCS` и HZB parameter helpers; previous-view setup/reset в SceneVisibility; RDG import/extraction, barrier compile/collection и resource reference handling. В Godot — indirect draw validation/tracking и named render-buffer creation/configuration/cleanup. В интернете — официальные Vulkan indirect/features/synchronization и Microsoft D3D12 indirect signatures. В этом исследовании не проверялись формат/driver capability matrix и runtime-поведение. Позднейшие проверки базового Faset renderer публикуются отдельно в [docs/validation](../validation/README.md); они не подтверждают GPU-driven техники этого раздела. +Прочитаны тела UE `FInstanceCullingContext` создания buffers/submission, `InstanceCullBuildInstanceIdBufferCS`, `ClearIndirectArgInstanceCountCS`, Nanite `FBoxCull::HZB`, `WriteOccludedInstance` и main/HZB/post orchestration; `BuildHZB`, `HZBBuildCS` и HZB parameter helpers; previous-view setup/reset в SceneVisibility; RDG import/extraction, barrier compile/collection и resource reference handling. В Godot — indirect draw validation/tracking и named render-buffer creation/configuration/cleanup. В интернете — официальные Vulkan indirect/features/synchronization и Microsoft D3D12 indirect signatures. В этом исследовании не проверялись формат/driver capability matrix и runtime-поведение. Позднейшие проверки базового Faset renderer опубликованы в [docs/validation](../validation/README.md); отдельные P2 GPU-проверки опубликованы в [приёмке P2](19-p2-gpu-visibility-acceptance.md) и [измерении P2](20-p2-gpu-visibility-benchmark-2026-09-23.md). Эти результаты не превращают исторические гипотезы исследования в доказанные свойства всех GPU. + +## Примечание к реализации P2 · 23.09.2026 + +P2 реализован для opaque static meshes с fixed bins, GPU frustum/indirect, HZB main/post и prepared mesh LOD. Реальный debug view показывает current HZB и счётчики; отдельного instance-ID attachment, предполагавшегося в проектном разборе, пока нет. Приёмка сравнивает финальные RGB-кадры с direct-эталоном и проверяет конкретные adversarial-пиксели и счётчики. Diagnostics readback включается по запросу, но существующий framebuffer capture в тестовом renderer всё ещё синхронен; исходное предложение о полностью асинхронном profiler/readback пока не выполнено. На Linux reference GPU первый Debug/validation benchmark выявил дорогой GPU MainCull, поэтому реализация не заявлена как универсальное ускорение. Детальные ограничения и числа находятся в [отчёте P2](20-p2-gpu-visibility-benchmark-2026-09-23.md), а не в проектных предположениях выше. diff --git a/docs/studies/README.md b/docs/studies/README.md index 7f9a450..3b50e63 100644 --- a/docs/studies/README.md +++ b/docs/studies/README.md @@ -1,6 +1,6 @@ # Исследования для Faset Engine -Обновлено 18.09.2026. Исходники и официальная документация исследовались прежде всего 17.09.2026; затем результаты согласованы с принятой архитектурой. +Обновлено 23.09.2026. Исходники и официальная документация исследовались прежде всего 17.09.2026; затем результаты согласованы с принятой архитектурой. P2 implementation/acceptance добавлены позже и отделены от исходного статического исследования. **Актуальные решения — в [ARCHITECTURE.md](../ARCHITECTURE.md), порядок реализации — в [PLAN.md](../../PLAN.md).** Реализация MVP и проверки идут отдельно: [журнал реализации](../IMPLEMENTATION.md), [результаты проверок](../validation/README.md), [пользовательский Manual](../manual/index.md). Исследования дают обоснования и проверочные сценарии; их статический анализ не является измерением Faset. @@ -34,16 +34,18 @@ Linux/Windows, десктопные 2D/3D, C++ сначала и Lua следу ## Углублённые технические материалы -- [15 — GPU-driven renderer](15-renderer-implementation-notes.md): visibility, HZB, синхронизация и управление историей; этап после MVP. +- [15 — GPU-driven renderer](15-renderer-implementation-notes.md): исходный проектный разбор visibility, HZB, синхронизации и управления историей для P2. - [16 — C++ gameplay и метаданные](16-native-gameplay-and-metadata.md): схемы, ABI, сериализация и будущий Lua. - [17 — Asset pipeline и Blender](17-asset-pipeline-and-blender-roundtrip.md): IDs, зависимости, reimport, overrides и физическая геометрия. - [18 — Сборка и доставка](18-build-cook-and-delivery.md): инкрементальность, cache, состав Player и единый BuildService. +- [19 — P2 GPU visibility: протокол приёмки](19-p2-gpu-visibility-acceptance.md): GPU-сценарии, допуски сравнения и методика измерений; отделяет проверку реализации от предложений исследования 15. +- [20 — P2 GPU visibility: первый benchmark](20-p2-gpu-visibility-benchmark-2026-09-23.md): три запуска, raw CSV, p50/p95 и границы интерпретации на Linux reference GPU. ## Происхождение и воспроизводимость [Манифест источников](source-manifest.json) фиксирует изученные версии и commits. Основные source-ссылки ведут на upstream-файлы конкретного commit с указанием строки; доступ к Unreal требует соответствующих прав Epic. Исходники сторонних движков не включены в этот репозиторий. -Исследование статическое и выборочное: читались отдельные реализации и официальные документы. Движки не собирались, пользовательские UX-тесты и GPU-бенчмарки не выполнялись. UnityCsReference содержит C# reference source и bindings, а не весь native движок. Blender изучался через sparse checkout и выбранные удалённые файлы. +Исходное сравнительное исследование статическое и выборочное: читались отдельные реализации и официальные документы. Сторонние движки не собирались, пользовательские UX-тесты и их GPU-бенчмарки не выполнялись. Позднейшие GPU-тесты и измерения **Faset P2** находятся отдельно в [протоколе 19](19-p2-gpu-visibility-acceptance.md) и [отчёте 20](20-p2-gpu-visibility-benchmark-2026-09-23.md); они не являются benchmark Unreal/Godot/Unity. UnityCsReference содержит C# reference source и bindings, а не весь native движок. Blender изучался через sparse checkout и выбранные удалённые файлы. [Карта](map/README.md) запускается на обычном clone Faset. Соседние checkout из manifest необязательны и нужны только для дополнительного локального просмотра исходников. Пути manifest считаются от корня проекта, а относительные Markdown-ссылки — от документа.