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
FrameTimingUI (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_dominancewarns 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 toshader_compilation). The issue stampsobservedDominantFrames, the dominant frames in the one-second span it judged, anddominantFrameCount, 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 (FrameTimingDetectordisabled), 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
-
- Object
- BaseDetector
- GpuPressureDetector
- Mixed-in types
- Annotations
-
- @experimental
Constructors
Properties
- criticalRasterDominantFrames → int
-
Raster-dominant frames inside one second at which
raster_dominanceis 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_dominancewarns. 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.dartEntryMonotonicUsdo not count toward the frame leg. Same clock and window asFrameTimingDetector'slifecyclePhase; the controller wires it fromDetectorThresholds.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_dominanceissue at the start of a capture scenario, so dominant frames from before the scenario cannot join its first record.expensive_gpu_nodesstays until the next scan. Called bySleuthController.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
SleuthControllerwhenever the resolved frame budget changes.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited