Performance Research G09 Pipeline Key Minimization

Pipeline-key minimization and texture-scale suppression

G09 — Implementation and validation notes

Field	Value
Evidence state	Historical measured local reduction; dependency proof still required for each new field
Inspected source	322986f4c5502b3fa887a9605ac8cd88e9b2c579
First experiment	One-field dependency table against always-recompute reference
Scope	Addendum dated September 15, 2026; not a current-main benchmark or implementation status

Unproven performance research · Performance research — common test protocol · Performance research — reproducible checks

Evidence and implementation reasoning

Local proof of merit exists. The retained history reports a texture/pipeline classification change with 79.9% fewer pipeline lookups and 1.079% better fixed-work Morrowind throughput. This is an excellent example of a large local reduction producing a much smaller end-to-end gain. It is historical evidence, not a promised gain for another key reduction. Research history.

Additional implementation detail. Separate shader code identity, fixed-function pipeline state, descriptor identity, content dirtiness, and uniform values. Remove a field from a key only after proving it cannot change the compiled program or pipeline behavior. Likewise, suppress texture-scale work only when its effective value and every consumer stay unchanged.

Proof style. Build a dependency table: mutate one field, then compare generated shader source/SPIR-V identity, pipeline requirements, uniform bytes, descriptors, and rendered output against an always-recompute path. This is stronger than a hit-rate counter.

Expected gain. Fewer hashes, comparisons, state derivations, lookups, and occasionally pipeline creations. If lookup is already cheap and a different stage dominates, the FPS effect may be small.

First patch boundary

Remove one redundant key dependency at a time. Hash equality is not a substitute for complete semantic identity.

state change -> shader/pipeline/descriptor/uniform dependency classification -> only affected cache/update paths

Locate the inspected seam before editing; names or ownership may have changed since the pinned review:

git grep -n -E 'ShaderState|pipeline|texture_bindings_changed|scale' -- hw/xbox/nv2a/pgraph/vk

Proposed focused tests

These are implementation gates to add or exercise, not claims that production tests already exist or passed. Retained standalone checks are on the checks page.

Test ID	Setup / deliberate control	Required oracle
G09.01	Vary one proposed-removed field at a time and compare against an always-recompute path.	Shader identity, pipeline requirements, uniforms, descriptors and rendered output remain correct.
G09.02	Paired descriptor-only and shader-affecting texture changes, including effective scale transitions.	Only descriptor-only changes avoid the pipeline/shader path; scale still reaches its true consumers.
G09.03	Alternate states across reset, cache eviction and object-handle reuse.	No stale cache identity is resurrected.

Counters and rejection criteria

Collect: pipeline_lookups, pipeline_hits, pipeline_creations, shader_source_changes, descriptor_updates, uniform_updates, prepare_cpu_ns. Keep exact counts separate from sampled durations; use an uninstrumented build for performance qualification.

Reject or hold: Reject missing dependency invalidation. Report local lookup count and fixed-work throughput separately; historical percentages cannot be reused as a forecast.

Follow the common protocol for source identities, previous-main/fixed-baseline controls, raw results, confidence and retail/XISO qualification. No gain becomes proven from a model, cache hit, local operation count, or shifted wait label alone.

Recent evidence — remove runtime-uniform values from executable identity

Merged PR #131 gives a concrete key-minimization rule. Alpha reference and polygon-offset magnitudes are runtime fragment uniforms, yet their raw values also participated in pipeline identity.

The fix canonicalizes only uniform-owned fields after the common state copy while leaving guest registers, dirty tracking, uniform generation, and shader polygon-offset logic intact.

flowchart LR
    A[Guest state] --> B[Copy common pipeline state]
    B --> C[Canonicalize runtime-uniform fields]
    C --> D[Pipeline key]
    D --> E[Foreground / fallback / background / publication]

Loading

A conservative dirty detector may remain conservative: a uniform-only write can enter the update path and then reuse the existing canonical pipeline.

Apply the same canonicalization to every key producer/consumer. Before removing another field, prove it does not affect generated code, fixed-function state, reflection/layout, or host capability selection.