Winscope

Introduction to Winscope

Winscope is a specialized tool developed specifically for analyzing window transitions, screen rendering, and input events within the Android OS. While Perfetto gives you a timeline of when things happened in the CPU, Winscope shows you exactly what the system UI, WindowManager, and SurfaceFlinger states looked like at any given millisecond.

If you are debugging a broken animation, a missing window, a black screen during app launch, or input not registering on a specific area of the screen, Winscope is the tool to use.

Capturing Winscope Traces

Winscope traces are fundamentally just protocol buffer dumps of the internal state of WindowManagerService (WMS) and SurfaceFlinger (SF).

You can capture these traces in a few ways:

1. Using the Winscope Web UI (ADB Extension)

The easiest way is to use the official web interface at https://ui.perfetto.dev (modern versions of Perfetto integrate Winscope) or the dedicated AOSP Winscope UI. By installing the Winscope ADB Chrome extension, you can connect directly to your device from the browser and click "Record".

2. Using adb shell (Command Line)

You can manually trigger recording on the device.

To trace SurfaceFlinger (layers, buffers, composition):

adb shell su root service call SurfaceFlinger 1025 i32 1 # Start
# ... reproduce the bug ...
adb shell su root service call SurfaceFlinger 1025 i32 0 # Stop
adb pull /data/misc/wmtrace/displays.pb .
adb pull /data/misc/wmtrace/layers_trace.pb .

To trace WindowManager (window states, focus, animations):

adb shell cmd window tracing start
# ... reproduce the bug ...
adb shell cmd window tracing stop
adb pull /data/misc/wmtrace/wm_trace.pb .

To trace input events:

adb shell cmd input tracing start
# ... reproduce the bug ...
adb shell cmd input tracing stop

Analyzing Transitions, Layers, and Input Events

When you load the .pb files into the Winscope UI, you are presented with several synchronized panels.

The Timeline

The bottom of the screen shows a timeline. Scrubbing through this timeline updates all other panels to reflect the exact state of the system at that timestamp. This is invaluable for analyzing animations frame by frame.

SurfaceFlinger Layers

The "Layers" view shows the hierarchical tree of all surfaces currently known to SurfaceFlinger.

• Z-Order: You can see exactly which layer is on top. If a window is invisible, it might be behind another layer, or its alpha might be set to 0.
• Buffer Size & Crop: You can inspect the exact dimensions of the buffer being drawn and any crop rectangles applied. This is critical for debugging UI elements that are cut off or scaled incorrectly.
• Composition Type: Indicates whether a layer was composited by the GPU (Client) or the display hardware (Device). Hardware composition is much more power efficient.

WindowManager State

The "Windows" view shows the logical hierarchy of windows as seen by the system server.

• Focus: You can clearly see which window currently holds input focus.
• Visibility: Sometimes a window is "visible" in WindowManager but has no corresponding layer in SurfaceFlinger because the app hasn't submitted a buffer yet (resulting in a black screen).
• Configuration: Inspect the exact bounds, insets (status bar/navigation bar), and rotation applied to the window.

Screen Recording Integration

Winscope allows you to record a video of the screen while capturing the trace. When you load both into the UI, scrubbing the timeline also scrubs the video. This makes it incredibly easy to correlate a visual glitch with the underlying layer state.

Diagnosing Jank and Display Issues

Winscope is usually used in conjunction with Perfetto to diagnose complex UI issues.

Scenario: Black Screen During Activity Transition

1. Record a trace with WindowManager and SurfaceFlinger tracing enabled.
2. Scrub to the exact frame where the screen is black.
3. Check the WindowManager hierarchy: Is the target Activity marked as visible? Does it have a valid window?
4. If yes, check the SurfaceFlinger layers: Does the layer exist? If the layer exists but has no buffer, the app's UI thread is likely blocked and hasn't called draw yet (use Perfetto to find out why). If the layer doesn't exist, there is a bug in the WindowManager to SurfaceFlinger communication.

Scenario: Touch Event Ignored

1. Record an input trace and a WindowManager trace.
2. Look at the input event in the timeline.
3. Check the WindowManager state at that exact moment: Which window has focus? Is there a transparent overlay window absorbing the touch event before it reaches your application? Winscope's layer view will visually highlight the touchable region of every window.

By providing a visual and structural snapshot of the display pipeline, Winscope removes the guesswork from debugging complex Android UI interactions.