Development

Development

This page separates current architecture from active experiments and closed research.

Architecture pages describe the code a developer should expect on main. Pull requests appear here when they are useful implementation history, ongoing research, or evidence for a design decision.

Status snapshot: 2026-09-13. Always use the linked PR as the final source of truth for current head and merge state.

Current merged foundations

These changes are part of current main and may be referenced as current behavior in architecture pages.

PR	Area	Current architectural effect	Read next
#70 — persistent Vulkan shader artifacts	Vulkan shaders	Adds bounded persistent SPIR-V reuse for previously encountered exact shader source/configuration	[[Vulkan Renderer
#75 — exact Vulkan adapter selection/reporting	Vulkan device selection	Makes renderer GPU selection/reporting explicit enough to verify the actual physical device	[[Vulkan Renderer
#76 — cross-adapter presentation fallback	Presentation	Adds a bounded host-copy path when Vulkan rendering cannot safely share external memory with the OpenGL presenter	[[Vulkan Renderer
#80 — guarded warm texture reuse	Vulkan textures	Reuses unchanged texture bindings only when effective source/DMA identity and freshness remain compatible	[[NV2A Graphics Architecture

Active Vulkan research

PR #71 — Ubershader & hybrid specialization

State: open draft / HOLD.

PR #71 researches how to hide genuinely unseen fragment specialization behind an already compiled runtime fallback while a specialized shader is prepared in the background.

Key concepts:

• Fail-closed ubershader admission.
• Fixed control ABI for runtime combiner state.
• Background speculative compiler lane.
• Independent required/blocking compiler lane.
• Generation/ticket checks before publishing asynchronous results.
• Fast-path avoidance of redundant route selection.
• Specialized path remains authoritative when ready.

The architecture is implemented on the PR branch, but exact-current-head retail qualification remains incomplete and prior cold-tail regressions remain a HOLD condition. Do not describe the feature as an established performance win.

Read: Ubershader & Hybrid Specialization.

PR #83 — Descriptor-capacity interaction

State: open draft / HOLD.

PR #83 investigates Vulkan descriptor/uniform capacity and the submission/finish behavior caused when the current resource pool is exhausted.

The important result is methodological: removing one local finish reason did not prove a throughput win because the same dependency could move to another later submission/fence boundary.

Read: Vulkan Renderer and Performance Methodology.

PR #85 — Surface / vertex freshness

State: open draft / HOLD.

PR #85 addresses cases where vertex data can overlap GPU-authored surfaces and guest memory may not yet contain the newest bytes.

The correctness question is:

Before CPU-side vertex decoding or upload,
is guest memory definitely authoritative for the exact fetched range?

If not, surface readback/coherency must happen before consuming the data.

Read: NV2A Graphics Architecture and Vertex Uploads & Render-Pass Lifetime.

PR #87 — Fresh-page direct vertex writes

State: open draft / HOLD.

PR #87 researches direct mapped writes into the Vulkan vertex-RAM mirror when the active command buffer has not already recorded a draw that reads those pages.

The safety rule is lifetime-based, not merely “use memcpy instead of staging”:

page unread by all earlier recorded draws in active batch
    → direct mapped write may be safe

page already consumed by an earlier recorded draw
    → preserve ordered staging copy/barriers

Morrowind exposes a meaningful opportunity, while PGR2 can pay bookkeeping cost for very little direct-copy benefit. Current performance qualification remains mixed.

Read: Vertex Uploads & Render-Pass Lifetime.

PR #88 — Graphics command-state reuse

State: open draft / HOLD.

PR #88 investigates reusing graphics command state across render-pass restarts rather than replaying state more broadly after every pass break.

The experiment is useful because it targets CPU command-recording overhead without assuming render-pass GPU time itself is removable. Current results remain adverse/mixed for at least part of the tested Morrowind workload, so it remains research rather than current architecture.

Read: Vulkan Renderer and Vulkan Performance.

PR #89 — Bounded immutable vertex versions

State: open draft.

PR #89 extends the vertex-lifetime work toward bounded immutable versions rather than relying only on rewriting a shared mirror.

The architectural question is whether xemu can let earlier recorded draws retain the bytes they were supposed to consume while later guest writes advance to a new version without forcing the same ordered-copy/pass-break path.

This sits on top of the #85/#87 correctness work and should be read as stacked research.

Read: Vertex Uploads & Render-Pass Lifetime.

Active timing research

PR #81 — Explicit PTIMER deadlines

State: open draft / HOLD.

PR #81 experiments with a more explicit NV2A PTIMER scheduling state machine.

The candidate separates:

• Guest-visible PTIMER state.
• Derived virtual-clock deadline.
• Whether a host QEMUTimer is armed.
• Whether the next operation should keep, cancel, or replace the queued deadline.
• Phase-aware conversion/rounding of future alarm ticks.

This is not current-main PTIMER architecture. Retail qualification remains mixed, including adverse OpenGL Morrowind evidence, so the branch remains HOLD.

Read: Clocks & Timers.

Closed diagnostic / negative research

Closed research still belongs in the Wiki when it established a useful architectural fact.

PR	State	What it established	Read next
#68 — classify Vulkan shader-module misses	Closed, unmerged diagnostic	The primary reproduced PGR2 hitch included genuinely first-seen shader sources; pipeline misses, binding misses and compiler calls must be measured separately	[[Shader Binding & Compilation
#54 — TCG return attribution	Closed diagnostic	Provided evidence for classifying why translated CPU execution returned to the TCG dispatcher	[[CPU & vCPU Execution
#55 — STI interrupt-shadow chaining	Closed, unmerged / HOLD	Tested a CPU-dispatch optimization around x86 STI interrupt-shadow semantics; correctness boundaries prevented treating fewer exits as automatically safe	[[CPU & vCPU Execution
#92 — live renderer reinitialization experiment	Closed, unmerged negative experiment	Showed that live renderer reset is coupled to framebuffer/UI ownership and synchronization; destroying/recreating the renderer is not an isolated settings operation	[[NV2A Graphics Architecture

How development pages should reference PRs

A Wiki page should normally say:

This is how the subsystem works.

Related Development
- PR #NN investigates changing this boundary because ...
- Current status: Draft / Hold / Merged / Closed diagnostic.

Avoid organizing permanent documentation as:

PR 71
PR 81
PR 87

PR numbers are implementation history. The durable subject is the subsystem and its data flow.

Status vocabulary

Label	Meaning in this Wiki
Merged / current	Behavior is present on current main and can be documented as architecture
Draft	Implementation/research exists but is not accepted mainline behavior
HOLD	One or more correctness/performance/qualification blockers remain
Diagnostic	Instrumentation/evidence branch intended to classify behavior, not ship
Historical	Measurement or implementation belongs to an older exact source state
Negative experiment	Useful result showed the proposed route was not beneficial/safe enough to continue in that form

Evidence discipline

When a PR changes rapidly, the PR body and evidence repository should identify:

• Exact tested head.
• Executable/build hash.
• Reference source.
• Workload seed.
• Instrumented versus normal build.
• Correctness gates.
• Performance gates.
• Historical results that no longer qualify the current head.

A new commit does not automatically inherit an earlier PASS. See Performance Methodology.

Architecture index

• System Architecture
• CPU & vCPU Execution
• Clocks & Timers
• NV2A Graphics Architecture
• OpenGL Renderer
• Vulkan Renderer
• OpenGL vs Vulkan