docs: GL Tracer, Device Monitor Tools for SDK r20

Change-Id: Ib45210b88a7eb93e3bba4f7d535f344ccb054a72

2 files changed, 127 insertions, 0 deletions

diff --git a/docs/html/tools/help/gltracer.jd b/docs/html/tools/help/gltracer.jd
new file mode 100644
index 0000000..35c405e
--- /dev/null
+++ b/docs/html/tools/help/gltracer.jd
@@ -0,0 +1,103 @@
+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
diff --git a/docs/html/tools/help/monitor.jd b/docs/html/tools/help/monitor.jd
new file mode 100644
index 0000000..8e2ea36
--- /dev/null
+++ b/docs/html/tools/help/monitor.jd
@@ -0,0 +1,24 @@
+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>