Hot Path Vulkan Approximate Occlusion Reports

Vulkan Approximate Occlusion Reports

Lifecycle: Performance - Unproven · Type: Approximate shortcut
State: Source-backed; runtime value is not established.

Status: Applicable title-scoped approximation candidate; not implemented, not benchmarked, and never equivalent to exact report counts.

Mechanism class: Approximate shortcut / guest-result substitution.

Reviewed source: 322986f4c5502b3fa887a9605ac8cd88e9b2c579

Backend: Vulkan.

Summary

Current xemu issues Vulkan occlusion queries, waits for exact results with VK_QUERY_RESULT_WAIT_BIT, accumulates counts, applies the surface-scale divisor, and writes a guest Z-pass report. Pending reports can also force pgraph_vk_finish() when PFIFO drains.

The proposed shortcut supplies a synthetic guest report for an admitted title/workload and stops issuing/retrieving the corresponding exact host queries.

This is a deliberate behavioral approximation. It may be useful where a title treats the report only as a nonzero visibility hint, but it can be wrong for exact counts, effects driven by magnitude, or synchronization-sensitive report use.

Current exact flow

flowchart TD
    A[Guest begins draws under Z-pass reporting] --> B[Issue Vulkan occlusion queries]
    B --> C[Queue clear/report commands in guest order]
    C --> D{PFIFO drained with pending reports?}
    D -->|Yes| E[Finish active graphics work]
    D -->|No| F[Process when completion boundary arrives]
    E --> G[vkGetQueryPoolResults with WAIT]
    F --> G
    G --> H[Accumulate exact pixel counts]
    H --> I[Apply surface-scale divisor]
    I --> J[Write guest report through DMA]

Loading

Candidate flow

flowchart TD
    A[Guest report/query command] --> B{Approximation policy admits this title and report type?}
    B -->|No| R[Run exact query route]
    B -->|Yes| C[Do not issue corresponding host occlusion query]
    C --> D[Track minimal guest-order metadata]
    D --> E{Clear or report?}
    E -->|Clear| F[Reset approximate visibility state]
    E -->|Report| G[Synthesize declared result, for example 0 or 1]
    G --> H[Write guest report in original order]
    F --> I[Continue]
    H --> I

Loading

The shortcut must remove both query issuance and exact result retrieval. Substituting the final value while retaining all host query work would not test the full hypothesis.

Candidate policies

Possible policies must be explicit and independently tested:

Policy	Meaning	Main risk
Assume visible	Report nonzero after any admitted draw	More objects/effects rendered; exact magnitude lost
Assume occluded	Report zero	Missing objects/effects; usually higher compatibility risk
Last exact result	Reuse a prior exact value for a bounded interval	Stale visibility and hidden synchronization
Title rule	Apply a known response for a specific report consumer	Narrow maintenance burden and version sensitivity

A first experiment should use a non-persistent title/workload override and one simple policy. It should not introduce a broad “fast occlusion” default.

Surface-scale trap

The exact path divides accumulated host counts by surface_scale_factor². A synthetic value of 1 must not be passed through that divisor and accidentally become zero at scales greater than one.

Approximate reports should be defined in guest-result units and written directly according to the approximation contract.

Ordering and ownership

The approximation may replace guest query results, but it must preserve:

• guest command order;
• clear/report sequencing;
• report DMA address and format;
• reuse of report addresses;
• interrupts or completion behavior associated with report publication;
• renderer and snapshot lifecycle.

It must remain separate from host fences and query/fence mechanisms used to retire Vulkan resources. Faking a guest-visible report never authorizes early destruction of in-flight host objects.

Emulation boundary

The physical NV2A produces a Z-pass count. Current xemu maps that behavior to Vulkan occlusion queries and exact host result retrieval.

This shortcut intentionally substitutes a cheaper answer. Its contract must state:

• which titles/workloads are admitted;
• whether only zero/nonzero semantics are preserved;
• maximum staleness if prior results are reused;
• expected visual/gameplay differences;
• how to disable the approximation immediately.

Why it may help

Potentially removed work includes:

• host query begin/end operations;
• query-pool pressure;
• exact result retrieval;
• VK_QUERY_RESULT_WAIT_BIT stalls;
• report-driven command-buffer finish operations;
• CPU processing of exact counts.

However, an optimistic result may cause the title to render more geometry. The correct decision metric is total CPU/GPU/frame cost, not only lower query wait time.

Seen in xemu

The exact wait, accumulation, scaling, and report queue are source-confirmed. No current evidence establishes:

• which titles consume only nonzero visibility;
• how much report waiting contributes to real lag;
• whether additional rendering would erase the gain;
• whether a title uses report magnitude or timing as part of game logic.

This candidate requires consumer-specific evidence before implementation.

Code and ownership map

Area	Role
hw/xbox/nv2a/pgraph/vk/reports.c	Query pool, report queue, exact wait, accumulation and guest report write
Draw/query begin/end path	Host query issuance that must be bypassed with the approximate route
pgraph_write_zpass_pixel_cnt_report()	Guest-visible DMA report publication
PFIFO/render thread	Preserves clear/report order and effective policy
Host resource lifetime	Must continue using real fences/completion independent of guest approximation

Required tests

Known-count fixture

Generate:

• zero visible samples;
• a known partial count;
• a known full count;
• clear, draw, report, clear, and report sequences.

The approximate route is expected to differ in declared cases. The test must report that difference rather than calling an exact-count oracle successful.

Consumer behavior

Test separately:

• count == 0 / count != 0 consumers;
• magnitude-dependent effects;
• reused report addresses;
• interleaved clear/report commands;
• delayed reads and busy polling;
• snapshot restore with queued reports.

Scene behavior

Move repeatedly behind and around occluders. Record missing objects, overdraw, effect changes, additional draw calls, GPU time, and guest progression.

Counters

zpass_report_requests
exact_queries_issued
exact_query_results_waited
exact_query_wait_ns
approximate_reports_written
approximate_policy_by_kind
report_queue_finishes
extra_draws_after_approximation
gpu_time_delta
visual_oracle_differences

Risks

• Missing geometry or effects.
• Rendering significantly more work than the query wait saved.
• Consumers depending on exact count magnitude.
• Report ordering or clear semantics changing.
• Approximate guest results leaking into host resource retirement.
• Scale-factor conversion turning optimistic values into zero.
• A title-specific workaround becoming a silent global default.
• False performance results because query work remained partially active.

Qualification

1. Profile report/query cost in a title that visibly reaches the path.
2. Identify how that title consumes the report.
3. Add a non-persistent, title-scoped diagnostic policy.
4. Prove host query issuance and exact retrieval are both absent on the approximate route.
5. Run known-count, ordering, report-address, and restore tests.
6. Compare total CPU/GPU/frame p95/p99, guest progression, draw count, and visual differences.
7. Define the accepted behavioral error and compatibility scope.
8. Keep exact reports as the default and maintained reference.

Disposition

Applicable only as a high-risk, title-scoped approximation. It is not an exact performance shortcut and should not be exposed generically without consumer-specific evidence.

Related pages

• Vulkan Renderer
• Vulkan Performance
• Assumption-Based Shortcut Validation
• Using Hot-Path Shortcuts

Full technical reference

Primary reference: This subject page is the design and research reference for Approximate Occlusion Reports. Pull requests are implementation/test history only.
Lifecycle: Performance - Unproven · Mechanism: Title-scoped guest-result approximation
Reviewed source: 322986f4c5502b3fa887a9605ac8cd88e9b2c579 · Acceptance class: approximate or scoped

1. Scope

Avoid issuing and retrieving exact host occlusion counts by substituting a documented approximate guest result for workloads that only need a visibility hint.

This entry remains Unproven: the source path and opportunity are concrete, but no accepted xemu runtime result has established that the candidate improves representative workloads. The page defines what must be bypassed, what remains mandatory, and how the hypothesis can be rejected.

2. Source seams

File / function	Role
hw/xbox/nv2a/pgraph/vk/reports.c	query allocation, clear/report ordering, VK_QUERY_RESULT_WAIT_BIT retrieval and DMA report writes

3. Current execution path

flowchart TD
    N0["Guest enables/counts occlusion"]
    N1["Issue Vulkan query commands"]
    N0 --> N1
    N2["Queue report in guest order"]
    N1 --> N2
    N3["Possibly finish/drain"]
    N2 --> N3
    N4["Wait/read exact host result"]
    N3 --> N4
    N5["Scale and write guest report"]
    N4 --> N5

Loading

4. Candidate execution path

flowchart TD
    N0["Recognize scoped approximate policy"]
    N1["Preserve guest clear/report order"]
    N0 --> N1
    N2["Skip exact host query work"]
    N1 --> N2
    N3["Write synthetic/last-known guest result"]
    N2 --> N3
    N4["Retain real host fences for resource retirement"]
    N3 --> N4

Loading

5. Why it may help

Exact query retrieval can introduce synchronization and report bookkeeping. Some games may only test count != 0, but others use magnitude. The candidate is therefore an explicit compatibility approximation, not an exact optimization. The draw side must stop issuing the exact queries; changing only the final value leaves much of the cost intact.

6. Work removed

• Host occlusion query issue/reset/result retrieval
• Exact pixel-count accumulation
• Some finish pressure caused solely by pending reports

7. Work that remains mandatory

• Guest report ordering
• Report address/DMA validation
• Host completion tracking unrelated to guest query value
• Fallback for titles needing exact counts

8. Implementation sketch

if (policy == QUERY_ASSUME_VISIBLE && report_is_admitted(report)) {
    uint32_t value = report.counted_draws_since_clear ? 1u : 0u;
    enqueue_guest_report_in_order(report, value);
    stats.approximate_reports++;
} else {
    enqueue_exact_occlusion_report(report);
}

The sketch defines the intended boundary; it is not a complete patch and does not replace source review, ownership design, or focused tests.

9. Correctness contract

• Synthetic results must remain in guest command order.
• A nonzero synthetic value must not be scaled down to zero accidentally.
• Guest-result substitution must never replace Vulkan fences/tickets used for resource lifetime.
• Policy scope and effective mode must be recorded.

10. State, ownership, invalidation, and fallback

Approximate state belongs to the guest report stream, not the host lifetime system. Policy should be title/session scoped initially. Clear/report address reuse and snapshot/reset must reset any last-result state.

The maintained reference path remains the fallback whenever admission, capability, lifetime, or validation is uncertain. A fast result with an unproven dependency is not acceptable as an exact optimization.

11. Advantages

• Can remove query and wait work entirely
• Useful diagnostic for query-bound scenes
• Maintains a complete exact route
• Can establish whether exact counts matter to a title

12. Costs and failure modes

• Can change visibility, draw counts, and game decisions
• Optimistic results may increase GPU work
• Magnitude consumers will behave incorrectly
• Title-scoped maintenance burden

13. Evidence counters

Counters must be cheap, subsystem-owned, and snapshotted outside the hot loop. Record at least:

• guest_query_begins
• exact_queries_issued
• approximate_reports
• query_result_wait_us
• finish_calls_for_reports
• additional_draws
• frame p95/p99
• visual/report mismatches

A local reduction is not enough. Evidence must connect route reachability and removed work to fixed guest progress, CPU/GPU time where applicable, and p95/p99 behavior.

14. Qualification matrix

• Known zero/partial/full visibility fixtures
• Boolean consumer vs magnitude consumer
• Interleaved clear/report and address reuse
• Scene moving behind occluders
• Surface-scale factors
• Snapshot/reset
• Compare total frame cost, not query wait alone

Correctness runs may use validation layers, detailed comparisons, and fault injection. Performance acceptance must use optimized Release builds with matching symbols and minimal instrumentation.

15. Acceptance rule

Accept only as an optional scoped compatibility/performance mode with measured title benefit and explicitly documented visual/gameplay differences.

16. Rejection rule

Reject as a general default, or when extra rendering outweighs saved query work, report ordering breaks, or the title uses exact magnitude.

17. Related architecture and history

Vulkan-Renderer · Performance-Unproven · Vulkan-Submission-and-Resource-Retirement · Using-Performance-Controls

PR pages may be linked as supporting evidence, but they are not substitutes for this reference.