mirror/AC6_recomp
1
0
Fork 0
mirror of https://github.com/sal063/AC6_recomp synced 2026-06-04 02:47:20 -04:00
Code Issues Packages Projects Releases Wiki Activity

Delete docs/native_graphics_migration directory

Browse Source
This commit is contained in:
sal063
2026-04-17 20:40:42 +03:00
committed by GitHub
parent 2e099f544e
commit 1f8ef9e9f5
5 changed files with 0 additions and 1435 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_API_DEPRECATION_TIMELINE.md
-137
View File
@@ -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
docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_DOC_TRACKER.md
-128
View File
@@ -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`
docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EMULATION_AUDIT_2026-04-17.md
-427
View File
@@ -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
docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_EXECUTION_PLAN_2026-04-17.md
-244
View File
@@ -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
docs/native_graphics_migration/AC6_NATIVE_GRAPHICS_MIGRATION_STRATEGY_2026-04-17.md
-499
View File
@@ -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