Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am e11744fe: am 4a6d5c93: Docs: Sample-walkthrough chapters for NDK documentation

Browse Source 
* commit 'e11744fefdb1678dc369a7fea5aaaf0a290fb697':
  Docs: Sample-walkthrough chapters for NDK documentation
This commit is contained in:
David Friedman
2015-05-26 05:37:15 +00:00
committed by Android Git Automerger
parent 056bc731ca e11744fefd
commit c25ff8e251
3 changed files with 442 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/html-ndk/ndk/guides/sample_hellojni.jd
View File

@@ -1,4 +1,4 @@
page.title=Sample: HelloJNI page.title=Sample: hello-jni
@jd:body @jd:body
<div id="qv-wrapper"> <div id="qv-wrapper">
@@ -16,14 +16,15 @@ page.title=Sample: HelloJNI
</div> </div>
</div> </div>
<p>This sample provides a bare-bones look at a minimal <p>This sample provides a bare-bones look at HelloJNI, a minimal
application built with the NDK.</p> application built with the NDK. This sample is in the {@code samples/hello-jni/} directory
under the root directory of your NDK installation.</p>
<h2 id="an">Android.mk</h2> <h2 id="an">Android.mk</h2>
<p>The following two lines provide the name of the native source file, along <p>The following two lines provide the name of the native source file, along
with the name of the shared library to build. The full name of the built with the name of the shared library to build. The full name of the built
library is {@code libhello-jni.so}, but you should omit the library is {@code libhello-jni.so}, once the build system adds the
{@code lib} prefix and the {@code .so} extension.</p> {@code lib} prefix and the {@code .so} extension.</p>
<pre class="no-pretty-print"> <pre class="no-pretty-print">
@@ -31,23 +32,23 @@ LOCAL_SRC_FILES := hello-jni.c
LOCAL_MODULE := hello-jni LOCAL_MODULE := hello-jni
</pre> </pre>
<p>For more information on what this file does, and how to use it, see <p>For more information about what the {@code Android.mk} file does, and how to use it, see
<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>.</p> <a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>.</p>
<h2 id="ap">Application.mk</h2> <h2 id="ap">Application.mk</h2>
<p>This line tells the build system the architecture against which to build. If <p>This line tells the build system the CPU and architecture against which to build. In this
you don't specify anything, the build system defaults to {@code armeabi}.</p> example, the build system builds for all supported architectures.</p>
<pre class="no-pretty-print"> <pre class="no-pretty-print">
APP_ABI := all APP_ABI := all
</pre> </pre>
<p>For more information on what this file does, and how to use it, see <p>For more information about the {@code Application.mk} file, and how to use it, see
<a href="{@docRoot}ndk/guides/application_mk.html">Application.mk</a>.</p> <a href="{@docRoot}ndk/guides/application_mk.html">Application.mk</a>.</p>
<h2 id="ji">Java-side implementation</h2> <h2 id="ji">Java-side Implementation</h2>
<p>This file calls a function to retrieve a string from the native side, then <p>The {@code helloJNI.java} file is located in {@code hellojni/src/com/example/hellojni/}. It calls
displays it on the screen.</p> a function to retrieve a string from the native side, then displays it on the screen.</p>
<p>The source code contains three lines of particular interest to the NDK user. <p>The source code contains three lines of particular interest to the NDK user.
They are presented here in the order in which they are used, rather than by They are presented here in the order in which they are used, rather than by
@@ -60,8 +61,8 @@ System.loadLibrary("hello-jni");
</pre> </pre>
<p>The {@code native} keyword in this method declaration tells the <p>The {@code native} keyword in this method declaration tells the
virtual machine that the function is in the shared library (i.e., implemented on the native side). virtual machine that the function is in the shared library (that is, implemented on the native
</p> side).</p>
<pre class="no-pretty-print"> <pre class="no-pretty-print">
public native String stringFromJNI(); public native String stringFromJNI();
@@ -74,15 +75,15 @@ previous steps, displaying the string on the screen.</p>
tv.setText( stringFromJNI() ); tv.setText( stringFromJNI() );
</pre> </pre>
<h2 id="ci">C-side implementation</h2> <h2 id="ci">C-side Implementation</h2>
<p>This file contains a function that returns a string that the Java side <p>The {@code hello-jni.c} file is located in {@code hello-jni/jni/}. It contains a function that
requested (see <a href="#ji">Java-side implementation</a>). The function declaration is as returns a string that <a href="#ji">the Java side requested</a>). The function declaration is as
follows:</p> follows:</p>
<pre> <pre>
jstring Java_com_example_hellojni_HelloJni_stringFromJNI( jstring
JNIEnv* env, Java_com_example_hellojni_HelloJni_stringFromJNI( JNIEnv* env,
jobject x ) jobject thiz )
</pre> </pre>
<p>This declaration corresponds to the native function declared in the <p>This declaration corresponds to the native function declared in the
@@ -104,12 +105,12 @@ according to the following rules:</p>
<li>After the last underscore, append the function name.</li> <li>After the last underscore, append the function name.</li>
</ul> </ul>
<p>Based on these rules, in this example, the function name <p>Following these rules, this example uses the function name
{@code Java_com_example_hellojni_HelloJni_stringFromJNI} refers to a Java {@code Java_com_example_hellojni_HelloJni_stringFromJNI}. This name refers to a Java
function called {@code stringFromJNI()}, which resides in function called {@code stringFromJNI()}, which resides in
{@code hellojni/src/com/example/hellojni/HelloJni.java}.</p> {@code hellojni/src/com/example/hellojni/HelloJni.java}.</p>
<p>Finally, {@code JNIEnv*} is the pointer to the VM, and <p>{@code JNIEnv*} is the pointer to the VM, and
{@code jobject} is a pointer to the implicit {@code this} object passed from {@code jobject} is a pointer to the implicit {@code this} object passed from
the Java side.</p> the Java side.</p>

259
docs/html-ndk/ndk/guides/sample_na.jd
View File

@@ -1,4 +1,4 @@
page.title=Sample: Native Activity page.title=Sample: native-activity
@jd:body @jd:body
<div id="qv-wrapper"> <div id="qv-wrapper">
@@ -6,102 +6,167 @@ page.title=Sample: Native Activity
<h2>On this page</h2> <h2>On this page</h2>
<ol> <ol>
<li><a href="#bb">Before Beginning</a></li> <li><a href="#am">AndroidManifest.xml</a></li>
<li><a href="#intro">Introduction</a></li> <li><a href="#anm">Android.mk</a></li>
<li><a href="#hiw">How It Works</a></li> <li><a href="#apm">Application.mk</a></li>
<li><a href="#naa">Native Activities and Applications</a></li> <li><a href="#mac">main.c</a></li>
</ol> </ol>
</li> </li>
</ol> </ol>
</div> </div>
</div> </div>
<p>This is a very simple example of a purely native <p>The native-activity sample resides under the NDK installation root, in
{@code samples/native-activity}. It is a very simple example of a purely native
application, with no Java source code. In the absence of any Java source, the application, with no Java source code. In the absence of any Java source, the
Java compiler still creates an executable stub for the Dalvik Virtual Machine Java compiler still creates an executable stub for the virtual machine to run.
("DVM") to run. The stub serves as a wrapper for the actual, native program, The stub serves as a wrapper for the actual, native program, which lives in the {@code .so}
which lives in the .so file.</p> file.</p>
<p>The application itself simply renders a color onto the entire screen, and
then changes the color partly in response to detected movement.</p> <p>The app itself simply renders a color onto the entire screen, and
<h3>AndroidManifest.xml</h3> then changes the color partly in response to movement that it detects.</p>
<p>Make sure not to specify an Android API level lower than 9.</p>
<pre class="fragment">&lt;uses-sdk android:minSdkVersion="9" /&gt; <h2 id="am">AndroidManifest.xml</h2>
</pre><p>Because this application has only native code, specify
<code>android:hasCode</code> as <code>false</code>.</p> <p>An app with only native code must not specify an Android API level lower than 9, which introduced
<pre class="fragment">&lt;application android:label="@string/app_name" the <a href="{@docRoot}ndk/guides/concepts.html#naa">{@code NativeActivity}</a> framework class.</p>
<pre class="no-pretty-print">
&lt;uses-sdk android:minSdkVersion="9" /&gt;
</pre>
<p>The following line declares {@code android:hasCode} as {@code false}, as this app has only
native code&ndash;no Java.
</p>
<pre class="no-pretty-print">
&lt;application android:label="@string/app_name"
android:hasCode="false"&gt; android:hasCode="false"&gt;
</pre><p>Declare the <code>NativeActivity</code> class.</p> </pre>
<pre class="fragment"> &lt;activity android:name="android.app.NativeActivity"
</pre><p>For <code>android:value</code>, provide the name of the shared library <p>The next line declares the {@code NativeActivity} class.</p>
to be built, minus the initial <code>lib</code> and the <code>.so</code>
extension. This value must be the same as the one you described for <pre class="no-pretty-print">
<code>LOCAL_MODULE</code> in <code>Android.mk</code>.</p> &lt;activity android:name="android.app.NativeActivity"
<pre class="fragment"> &lt;meta-data android:name="android.app.lib_name" </pre>
android:value="native-activity" /&gt;
</pre><h3>Android.mk</h3> <p>Finally, the manifest specifies {@code android:value} as the name of the shared library to be
<p>This file tells the build system the following information:</p> built, minus the initial {@code lib} and the {@code .so} extension. This value must be the same as
<p>The name of the shared library to generate.</p> the name of {@code LOCAL_MODULE} in {@code Android.mk}.</p>
<pre class="fragment">LOCAL_MODULE := native-activity
</pre><p>The name of the native source-code file.</p> <pre class="no-pretty-print">
<pre class="fragment">LOCAL_SRC_FILES := main.c &lt;meta-data android:name="android.app.lib_name"
</pre><p>A list of external libraries that will be used in building the binary, android:value="native-activity" /&gt;
each preceded by the <code>-l</code> (link-against) option.</p> </pre>
<h2 id="anm">Android.mk</h2>
<p>This file begins by providing the name of the shared library to generate.</p>
<pre class="no-pretty-print">
LOCAL_MODULE := native-activity
</pre>
<p>Next, it declares the name of the native source-code file.</p>
<pre class="no-pretty-print">
LOCAL_SRC_FILES := main.c
</pre>
<p>Next, it lists the external libraries for the build system to use in building the binary. The
{@code -l} (link-against) option precedes each library name.</p>
<ul> <ul>
<li>log is a logging library.</li> <li>{@code log} is a logging library.</li>
<li>android encompasses the standard Android support APIs for NDK. The <a href="./md_3__key__topics__libraries__s_t_a_b_l_e-_a_p_i_s.html">Stable APIs</a> <li>{@code android} encompasses the standard Android support APIs for NDK. For more information about
section discusses these in more detail.</li> the APIs that Android and the NDK support, see <a href="stable_apis.html">Android NDK Native
<li>EGL, standardized by Khronos, corresponds to the platform-specific portion APIs</a>.</li>
of the graphics API.</li> <li>{@code EGL} corresponds to the platform-specific portion of the graphics API.</li>
<li>OpenGL ES, the version of OpenGL for Android, depends on EGL.</li> <li>{@code GLESv1_CM} corresponds to OpenGL ES, the version of OpenGL for Android. This library
depends on EGL.</li>
</ul> </ul>
<p>Note that, for each library:</p>
<p>For each library:</p>
<ul> <ul>
<li>The actual file name starts with <code>lib</code>, and ends with the <li>The actual file name starts with {@code lib}, and ends with the
<code>.so</code> extension. For example, the actual file name for the {@code .so} extension. For example, the actual file name for the
<code>log</code> library is <code>liblog.so</code>.</li> {@code log} library is {@code liblog.so}.</li>
<li>The library lives in the following directory, relative to the NDK root: <li>The library resides in the following directory, NDK root:
<code>&lt;ndk&gt;/platforms/android-&lt;sdk_version&gt;/arch-&lt;abi&gt;/usr/lib/</code>.</li> {@code &lt;ndk&gt;/platforms/android-&lt;sdk_version&gt;/arch-&lt;abi&gt;/usr/lib/}.</li>
</ul> </ul>
<pre class="fragment">LOCAL_LDLIBS := -llog -landroid -lEGL -lGLESv1_CM
</pre><p>A static library, <code>android_native_app_glue</code>, that the <pre class="no-pretty-print">
application uses to manage <code>NativeActivity</code> lifecycle events, along LOCAL_LDLIBS := -llog -landroid -lEGL -lGLESv1_CM
with touch input.</p> </pre>
<pre class="fragment">LOCAL_STATIC_LIBRARIES := android_native_app_glue
</pre><p>The final line tells the build system to build this static library. <p>The next line provides the name of the static library, {@code android_native_app_glue}, which the
<code>ndk-build</code> places the built library application uses to manage {@code NativeActivity} lifecycle events and touch input.</p>
(<code>libandroid_native_app_glue.a</code>) into the <code>obj</code> directory
generated during the build process. The next sample discusses the <pre class="no-pretty-print">
android_native_app_glue in more detail.</p> LOCAL_STATIC_LIBRARIES := android_native_app_glue
<pre class="fragment">$(call import-module,android/native_app_glue) </pre>
</pre><p>For more information about the Application.mk file, consult the <a
href="./md_3__key__topics__building__a_p_p_l_i_c_a_t_i_o_n-_m_k.html">Application.mk section</a> of this guide.</p> <p>The final line tells the build system to build this static library.
<h3><code>Application.mk</code></h3> The {@code ndk-build} script places the built library
({@code libandroid_native_app_glue.a}) into the {@code obj} directory
generated during the build process. For more information about the {@code android_native_app_glue}
library, see its {@code android_native_app_glue.h} header and corresponding {@code .c}source file.
</p>
<pre class="no-pretty-print">
$(call import-module,android/native_app_glue)
</pre>
<p>For more information about the {@code Android.mk} file, see
<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>.</p>
<h2 id="apm">Application.mk</h2>
<p>This line defines the minimum level of Android API Level support.</p> <p>This line defines the minimum level of Android API Level support.</p>
<pre class="fragment">APP_PLATFORM := android-10
</pre><p>Because there is no ABI definition, the build system defaults to <pre class="no-pretty-print">
building only for armeabi.</p> APP_PLATFORM := android-10
<h3>main.c</h3> </pre>
<p>Because there is no ABI definition, the build system defaults to building only for
{@code armeabi}.</p>
<h2 id="mac">main.c</h2>
<p>This file essentially contains the entire progam.</p> <p>This file essentially contains the entire progam.</p>
<p>The following includes correspond to the libraries, both shared and static, <p>The following includes correspond to the libraries, both shared and static,
enumerated in <code>Android.mk</code>.</p> enumerated in {@code Android.mk}.</p>
<pre class="fragment">#include &lt;EGL/egl.h&gt;
<pre class="no-pretty-print">
#include &lt;EGL/egl.h&gt;
#include &lt;GLES/gl.h&gt; #include &lt;GLES/gl.h&gt;
#include &lt;android/sensor.h&gt; #include &lt;android/sensor.h&gt;
#include &lt;android/log.h&gt; #include &lt;android/log.h&gt;
#include &lt;android_native_app_glue&gt; #include &lt;android_native_app_glue&gt;
</pre><p><code>android_native_app_glue</code> calls the following function, </pre>
<p>The {@code android_native_app_glue} library calls the following function,
passing it a predefined state structure. It also serves as a wrapper that passing it a predefined state structure. It also serves as a wrapper that
simplifies handling of <code>NativeActivity</code> callbacks.</p> simplifies handling of {@code NativeActivity} callbacks.</p>
<pre class="fragment">void android_main(struct android_app* state) {
</pre><p>Next, the program handles events queued by the glue library. The event <pre class="no-pretty-print">
void android_main(struct android_app* state) {
</pre>
<p>Next, the program handles events queued by the glue library. The event
handler follows the state structure.</p> handler follows the state structure.</p>
<pre class="fragment">struct engine engine;
<pre class="no-pretty-print">
struct engine engine;
// Make sure glue isn't stripped by suppressing link-time optimization that
removes unreferenced code. // Suppress link-time optimization that removes unreferenced code
// to make sure glue isn't stripped.
app_dummy(); app_dummy();
@@ -110,21 +175,29 @@ state-&gt;userData = &amp;engine;
state-&gt;onAppCmd = engine_handle_cmd; state-&gt;onAppCmd = engine_handle_cmd;
state-&gt;onInputEvent = engine_handle_input; state-&gt;onInputEvent = engine_handle_input;
engine.app = state; engine.app = state;
</pre><p>The application prepares to start monitoring the sensors, using the </pre>
APIs in <code>sensor.h</code>.</p>
<pre class="fragment"> engine.sensorManager = ASensorManager_getInstance(); <p>The application prepares to start monitoring the sensors, using the
APIs in {@code sensor.h}.</p>
<pre class="no-pretty-print">
engine.sensorManager = ASensorManager_getInstance();
engine.accelerometerSensor = engine.accelerometerSensor =
ASensorManager_getDefaultSensor(engine.sensorManager, ASensorManager_getDefaultSensor(engine.sensorManager,
ASENSOR_TYPE_ACCELEROMETER); ASENSOR_TYPE_ACCELEROMETER);
engine.sensorEventQueue = engine.sensorEventQueue =
ASensorManager_createEventQueue(engine.sensorManager, ASensorManager_createEventQueue(engine.sensorManager,
state-&gt;looper, LOOPER_ID_USER, NULL, NULL); state-&gt;looper, LOOPER_ID_USER, NULL, NULL);
</pre><p>Now, a loop begins, in which the application polls the system for </pre>
<p>Next, a loop begins, in which the application polls the system for
messages (sensor events). It sends messages to messages (sensor events). It sends messages to
<code>android_native_app_glue</code>, which checks to see whether they match {@code android_native_app_glue}, which checks to see whether they match
any <code>onAppCmd</code> events defined in <code>android_main</code>. When a any {@code onAppCmd} events defined in {@code android_main}. When a
match occurs, the message is sent to the handler for execution.</p> match occurs, the message is sent to the handler for execution.</p>
<pre class="fragment">while (1) {
<pre class="no-pretty-print">
while (1) {
// Read all pending events. // Read all pending events.
int ident; int ident;
int events; int events;
@@ -135,7 +208,7 @@ match occurs, the message is sent to the handler for execution.</p>
// If animating, we loop until all events are read, then continue // If animating, we loop until all events are read, then continue
// to draw the next frame of animation. // to draw the next frame of animation.
while ((ident=ALooper_pollAll(engine.animating ? 0 : -1, NULL, while ((ident=ALooper_pollAll(engine.animating ? 0 : -1, NULL,
&amp;events, &amp;events,
(void**)&amp;source)) &gt;= 0) { (void**)&amp;source)) &gt;= 0) {
@@ -165,9 +238,12 @@ match occurs, the message is sent to the handler for execution.</p>
return; return;
} }
} }
</pre><p>Once the queue is empty, and the program exits the polling loop, the </pre>
<p>Once the queue is empty, and the program exits the polling loop, the
program calls OpenGL to draw the screen.</p> program calls OpenGL to draw the screen.</p>
<pre class="fragment"> if (engine.animating) { <pre class="no-pretty-print">
if (engine.animating) {
// Done with events; draw next animation frame. // Done with events; draw next animation frame.
engine.state.angle += .01f; engine.state.angle += .01f;
if (engine.state.angle &gt; 1) { if (engine.state.angle &gt; 1) {
@@ -179,16 +255,5 @@ program calls OpenGL to draw the screen.</p>
// is no need to do timing here. // is no need to do timing here.
engine_draw_frame(&amp;engine); engine_draw_frame(&amp;engine);
} }
} </pre> </div></div><!-- contents --> }
</div><!-- doc-content --> </pre>
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK
Programmer&#39;s Guide by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
</ul>
</div>
</body>
</html>

390
docs/html-ndk/ndk/guides/sample_teapot.jd
View File

@@ -6,58 +6,80 @@ page.title=Sample: Teapot
<h2>On this page</h2> <h2>On this page</h2>
<ol> <ol>
<li><a href="#bb">Before Beginning</a></li> <li><a href="#am">AndroidManifest.xml</a></li>
<li><a href="#intro">Introduction</a></li> <li><a href="#ap">Application.mk</a></li>
<li><a href="#hiw">How It Works</a></li> <li><a href="#ji">Java-side Implementation</a></li>
<li><a href="#naa">Native Activities and Applications</a></li> <li><a href="#ni">Native-side Implementation</a></li>
</ol> </ol>
</li> </li>
</ol> </ol>
</div> </div>
</div> </div>
<p>This sample uses the OpenGL library to render the <p>The Teapot sample is located under in the {@code samples/Teapot/} directory, under the NDK
iconic <a installation's root directory. This sample uses the OpenGL library to render the iconic
href="http://math.hws.edu/bridgeman/courses/324/s06/doc/opengl.html#basic">Utah <a href="http://math.hws.edu/bridgeman/courses/324/s06/doc/opengl.html#basic">Utah
teapot</a>. It particularly showcases the <code>ndk_helper</code> helper class, teapot</a>. In particular, it showcases the {@code ndk_helper} helper class,
a collection of native helper functions required for implementing games and a collection of native helper functions required for implementing games and
similar applications as native applications. This class provides:</p> similar applications as native applications. This class provides:</p>
<ul> <ul>
<li>an abstraction layer that handles certain NDK-specific behaviors (e.g., <li>An abstraction layer, {@code GLContext}, that handles certain NDK-specific behaviors.</li>
<code>GLContext</code>).</li> <li>Helper functions that are useful but not present in the NDK, such as tap detection.</li>
<li>some helper functions that are useful but not present in the NDK, itself <li>Wrappers for JNI calls for platform features such as texture loading.</li>
(e.g., tap detection).</li>
<li>wrappers for JNI calls for certain platform features (e.g., texture
loading).</li>
</ul> </ul>
<h3>AndroidManifest.xml</h3>
<p>The activity declaration here is not <code>NativeActivity</code> itself, but <h2 id="am">AndroidManifest.xml</h2>
a subclass: <code>TeapotNativeActivity</code>.</p> <p>The activity declaration here is not {@link android.app.NativeActivity} itself, but
<pre class="fragment"> &lt;activity a subclass of it: {@code TeapotNativeActivity}.</p>
android:name="com.sample.teapot.TeapotNativeActivity"
<pre class="no-pretty-print">
&lt;activity android:name="com.sample.teapot.TeapotNativeActivity"
android:label="@string/app_name" android:label="@string/app_name"
android:configChanges="orientation|keyboardHidden"&gt; android:configChanges="orientation|keyboardHidden"&gt;
</pre><p>The name of the <code>.so</code> file is </pre>
<code>libTeapotNativeActivity.so</code>; the <code>lib</code> and
<code>.so</code> are stripped off from the value assigned to
<code>android:value</code>.</p>
<pre class="fragment"> &lt;meta-data android:name="android.app.lib_name"
android:value="TeapotNativeActivity" /&gt;
</pre><h3><code>Application.mk</code></h3>
<p>Define the minimum level of Android API Level support.</p>
<pre class="fragment">APP_PLATFORM := android-9
</pre><p>Build for all supported architectures.</p>
<pre class="fragment">APP_ABI := all
</pre><p>Specify the <a
href="./md_3__key__topics__libraries__c_p_l_u_s_p_l_u_s-_s_u_p_p_o_r_t.html">C++
runtime support library</a> to use. </p>
<pre class="fragment">APP_STL := stlport_static
</pre><h3>Java-side implementation: TeapotNativeActivity.java</h3>
<p>This file handles activity lifecycle events, as well as displaying text on
the screen.</p>
<pre class="fragment">// Our popup window, you will call it from your C/C++
code later
<p>Ultimately, the name of the shared-object file that the build system builds is
{@code libTeapotNativeActivity.so}. The build system adds the {@code lib} prefix and the {@code .so}
extension; neither is part of the value that the manifest originally assigns to
{@code android:value}.</p>
<pre class="no-pretty-print">
&lt;meta-data android:name="android.app.lib_name"
android:value="TeapotNativeActivity" /&gt;
</pre>
<h2 id="ap">Application.mk</h2>
<p>An app that uses the {@link android.app.NativeActivity} framework class must not specify an
Android API level lower than 9, which introduced that class. For more information about the
{@link android.app.NativeActivity} class, see
<a href="{@docRoot}ndk/guides/concepts.html#naa">Native Activities and Applications</a>.
</p>
<pre class="no-pretty-print">
APP_PLATFORM := android-9
</pre>
<p>The next line tells the build system to build for all supported architectures.</p>
<pre class="no-pretty-print">
APP_ABI := all
</pre>
<p>Next, the file tells the build system which
<a href="{@docRoot}ndk/guides/cpp-support.html">C++ runtime support library</a> to use. </p>
<pre class="no-pretty-print">
APP_STL := stlport_static
</pre>
<h2 id="ji">Java-side Implementation</h2>
<p>The {@code TeapotNativeActivity.java} file is located in
{@code samples/Teapot/src/com/sample/teapot}, under the NDK installation root directory. It handles
activity lifecycle events, and also enables the app to display text on the screen. The following
block of code is most important from the perspective of the native-side implementation: The native
code calls it to display a popup window for text display.</p>
<pre class="no-pretty-print">
void setImmersiveSticky() { void setImmersiveSticky() {
View decorView = getWindow().getDecorView(); View decorView = getWindow().getDecorView();
@@ -68,17 +90,19 @@ void setImmersiveSticky() {
| View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
| View.SYSTEM_UI_FLAG_LAYOUT_STABLE); | View.SYSTEM_UI_FLAG_LAYOUT_STABLE);
} }
</pre><h3>Native-side implementation</h3> </pre>
<p>This section explores the C++ part of the Teapot app.</p> <h2 id="ni">Native-side Implementation</h2>
<h4>TeapotRenderer.*</h4> <p>This section explores the part of the Teapot app implemented in C++.</p>
<p>This code does the actual rendering of the teapot. It uses <h3>TeapotRenderer.h</h3>
<code>ndk_helper</code> for matrix calculation, and to reposition the camera
based on where the user taps:</p>
<pre> <p>These function calls perform the actual rendering of the teapot. It uses
{@code ndk_helper} for matrix calculation and to reposition the camera
based on where the user taps.</p>
<pre class="no-pretty-print">
ndk_helper::Mat4 mat_projection_; ndk_helper::Mat4 mat_projection_;
ndk_helper::Mat4 mat_view_; ndk_helper::Mat4 mat_view_;
ndk_helper::Mat4 mat_model_; ndk_helper::Mat4 mat_model_;
@@ -87,50 +111,75 @@ ndk_helper::Mat4 mat_model_;
ndk_helper::TapCamera* camera_; ndk_helper::TapCamera* camera_;
</pre> </pre>
<h4>TeapotNativeActivity.cpp</code></h4> <h3>TeapotNativeActivity.cpp</h3>
<p>Include <code>ndk_helper</code> in your native source file, and define the <p>The following lines include {@code ndk_helper} in the native source file, and define the
helper-class name:</p> helper-class name.</p>
<pre class="fragment">#include "NDKHelper.h"
<pre class="no-pretty-print">
#include "NDKHelper.h"
//------------------------------------------------------------------------- //-------------------------------------------------------------------------
//Preprocessor //Preprocessor
//------------------------------------------------------------------------- //-------------------------------------------------------------------------
#define HELPER_CLASS_NAME "com/sample/helper/NDKHelper" //Class name of helper #define HELPER_CLASS_NAME "com/sample/helper/NDKHelper" //Class name of helper
function function
</pre><p>The first use of the <code>ndk_helper</code> class is to handle the </pre>
<p>The first use of the {@code ndk_helper} class is to handle the
EGL-related lifecycle, associating EGL context states (created/lost) with EGL-related lifecycle, associating EGL context states (created/lost) with
Android lifecycle events. It enables the application to preserve context Android lifecycle events. The {@code ndk_helper} class enables the application to preserve context
information so that a destroyed activity can be restored. This is useful, for information so that the system can restore a destroyed activity. This ability is useful, for
example, when the target machine is rotated (causing an activity to be example, when the target machine is rotated (causing an activity to be
destroyed, then immediately restored in the new orientation), or when the lock destroyed, then immediately restored in the new orientation), or when the lock
screen appears.</p> screen appears.</p>
<pre class="fragment">ndk_helper::GLContext* gl_context_; // handles
EGL-related lifecycle. <pre class="no-pretty-print">
</pre><p>Next, <code>ndk_helper</code> provides touch control.</p> ndk_helper::GLContext* gl_context_; // handles EGL-related lifecycle.
<pre class="fragment">ndk_helper::DoubletapDetector doubletap_detector_; </pre>
<p>Next, {@code ndk_helper} provides touch control.</p>
<pre class="no-pretty-print">
ndk_helper::DoubletapDetector doubletap_detector_;
ndk_helper::PinchDetector pinch_detector_; ndk_helper::PinchDetector pinch_detector_;
ndk_helper::DragDetector drag_detector_; ndk_helper::DragDetector drag_detector_;
ndk_helper::PerfMonitor monitor_; ndk_helper::PerfMonitor monitor_;
</pre><p>And camera control (openGL view frustum).</p> </pre>
<pre class="fragment">ndk_helper::TapCamera tap_camera_;
</pre><p>As in the native-activity sample, the application prepares to use the <p>It also provides camera control (openGL view frustum).</p>
sensors, using the native APIs provided in the NDK.</p>
<pre class="fragment">ASensorManager* sensor_manager_; <pre class="no-pretty-print">
ndk_helper::TapCamera tap_camera_;
</pre>
<p>The app then prepares to use the device's sensors, using the native APIs provided in the NDK.</p>
<pre class="no-pretty-print">
ASensorManager* sensor_manager_;
const ASensor* accelerometer_sensor_; const ASensor* accelerometer_sensor_;
ASensorEventQueue* sensor_event_queue_; ASensorEventQueue* sensor_event_queue_;
</pre><p>The following functions are called in response to various Android </pre>
<p>The app calls the following functions in response to various Android
lifecycle events and EGL context state changes, using various functionalities lifecycle events and EGL context state changes, using various functionalities
provided by <code>ndk_helper</code> via the <code>Engine</code> class.</p> provided by {@code ndk_helper} via the {@code Engine} class.</p>
<pre class="fragment">void LoadResources();
<pre class="no-pretty-print">
void LoadResources();
void UnloadResources(); void UnloadResources();
void DrawFrame(); void DrawFrame();
void TermDisplay(); void TermDisplay();
void TrimMemory(); void TrimMemory();
bool IsReady(); bool IsReady();
</pre><p>This function calls back to the Java side to update the UI display.</p> </pre>
<pre class="fragment">void Engine::ShowUI()
<p>Then, the following function calls back to the Java side to update the UI display.</p>
<pre class="no-pretty-print">
void Engine::ShowUI()
{ {
JNIEnv *jni; JNIEnv *jni;
app_-&gt;activity-&gt;vm-&gt;AttachCurrentThread( &amp;jni, NULL ); app_-&gt;activity-&gt;vm-&gt;AttachCurrentThread( &amp;jni, NULL );
@@ -145,10 +194,14 @@ bool IsReady();
app_-&gt;activity-&gt;vm-&gt;DetachCurrentThread(); app_-&gt;activity-&gt;vm-&gt;DetachCurrentThread();
return; return;
} }
</pre><p>And this one calls back to the Java side to draw a text box </pre>
<p>Next, this function calls back to the Java side to draw a text box
superimposed on the screen rendered on the native side, and showing frame superimposed on the screen rendered on the native side, and showing frame
count.</p> count.</p>
<pre class="fragment">void Engine::UpdateFPS( float fFPS )
<pre class="no-pretty-print">
void Engine::UpdateFPS( float fFPS )
{ {
JNIEnv *jni; JNIEnv *jni;
app_-&gt;activity-&gt;vm-&gt;AttachCurrentThread( &amp;jni, NULL ); app_-&gt;activity-&gt;vm-&gt;AttachCurrentThread( &amp;jni, NULL );
@@ -163,74 +216,145 @@ count.</p>
app_-&gt;activity-&gt;vm-&gt;DetachCurrentThread(); app_-&gt;activity-&gt;vm-&gt;DetachCurrentThread();
return; return;
} }
</pre><p>The application gets the system clock and supplies it to the renderer
for time-based animation based on real-time clock. For example, calculating
momentum, where speed declines as a function of time.</p>
<pre class="fragment">renderer_.Update( monitor_.GetCurrentTime() );
</pre><p>Having earlier been set up to preserve context information, the
application now checks whether <code>GLcontext</code> is still valid. If not,
<code>ndk-helper</code> swaps the buffer, reinstantiating the GL context.</p>
<pre class="fragment">if( EGL_SUCCESS != gl_context_-&gt;Swap() ) // swaps
buffer.
</pre><p>The program passes touch-motion events to the gesture detector defined
in the <code>ndk_helper</code> class. The gesture detector tracks multitouch
gestures, such as pinch-and-drag, and sends a notification when triggered by
any of these events.</p>
<pre class="fragment">if( AInputEvent_getType( event ) ==
AINPUT_EVENT_TYPE_MOTION )
{
ndk_helper::GESTURE_STATE doubleTapState =
eng-&gt;doubletap_detector_.Detect( event );
ndk_helper::GESTURE_STATE dragState = eng-&gt;drag_detector_.Detect( event
);
ndk_helper::GESTURE_STATE pinchState = eng-&gt;pinch_detector_.Detect(
event );
//Double tap detector has a priority over other detectors
if( doubleTapState == ndk_helper::GESTURE_STATE_ACTION )
{
//Detect double tap
eng-&gt;tap_camera_.Reset( true );
}
else
{
//Handle pinch state
if( pinchState &amp; ndk_helper::GESTURE_STATE_START )
{
//Start new pinch
ndk_helper::Vec2 v1;
ndk_helper::Vec2 v2;
eng-&gt;pinch_detector_.GetPointers( v1, v2 );
</pre><p><code>ndk_helper</code> also provides access to a vector-math library
(<code>vecmath.h</code>), using it here to transform touch coordinates.</p>
<pre class="fragment">void Engine::TransformPosition( ndk_helper::Vec2&amp; vec
) { vec = ndk_helper::Vec2( 2.0f, 2.0f ) * vec / ndk_helper::Vec2(
gl_context_-&gt;GetScreenWidth(), gl_context_-&gt;GetScreenHeight() )
ndk_helper::Vec2( 1.f, 1.f ); }</li></pre>
</ul>
<p><code>HandleCmd()</code> handles commands posted from the
android_native_app_glue library. For more information about what the messages
mean, refer to the comments in the <code>android_native_app_glue.h</code> and
<code>.c</code> source files.</p>
<pre>
void Engine::HandleCmd( struct android_app* app, int32_t
cmd ) { Engine* eng = (Engine*) app-&gt;userData; switch( cmd ) { case
APP_CMD_SAVE_STATE: break; case APP_CMD_INIT_WINDOW: // The window is being
shown, get it ready. if( app-&gt;window != NULL )
</pre> </pre>
<p><code>ndk_helper</code> posts APP_CMD_INIT_WINDOW when android_app_glue <p>The application gets the system clock and supplies it to the renderer
receives an <code>onNativeWindowCreated()</code> callback from the system. for time-based animation based on real-time clock. This information is used, for example, in
calculating momentum, where speed declines as a function of time.</p>
<pre class="no-pretty-print">
renderer_.Update( monitor_.GetCurrentTime() );
</pre>
<p>The application now checks whether the context information that {@code GLcontext} holds is still
valid. If not, {@code ndk-helper} swaps the buffer, reinstantiating the GL context.</p>
<pre class="no-pretty-print">
if( EGL_SUCCESS != gl_context_-&gt;Swap() ) // swaps
buffer.
</pre>
<p>The program passes touch-motion events to the gesture detector defined
in the {@code ndk_helper} class. The gesture detector tracks multitouch
gestures, such as pinch-and-drag, and sends a notification when triggered by
any of these events.</p>
<pre class="no-pretty-print">
if( AInputEvent_getType( event ) == AINPUT_EVENT_TYPE_MOTION )
{
ndk_helper::GESTURE_STATE doubleTapState =
eng->doubletap_detector_.Detect( event );
ndk_helper::GESTURE_STATE dragState = eng->drag_detector_.Detect( event );
ndk_helper::GESTURE_STATE pinchState = eng->pinch_detector_.Detect( event );
//Double tap detector has a priority over other detectors
if( doubleTapState == ndk_helper::GESTURE_STATE_ACTION )
{
//Detect double tap
eng->tap_camera_.Reset( true );
}
else
{
//Handle drag state
if( dragState & ndk_helper::GESTURE_STATE_START )
{
//Otherwise, start dragging
ndk_helper::Vec2 v;
eng->drag_detector_.GetPointer( v );
eng->TransformPosition( v );
eng->tap_camera_.BeginDrag( v );
}
// ...else other possible drag states...
//Handle pinch state
if( pinchState & ndk_helper::GESTURE_STATE_START )
{
//Start new pinch
ndk_helper::Vec2 v1;
ndk_helper::Vec2 v2;
eng->pinch_detector_.GetPointers( v1, v2 );
eng->TransformPosition( v1 );
eng->TransformPosition( v2 );
eng->tap_camera_.BeginPinch( v1, v2 );
}
// ...else other possible pinch states...
}
return 1;
}
</pre>
<p>The {@code ndk_helper} class also provides access to a vector-math library
({@code vecmath.h}), using it here to transform touch coordinates.</p>
<pre class="no-pretty-print">
void Engine::TransformPosition( ndk_helper::Vec2& vec )
{
vec = ndk_helper::Vec2( 2.0f, 2.0f ) * vec
/ ndk_helper::Vec2( gl_context_->GetScreenWidth(),
gl_context_->GetScreenHeight() ) - ndk_helper::Vec2( 1.f, 1.f );
}
</pre>
</ul>
<p>The {@code HandleCmd()} method handles commands posted from the
android_native_app_glue library. For more information about what the messages
mean, refer to the comments in the {@code android_native_app_glue.h} and
{@code .c} source files.</p>
<pre class="no-pretty-print">
void Engine::HandleCmd( struct android_app* app,
int32_t cmd )
{
Engine* eng = (Engine*) app->userData;
switch( cmd )
{
case APP_CMD_SAVE_STATE:
break;
case APP_CMD_INIT_WINDOW:
// The window is being shown, get it ready.
if( app->window != NULL )
{
eng->InitDisplay();
eng->DrawFrame();
}
break;
case APP_CMD_TERM_WINDOW:
// The window is being hidden or closed, clean it up.
eng->TermDisplay();
eng->has_focus_ = false;
break;
case APP_CMD_STOP:
break;
case APP_CMD_GAINED_FOCUS:
eng->ResumeSensors();
//Start animation
eng->has_focus_ = true;
break;
case APP_CMD_LOST_FOCUS:
eng->SuspendSensors();
// Also stop animating.
eng->has_focus_ = false;
eng->DrawFrame();
break;
case APP_CMD_LOW_MEMORY:
//Free up GL resources
eng->TrimMemory();
break;
}
}
</pre>
<p>The {@code ndk_helper} class posts {@code APP_CMD_INIT_WINDOW} when {@code android_app_glue}
receives an {@code onNativeWindowCreated()} callback from the system.
Applications can normally perform window initializations, such as EGL Applications can normally perform window initializations, such as EGL
initialization. They do this outside of the activity lifecycle, since the initialization. They do this outside of the activity lifecycle, since the
activity is not yet ready.</p> activity is not yet ready.</p>
<pre class="fragment">ndk_helper::JNIHelper::Init( state-&gt;activity,
HELPER_CLASS_NAME );
<pre class="no-pretty-print">
//Init helper functions
ndk_helper::JNIHelper::Init( state->activity, HELPER_CLASS_NAME );
state-&gt;userData = &amp;g_engine; state->userData = &g_engine;
state-&gt;onAppCmd = Engine::HandleCmd; state->onAppCmd = Engine::HandleCmd;
state-&gt;onInputEvent = Engine::HandleInput; </pre> state->onInputEvent = Engine::HandleInput;
</pre>