site/docs/dev/tools/debugger.md - skia - Git at Google

 ---
 title: 'Skia Debugger'
 linkTitle: 'Skia Debugger'
 ---

 ## Introduction

 The Skia Debugger is a graphical tool used to step through and analyze the
 contents of the Skia picture format. The tool is available online at
 [https://debugger.skia.org](https://debugger.skia.org/) or can be run locally.

 Features:

 - Draw command and multiple frame playback
 - Shows the current clip and matrix at any step
 - Zoomed viewer with crosshair for selecting pixels.
 - Breakpoints that stop playback when a pixel's color changes.
 - GPU or CPU backed execution.
 - GPU op bounds visualization
 - Android offscreen layer visualization
 - Shared resource viewer

 <img src="../onlinedebugger.png" style="display: inline-block;" />

 ## User Guide

 SKP files can contain a single frame or multiple frames. Single frame files have
 the .skp extension and Multi-frame files have the .mskp extension. In the online
 debugger linked above, Open a [sample mskp file](/docs/dev/tools/calendar.mskp)
 or capture one from an android device using the
 [instructions here](https://sites.google.com/a/google.com/skia/android/skp-from-framework).

 ### Command Playback and Filters

 Try playing back the commands within the current frame using the lower play
 button <img src="../playcommands.png" style="display: inline-block;" />, (the
 one not in a circle) You should see the image built up one draw at a time.

 Many commands manipulate the matrix or clip but don't make any visible change
 when run. Try filtering these out by pasting
 `!drawannotation save restore concat setmatrix cliprect` in to the filter
 textbox just below the command playback controls. Press enter to apply the
 filter, and resume playback if it was paused. This will have the effect of
 making the playback appear to be much faster as there are only 29 commands in
 the first frame of the sample file that pass this filter.

 Try pausing command playback and stepping forward and back through the commands
 using `,` (comma) and `.` (period).

 > Filters are case insensitive, and the only supported logical operator is !
 > (not) which applies to the entire filter and is only recognised when it occurs
 > at the beginning.

 Any command can be expanded using the
 <img src="../expand.png" style="display: inline-block;" /> icon to see all of
 the parameters that were recorded with that command.

 Commands can be disabled or enabled with the checkbox that becomes available
 after expanding the command's detail view.

 Jog the command playhead to the end of the list with the
 <img src="../end.png" style="display: inline-block;" /> button.

 ### Frame playback

 <img src="../frameplayback.png" style="display: inline-block;" />

 The sample file contains multiple frames. Use the encircled play button to play
 back the frames. The current frame is indictated by the slider position, and the
 slider can be set manually. Frames can be stepped through with `w` (back) and
 `s` forward. `p` pauses or unpauses the frame playback.

 Not all frames in a file will have the same number of commands. When the command
 playhead is left at the end of the list the debugger will play every frame to
 the end of its list. If the command playhead is somewhere in the middle, say
 155, the debugger will try to play every frame to its 155th command.

 ### Resources Tab

 <img src="../resources.png" style="display: inline-block;" />

 Any resources that were referenced by commands in the file appear here. As of
 Dec 2019, this only shows images.

 Any resource can be selected and viewed. You may find it helpful to toggle the
 Light/Dark setting if you cannot see an image.

 Images' names are formatted as `7 @24205864 (99, 99)` where `7` is the index of
 the image as it was saved in the file, `@24205864` is it's address in wasm
 memory, for cross referencing with DrawImage\* commands in the command list
 which also show this address, and `(99, 99)` is the size of the image.

 The resource viewer allows a user to determine if an image was not effectively
 shared between frames or draw commands. If it occurs more than once in the
 resource tab, then there were multiple copies of it with different generation
 ids in the process that recorded the SKP.

 ### Android Layers

 <img src="../layers.png" style="display: inline-block;" />

 When MSKPs are recorded in Android, Extra information about offscreen hardware
 layers is recorded. The sample google calendar mskp linked above contains this
 information. You will find two layers on frame 3.

 There are two kinds of events relevant to recorded android layer use.

 1. Draw Events - points when an offscreen surface was drawn to. They may be
    complete, meaning the clip equalled the surface's size, or partial, meaning
    the clip was smaller.
 2. Use events - points when the offscreen surface was used as an SkImage in the
    main surface.

 Layers are shown as boxes in the bottom right of the interface when viewing a
 frame where a layer draw event occurred. Each Layer box has two buttons:
 `Show Use` will cycle through use events for that layer in the current frame if
 there are any, and `Inspector` will open the draw event as if it were a single
 frame SKP. you can play back it's commands, enable or disabled them, inspect GPU
 op bounds or anything else you could do with an ordinary SKP. Exit the inspector
 by clicking the `Exit` button on the layer box.

 ### Crosshair and Breakpoints

 <img src="../crosshair.png" style="display: inline-block;" />

 Clicking any point in the main view will toggle a red crosshair for selecting
 pixels. the selected pixel's color is shown in several formats on the right
 pane. A zoomed view centered on the selected pixel is shown below it. The
 position can be moved precicely by either clicking neighboring pixels in the
 zoom view, or using `H` (left) `L` (right) `J` (down) `K` (up).

 When "Break on change" is selected, command playback will pause on any command
 which changes the color of the selected pixel. this can be used to find the
 command that draws something you see in the viewer.

 ### GPU Op Bounds and Other settings

 <img src="../settings.png" style="display: inline-block;" />

 Each of the filtered commands from above has a colored number to its right
 <img src="../gpuop.png" style="display: inline-block;" />. This is the GPU
 operation id. When multiple commands share a GPU op id, this indicates that they
 were batched together when sent to the GPU. In the WASM debugger, this goes
 though WebGL.

 There is a "Display GPU Op Bounds" toggle in the upper right of the interface.
 Turning this on will show a colored rectangle to represent the bounds of the GPU
 op of the currently selected command.

 GPU - Controls which backend Skia uses to draw to the screen. GPU in the online
 wasm debugger means WebGL. CPU means skia draws into a surface in memory which
 is copied into an HTML canvas without using the GPU.

 Light/Dark - this toggle changes the appearance of the checkerboard behind the
 main view and zoom views to assist in viewing content with transparency.

 Display Overdraw Viz - This vizualization shows a red overlay that is darker in
 propertion to how much overdraw has occurred on a pixel. Overdraw meaning that
 the pixel was drawn to more than once.

 - As of Dec 2019, this feature may not be working correctly.

 ### Image fit and download buttons.

 <img src="../settings.png" style="display: inline-block;" />

 These buttons resize the main view. they are, from left to right:

 Original size - the natural size of the canvas, when it was recorded. Fit to
 page - shrink enough that the whole canvas fits in the center pane. Fit to page
 width - make the canvas fit horizontally but allow scrolling vertically Fit to
 page height - make the canvas fit vertically but allow scrolling horizontally.

 next to these is a 5th, unrelated download button which saves the current canvas
 as a PNG file.

 ## Building and running locally

 Begin by following the instructions to
 [download and build Skia](/docs/user/build). Next, you'll need Skia's infrastructure repository,
 which can be downloaded with

 <!--?prettify lang=sh?-->
     git clone https://skia.googlesource.com/buildbot

 See further instructions in buildbot/debugger-app/README.md.
	---
	title: 'Skia Debugger'
	linkTitle: 'Skia Debugger'
	---

	## Introduction

	The Skia Debugger is a graphical tool used to step through and analyze the
	contents of the Skia picture format. The tool is available online at
	[https://debugger.skia.org](https://debugger.skia.org/) or can be run locally.

	Features:

	- Draw command and multiple frame playback
	- Shows the current clip and matrix at any step
	- Zoomed viewer with crosshair for selecting pixels.
	- Breakpoints that stop playback when a pixel's color changes.
	- GPU or CPU backed execution.
	- GPU op bounds visualization
	- Android offscreen layer visualization
	- Shared resource viewer

	<img src="../onlinedebugger.png" style="display: inline-block;" />

	## User Guide

	SKP files can contain a single frame or multiple frames. Single frame files have
	the .skp extension and Multi-frame files have the .mskp extension. In the online
	debugger linked above, Open a [sample mskp file](/docs/dev/tools/calendar.mskp)
	or capture one from an android device using the
	[instructions here](https://sites.google.com/a/google.com/skia/android/skp-from-framework).

	### Command Playback and Filters

	Try playing back the commands within the current frame using the lower play
	button <img src="../playcommands.png" style="display: inline-block;" />, (the
	one not in a circle) You should see the image built up one draw at a time.

	Many commands manipulate the matrix or clip but don't make any visible change
	when run. Try filtering these out by pasting
	`!drawannotation save restore concat setmatrix cliprect` in to the filter
	textbox just below the command playback controls. Press enter to apply the
	filter, and resume playback if it was paused. This will have the effect of
	making the playback appear to be much faster as there are only 29 commands in
	the first frame of the sample file that pass this filter.

	Try pausing command playback and stepping forward and back through the commands
	using `,` (comma) and `.` (period).

	> Filters are case insensitive, and the only supported logical operator is !
	> (not) which applies to the entire filter and is only recognised when it occurs
	> at the beginning.

	Any command can be expanded using the
	<img src="../expand.png" style="display: inline-block;" /> icon to see all of
	the parameters that were recorded with that command.

	Commands can be disabled or enabled with the checkbox that becomes available
	after expanding the command's detail view.

	Jog the command playhead to the end of the list with the
	<img src="../end.png" style="display: inline-block;" /> button.

	### Frame playback

	<img src="../frameplayback.png" style="display: inline-block;" />

	The sample file contains multiple frames. Use the encircled play button to play
	back the frames. The current frame is indictated by the slider position, and the
	slider can be set manually. Frames can be stepped through with `w` (back) and
	`s` forward. `p` pauses or unpauses the frame playback.

	Not all frames in a file will have the same number of commands. When the command
	playhead is left at the end of the list the debugger will play every frame to
	the end of its list. If the command playhead is somewhere in the middle, say
	155, the debugger will try to play every frame to its 155th command.

	### Resources Tab

	<img src="../resources.png" style="display: inline-block;" />

	Any resources that were referenced by commands in the file appear here. As of
	Dec 2019, this only shows images.

	Any resource can be selected and viewed. You may find it helpful to toggle the
	Light/Dark setting if you cannot see an image.

	Images' names are formatted as `7 @24205864 (99, 99)` where `7` is the index of
	the image as it was saved in the file, `@24205864` is it's address in wasm
	memory, for cross referencing with DrawImage\* commands in the command list
	which also show this address, and `(99, 99)` is the size of the image.

	The resource viewer allows a user to determine if an image was not effectively
	shared between frames or draw commands. If it occurs more than once in the
	resource tab, then there were multiple copies of it with different generation
	ids in the process that recorded the SKP.

	### Android Layers

	<img src="../layers.png" style="display: inline-block;" />

	When MSKPs are recorded in Android, Extra information about offscreen hardware
	layers is recorded. The sample google calendar mskp linked above contains this
	information. You will find two layers on frame 3.

	There are two kinds of events relevant to recorded android layer use.

	1. Draw Events - points when an offscreen surface was drawn to. They may be
	complete, meaning the clip equalled the surface's size, or partial, meaning
	the clip was smaller.
	2. Use events - points when the offscreen surface was used as an SkImage in the
	main surface.

	Layers are shown as boxes in the bottom right of the interface when viewing a
	frame where a layer draw event occurred. Each Layer box has two buttons:
	`Show Use` will cycle through use events for that layer in the current frame if
	there are any, and `Inspector` will open the draw event as if it were a single
	frame SKP. you can play back it's commands, enable or disabled them, inspect GPU
	op bounds or anything else you could do with an ordinary SKP. Exit the inspector
	by clicking the `Exit` button on the layer box.

	### Crosshair and Breakpoints

	<img src="../crosshair.png" style="display: inline-block;" />

	Clicking any point in the main view will toggle a red crosshair for selecting
	pixels. the selected pixel's color is shown in several formats on the right
	pane. A zoomed view centered on the selected pixel is shown below it. The
	position can be moved precicely by either clicking neighboring pixels in the
	zoom view, or using `H` (left) `L` (right) `J` (down) `K` (up).

	When "Break on change" is selected, command playback will pause on any command
	which changes the color of the selected pixel. this can be used to find the
	command that draws something you see in the viewer.

	### GPU Op Bounds and Other settings

	<img src="../settings.png" style="display: inline-block;" />

	Each of the filtered commands from above has a colored number to its right
	<img src="../gpuop.png" style="display: inline-block;" />. This is the GPU
	operation id. When multiple commands share a GPU op id, this indicates that they
	were batched together when sent to the GPU. In the WASM debugger, this goes
	though WebGL.

	There is a "Display GPU Op Bounds" toggle in the upper right of the interface.
	Turning this on will show a colored rectangle to represent the bounds of the GPU
	op of the currently selected command.

	GPU - Controls which backend Skia uses to draw to the screen. GPU in the online
	wasm debugger means WebGL. CPU means skia draws into a surface in memory which
	is copied into an HTML canvas without using the GPU.

	Light/Dark - this toggle changes the appearance of the checkerboard behind the
	main view and zoom views to assist in viewing content with transparency.

	Display Overdraw Viz - This vizualization shows a red overlay that is darker in
	propertion to how much overdraw has occurred on a pixel. Overdraw meaning that
	the pixel was drawn to more than once.

	- As of Dec 2019, this feature may not be working correctly.

	### Image fit and download buttons.

	<img src="../settings.png" style="display: inline-block;" />

	These buttons resize the main view. they are, from left to right:

	Original size - the natural size of the canvas, when it was recorded. Fit to
	page - shrink enough that the whole canvas fits in the center pane. Fit to page
	width - make the canvas fit horizontally but allow scrolling vertically Fit to
	page height - make the canvas fit vertically but allow scrolling horizontally.

	next to these is a 5th, unrelated download button which saves the current canvas
	as a PNG file.

	## Building and running locally

	Begin by following the instructions to
	[download and build Skia](/docs/user/build). Next, you'll need Skia's infrastructure repository,
	which can be downloaded with

	<!--?prettify lang=sh?-->
	git clone https://skia.googlesource.com/buildbot

	See further instructions in buildbot/debugger-app/README.md.