Hot Path Vulkan Hybrid Ubershader

Vulkan Hybrid Ubershader

Reviewed: November 1, 2026 · Source: main b7140848. Release availability: Hybrid #71, Prewarm default #150 and missing-stage readiness #228 are in v0.8.136-0-g458730bf5373 (September 30, 2026). #335 completion scheduling and #336 future-launch admission are reviewed-main only.

Lifecycle: Performance — Implemented · Type: Alternate execution path State: Implemented; measured benefits and retained adverse observations are workload-specific.

A ready compatible fallback can serve admitted fragment-combiner state while workers prepare exact specialization. Takeover waits for matching binding metadata and a complete graphics pipeline. A module-only result is insufficient. Uncovered or unsupported draws keep the required accurate specialized route.

Operation

In Machine → Settings → Advance, the Vulkan section offers Off, Fallback, Prewarm and Always (diagnostic). Fresh configurations use Prewarm, following #150; explicitly saved modes remain selected. The policy is latched at process startup. Restart xemu after changing it; changing renderer alone does not activate the selected mode.

Mode	Draw and preparation policy
Off	Exact specialization.
Fallback	Already-ready fallback while exact specialization is prepared; missing fallback can still block.
Prewarm	Fallback plus bounded preparation from history loaded at this launch, with asynchronous preparation of missing stages.
Always (diagnostic)	Interpreter for admitted draws; no specialized fragment preparation for those draws. Missing interpreter executables can still require synchronous construction.

Cross-launch prewarm requires Cache shaders, enabled by default. Skip unchanged shader work is an independent Vulkan control and must be isolated as a separate benchmark variable. The control guide explains selected versus active policy.

Current flow

flowchart TD
    A[Normal hybrid draw] --> B{Exact complete pipeline ready?}
    B -->|Yes| C[Draw specialized; learn family once for future launch]
    B -->|No| D{Admitted and complete compatible fallback ready?}
    D -->|No| E[Required specialized construction and draw]
    D -->|Yes| F[Draw fallback with dynamic controls]
    F --> G[Bounded exact compile and pipeline work]
    G --> H[Completion wakes renderer; validate generation and ticket]
    H --> I[Publish complete pipeline; later matching draw takes over]
    J[History loaded at launch] --> K[Bounded async fallback-family preparation]
    K --> D

Loading

Always is a separate diagnostic selection path. New demand does not imply a ready fallback, and missing history/lead time remains a first-launch limit.

Delivered scheduling changes

#228 retains missing-stage learned families, prepares vertex/optional geometry/fallback-fragment stages asynchronously, and services matching completions before demand where possible. #335 replaces pending-job timer polling with completion wakes, preserving bounded timed retries. #336 learns from already-served specialized draws without enqueueing optional live fallback compilation. Only validated launch-loaded history feeds speculative prewarm; newly learned recipes are saved for later launches. Required demand and Always keep their existing paths.

BEFORE: served specialized draw -> learn -> optional fallback build this launch
AFTER:  served specialized draw -> record once -> future-launch recipe
        loaded history -> bounded prewarm
        pending pipeline -> completion wake; failed work -> timed backoff

Requests own immutable inputs. Renderer publication validates generation/ticket and retains object lifetimes through command completion. Workers stop/join before dependent Vulkan objects are destroyed. The stable control ABI and fail-closed combiner admission protect output, while independent required/speculative compile lanes bound interference. Limits and full source map are in Hybrid Specialization.

Evidence and limits

#71 established implementation and focused/XISO correctness, with incomplete retail benefit attribution and mixed warm results. The delivered route and its Prewarm default are source facts; they do not make every workload a proven win.

#228's September evidence demonstrates missing-stage preparation and fewer synchronous pipeline intervals on exact historical candidates. Total visible work and tails were mixed. Empty-history controls were uncovered as designed.

#335 improved its balanced Deck PGR2 route but retained the accepted 2.40% texture-control p95/max increase, unqualified Windows cache timings and missing readiness oracles. #336 improved its balanced Deck PGR2 guest cadence/CPU/tails, while a separate seeded-history candidate run produced black images and stopped flips on a fixture that passed on its parent. The intermittent failure remains unresolved and explicitly accepted for proceeding; a later pass is not a repair. Full records are private; the PRs publish compact metrics, identities and limitations.

Those October results are tied to their parent/candidate pairs. Guest cadence is not host-presented FPS or proof of identical simulation progress. Interpreter GPU cost, compiler/driver contention, memory/cache pressure and deferred future first-use work remain tradeoffs.

Current source

• config_spec.yml, ui/xemu-tweaks.c and ui/xui/main-menu.cc: default, process latch and UI.
• vk/shaders.c, vk/draw.c: stage/binding/pipeline selection and publication.
• vk/hybrid-family.c, vk/hybrid-family-history.c, vk/hybrid-ready.h: family learning, launch admission and completion/retry contracts.

See Shader Caching, Learned Fallback Readiness, historical PR #71 design and cold-trace reference.