GpuPressureDetector class

Detects GPU pressure from expensive rendering operations.

Hybrid Detector with three evidence sources:

  • Frame leg (every tier). processFrame receives each presented frame's FrameTiming UI (build + layout + paint) and raster durations. A frame is raster-dominant when its UI time is positive, its raster time exceeds the frame's own budget (so the frame missed its deadline on the raster thread) and maxFrameRasterFloorUs, and raster exceeds rasterMultiplierThreshold × UI. raster_dominance warns when at least minRasterDominantFrames dominant frames fall inside a one-second span, and is critical at criticalRasterDominantFrames. Dominant frames from the last second before the newest frame carry across a scan, so a burst split by a scan counts once. Frames that arrive within startupPhaseWindowSeconds of Dart entry are ignored (cold-start pipeline compilation belongs to shader_compilation). The issue stamps observedDominantFrames, the dominant frames in the one-second span it judged, and dominantFrameCount, the dominant frames since the previous scan. The two differ when a span reaches back across a scan.
  • VM leg. Raster and UI timeline events from the VM, ignored inside the same startup window, read once per scan. When the frame leg fires and a VM raster frame since the last scan also exceeds the budget and rasterMultiplierThreshold times the UI time of an average frame in its batch, the issue is confirmed. When no frames arrived since the last scan (FrameTimingDetector disabled), the VM leg emits on its own once one poll holds minRasterDominantFrames such frames, critical at criticalRasterDominantFrames.
  • Structural leg. Opacity, ClipPath, BackdropFilter, ShaderMask and ColorFiltered over deep subtrees (expensive_gpu_nodes).
Inheritance
Mixed-in types
Annotations
  • @experimental

Constructors

GpuPressureDetector({double rasterMultiplierThreshold = 2.0, int maxFrameRasterFloorUs = 8000, int minRasterDominantFrames = 3, int criticalRasterDominantFrames = 10, int startupPhaseWindowSeconds = 5, String? sourceRouteProvider()?, int? appStartMonotonicUsForTest()?})

Properties

criticalRasterDominantFrames → int
Raster-dominant frames inside one second at which raster_dominance is critical. Default 10. On a Galaxy A07 the GPU Pressure, Cupertino blur and IntrinsicHeight demos dropped 26 to 54 such frames a second; other screens there and on an iPhone 12 dropped 5 or fewer.
final
description → String
Short description of what this detector checks.
finalinherited
effectiveMaxFrameRasterFloorUs → int
Raster time the VM leg's worst frame must exceed: the resolved frame budget, or maxFrameRasterFloorUs when that is larger. The frame leg uses each frame's own budget.
no setter
hashCode → int
The hash code for this object.
no setterinherited
highlights → List<WidgetHighlight>
Highlight candidates collected during the last scan. Empty for detectors that don't produce visual highlights.
no setteroverride
isEnabled ↔ bool
Whether this detector is currently active.
getter/setter pairoverride
issues → List<PerformanceIssue>
Current list of detected issues. Reset each analysis cycle.
no setteroverride
key → String?
Stable identifier for config-driven gating of custom detectors.
finalinherited
lifecycle → DetectorLifecycle
Lifecycle classification determining data source requirements.
finalinherited
maxFrameRasterFloorUs → int
Raster time (microseconds) a frame must exceed to count, on top of its frame budget. The default 8000 is below the budget of every display up to 120 Hz, so it takes effect only when raised.
final
minRasterDominantFrames → int
Raster-dominant frames inside one second at which raster_dominance warns. Default 3.
final
name → String
Human-readable name of this detector (e.g., "Frame Timing").
finalinherited
rasterMultiplierThreshold → double
Flag when raster time exceeds UI time by this factor.
final
requiresTreeScan → bool
Whether this detector scans the widget/render tree.
no setterinherited
requiresVm → bool
Whether this detector needs VM service data to function. DetectorLifecycle.runtime detectors benefit from VM data but don't require it.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
startupPhaseWindowSeconds → int
Frames arriving within this many seconds of StartupTracker.dartEntryMonotonicUs do not count toward the frame leg. Same clock and window as FrameTimingDetector's lifecyclePhase; the controller wires it from DetectorThresholds.startupPhaseWindowSeconds.
final
type → DetectorType
The detector type identifier used for configuration.
finalinherited
validationMetadata → DetectorMetadata
Metadata for this detector. Must be non-null on shipping detectors — the audit test gates this.
no setteroverride
vmConnected ↔ bool
Current VM connectivity — set by the controller.
getter/setter pairoverride-setter

Methods

afterElement(Element element) → void
Called after an element's children have all been visited.
override
checkElement(Element element) → void
Check a single element during the unified tree walk.
override
dispose() → void
Dispose of any resources held by this detector.
override
evaluateNow() → void
Triggers issue evaluation using whatever data has been staged.
inherited
finalizeScan() → void
Finalise the scan: process accumulated data and create issues.
override
markRouteEpoch() → void
Starts a new frame window at a route change: raster-dominant frames and VM raster timing seen on the previous route no longer count.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyWalkCompleted() → void
Called when the tree walk completed without exceptions.
inherited
prepareScan(BuildContext context) → void
Prepare for a new scan cycle. Called once before the unified tree walk.
override
processFrame(FrameStats frame) → void
Process one presented frame from FrameTiming.
override
processTimelineData(ParsedTimelineData data) → void
Process VM timeline data.
override
resetCaptureState() → void
Clears the frame leg, the VM leg and any raster_dominance issue at the start of a capture scenario, so dominant frames from before the scenario cannot join its first record. expensive_gpu_nodes stays until the next scan. Called by SleuthController.resetCaptureState, which runs only in capture mode.
resetFrameBudget() → void
Restores the 60 Hz budget (16667 us).
scanTree(BuildContext context) → void
Scan the widget/render tree for issues.
inherited
toString() → String
A string representation of this object.
inherited
updateDebugSnapshot(DebugSnapshot snapshot) → void
Called with debug callback data when available.
inherited
updateFrameBudget(int budgetUs) → void
Sets the frame budget the VM leg judges against. Called by SleuthController whenever the resolved frame budget changes.

Operators

operator ==(Object other) → bool
The equality operator.
inherited