diff options
Diffstat (limited to 'docs/html/tools/performance/hierarchy-viewer')
3 files changed, 588 insertions, 0 deletions
diff --git a/docs/html/tools/performance/hierarchy-viewer/index.jd b/docs/html/tools/performance/hierarchy-viewer/index.jd new file mode 100644 index 0000000..ebf23e5 --- /dev/null +++ b/docs/html/tools/performance/hierarchy-viewer/index.jd @@ -0,0 +1,330 @@ +page.title=Hierarchy Viewer Walkthrough +meta.tags="android, performance, profiling, tools, rendering, hierarchyviewer" +page.tags="android", "performance", "profiling", "tools", "rendering", "hierarchyviewer" +page.metaDescription=Visualize your app's view hierarchy to help you simplify your layouts. +page.image=tools/performance/thumbnails/tools_hierarchy_viewer.png +page.article=true + +@jd:body + +<style> + .no-bullet { + list-style-type: none; + } + .padded { + padding-left: 10px; + } +</style> + +<div id="tb" style="margin-left: 7px; margin-bottom: 5px;"> + +<h2>In this document</h2> +<ul> + <li><a href="#WhatYouNeed">Prerequisites</a></li> + <li><a href="#WorkingWithHierarchyViewer">Working with Hierarchy Viewer</a></li> +</ul> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}tools/performance/hierarchy-viewer/setup.html"> + Device Setup for Hierarchy Viewer</a></li> + <li><a href="{@docRoot}tools/performance/hierarchy-viewer/profiling.html"> + Profiling with Hierarchy Viewer</a></li> + <li><a href= + "http://developer.android.com/tools/debugging/debugging-ui.html#viewhierarchy">Hierarchy Viewer + </a></li> + <li><a href="/guide/topics/ui/overview.html#Layout">View Hierarchies</a></li> + <li><a href="{@docRoot}tools/performance/importing-legacy-apps.html"> + Importing Legacy Apps into Android Studio<a></li> + <li><a href="{@docRoot}tools/device.html">Using Hardware Devices</a></li> +</ul> + +</div> + + <p>This walkthrough shows the basic usage and workflow for the Hierarchy Viewer tool.</p> + + <p>The Hierarchy Viewer tool visualizes your app's <a href= + "http://developer.android.com/guide/topics/ui/overview.html#Layout">view hierarchy</a> and + profiles the relative rendering speed for each view. + + <p>What it's good for:</p> + + <ul> + <li>Simplifying your view hierarchy to reduce overdraw, and make it easier to manage.</li> + + <li>Finding potential rendering performance bottlenecks related to the structure and shape of your + view hierarchy.</li> + </ul> + + <h2 id="WhatYouNeed">Prerequisites</h2> + + <ul> + <li>A mobile device set up to work with Hierarchy Viewer:</li> + + <li style="list-style: none; display: inline"> + <ol> + <li>You must have <a href= + "http://developer.android.com/tools/device.html#developer-device-options">Developer + Options</a> enabled on your mobile device. You must use a physical device to get + accurate measurements.</li> + + <li>Set an {@code ANDROID_HVPROTO} environment variable on the desktop machine + that is connected to your device. For more information, see + <a href="{@docRoot}tools/performance/hierarchy-viewer/setup.html">Device Setup for Hierarchy Viewer</a>.</li> + </ol> + </li> + + <li>Debuggable app code with a view hierarchy. Use your own code, or the code for the <a href= + "https://github.com/udacity/Sunshine-Version-2">Sunshine</a> sample app from the <a href= + "https://www.udacity.com/course/ud853">Android Fundamentals Udacity course</a>.</li> + </ul> + + <h2 id="WorkingWithHierarchyViewer">Working with Hierarchy Viewer</h2> + +<ul class="no-bullet"> +<!-- this also hides bullet, by default outside box --> + <li><div style="overflow:hidden"> + <ol class="padded"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image001.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 1. </strong>Starting Android Device Monitor. + </p> + </div> + + <li>Connect your mobile device to your computer.</li> + + <li>Open your application in Android Studio, build the source, and run it on your device.</li> + + <li>From Android Studio, start the Android Device Monitor: <b>Tools > Android > + Android Device Monitor</b>.</li> + + <li>Allow <b>USB Debugging</b> on your phone (if asked).</li> + +</ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="6"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image005.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 2. </strong>Android Device Monitor. + </p> + </div> + + <li>Figure 2 illustrates what is initially shown in the Device Monitor tool. This varies + depending on your setup. + <p>Make sure your device + and the package for your application are showing in the Devices (DDMS mode) or Windows + (Hierarchy Viewer mode) tab. You can choose <b>Window > Reset Perspective</b> to get + back to the default arrangement.</p> + <p>If the app does not appear, make sure you + followed the <a href="{@docRoot}tools/performance/hierarchy-viewer/setup.html"> device + setup instructions</a>, then start over at step 1.</p></li> + +</ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="7"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image002.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 3. </strong>Changing Perspective to Hierarchy Viewer. + </p> + </div> + + <li>In Android Device Monitor (ADM), in the menu bar, choose <b>Window > Open + Perspective</b>, and in the popup click <b>Hierarchy View</b>.<br> + + <p>OR</p> + <p> Click the <b>Hierarchy View</b> button if it's already visible.<br> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image003.png"> + </p></li> + +</ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="9"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image006.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 4. </strong>Hierarchy Viewer layout. + </p> + </div> + + <li>If not already open, the Hierarchy View panes open.<br> + The example screen in Figure 4 shows an example of these panes.</li> + + </ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="10"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image004.png" + alt="" + width="240px" /> + <p class="img-caption"> + <strong>Figure 5. </strong>Resetting the Perspective. + </p> + </div> + + <li>If you see a different window arrangement, in Android Device Manager, use + <b>Window > Reset Perspective</b> to return to the default layout for this tutorial. + + </ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="11"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image007.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 6. </strong>Populated Hierarchy Viewer. + </p> + </div> + + <li>Double-click your application in the Windows tab. This populates the panes with the + view hierarchy of your application. + This display is a static representation of the complete view hierarchy defined for the + app.</li> + + <li>You can adjust the sizes of the panes and ADM will preserve your + arrangement in future sessions.</li> + + </ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="13"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image008.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 7. </strong>Hierarchy Viewer panes. + </p> + </div> + + <li>If necessary, click the <b>Layout View</b> tab to hide the Console and show a wireframe of + your layout. The outline of the currently selected view is red. Click an outline to select + it.</li> + + <li>The rest of the panes: + + <ul> + <li>The <b>Tree Overview</b> in the upper right gives you a bird's-eye view of your + app's complete <a href= + "http://developer.android.com/guide/topics/ui/overview.html#Layout">View</a> <a href= + "http://developer.android.com/guide/topics/ui/overview.html#Layout">Hierarchy</a>.</li> + + <li>In the <b>Tree Overview</b>, move the gray viewport rectangle to change what section of + your hierarchy shows in the <b>Tree View</b> pane (in the center).</li> + + <li>In the <b>Tree View</b>, you can drag and zoom the tree using your mouse.</li> + </ul> + </ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="15"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image009.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 7. </strong>Parts of the View node display. + </p> + </div> + + <li>Click on a View node to display details. Here is an annotated close-up of a node + and its details.</li> + + + </ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="16"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image010.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 8. </strong>Location of View Properties tab. + </p> + </div> + + <li>Click the <b>View Properties</b> tab at the top right (next to the Windows tab) to see + properties of the selected View node.</li> + + </ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="17"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image011.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 9. </strong>Rendering a view in a popup. + </p> + </div> + + <li>Double-click a View node in the Tree View to render it in a popup window.</li> + + </ol> +</div></li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="18"> + + <div class="figure" style=""> + <img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image012.png" + alt="" + width="240px" /> + <p class="img-caption"> + <strong>Figure 10. </strong>Node with its type and id. + </p> + </div> + + <li>Nodes in the Tree View show a Type, which indicates the View class, + and an id, which is the view identifier in your code.</li> + + </ol> +</div></li> +</ul> diff --git a/docs/html/tools/performance/hierarchy-viewer/profiling.jd b/docs/html/tools/performance/hierarchy-viewer/profiling.jd new file mode 100644 index 0000000..b505228 --- /dev/null +++ b/docs/html/tools/performance/hierarchy-viewer/profiling.jd @@ -0,0 +1,169 @@ +page.title=Profiling with Hierarchy Viewer +meta.tags="android, performance, profiling, tools, rendering, hierarchyviewer +page.tags="android", "performance", "profiling", "tools", "rendering", "hierarchyviewer" +page.metaDescription=Profile the relative rendering speed for each view. +page.image=tools/performance/thumbnails/tools_hierarchy_viewer_profiling.png +page.article=true + +@jd:body + +<style> + .no-bullet { + list-style-type: none; + } + .padded { + padding-left: 10px; + } +</style> + +<div id="tb" style="margin-left: 7px; margin-bottom: 5px;"> + +<h2>In this document</h2> +<ul> + <li><a href="#WhatYouNeed">Prerequisites</a></li> + <li><a href="#ProfilingWithHierarchyViewer">Profiling with Hierarchy Viewer</a></li> + <li><a href="#InterpretingResults">Interpreting Profiling Results</a></li> + +</ul> +</div> + +<p>This walkthrough shows you how to profile your app's view hiearchy with + Hierarchy Viewer, and how to interpret the results.</p> + +<h2 id="WhatYouNeed">Prerequisites</h2> + +<ul> + <li><a href="{@docRoot}tools/performance/hierarchy-viewer/setup.html"> + Device Setup for Hierarchy Viewer</a></li> + <li><a href="{@docRoot}tools/performance/hierarchy-viewer/index.html"> + Hierarchy Viewer Walkthrough</a></li> +</ul> + +<h2 id="ProfilingWithHierarchyViewer">Profiling Steps</h2> + +<ul class="no-bullet"> +<!-- this also hides bullet, by default outside box --> + <li><div style="overflow:hidden"> + + <ol class="padded"> + + <div class="figure" style=""> +<img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image014.png" + alt="" + width="400px" /> + <p class="img-caption"> + <strong>Figure 1. </strong>View hierarchy after profiling. + </p> + </div> + + <li>Start Hierarchy Viewer for your app.</li> + + <li>In the <b>Tree View</b> or the <b>Layout View</b>, click on the View node whose + children you want to profile.</li> + + <li>To start profiling, click the small button with three circles +<img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image013.png"> + at the top of the Tree View. + + </li> + + <li>For large view hierarchies, profiling may take a few seconds.</li> + + <li>Each view in your subtree gets three dots, which can be green, yellow, or red. + + <ul> + <li>The left dot represents the Draw Process of the rendering pipeline.</li> + <li>The middle dot represents the Layout Phase.</li> + <li>The right dot represents the Execute Phase.</li> + </ul> + </li> + +</ol></div> + +</li> + +<li><div style="overflow:hidden"> +<hr> + <ol class="padded" start="5"> + + <div class="figure" style=""> +<img src="{@docRoot}images/tools/performance/hierarchy-viewer/gettingstarted_image015.png" + alt="" + width="240px" /> + <p class="img-caption"> + <strong>Figure 2. </strong>How the colored dots relate<br>to the rendering pipeline. + </p> + </div> + + <li>These dots roughly correspond to the Measure, + Layout, and Draw + phases of the processing pipeline.</li> + + <li>The color of the dots indicates the relative performance + of this node in respect to all other profiled nodes. + + <ul> + <li><strong>Green</strong> means the view renders faster than at least + half of the other views.</li> + + <li><strong>Yellow</strong> means the view renders faster than the bottom + half of the other views.</li> + + <li><strong>Red</strong> means the view is among the slowest + half of views.</li> + </ul> + </li> + + </ol> +</div></li> +</ul> + + <h2 id="InterpretingResults">Interpreting Hierarchy Viewer Profiling Results</h2> + + <p>Hierarchy Viewer measures the <em>relative performance</em> of a + node</b>, so there are always red nodes in a profile, and it + doesn't necessarily mean that view is too slow for the users of + your app.</p> + + <p>Hierarchy Viewer software rasterizes your Activity to acquire the timing + information. Rasterization is the process of taking a high-level primitive, such as a + circle or a vector font, and turning it into pixels on the screen. Typically, + rasterization is done by the GPU on your device, but in the case of + software rasterization, rendering is done on the CPU with + ordinary software. This means that the absolute + reported timings are correct relative to each other, but are bloated and vary + depending on the overall and changing CPU workload on your device and PC. Profile + several times to get a feel for the average measurements.</p> + + <p>The following are guidelines for interpreting Hierarchy Viewer profiling output.</p> + + <p>A red node is a potential problem in any situation where your app has + unexpectedly slow performance. In a relative setting, there is always a + slowest node; make sure it is the node you expect. + The following examples illustrate how to interpret red dots.</p> + + <ul> + <li>Look for red dots in leaf nodes or view groups with only a few children. This + might point to a problem. Your app may not be slow, or it may not be slow on your + device, but you need to be aware of why that dot is red. + <a href="{@docRoot}tools/performance/systrace/index.html"> Systrace</a> or + <a href="{@docRoot}tools/performance/traceview/index.html"> Traceview</a> + can give you additional information. </li> + + <li>If you have a view group with many children and a red measure phase, take a + look at the children to see how they are performing.</li> + + <li>A view with yellow or even red dots might not be performing slowly on the + device. That's where the actual numbers are helpful. + <a href="{@docRoot}tools/performance/systrace/index.html"> Systrace</a> or + <a href="{@docRoot}tools/performance/traceview/index.html"> Traceview</a> + can give you additional information.</li> + + <li>If the root view of a hierarchy has a red measure phase, red layout phase, and + yellow draw phase, this is somewhat typical, because it's the + parent of all the other views.</li> + + <li>If a leaf node in a tree with 20+ views has a red draw phase, this <i>is</i> a + problem. Check your OnDraw method for code that shouldn't be + there.</li> + </ul> diff --git a/docs/html/tools/performance/hierarchy-viewer/setup.jd b/docs/html/tools/performance/hierarchy-viewer/setup.jd new file mode 100644 index 0000000..aaac1ca --- /dev/null +++ b/docs/html/tools/performance/hierarchy-viewer/setup.jd @@ -0,0 +1,89 @@ +page.title=Device Setup for Hierarchy Viewer +meta.tags="android, performance, profiling, tools, rendering, hierarchyviewer" +page.tags="android", "performance", "profiling", "tools", "rendering", "hierarchyviewer" +page.metaDescription=Set up your mobile device to work with Hierarchy Viewer. +page.image=tools/performance/thumbnails/tools_hierarchy_viewer.png +page.article=true + +@jd:body + +<div id="tb" style="margin-left: 7px; margin-bottom: 5px;"> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}tools/performance/hierarchy-viewer/index.html"> + Hierarchy Viewer Walkthrough</a></li> + <li><a href="{@docRoot}tools/performance/hierarchy-viewer/profiling.html"> + Profiling with Hierarchy Viewer</a></li> +</ul> + +</div> + + <p>To run Hierarchy Viewer, you must enable Developer Options on your mobile device and perform + some setup on your computer.</p> + + <h2>Configuring Devices</h2> + + <ol> + <li><p>Enable <a href= + "http://developer.android.com/tools/device.html#developer-device-options">Developer Options</a> + on your mobile device.</p></li> + + <li>Depending on the type of device you have, do one of the following: + <ul> + <li>If you have a locked device running Android 4.0 or lower, follow the instructions + for <a href= + "https://github.com/romainguy/ViewServer">installing and configuring ViewServer</a>. + </li> + <li>If you have an unlocked device running Android 4.0 or lower, + no further configuration is needed.</li> + <li>If you have a device running Android 4.1 or higher, you must set an environment + variable on your development machine. For more information, + see <a href="#hvproto-variable">Setting the ANDROID_HVPROTO variable</a> + </ul> + </li> + </ol> + + + <h2 id="hvproto-variable">Setting the ANDROID_HVPROTO variable</h2> + + <h3>Windows</h3> + + <ol> + <li>Click <b>My Computer > Property > Advanced > Environment Variables.</b></li> + + <li>Click <b>New.</b></li> + + <li>In variables name put: <code>ANDROID_HVPROTO</code></li> + + <li>In variable value put: <code>ddm</code></li> + + <li>Click <b>OK</b><./li> + </ol> + + <h3>Mac</h3> + + <ol> + <li>Edit <code>~/.bash_profile</code></li> + + <li>Add: + <br><code>#Hierarchy Viewer Variable + <br>export ANDROID_HVPROTO=ddm</code> + </li> + + <li><code>source ~/.bash_profile</code></li> + </ol> + + <h3>Linux</h3> + + <ol> + <li>Edit <code>~/.bash_profile</code></li> + + <li>Add: + + <br><code>#Hierarchy Viewer Variable + <br>export ANDROID_HVPROTO=ddm</code> + </li> + + <li><code>source ~/.bash_profile</code></li> + </ol> |