From 1f8ef9e9f56a92ea744b2ffda4d8e46ffaf59874 Mon Sep 17 00:00:00 2001 From: sal063 <107197232+sal063@users.noreply.github.com> Date: Fri, 17 Apr 2026 20:40:42 +0300 Subject: [PATCH] Delete docs/native_graphics_migration directory --- ...ATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md | 137 ----- .../AC6_NATIVE_GRAPHICS_DOC_TRACKER.md | 128 ----- ...IVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md | 427 --------------- ...TIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md | 244 --------- ..._GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md | 499 ------------------ 5 files changed, 1435 deletions(-) delete mode 100644 docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md delete mode 100644 docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_DOC_TRACKER.md delete mode 100644 docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md delete mode 100644 docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md delete mode 100644 docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md diff --git a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md b/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md deleted file mode 100644 index 1c6462fd..00000000 --- a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md +++ /dev/null @@ -1,137 +0,0 @@ -# AC6 Native Graphics API Deprecation Timeline - -Date: 2026-04-17 -Scope: AC6 recomp graphics only - -This document defines which legacy emulation-facing APIs, flags, and behaviors are deprecated, when they will be removed from AC6 shipping builds, and what replaces them. - -Companion planning documents: - -- `AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md` defines target architecture, phase goals, and validation gates. -- `AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md` defines the current emulation-owned components and their retirement priorities. -- `AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md` defines workstreams, owner roles, dependencies, and required phase artifact packages. - -## Principles - -- Deprecations are communicated with a hard calendar date and a version tag. -- Every deprecated API has: - - a replacement API - - a migration script or mechanical recipe - - a test plan proving parity before removal -- AC6 production releases remain stable; removals happen only after a full milestone with native default-on canary success. - -## Timeline - -### Milestone M0: Announcement and inventory (T0) - -- Freeze: no new features added to legacy PM4/Xenos render path. -- Publish: migration strategy and emulation audit. -- Add: compiler warnings or runtime warnings for deprecated config values. - -### Milestone M1: Parallel native scaffolding (T0 + 4-6 weeks) - -- Add: native renderer modules behind opt-in flags. -- Keep: legacy renderer as production default. -- Deprecate (soft): legacy render debug flags that only apply to emulation internals. - -### Milestone M2: Native assets and shaders (T0 + 8-12 weeks) - -- Add: offline shader compilation and asset cooker. -- Deprecate (soft): runtime shader translation on the native path (native must not depend on it). - -### Milestone M3: Hybrid subsystem migration (T0 + 12-20 weeks) - -- Add: subsystem routing flags. -- Deprecate (hard): any new reliance on `PM4_XE_SWAP` behavior in AC6 builds. -- Start: dual-render parity gates for selected scenes in CI. - -### Milestone M4: Native present authority (T0 + 20-28 weeks) - -- Default-on: native present for canary channel. -- Deprecate (hard): `VdSwap` synthesized PM4 swap as a required behavior in AC6 shipping. - -### Milestone M5: Remove emulation render linkage from AC6 (T0 + 28-36 weeks) - -- Remove from AC6 target linkage: - - `CommandProcessor` - - Xenos shader translators - - texture cache / render target cache tied to guest state - - shared memory hot-path GPU resource model -- Keep only: - - presenter / windowing - - minimal kernel compatibility shims - -### Milestone M6: Clean-up and stabilization (T0 + 36-48 weeks) - -- Delete: dead flags, emulation-only code paths, and debug tools that depend on PM4/Xenos. -- Lock: final API surface and documentation. -- Start: 90-day regression watch window for production. - -## Deprecated / Removed Items (AC6 Scope) - -### Legacy swap authority - -Deprecated: - -- `PM4_XE_SWAP` as the authoritative display path for AC6. - -Replacement: - -- native frame boundary and final composite owned by native renderer, presented via presenter. - -Removal milestone: - -- M5 - -### Runtime shader translation and guest shader caches - -Deprecated: - -- any reliance on Xenos microcode translation for AC6-native rendering - -Replacement: - -- offline-compiled HLSL outputs (DXIL, SPIR-V, MSL) and pipeline libraries - -Removal milestone: - -- M5 - -### Guest texture decode / untiling / cache invalidation (shipping) - -Deprecated: - -- texture cache for static content in shipping builds - -Replacement: - -- cooked textures and explicit streaming residency - -Removal milestone: - -- M5 (with transitional support in M3-M4 for genuinely dynamic textures only) - -## Compatibility Flags Policy - -- Flags that control emulation internals remain dev-only immediately after M2. -- Production builds may keep: - - presenter scaling options - - vsync / tearing options - - GPU debug markers toggles - - quality settings backed by native renderer options - -## Required Documentation Updates - -- `README.md` must describe: - - how to enable native renderer - - supported platforms and backends - - how to run parity tests - - how to run benchmarks and leak checks - -## Migration Script Requirements - -All legacy config keys must have: - -- mechanical mapping or safe removal guidance -- a linter mode to detect unknown or deprecated keys -- CI job that validates clean config on the default distribution diff --git a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_DOC_TRACKER.md b/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_DOC_TRACKER.md deleted file mode 100644 index e446c5ec..00000000 --- a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_DOC_TRACKER.md +++ /dev/null @@ -1,128 +0,0 @@ -# AC6 Native Graphics Doc Tracker - -Date: 2026-04-17 -Scope: `AC6 recomp`, `Windows + Linux + macOS` -Purpose: living documentation tracker for the AC6 native graphics migration package. This file is intended to be updated often as the doc set grows, changes direction, or closes gaps. - -## Current Doc Set - -| File | Role | Status | -| --- | --- | --- | -| `AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md` | high-level target architecture, phases, validation, governance, and rollout rules | drafted and broadly structured | -| `AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md` | inventory of the emulator-authoritative graphics stack, retirement priorities, and replacement targets | drafted and actionable | -| `AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md` | deprecation schedule, removal milestones, compatibility flag policy, and migration-script requirements | drafted but still narrow in scope | -| `AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md` | workstreams, ownership model, phase artifact packages, gates, and first-30-day execution planning | drafted and actionable | - -## Scan Summary - -What is already covered well: - -- architecture direction for the native renderer -- phased rollout from scaffolding to final emulation removal -- current emulation dependency inventory with `P0` / `P1` / `P2` retirement priorities -- deprecation timing for the biggest legacy render behaviors -- execution structure with workstreams, gates, and first-month checkpoints -- implementation now includes parallel native frame observation, an initial frame-plan stage, and stage-aware diagnostic composition for scene, post-FX, and UI preview bring-up with per-stage captured clear history - -What is not yet documented deeply enough: - -- exact legacy config key to native replacement mapping -- exact legacy API / symbol / build-linkage removal matrix -- benchmark scene manifest definitions and ownership -- concrete benchmark hardware matrix and baseline capture format -- status history of what doc work has been added on each pass - -## Completed Documentation Work - -As of this scan, the native graphics docs package has completed the following planning layers: - -1. Strategy: - - defines success criteria, renderer architecture, phased rollout, validation, security, rollback, and governance -2. Audit: - - identifies current emulator-owned graphics systems, why they must go, and what replaces them -3. Deprecation: - - assigns milestone-based retirement timing for major legacy graphics-facing behavior -4. Execution: - - maps planning into workstreams, owner roles, decision gates, artifact packages, and a first-30-day plan -5. Early implementation tracking: - - records that AC6 bootstrap code now builds observed passes from captured D3D activity, derives an initial native frame plan for scene, post-FX, UI, and present selection, feeds that planner into the live swap path, and composes stage-aware preview output in both minimal-UAV and raster preview modes using per-stage captured clear colors and rect coverage - -## Gaps To Fill Next - -Priority order for missing docs: - -1. `config migration matrix` - - map every legacy graphics config key to `replace`, `rename`, `keep`, `dev-only`, or `delete` -2. `render API removal map` - - list legacy render interfaces, where they are referenced, what replaces them, and in which milestone they disappear -3. `benchmark and parity pack` - - define scene manifests, golden image ownership, naming, storage, and pass criteria -4. `module bring-up notes` - - track backend bring-up status for `D3D12`, `Vulkan`, and `Metal` - -## Active Focus - -Current doc work should focus on making the package easier to execute, not broader. - -That means: - -- prefer concrete mappings over new strategy prose -- prefer tables and checklists over long narrative sections -- prefer documents that unblock implementation reviews and milestone signoff -- implementation follow-up should convert stage-aware diagnostic fills into real stage-specific replay inputs, starting with scene-stage ownership and then post-FX and UI composition -- next replay milestone should prioritize scene-stage draw and state reconstruction over more preview polish, because the preview path now already reflects stage-local clear structure -- keep the presenter and swap interception seam stable while replacing diagnostic color fills with captured-resource or native-resource driven content - -## Working Rules For This File - -- update this file every time a new native graphics migration doc is added -- update this file every time a major section is added or removed from an existing doc -- update `Completed Documentation Work`, `Gaps To Fill Next`, and `Next Doc To Write` together -- keep entries short and factual -- do not treat this as final design authority; it is the control page for the doc set - -## Next Doc To Write - -Recommended next document: - -- `AC6_NATIVE_GRAPHICS_CONFIG_MIGRATION_MATRIX.md` - -Why this is next: - -- it is explicitly required by the deprecation timeline -- it converts policy into a migration tool for actual builds and configs -- it closes one of the biggest remaining gaps between planning and implementation - -Suggested minimum contents: - -- legacy key -- current meaning -- replacement key or behavior -- action (`keep`, `rename`, `remove`, `dev-only`) -- milestone of enforcement -- user migration note -- CI or linter rule needed - -## Change Log - -### 2026-04-17 - -- scanned the current native graphics migration doc folder -- confirmed four core planning docs exist: strategy, audit, deprecation timeline, and execution plan -- identified the main missing layer as concrete migration matrices and validation-pack detail -- created this living tracker so future doc work has a single update point -- noted implementation progress: the parallel native renderer now ingests captured frame activity, classifies observed passes, and derives an initial explicit frame plan for present bring-up -- updated implementation status: the live AC6 direct-swap path now consumes the parallel frame planner when selecting the present candidate instead of relying only on the older replay heuristic -- updated implementation status: both the minimal-UAV preview path and the raster preview path now compose a stage-aware diagnostic frame using planned scene, post-FX, and UI stages -- updated implementation status: planned scene, post-FX, and UI stages now carry captured clear histories and clear rect coverage into the stage-aware preview paths, so the preview output reflects stage-local clear structure rather than only broad stage tinting -- next implementation instruction: keep Phase 3 and Phase 4 scope focused on replacing stage-aware diagnostic fills with actual stage replay or native resource composition, not on adding new behavior to the legacy PM4 or Xenos path - -## Ready State - -The docs are no longer empty planning notes. They now form a usable planning stack: - -- strategy answers `what the target is` -- audit answers `what must be replaced` -- deprecation answers `when legacy behavior goes away` -- execution answers `how the work gets organized` -- this tracker answers `what doc work is done and what comes next` diff --git a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md b/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md deleted file mode 100644 index 9c537f86..00000000 --- a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md +++ /dev/null @@ -1,427 +0,0 @@ -# AC6 Native Graphics Emulation Audit - -Date: 2026-04-17 -Scope: `AC6 only`, `PC only` (`Windows`, `Linux`, `macOS`) -Goal: catalog every current graphics component that exists because the title still runs through a Xenia-derived Xenos / PM4 / guest-D3D emulation model. - -Companion planning documents: - -- `AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md` defines the target architecture and release gates. -- `AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md` defines when legacy interfaces become dev-only, blocked, or removed. -- `AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md` maps the audit items in this file to workstreams, owner roles, dependencies, and phase exit artifacts. - -## Executive Summary - -The active AC6 graphics stack is still emulator-authoritative. - -Current live path: - -`guest D3D call -> AC6 hook/shadow capture -> guest-side D3D implementation -> VdSwap -> GraphicsSwapSubmission -> optional AC6 interception -> PM4_XE_SWAP fallback -> CommandProcessor -> D3D12/Vulkan backend -> Presenter -> host swapchain` - -What is already native enough to keep for the migration: - -- window creation -- presenter / swapchain ownership -- host graphics provider abstraction -- overlays / immediate UI -- runtime injection seam via `RuntimeConfig.graphics` - -What must be retired to eliminate graphics emulation: - -- PM4 packet submission for rendering -- Xenos register/MMIO ownership of frame construction -- command processor driven draw/resolve execution -- shader microcode translation on the hot path -- guest GPU shared-memory resource interpretation on the hot path -- EDRAM emulation / resolve heuristics / render-target ownership emulation -- swap extraction from emulated frontbuffer state - -## Current Authoritative Render Ownership - -### App / title-local layer - -Files: - -- `src/ac6recomp_app.h` -- `src/ac6_native_graphics.cpp` -- `src/ac6_native_graphics_overlay.cpp` -- `src/d3d_hooks.cpp` -- `src/d3d_state.h` -- `src/render_hooks.cpp` - -Current role: - -- bootstraps an alternate graphics system -- captures guest D3D state and frame summaries -- performs swap interception experiments -- shows diagnostic overlay state -- does not build the real frame yet - -Migration disposition: - -- keep as temporary bridge -- evolve into title-native capture, validation, and compatibility control plane -- eventually split into: - - native renderer frontend - - compatibility shim layer - - debug / validation tools - -### Runtime injection seam - -Files: - -- `thirdparty/rexglue-sdk/src/native/ui/rex_app.cpp` -- `thirdparty/rexglue-sdk/src/system/runtime.cpp` -- `thirdparty/rexglue-sdk/include/rex/system/interfaces/graphics.h` - -Current role: - -- chooses default graphics backend -- boots injected graphics implementation -- exposes `GraphicsSwapSubmission` - -Migration disposition: - -- keep -- expand interface surface for native renderer lifecycle, telemetry, capture, and validation - -## Emulation Dependency Inventory - -### 1. Guest submission and swap synthesis - -Files: - -- `thirdparty/rexglue-sdk/src/kernel/xboxkrnl/xboxkrnl_video.cpp` - -Emulation behavior: - -- `VdInitializeRingBuffer` and `VdEnableRingBufferRPtrWriteBack` preserve guest command-buffer semantics -- `VdSwap` interprets guest texture fetch state and can still synthesize `PM4_XE_SWAP` -- guest-visible interrupt semantics depend on this path - -Why it must go: - -- frame submission is still modeled as Xbox 360 GPU behavior rather than native frame production -- the native renderer cannot fully own frame pacing, presentation, or resource lifetime while `VdSwap` remains a PM4 bridge - -Replacement target: - -- AC6-native frame boundary API -- thin `xboxkrnl_video` compatibility shim that forwards title state into native frame submission -- retained interrupt timing contract only where the recompiled title still observes it - -Retirement priority: `P0` - -### 2. Graphics system and MMIO ownership - -Files: - -- `thirdparty/rexglue-sdk/include/rex/graphics/graphics_system.h` -- `thirdparty/rexglue-sdk/src/graphics/graphics_system.cpp` - -Emulation behavior: - -- maps GPU MMIO -- owns vblank worker -- owns command processor lifecycle -- owns register file / guest-facing GPU register semantics - -Why it must go: - -- the graphics core is still described as an emulated device -- render lifetime is still coupled to MMIO and command ring state - -Replacement target: - -- `Ac6NativeRenderSystem` -- explicit frame scheduler -- host-owned timing, telemetry, resource device, and native presentation coordinator - -Retirement priority: `P0` - -### 3. PM4 command stream parsing and command processor - -Files: - -- `thirdparty/rexglue-sdk/src/graphics/command_processor.cpp` -- `thirdparty/rexglue-sdk/src/graphics/d3d12/command_processor.cpp` -- `thirdparty/rexglue-sdk/src/graphics/vulkan/command_processor.cpp` -- `thirdparty/rexglue-sdk/include/rex/graphics/command_processor.h` - -Emulation behavior: - -- parses PM4 packet stream -- executes draw/clear/resolve through emulated Xenos semantics -- handles swap packets -- owns emulated GPU caches and synchronization conventions - -Why it must go: - -- it is the central emulation layer -- any renderer built on top of it still pays the cost and correctness risks of emulation - -Replacement target: - -- title-native render graph compiler -- pass scheduler fed directly by recompiled AC6 draw APIs and extracted asset/material metadata - -Retirement priority: `P0` - -### 4. Xenos register, packet, and hardware model - -Files: - -- `thirdparty/rexglue-sdk/src/graphics/registers.cpp` -- `thirdparty/rexglue-sdk/src/graphics/register_file.cpp` -- `thirdparty/rexglue-sdk/src/graphics/xenos.cpp` -- `thirdparty/rexglue-sdk/src/graphics/packet_disassembler.cpp` -- headers under `thirdparty/rexglue-sdk/include/rex/graphics/*` - -Emulation behavior: - -- maintains Xbox 360 GPU data model -- drives command interpretation, shader decoding, and state binding - -Why it must go: - -- the native renderer should consume AC6-native pass/material/resource data, not Xenos state - -Replacement target: - -- native render-state descriptors -- native material schema -- compiled scene/pass metadata - -Retirement priority: `P1` - -### 5. Shared guest GPU memory and aliasing model - -Files: - -- `thirdparty/rexglue-sdk/src/graphics/shared_memory.cpp` -- `thirdparty/rexglue-sdk/src/graphics/d3d12/shared_memory.cpp` -- `thirdparty/rexglue-sdk/src/graphics/vulkan/shared_memory.cpp` - -Emulation behavior: - -- interprets guest GPU memory as if the host were managing Xbox 360 resource backing -- aliases memory through guest physical/virtual address translation - -Why it must go: - -- this is the main CPU overhead source for dynamic resource interpretation -- it preserves emulator-style lifetime and coherency problems - -Replacement target: - -- host-native resource allocator -- upload / streaming heap manager -- explicit transient arena -- immutable asset pool for converted textures and geometry - -Retirement priority: `P1` - -### 6. Texture cache, tiling, format conversion, and invalidation - -Files: - -- `thirdparty/rexglue-sdk/src/graphics/pipeline/texture/cache.cpp` -- `thirdparty/rexglue-sdk/src/graphics/pipeline/texture/conversion.cpp` -- `thirdparty/rexglue-sdk/src/graphics/d3d12/texture_cache.cpp` -- `thirdparty/rexglue-sdk/src/graphics/vulkan/texture_cache.cpp` - -Emulation behavior: - -- decodes Xbox 360 texture layout and formats on demand -- performs untiling / conversion / invalidation logic -- reconstructs swap textures from emulated state - -Why it must go: - -- texture correctness bugs are still tied to emulated decode and filtering behavior -- texture conversion belongs in offline cooking, not hot-path per-frame interpretation - -Replacement target: - -- offline asset cooker -- host-native texture packages -- runtime streaming for only genuinely dynamic textures - -Retirement priority: `P1` - -### 7. Render-target cache, EDRAM emulation, and resolve ownership - -Files: - -- `thirdparty/rexglue-sdk/src/graphics/pipeline/render_target/cache.cpp` -- `thirdparty/rexglue-sdk/src/graphics/d3d12/render_target_cache.cpp` -- `thirdparty/rexglue-sdk/src/graphics/vulkan/render_target_cache.cpp` - -Emulation behavior: - -- reconstructs EDRAM-backed render-target ownership -- manages resolve and aliasing behaviors to mimic Xbox 360 output rules - -Why it must go: - -- effect/composite bugs are still heavily correlated with this layer -- native render targets should be explicit passes, not inferred ownership transfers - -Replacement target: - -- native render graph attachments -- explicit post-process history buffers -- explicit effect composition passes - -Retirement priority: `P1` - -### 8. Shader microcode interpretation and translation - -Files: - -- `thirdparty/rexglue-sdk/src/graphics/pipeline/shader/interpreter.cpp` -- `thirdparty/rexglue-sdk/src/graphics/pipeline/shader/translator.cpp` -- `thirdparty/rexglue-sdk/src/graphics/pipeline/shader/dxbc_translator*.cpp` -- `thirdparty/rexglue-sdk/src/graphics/pipeline/shader/spirv_translator*.cpp` -- `thirdparty/rexglue-sdk/src/graphics/d3d12/pipeline_cache.cpp` -- `thirdparty/rexglue-sdk/src/graphics/vulkan/pipeline_cache.cpp` - -Emulation behavior: - -- translates Xenos microcode into host shader forms at runtime -- caches host pipelines based on guest shader identity and emulated state - -Why it must go: - -- runtime translation is a major CPU cost and validation risk -- native renderer should use author-owned shaders with offline compilation - -Replacement target: - -- canonical HLSL source set -- offline compilation to DXIL, SPIR-V, and MSL -- stable pipeline-library generation and shader reflection at build time - -Retirement priority: `P1` - -### 9. Emulation diagnostics and traces - -Files: - -- `thirdparty/rexglue-sdk/src/graphics/trace_writer.cpp` -- trace headers / trace dump / trace player / trace viewer -- PM4 logging paths - -Emulation behavior: - -- introspects guest GPU traffic and emulated resources - -Why it must change: - -- title-native diagnostics still matter, but they should observe native frame graph and assets, not PM4/Xenos internals - -Replacement target: - -- native render capture -- pass timeline dumps -- asset/material resolution logs -- backend-specific GPU markers and RenderDoc/Xcode capture guides - -Retirement priority: `P2` - -### 10. Presenter / provider / window system - -Files: - -- `thirdparty/rexglue-sdk/src/native/ui/presenter.cpp` -- `thirdparty/rexglue-sdk/src/native/ui/d3d12/d3d12_presenter.cpp` -- provider / window / overlay code in `thirdparty/rexglue-sdk/src/native/ui/*` - -Current state: - -- already host-native enough -- not an emulation layer by itself -- currently consumes an emulation-produced guest output image - -Migration disposition: - -- keep, but retarget to native renderer outputs -- extend for backend-agnostic swapchain and frame pacing metrics - -Retirement priority: `keep and adapt` - -## Build-System Evidence - -The current build still compiles the emulator-era graphics stack: - -- project root `CMakeLists.txt` still relies on `generated/rexglue.cmake` -- `thirdparty/rexglue-sdk/src/graphics/CMakeLists.txt` still includes: - - `graphics_system.cpp` - - `command_processor.cpp` - - `shared_memory.cpp` - - `pipeline/texture/cache.cpp` - - `pipeline/texture/conversion.cpp` - - `pipeline/render_target/cache.cpp` - - `pipeline/shader/*translator*` - - `d3d12/*` - - `vulkan/*` - -Conclusion: - -- the emulation stack is not auxiliary -- it is still linked as the shipping graphics core - -## Components To Keep Versus Replace - -### Keep and extend - -- `RuntimeConfig.graphics` injection seam -- native presenter / provider / window abstractions -- AC6-local capture hooks during transition -- debug overlay plumbing -- title timing stats - -### Replace completely - -- PM4 swap path -- ringbuffer submission path -- `GraphicsSystem` as renderer owner -- `CommandProcessor` -- register file and Xenos state ownership for rendering -- shared memory hot-path resource model -- texture cache / untiling on the hot path -- EDRAM emulation -- runtime shader translation -- backend-specific emulated renderers - -### Narrow into compatibility shims - -- `xboxkrnl_video` exports -- guest interrupt callback semantics -- limited AC6 guest-D3D bridge while call sites are redirected - -## Retirement Order - -1. Introduce native renderer side by side with current presenter/provider. -2. Make `VdSwap` a native frame-boundary call, not a PM4 authoring point. -3. Redirect AC6 guest-D3D hot paths into native command recording. -4. Replace swap-source extraction with native final-composite ownership. -5. Replace shader translation with offline-native shaders. -6. Replace texture cache and guest resource ownership with cooked native assets. -7. Remove EDRAM / render-target emulation dependencies. -8. Delete PM4 / command-processor rendering path from AC6 build. - -## Audit Exit Criteria - -This audit is complete enough to drive implementation when the following are accepted: - -- every component above is assigned an owner and milestone -- each `P0` / `P1` item has a native replacement module defined -- validation targets are attached to each retirement step -- issue-tracker bugs are mapped to migration epics rather than ad hoc fixes - -## Non-Goals - -- iOS and Android support -- keeping Xenos semantics as a hidden fallback indefinitely -- pixel-perfect guarantees for every build during bring-up; parity gates apply before production diff --git a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md b/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md deleted file mode 100644 index bdb58572..00000000 --- a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md +++ /dev/null @@ -1,244 +0,0 @@ -# AC6 Native Graphics Execution Plan - -Date: 2026-04-17 -Scope: `AC6 recomp`, `Windows + Linux + macOS` -Purpose: convert the migration strategy, emulation audit, and deprecation timeline into an execution model with named workstreams, owner roles, dependencies, deliverables, and near-term checkpoints. - -Related documents: - -- `AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md` -- `AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md` -- `AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md` - -## Operating Rules - -- The strategy document defines target architecture, release gates, and phase sequence. -- The audit document defines what must be retired and its replacement targets. -- The deprecation timeline governs when legacy interfaces become dev-only, blocked, or removed. -- This execution plan assigns work ownership by role, defines handoff artifacts, and turns phase goals into weekly-trackable work. -- No workstream may expand the legacy PM4 / Xenos path except for temporary validation hooks required to compare outputs or preserve release safety. - -## Workstream Ownership Matrix - -| ID | Workstream | Primary owner role | Supporting roles | Source driver | Exit artifact | -| --- | --- | --- | --- | --- | --- | -| WS1 | Native render core (`RenderDevice`, `RenderGraph`, `FrameScheduler`) | backend lead | engine integration lead, QA / validation lead | strategy phases 1, 3, 4 | bootable native renderer core on all target platforms | -| WS2 | AC6 frontend integration (`Ac6RenderFrontend`, patched entry points, routing flags) | engine integration lead | backend lead, QA / validation lead | strategy phases 1, 3 | redirected AC6 render call sites with subsystem routing controls | -| WS3 | Asset cooker and package schemas | assets / tools lead | backend lead, security lead | strategy phase 2 | versioned cooker outputs and schema validation job | -| WS4 | Shader authoring and offline compilation | backend lead | assets / tools lead, QA / validation lead | strategy phase 2 | DXIL / SPIR-V / MSL package pipeline with reflection manifests | -| WS5 | Validation harness, benchmark scenes, golden images | QA / validation lead | engine integration lead, backend lead | strategy phases 0, 1, 3, 6 | deterministic scene manifests, diff thresholds, perf dashboards | -| WS6 | Presentation cutover and frame pacing | backend lead | engine integration lead, QA / validation lead | strategy phase 4 | native-present shipping route with pacing telemetry | -| WS7 | Compatibility shims (`xboxkrnl_video`, interrupt timing, limited bridge exports) | engine integration lead | backend lead | audit P0 items, strategy phases 3, 4, 5 | minimal non-render compatibility layer after cutover | -| WS8 | Emulation retirement and AC6 link cleanup | backend lead | engine integration lead, security lead | audit P0 and P1 retirements, strategy phase 5 | build evidence showing AC6 render linkage no longer depends on emulation stack | -| WS9 | Security, fuzzing, and package hardening | security lead | assets / tools lead, backend lead | strategy phase 6 | signed or checked package path, parser review, fuzz coverage | -| WS10 | Docs, config migration, and deprecation closure | AC6 graphics migration lead | all leads | deprecation timeline phases 2 through 6 | user and developer docs, config mappings, removed-API change log | - -## Audit Item To Workstream Mapping - -| Audit item | Priority | Replacement target | Owning workstream | -| --- | --- | --- | --- | -| `VdSwap` / guest submission / PM4 swap synthesis | `P0` | AC6-native frame boundary API | WS2, WS6, WS7 | -| `GraphicsSystem` MMIO ownership | `P0` | `Ac6NativeRenderSystem` behavior split across native core and scheduler | WS1, WS7 | -| `CommandProcessor` and PM4 parsing | `P0` | title-native render graph compiler | WS1, WS2, WS8 | -| Xenos registers and packet model | `P1` | native render-state and material descriptors | WS2, WS4, WS8 | -| shared guest GPU memory model | `P1` | host-native allocators and transient arenas | WS1, WS8 | -| texture cache / untiling / invalidation | `P1` | cooked textures and explicit streaming | WS3, WS8 | -| render-target cache / EDRAM / resolve ownership | `P1` | explicit render graph attachments and history buffers | WS1, WS6, WS8 | -| shader translation and guest shader caches | `P1` | authored HLSL plus offline backend outputs | WS4, WS8 | -| emulation traces and PM4 diagnostics | `P2` | native capture and pass timeline logs | WS5, WS10 | -| presenter / provider / windowing | keep and adapt | native final-color presentation path | WS6 | - -## Phase Exit Package - -Every phase closes only when the following package exists in source control or CI artifacts. - -### Phase 0 package - -- baseline performance report on agreed hardware matrix -- frozen benchmark scene manifest list -- initial golden image set from the current shipping path -- issue-tracker export for `graphics-emulation` -- accepted ownership table for all `P0` and `P1` audit items - -### Phase 1 package - -- boot logs proving native stack initialization on Windows, Linux, and macOS -- dual-run telemetry showing native scene-build cost -- compile-time flag and runtime kill switch for native scaffolding -- first integration document for patched render entry points - -### Phase 2 package - -- shader compile manifest with per-backend outputs -- asset cooker schema reference and versioning policy -- placeholder-correct render evidence for benchmark scenes -- CI jobs for shader validation and schema validation - -### Phase 3 package - -- subsystem routing matrix showing native versus legacy coverage -- parity dashboard for benchmark scenes per migrated subsystem -- canary performance deltas for each subsystem cutover -- rollback instructions for subsystem-level disablement - -### Phase 4 package - -- `VdSwap` contract note describing its reduced role as native frame boundary only -- present timing telemetry against baseline -- proof that production no longer depends on emulated swap extraction -- release-branch rollback plan for one milestone - -### Phase 5 package - -- link or build report proving AC6 no longer links `CommandProcessor`, shader translators, shared-memory render resources, or guest-state render caches -- updated compatibility shim inventory showing what remains and why -- full regression matrix results against parity, perf, and memory gates -- removed-interface change log draft for release notes - -### Phase 6 package - -- security review signoff -- fuzzing coverage report and unresolved issue list -- 90-day watch plan with owners for crash, regression, and memory signals -- deprecation closure checklist marked complete - -## Dependency Chain - -The main sequence for delivery is: - -1. WS5 establishes baselines and benchmark scenes. -2. WS1 and WS2 make native scaffolding boot and accept AC6-originated requests. -3. WS3 and WS4 replace runtime asset and shader interpretation. -4. WS5 validates subsystem migration while WS2 routes one subsystem at a time. -5. WS6 moves presentation authority to native outputs. -6. WS7 keeps only the smallest compatibility surface needed by the title. -7. WS8 removes emulation-linked rendering code from the AC6 target. -8. WS9 and WS10 close production-hardening and deprecation requirements. - -Blocking dependencies: - -- WS2 depends on WS1 interface stability. -- WS3 and WS4 must land before any subsystem is considered production-native. -- WS6 must not cut over until WS5 parity dashboards are green for the selected canary set. -- WS8 must not delete linkage until WS6 has held stable for one milestone and deprecation gates are satisfied. -- WS10 cannot close until config migration rules, README updates, and removed-interface notes are merged. - -## First 30 Days - -### Week 1 - -- confirm owner roles for WS1 through WS10 -- freeze target hardware matrix and benchmark scene candidates -- create the `ac6_native_renderer/` module tree and backend interface skeleton -- define the runtime flag names for global enable plus subsystem routing - -### Week 2 - -- patch one AC6 render entry point into `Ac6RenderFrontend` -- establish dual-run telemetry capture for scene build cost -- write the initial benchmark scene manifest format -- inventory every config flag or runtime switch that currently affects emulation-era graphics behavior - -### Week 3 - -- stand up shader compile prototypes for DXIL and SPIR-V -- draft asset cooker schema version `v0` -- capture the first golden images for UI, cockpit, terrain, and effects scenes -- define the canary perf dashboard and threshold owners - -### Week 4 - -- review boot status on all three desktop platforms -- decide whether the first migrated subsystem after scaffolding is post-FX or terrain -- publish the deprecation warning list for dev-only emulation flags -- lock the first milestone review deck with risks, blockers, and go / no-go criteria - -## Weekly Review Format - -Every weekly program review must answer the following: - -- which workstreams changed state this week -- which audit `P0` or `P1` items moved closer to retirement -- which benchmark or parity gates improved or regressed -- whether any subsystem rollback switch was required -- which deprecation warnings were added, expanded, or blocked by compatibility needs -- which unresolved risks threaten the next milestone - -Required metrics: - -- open `graphics-emulation` issues -- migrated subsystem count -- benchmark delta versus baseline -- parity diff pass rate -- native boot status by platform -- memory watermark trend -- crash-free soak hours - -## Decision Gates - -### Gate A: Native scaffolding ready - -Approve only if: - -- native stack boots on Windows, Linux, and macOS -- native scene build executes without presenting -- kill switch restores current shipping behavior - -### Gate B: Native assets and shaders ready - -Approve only if: - -- no runtime shader translation remains on the native path -- native assets render placeholder-correct benchmark scenes -- cooker and shader validation jobs run in CI - -### Gate C: Subsystem canary ready - -Approve only if: - -- target subsystem passes parity thresholds for benchmark scenes -- canary performance stays within agreed tolerance -- subsystem rollback flag is proven in a test build - -### Gate D: Native present authority ready - -Approve only if: - -- `VdSwap` is no longer required to synthesize `PM4_XE_SWAP` -- present timing meets or beats baseline -- no production frame depends on emulated frontbuffer extraction - -### Gate E: Emulation render linkage removal ready - -Approve only if: - -- AC6 link outputs exclude the retired emulation render objects -- perf, memory, and parity release gates are green -- fallback strategy exists only as a tagged branch, not a shipping runtime path - -## Deprecation Closure Checklist - -- every legacy graphics-facing config key is mapped, replaced, or explicitly removed -- dev-only emulation flags are blocked from production builds after phase 2 -- every removed interface has a replacement or compatibility note -- CI validates that the default distribution contains no deprecated production config -- release notes include the removal milestone and user-visible migration guidance - -## Open Risks - -| Risk | Impact | Owner role | Mitigation | -| --- | --- | --- | --- | -| AC6 render entry points are more fragmented than expected | slows WS2 and increases bridge complexity | engine integration lead | front-load call-site inventory and group hooks by subsystem | -| Cross-platform backend drift causes different visual behavior | blocks parity and canary promotion | backend lead | keep shared render graph semantics strict and validate with deterministic scene manifests | -| Asset cooker schema churn invalidates earlier native content | slows WS3 and WS5 | assets / tools lead | version schemas from day one and pin benchmark manifests to versions | -| `VdSwap` timing contracts affect non-render title behavior | delays WS6 and WS7 | engine integration lead | isolate interrupt-sensitive behavior into compatibility shims and test title timing explicitly | -| Removal of emulation diagnostics leaves developers blind during bring-up | increases defect turnaround time | QA / validation lead | deliver native capture, pass timeline dumps, and GPU marker conventions before broad deletion | - -## Definition Of Done - -This execution plan is considered complete enough to drive delivery when: - -- every workstream has an accepted owner role -- every `P0` and `P1` audit item is mapped to a workstream and target phase -- every phase has a required artifact package and approval gate -- the first 30 days of work can begin without waiting for another planning document diff --git a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md b/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md deleted file mode 100644 index 7a014ffd..00000000 --- a/docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md +++ /dev/null @@ -1,499 +0,0 @@ -# AC6 Native Graphics Migration Strategy - -Date: 2026-04-17 -Scope: `AC6 recomp`, `Windows + Linux + macOS` -Target: replace Rexglue's emulation-authoritative graphics stack with an AC6-native renderer while keeping production builds releasable at every phase. - -Companion planning documents: - -- `AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md` catalogs the current emulation-owned stack and replacement targets. -- `AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md` defines the deprecation and removal schedule for legacy graphics interfaces. -- `AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md` translates this strategy into workstreams, owner roles, dependencies, artifact packages, and weekly checkpoints. - -## Success Criteria - -The migration is considered successful only when all of the following are true in production: - -- emulation-authoritative rendering code is removed from the AC6 build -- issue tracker shows `100 percent` closure of bugs tagged `graphics-emulation` -- CPU overhead attributable to graphics drops by `20 percent` or more relative to the current baseline -- renderer-owned memory footprint drops by `30 percent` or more relative to the current baseline -- median frame time stays at or below `16.6 ms` on the 30 FPS production profile -- average GPU utilization stays below `80 percent` on the validated target matrix -- no critical or major severity regressions are opened within `90 days` of production release - -These are release gates, not assumptions. Baselines must be captured before Phase 1 ends. - -## Native Replacement Stack - -### Rendering API strategy - -Canonical engine interfaces: - -- `D3D12` backend for Windows -- `Vulkan` backend for Linux -- `Metal` backend for macOS - -Renderer architecture: - -- API-agnostic `RenderDevice` / `RenderGraph` / `FrameScheduler` core -- backend-specific device modules behind a thin, explicit portability layer -- no translation layer such as ANGLE, MoltenVK-as-primary, or emulated guest GPU state - -Decision: - -- author the renderer around explicit resource states, pipeline objects, descriptor sets/heaps, and timeline-style frame scheduling -- do not preserve Xenos concepts in the public rendering API - -### Shader stack - -Canonical source: - -- `HLSL` as the authored shading language for all AC6-native shaders - -Offline outputs: - -- `DXIL` for D3D12 -- `SPIR-V` for Vulkan -- `MSL` for Metal - -Toolchain: - -- `DXC` for HLSL to DXIL / SPIR-V -- `SPIRV-Cross` or equivalent validated codegen for MSL -- offline reflection manifest generation for resource layouts, permutations, and pipeline compatibility - -Rules: - -- no runtime Xenos microcode translation -- no guest-shader-derived pipeline creation in shipping mode -- shader permutations are compiled and cached before runtime, with pipeline libraries per backend - -### Buffer management - -Static content: - -- cooked immutable GPU buffers for meshes, index data, and prebuilt acceleration tables if needed later - -Dynamic content: - -- per-frame transient arena for constants, skinning, UI, and streaming draws -- persistently mapped upload ring for small dynamic updates -- segmented upload jobs for large texture or geometry streaming - -Lifetime model: - -- frame-indexed retirement with fence-backed reclamation -- descriptor lifetime tied to resource generations rather than guest addresses - -### Texture handling - -Cooked asset formats: - -- `KTX2` with `BasisU` or backend-native compressed output for static textures where feasible -- backend-native HDR / depth-capable formats for runtime render targets -- explicit metadata for color space, sampler class, mips, and streaming priority - -Runtime behavior: - -- no hot-path Xbox 360 untiling for shipping builds -- no guest texture cache for native-owned resources -- explicit residency manager for large terrains, cockpits, and effects textures - -### Asset loading - -Offline asset pipeline: - -- extract AC6 meshes, materials, textures, shaders, and effect descriptors from recompiled or game asset sources -- convert into native packages with stable IDs and versioned schemas -- bake material graphs and shader permutation keys at cook time - -Runtime asset loader: - -- async streaming on background threads -- integrity-checked package manifests -- deterministic scene bootstrap manifests for benchmark and pixel tests - -### Synchronization primitives - -Core abstraction: - -- timeline-style `RenderFence` -- `BinarySemaphore` only where backend interop requires it -- explicit resource barriers and pass dependencies in the render graph - -Backend mapping: - -- D3D12 fences + queue synchronization -- Vulkan timeline semaphores + pipeline barriers -- Metal shared events / command-buffer completion handlers - -Requirement: - -- frame submission and async compute ownership must remain host-native and explicit - -## Target Renderer Architecture - -### Core modules - -1. `Ac6RenderFrontend` - - receives patched calls from recompiled AC6 code - - builds scene, pass, and material requests - -2. `Ac6AssetCooker` - - converts source assets to native packages - - emits stable schemas and version manifests - -3. `RenderDevice` - - owns backend objects, queues, descriptor allocators, and memory allocators - -4. `RenderGraph` - - describes passes, attachments, synchronization, and transient resources - -5. `FrameScheduler` - - controls frame pacing, in-flight frames, async uploads, and capture points - -6. `MaterialSystem` - - resolves shader permutations, resource layouts, pipeline variants, and material constants - -7. `SceneStreaming` - - loads meshes, textures, and effect resources asynchronously - -8. `PostFXStack` - - tonemap, bloom, HUD composite, anti-aliasing, and display transforms - -9. `ValidationHarness` - - pixel diff, perf telemetry, memory tracking, deterministic captures, and replayable scene manifests - -### Game integration model - -The title code is allowed to change, so the correct strategy is direct call-site replacement rather than deeper emulation. - -Phase-in model: - -- patch AC6 rendering entry points to call `Ac6RenderFrontend` -- preserve the current hook-based frame capture only long enough to compare outputs -- migrate one subsystem at a time: - - frame setup - - camera / transforms - - terrain / environment - - aircraft - - particles / trails - - UI / HUD - - post-processing - -Hard rule: - -- no new rendering features may be added to the PM4/Xenos path once migration starts - -## Phased Rollout - -### Phase 0: Baseline and ownership - -Deliverables: - -- freeze current performance baselines on target hardware -- tag and export all issue-tracker items caused by graphics emulation -- lock the AC6 render-surface contract and benchmark scenes -- complete the emulation audit - -Exit gates: - -- baseline frame time, CPU cost, GPU utilization, and memory footprint recorded -- current golden images captured from the shipping emulator-authoritative path - -### Phase 1: Native scaffolding in parallel - -Deliverables: - -- add `Ac6RenderFrontend`, `RenderDevice`, `RenderGraph`, and backend stubs -- keep current renderer shipping -- add dual-run instrumentation: native scene build runs but does not present - -Exit gates: - -- AC6 boots with native stack initialized on all three PC platforms -- no user-visible behavior change -- telemetry compares native scene graph generation cost against emulated path - -Rollback: - -- disable with single runtime feature flag and compile-time option - -### Phase 2: Native asset and shader pipeline - -Deliverables: - -- offline shader compilation pipeline -- asset cooker for textures, materials, meshes, and effect metadata -- package manifests and versioning - -Exit gates: - -- benchmark scenes can render placeholder-correct geometry from native assets -- no runtime shader translation remains on the native path - -Rollback: - -- keep cooked assets optional while legacy assets remain authoritative - -### Phase 3: Hybrid native rendering by subsystem - -Deliverables: - -- terrain / sky / cockpit / aircraft / particle / HUD passes migrate incrementally -- native renderer writes final composite to existing presenter -- dual-render compare mode for selected scenes - -Exit gates per subsystem: - -- golden image threshold passes for benchmark scenes -- frame time does not regress more than agreed tolerance during canary -- issue count trends downward against emulation-tagged bug bucket - -Zero-downtime mechanism: - -- runtime routing flag per subsystem -- canary builds support mixed mode: - - native terrain with legacy particles - - native post-FX with legacy geometry - - native UI with legacy world render - -Rollback: - -- turn off only the failing subsystem, not the whole renderer - -### Phase 4: Native presentation authority - -Deliverables: - -- `VdSwap` becomes native frame boundary only -- PM4 `XE_SWAP` path removed from AC6 shipping route -- presenter consumes only native final-color output and UI overlays - -Exit gates: - -- no frame in production depends on emulated swap-source extraction -- native frame pacing and present timing match or beat baseline - -Rollback: - -- release branch keeps previous mixed-mode build for one milestone - -### Phase 5: Delete emulation rendering path from AC6 build - -Deliverables: - -- remove `CommandProcessor`, shader translators, shared memory, texture cache, and render-target cache from AC6 linkage -- keep only minimal compatibility exports required by non-render kernel behavior - -Exit gates: - -- build proves no AC6 rendering object files are linked from the emulation stack -- perf, memory, and parity goals pass full regression test matrix - -Rollback: - -- tagged fallback branch only; no hidden production runtime switch after signoff - -### Phase 6: Production hardening - -Deliverables: - -- security signoff -- fuzzing signoff -- 90-day production watch plan -- deprecation closure of legacy graphics configuration and docs - -Exit gates: - -- zero critical or major regressions within 90 days -- emulation bug label stays at zero open issues - -## Validation and Test Strategy - -### Pixel validation - -Primary method: - -- golden image diff on deterministic scenes - -Modes: - -- exact match for UI and deterministic post-FX scenes -- tolerance-based diff for scenes with backend precision drift -- review workflow for approved intentional visual changes - -Required coverage: - -- menus and HUD -- cockpit -- missile trails and smoke -- clouds and sky -- water / terrain -- lighting-heavy missions -- mission briefing / loading overlays - -### Performance benchmarks - -Metrics: - -- median, P95, and worst-frame CPU frame time -- GPU frame time -- GPU utilization -- draw / dispatch counts -- upload bandwidth -- shader compilation stalls - -Release gates: - -- `<= 16.6 ms` frame time on 30 FPS profile -- `< 80 percent` average GPU utilization on target matrix -- `>= 20 percent` lower graphics CPU overhead than baseline - -### Memory and leak detection - -Checks: - -- renderer heap watermark -- transient arena peaks -- descriptor exhaustion -- texture residency churn -- shutdown leak scan - -Tools by platform: - -- D3D12 debug layer and DRED -- Vulkan validation and memory alloc telemetry -- Metal API validation and Xcode memory capture -- ASan / LSan capable builds where available - -Release gates: - -- `>= 30 percent` lower renderer memory footprint than baseline -- zero unbounded growth in 4-hour soak tests - -### Cross-platform matrix - -Platforms: - -- Windows: D3D12 primary -- Linux: Vulkan primary -- macOS: Metal primary - -Required test classes: - -- smoke boot -- benchmark scenes -- full-mission traversal -- alt-tab / resize / suspend-resume -- shader cache cold / warm runs - -### Automated regression suite - -Required CI jobs: - -- shader compile validation -- asset cooker schema validation -- scene-manifest render tests -- golden image diff -- performance benchmark trend check -- memory leak / sanitizer runs -- fuzz suite for malformed assets and package manifests - -## Security Review Requirements - -Mandatory review areas: - -- native code injection points used to patch recompiled AC6 render call sites -- asset package parsing -- shader package loading -- descriptor / buffer bounds validation -- file-format conversion tools -- telemetry and capture ingestion - -Controls: - -- signed or checksummed native asset packages -- bounds-checked parsers -- hardened debug-only injection interfaces -- explicit separation between shipping and dev-only capture hooks - -Fuzzing scope: - -- malformed textures -- malformed mesh buffers -- corrupted package manifests -- invalid shader permutation metadata -- oversized or cyclic material graphs - -## Documentation Package Requirements - -The migration is not complete until the following ship: - -- renderer architecture guide -- backend bring-up guide for D3D12 / Vulkan / Metal -- asset cooker schema reference -- shader authoring and permutation guide -- API change log for all removed Rexglue-era render interfaces -- user migration guide for config and build switches -- deprecation schedule for legacy render flags and code paths - -## Rollback and Zero-Downtime Policy - -Rules: - -- production builds stay releasable after every phase -- every phase has a feature flag rollback -- subsystem-level rollback is preferred over whole-renderer rollback -- no destructive removal happens until the native path has passed parity and perf gates for at least one milestone - -Cutover policy: - -- internal canary -- opt-in external experimental -- default-on stable -- legacy branch retained for one release train only - -## Governance - -Program owner: - -- AC6 graphics migration lead - -Required leads: - -- backend lead -- assets / tools lead -- engine integration lead -- QA / validation lead -- security lead - -Weekly review metrics: - -- open emulation bugs remaining -- migrated subsystems count -- benchmark trend deltas -- memory trend deltas -- parity diff pass rate -- crash-free hours in soak runs - -## Recommended Implementation Order - -1. native renderer core and telemetry -2. asset cooker and shader pipeline -3. native post-FX and final composite -4. terrain / sky / environment -5. aircraft and world objects -6. particles and effects -7. HUD / menus / overlays -8. swap ownership and presenter handoff -9. deletion of PM4 / Xenos render path from AC6 target - -## Immediate Next Actions - -1. create `ac6_native_renderer/` module tree and backend interfaces -2. capture benchmark baselines on the agreed hardware matrix -3. inventory issue-tracker bugs tagged `graphics-emulation` -4. define the first three benchmark scene manifests -5. patch one AC6 render entry point into a no-op native frontend path