Performance Research G05 Descriptor Reuse and Capacity

Descriptor reuse and pool capacity

G05 — Implementation and validation notes

Field	Value
Evidence state	Production mechanism plus local wait-relocation negative evidence
Inspected source	322986f4c5502b3fa887a9605ac8cd88e9b2c579
First experiment	Reuse complete effective descriptor identity
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

Real precedent. Khronos provides an explicit descriptor-management sample that caches sets by their resource contents instead of constantly allocating/updating them. This supports pursuing CPU-side descriptor overhead in draw-heavy workloads. Descriptor management.

Crucial local counterevidence. The Morrowind descriptor-capacity probe removed NEED_BUFFER_SPACE submissions but moved waiting into SURFACE_DOWN. That is not evidence of a throughput improvement. Issue #86.

Implementation. Cache complete descriptor identity, including image view, sampler, required layout/buffer-range identity, and resource generation. Retain referenced resources until submitted work completes. Recycle pools by completed epochs, not arbitrary frame labels. Account for shader fallback/specialized layout differences.

Expected gain. Fewer CPU descriptor allocations/updates and capacity drains. Larger pools alone can add memory and defer the same stall. Prefer eliminating duplicate descriptors before simply increasing capacity.

Acceptance. Resource destruction/recreation with reused handles, eviction while work is in flight, layout changes, shader transitions, low-capacity stress, and exact output. Compare total descriptor CPU cost, peak memory, and all wait reasons.

First patch boundary

Include all descriptor-relevant identity and lifetime. Separate caching from merely increasing pool capacity.

effective descriptor identity -> reuse or allocate/update -> GPU-owned pool retirement

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

git grep -n -E 'descriptor|NEED_BUFFER_SPACE|SURFACE_DOWN' -- 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
G05.01	Identical descriptor state across draws and content changes that do not change descriptor identity.	Only eligible updates are skipped; dependent synchronization still occurs.
G05.02	Change buffers, offsets/ranges, views, samplers or layouts independently.	Every descriptor-relevant mutation misses or updates correctly.
G05.03	Exhaust a small pool with GPU readers delayed; compare an enlarged-pool-only control.	No live set/pool is reset; any wait relocation is recorded across all reasons.

Counters and rejection criteria

Collect: descriptor_allocations, descriptor_updates, descriptor_hits, live_sets, pool_resets, allocation_cpu_ns, total_fence_ns. Keep exact counts separate from sampled durations; use an uninstrumented build for performance qualification.

Reject or hold: Reject stale descriptors and premature pool reuse. Capacity changes alone need total-work/tail evidence; fewer NEED_BUFFER_SPACE submits are not sufficient.

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 — retained publication obligations

Draft PR #134 separates descriptor-visible identity from the obligation to publish it.

A slow texture traversal can validate sources, upload bytes, retry a bind, or abandon a draw. Publication should be requested only when descriptor-visible identity changes, but once requested that obligation must survive until descriptor publication actually succeeds.

flowchart TD
    A[Validate stages] --> B{Descriptor identity changed?}
    B -->|No| C[Keep publication state]
    B -->|Yes| D[Set publication required]
    D --> E{Abandoned or retried?}
    E -->|Yes| F[Retain obligation]
    E -->|No| G[Update descriptor set]
    F --> G
    G --> H[Clear only after publication]

Loading

Do not clear the obligation because a draw was rejected, a retry found the same binding, uniform reconciliation completed, or a stage became temporarily disabled. PR #134 also preserves guest dirty state when an already-dummy stage bypasses slow work so a later re-enable still performs required work.

PR #135 adds a separate dependency: texture-scale uniform reconciliation may use publication as a trigger, but must not consume descriptor ownership.

Track descriptor identity changes, obligations created/carried, actual descriptor updates/writes, rollovers, and uniform-only reconciliation separately.

Reviewed head: #134 draft 4359f048.