1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
// SPDX-License-Identifier: MIT OR Apache-2.0
/// Which path a frame went down. Carried on per-call result types (an
/// interop layer's import / export results) rather than process-global
/// cells.
///
/// The reason in `CpuBounceFallback` is a `&'static str` **deliberately**
/// — no allocation, no formatting, and CI can assert specific strings
/// without string-slicing the whole output.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum ExecutionPath {
/// No run has completed yet — the initial state of a
/// freshly-constructed processor's metrics. Distinct from every
/// "work happened" path so a caller can tell "no measurement yet"
/// apart from "ran, took the CPU-bounce path". A metrics record's
/// default reports this; it never appears after a completed run.
NotRun,
/// The source resource was aliased into a `wgpu::Texture` / `wgpu::Buffer`
/// without any host or device-to-device copy on this frame.
ZeroCopy,
/// A **host-side** full-buffer copy was elided: the consumer referenced the
/// producer's existing CPU allocation (a refcount bump) instead of memcpy-ing
/// the payload into its own buffer. No GPU resource was aliased and no device
/// was involved at all.
///
/// Deliberately NOT [`Self::ZeroCopy`], which asserts a GPU aliasing import —
/// conflating the two makes a pure-software path read as GPU zero-copy in
/// every matrix report. Deliberately NOT [`Self::CpuBounceFallback`] either:
/// no host memcpy ran, so it is not a bounce.
///
/// Reported by software-encode input paths that take a new reference to a
/// decoded frame's existing CPU planes instead of copying them into the
/// encoder's input frame.
HostCopyElided,
/// Zero-copy modulo a GPU-side staging copy (e.g. the wgpu-GL OES→2D
/// blit, or a D3D11→D3D12 row-major stage). `copies` counts how
/// many on-device copies happened: `1` for the "single staging
/// copy" case; `2+` for forced bounce-and-rewrap. Distinguished
/// from `ZeroCopy` so callers gating on "no driver-side copy at
/// all" don't conflate them, and from `CpuBounceFallback` because
/// the staging cost is GPU-side.
///
/// `reason` is an optional `&'static str` tag — same no-alloc,
/// CI-assertable rule as `CpuBounceFallback::reason` — naming the
/// specific GPU-local route that ran (e.g. which bonded CUDA→GPU
/// path), for diagnostics. `None` when the path has no finer label
/// worth pinning. It does **not** participate in the "how much work
/// happened" signal — `copies` does — but it is part of the variant's
/// `Eq`/`Hash`, so two `DeviceLocalCopy`s with the same `copies` but
/// different `reason` compare unequal.
DeviceLocalCopy { copies: u8, reason: Option<&'static str> },
/// Web only. The operation went through a browser API that is a copy
/// at the spec surface (`copyExternalImageToTexture`,
/// `new VideoFrame(canvas)`) executed **inside the browser** —
/// typically GPU-to-GPU, but unobservable and uncountable from wasm.
///
/// Distinct from [`Self::DeviceLocalCopy`] (which asserts a counted,
/// known copy on a device we control) and from
/// [`Self::CpuBounceFallback`] (no CPU memcpy ran on our hot path).
/// An option that silences cross-backend CPU-bounce warnings should
/// never silence this — it is the expected default on the web and
/// exists for visibility, not noise.
BrowserGpuCopy,
/// A prior import (any path) was reused this frame from the import
/// cache; no work happened in this call. Distinct from `ZeroCopy`
/// because the *original* import may have been a CPU upload — a
/// caller gating "is this frame zero-copy aliased?" must not
/// conflate the two.
CacheHit,
/// A CPU host memcpy ran on the per-frame hot path. The `reason`
/// disambiguates which call site flipped the path so a once-per-
/// reason bounce logger can warn exactly once per cause.
CpuBounceFallback { reason: &'static str },
}