Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit dcae36ab authored by David Friedman's avatar David Friedman Committed by Android Git Automerger
Browse files

am bfd5b22b: am 19abfb77: am 337089c8: am e0f14f48: am c25ff8e2: am e11744fe:... 

am bfd5b22b: am 19abfb77: am 337089c8: am e0f14f48: am c25ff8e2: am e11744fe: am 4a6d5c93: Docs: Sample-walkthrough chapters for NDK documentation

* commit 'bfd5b22b':
  Docs: Sample-walkthrough chapters for NDK documentation
parents 90d59e31 bfd5b22b

docs/html-ndk/ndk/guides/sample_hellojni.jd

+23 −22
Original line number Diff line number Diff line 
page.title=Sample: HelloJNI

page.title=Sample: hello-jni

@jd:body



<div id="qv-wrapper">
@@ -16,14 +16,15 @@ page.title=Sample: HelloJNI 
    </div>

  </div>



<p>This sample provides a bare-bones look at a minimal

application built with the NDK.</p>

<p>This sample provides a bare-bones look at HelloJNI, a minimal

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>



<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

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>



<pre class="no-pretty-print">
@@ -31,23 +32,23 @@ LOCAL_SRC_FILES := hello-jni.c 
LOCAL_MODULE    := hello-jni

</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>



<h2 id="ap">Application.mk</h2>

<p>This line tells the build system the architecture against which to build. If

you don't specify anything, the build system defaults to {@code armeabi}.</p>

<p>This line tells the build system the CPU and architecture against which to build. In this

example, the build system builds for all supported architectures.</p>



<pre class="no-pretty-print">

APP_ABI := all

</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>



<h2 id="ji">Java-side implementation</h2>

<p>This file calls a function to retrieve a string from the native side, then

displays it on the screen.</p>

<h2 id="ji">Java-side Implementation</h2>

<p>The {@code helloJNI.java} file is located in {@code hellojni/src/com/example/hellojni/}. It calls

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.

They are presented here in the order in which they are used, rather than by
@@ -60,8 +61,8 @@ System.loadLibrary("hello-jni"); 
</pre>



<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).

</p>

virtual machine that the function is in the shared library (that is, implemented on the native

side).</p>



<pre class="no-pretty-print">

public native String stringFromJNI();
@@ -74,15 +75,15 @@ previous steps, displaying the string on the screen.</p> 
tv.setText( stringFromJNI() );

</pre>



<h2 id="ci">C-side implementation</h2>

<p>This file contains a function that returns a string that the Java side

requested (see <a href="#ji">Java-side implementation</a>). The function declaration is as

<h2 id="ci">C-side Implementation</h2>

<p>The {@code hello-jni.c} file is located in {@code hello-jni/jni/}. It contains a function that

returns a string that <a href="#ji">the Java side requested</a>). The function declaration is as

follows:</p>



<pre>

jstring Java_com_example_hellojni_HelloJni_stringFromJNI(

JNIEnv* env,

                                              jobject x )

jstring

Java_com_example_hellojni_HelloJni_stringFromJNI( JNIEnv* env,

                                                  jobject thiz )

</pre>



<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>

</ul>



<p>Based on these rules, in this example, the function name

{@code Java_com_example_hellojni_HelloJni_stringFromJNI} refers to a Java

<p>Following these rules, this example uses the function name

{@code Java_com_example_hellojni_HelloJni_stringFromJNI}. This name refers to a Java

function called {@code stringFromJNI()}, which resides in

{@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

the Java side.</p>

docs/html-ndk/ndk/guides/sample_na.jd

+162 −97
Original line number Diff line number Diff line 
page.title=Sample: Native Activity

page.title=Sample: native-activity

@jd:body



<div id="qv-wrapper">
@@ -6,102 +6,167 @@ page.title=Sample: Native Activity 
      <h2>On this page</h2>



      <ol>

        <li><a href="#bb">Before Beginning</a></li>

        <li><a href="#intro">Introduction</a></li>

        <li><a href="#hiw">How It Works</a></li>

        <li><a href="#naa">Native Activities and Applications</a></li>

        <li><a href="#am">AndroidManifest.xml</a></li>

        <li><a href="#anm">Android.mk</a></li>

        <li><a href="#apm">Application.mk</a></li>

        <li><a href="#mac">main.c</a></li>

          </ol>

        </li>

      </ol>

    </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

Java compiler still creates an executable stub for the Dalvik Virtual Machine

("DVM") to run. The stub serves as a wrapper for the actual, native program,

which lives in the .so 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>

<h3>AndroidManifest.xml</h3>

<p>Make sure not to specify an Android API level lower than 9.</p>

<pre class="fragment">&lt;uses-sdk android:minSdkVersion="9" /&gt;

</pre><p>Because this application has only native code, specify

<code>android:hasCode</code> as <code>false</code>.</p>

<pre class="fragment">&lt;application android:label="@string/app_name"

Java compiler still creates an executable stub for the virtual machine to run.

The stub serves as a wrapper for the actual, native program, which lives in the {@code .so}

file.</p>



<p>The app itself simply renders a color onto the entire screen, and

then changes the color partly in response to movement that it detects.</p>



<h2 id="am">AndroidManifest.xml</h2>



<p>An app with only native code must not specify an Android API level lower than 9, which introduced

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;

</pre><p>Declare the <code>NativeActivity</code> class.</p>

<pre class="fragment">    &lt;activity android:name="android.app.NativeActivity"

</pre><p>For <code>android:value</code>, provide the name of the shared library

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

<code>LOCAL_MODULE</code> in <code>Android.mk</code>.</p>

<pre class="fragment">        &lt;meta-data android:name="android.app.lib_name"

</pre>



<p>The next line declares the {@code NativeActivity} class.</p>



<pre class="no-pretty-print">

&lt;activity android:name="android.app.NativeActivity"

</pre>



<p>Finally, the manifest specifies {@code android:value} as the name of the shared library to be

built, minus the initial {@code lib} and the {@code .so} extension. This value must be the same as

the name of {@code LOCAL_MODULE} in {@code Android.mk}.</p>



<pre class="no-pretty-print">

&lt;meta-data android:name="android.app.lib_name"

        android:value="native-activity" /&gt;

</pre><h3>Android.mk</h3>

<p>This file tells the build system the following information:</p>

<p>The name of the shared library to generate.</p>

<pre class="fragment">LOCAL_MODULE    := native-activity

</pre><p>The name of the native source-code file.</p>

<pre class="fragment">LOCAL_SRC_FILES := main.c

</pre><p>A list of external libraries that will be used in building the binary,

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>

<li>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>

section discusses these in more detail.</li>

<li>EGL, standardized by Khronos, 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 log} is a logging library.</li>

<li>{@code android} encompasses the standard Android support APIs for NDK. For more information about

the APIs that Android and the NDK support, see  <a href="stable_apis.html">Android NDK Native

APIs</a>.</li>

<li>{@code EGL} corresponds to the platform-specific portion of the graphics API.</li>

<li>{@code GLESv1_CM} corresponds to OpenGL ES, the version of OpenGL for Android. This library

depends on EGL.</li>

</ul>

<p>Note that, for each library:</p>



<p>For each library:</p>



<ul>

<li>The actual file name starts with <code>lib</code>, and ends with the

<code>.so</code> extension. For example, the actual file name for the

<code>log</code> library is <code>liblog.so</code>.</li>

<li>The library lives in the following directory, relative to the NDK root:

<code>&lt;ndk&gt;/platforms/android-&lt;sdk_version&gt;/arch-&lt;abi&gt;/usr/lib/</code>.</li>

<li>The actual file name starts with {@code lib}, and ends with the

{@code .so} extension. For example, the actual file name for the

{@code log} library is {@code liblog.so}.</li>

<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/}.</li>

</ul>

<pre class="fragment">LOCAL_LDLIBS    := -llog -landroid -lEGL -lGLESv1_CM

</pre><p>A static library, <code>android_native_app_glue</code>, that the

application uses to manage <code>NativeActivity</code> lifecycle events, along

with touch input.</p>

<pre class="fragment">LOCAL_STATIC_LIBRARIES := android_native_app_glue

</pre><p>The final line tells the build system to build this static library.

<code>ndk-build</code> places the built library

(<code>libandroid_native_app_glue.a</code>) into the <code>obj</code> directory

generated during the build process. The next sample discusses the

android_native_app_glue in more detail.</p>

<pre class="fragment">$(call import-module,android/native_app_glue)

</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>

<h3><code>Application.mk</code></h3>



<pre class="no-pretty-print">

LOCAL_LDLIBS    := -llog -landroid -lEGL -lGLESv1_CM

</pre>



<p>The next line provides the name of the static library, {@code android_native_app_glue}, which the

application uses to manage {@code NativeActivity} lifecycle events and touch input.</p>



<pre class="no-pretty-print">

LOCAL_STATIC_LIBRARIES := android_native_app_glue

</pre>



<p>The final line tells the build system to build this static library.

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>

<pre class="fragment">APP_PLATFORM := android-10

</pre><p>Because there is no ABI definition, the build system defaults to

building only for armeabi.</p>

<h3>main.c</h3>



<pre class="no-pretty-print">

APP_PLATFORM := android-10

</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>The following includes correspond to the libraries, both shared and static,

enumerated in <code>Android.mk</code>.</p>

<pre class="fragment">#include &lt;EGL/egl.h&gt;

enumerated in {@code Android.mk}.</p>



<pre class="no-pretty-print">

#include &lt;EGL/egl.h&gt;

#include &lt;GLES/gl.h&gt;





#include &lt;android/sensor.h&gt;

#include &lt;android/log.h&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

simplifies handling of <code>NativeActivity</code> 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

simplifies handling of {@code NativeActivity} callbacks.</p>



<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>

<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();
@@ -110,21 +175,29 @@ state-&gt;userData = &amp;engine; 
state-&gt;onAppCmd = engine_handle_cmd;

state-&gt;onInputEvent = engine_handle_input;

engine.app = state;

</pre><p>The application prepares to start monitoring the sensors, using the

APIs in <code>sensor.h</code>.</p>

<pre class="fragment">    engine.sensorManager = ASensorManager_getInstance();

</pre>



<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 =

                    ASensorManager_getDefaultSensor(engine.sensorManager,

                        ASENSOR_TYPE_ACCELEROMETER);

    engine.sensorEventQueue =

                    ASensorManager_createEventQueue(engine.sensorManager,

                        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

<code>android_native_app_glue</code>, which checks to see whether they match

any <code>onAppCmd</code> events defined in <code>android_main</code>. When a

{@code android_native_app_glue}, which checks to see whether they match

any {@code onAppCmd} events defined in {@code android_main}. When a

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.

        int ident;

        int events;
@@ -165,9 +238,12 @@ match occurs, the message is sent to the handler for execution.</p> 
            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>

<pre class="fragment">    if (engine.animating) {

<pre class="no-pretty-print">

    if (engine.animating) {

        // Done with events; draw next animation frame.

        engine.state.angle += .01f;

        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.

        engine_draw_frame(&amp;engine);

    }

} </pre> </div></div><!-- contents -->

</div><!-- doc-content -->

<!-- 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>
 
}

</pre>
 
 No newline at end of file

docs/html-ndk/ndk/guides/sample_teapot.jd

+247 −123

File changed.

Preview size limit exceeded, changes collapsed.