Merge "docs: GL Tracer, Device Monitor Tools for SDK r20" into jb-dev

page.title=Tracer for OpenGL ES

@jd:body

<div id="qv-wrapper">

<div id="qv">

  <h2>In this document</h2>

  <ol>

    <li><a href="running">Running Tracer</a></li>

    <li><a href="generating">Generating a Trace</a></li>

    <li><a href="analyzing">Analyzing a Trace</a></li>

  </ol>

  <h2>See also</h2>

  <ol>

    <li><a href="{@docRoot}tools/index.html">Tools</a></li>

  </ol>

</div>

</div>

<p>Tracer is a tool for analyzing OpenGL for Embedded Systems (ES) code in your Android application.

The tool allows you to capture OpenGL ES commands and frame by frame images to help you understand

how your graphics commands are being executed.</p>

<p class="note"><strong>Note:</strong> The Tracer tool requires a device running Android 4.1 (API

Level 16) or higher.</p>

<h2 id="running">Running Tracer</h2>

<p>Tracer can be run as part of the Eclipse Android Development Tools (ADT) plugin or as part of the

Device Monitor tool.</p>

<p>To run Tracer in Eclipse:</p>

<ol>

  <li>Start Eclipse and open a workspace that contains an Android project.</li>

  <li>Activate the perspective for Tracer by choosing <strong>Window > Open Perspective >

Other...</strong></li>

  <li>Select <strong>Tracer for OpenGL ES</strong> and click <strong>OK</strong>.</li>

</ol>

<p>To run Tracer in Device Monitor:</p>

<ol>

  <li>Start the <a href="monitor.html">Device Monitor</a> tool.</li>

  <li>Activate the perspective for Tracer by choosing <strong>Window > Open

Perspective...</strong></li>

  <li>Select <strong>Tracer for OpenGL ES</strong> and click <strong>OK</strong>.</li>

</ol>

<h2 id="generating">Generating a Trace</h2>

<p>Tracer captures OpenGL ES command execution logs and can also capture progressive images of the

frames generated by those commands to enable you to perform logical and visual analysis of your

OpenGL ES code. The Tracer tool operates by connecting to a device running Android 4.1 (API Level

16) or higher that is running the application you want to analyze. The Tracer tool captures trace

information while the application is running and saves it to a {@code .gltrace} file for

analysis.</p>

<img src="{@docRoot}images/gltracer/dialog-trace.png">

<p class="img-caption"><strong>Figure 1.</strong> Trace capture dialog box.</p>

<p>To capture an OpenGL ES trace for an Android application:</p>

<ol>

  <li>Connect the Android device using a USB cable and make sure it is enabled for debugging. For

more information, see <a href="{@docRoot}tools/device.html">Using Hardware Devices</a>.</li>

  <li>In Eclipse or Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>

perspective.</li>

  <li>On the toolbar, click the trace capture button (<img

src="{@docRoot}images/gltracer/icon-capture.png">).</li>

  <li>In the dialog box, select the <strong>Device</strong> to use for the trace.</li>

  <li>In the <strong>Application Package</strong> field, enter the full application package name

containing the activity you want to trace, for example: {@code com.example.android.opengl}</li>

  <li>In the <strong>Activity to launch</strong> field, enter the class name of the activity you

want to trace, for example: {@code OpenGLES20Complete}

  <p class="note"><strong>Note:</strong> If you are tracing the default activity for the

application, you can leave this field blank.</p>

  </li>

  <li>Select the desired <strong>Data Collection Options</strong>.

    <p class="note"><strong>Note:</strong> If you want to capture progressive frame images for each

drawing call, enable the <strong>Read back currently bound framebuffer on glDraw*()</strong> option.

Be aware that using this option can result in large trace files.</p>

  </li>

  <li>Enter a <strong>Destination File</strong> for the trace output.</li>

  <li>Click <strong>Trace</strong> to start the trace capture.</li>

  <li>On the connected device, exercise the functions of your application you want to trace.</li>

  <li>In the dialog box, <strong>Stop Tracing</strong> to complete the tracing run.</li>

</ol>

<h2 id="analyzing">Analyzing a Trace</h2>

<p>After you have generated a trace, you can load it for review and analysis.</p>

<p>To review a captured trace:</p>

<ol>

  <li>In Eclipse or Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>

perspective.</li>

  <li>On the toolbar, click the trace load button (<img

src="{@docRoot}images/gltracer/icon-load-trace.png">).</li>

  <li>After loading a trace, select a frame and review the OpenGL ES calls. Drawing commands are

highlighted in blue.</li>

</ol>

 No newline at end of file

page.title=Debug Monitor

@jd:body

<p>Android Debug Monitor is a stand-alone tool that provides a graphical user interface for

several Android application debugging and analysis tools. The Monitor tool does not

require installation of a integrated development environment, such as Eclipse, and encapsulates the

following tools:</p>

<ul>

  <li><a href="{@docRoot}tools/debugging/ddms.html">DDMS</a></li>

  <li><a href="gltracer.html">Tracer for OpenGL ES</a></li>

  <li><a href="hierarchy-viewer.html">Hierarchy Viewer</a></li>

  <li><a href="traceview.html">Traceview</a></li>

  <li>Pixel Perfect magnification viewer</li>

</ul>

<h2 id="usage">Usage</h2>

<p>To start Debug Monitor, enter the following command from the SDK <code>tools/</code>

directory:</p>

  <pre>monitor</pre>

<p>Start an Android emulator or connect an Android device via USB cable, and connect the Debug

Monitor to the device by selecting it in the <strong>Devices</strong> window.</p>