Doc change: move ndk docs jd into main docs tree.

Change-Id: I5c1ac7645dc68c28da97f46babcab5926c38dbea

1 files changed, 501 insertions, 0 deletions

diff --git a/docs/html/ndk/guides/stable_apis.jd b/docs/html/ndk/guides/stable_apis.jd
new file mode 100644
index 0000000..cad02ac
--- /dev/null
+++ b/docs/html/ndk/guides/stable_apis.jd
@@ -0,0 +1,501 @@
+page.title=Android NDK Native APIs
+@jd:body
+
+<div id="qv-wrapper">
+    <div id="qv">
+      <h2>On this page</h2>
+
+      <ol>
+        <li><a href="#purpose">Overview</a></li>
+        <li><a href="#mnu">Major Native API Updates</a><li>
+          <ol>
+        <li><a href="#a3">Android API level 3</a></li>
+        <li><a href="#a4">Android API level 4</a></li>
+        <li><a href="#a5">Android API level 5</a></li>
+        <li><a href="#a8">Android API level 8</a></li>
+        <li><a href="#a9">Android API level 9</a></li>
+        <li><a href="#a14">Android API level 14</a></li>
+        <li><a href="#a18">Android API level 18</a></li>
+          </ol>
+      </ol>
+    </div>
+  </div>
+
+<p>The Android NDK provides a set of native headers and shared library files that has gradually
+increased with successive releases of new Android API levels. This page explains these headers and
+files, and maps them to specific
+<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels"> Android API levels</a>.
+</p>
+
+<h2 id="purpose">Overview</h2>
+<p>There are two basic steps to enable your app to use the libraries that the NDK provides:
+</p>
+
+<ol type ="1">
+<li>Include in your code the headers associated with the libraries you wish to use.</li>
+
+<li>Tell the build system that your native module needs to link against the libraries at load time.
+For example, to link against  {@code /system/lib/libfoo.so}, add the following line to your
+<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a> file:</li>
+
+<pre>
+LOCAL_LDLIBS := -lfoo
+</pre>
+
+<p>To list multiple libraries, use a space as a delimiter. For more information about using the
+{@code LOCAL_LDLIBS} variable, see <a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>.
+</p>
+
+</ol>
+
+<p>For all API levels, the build system automatically links the standard C libraries, the
+standard C++ libraries, real-time extensions, and {@code pthread}; you do not need
+to include them when defining your {@code LOCAL_LDLIBS} variable. For more information about
+the C and C++ libraries, see <a href="#a3">Android API level 3</a>.</p>
+
+<p>The NDK often provides new headers and libraries for new Android releases. These files reside
+under {@code $NDK/platforms/android-&lt;level&gt;/&lt;abi&gt;/usr/include}. When the NDK does not
+have a specific new group of headers and libraries for an Android API level, it means that
+an app targeting that level should use the most recently released NDK assets. For example,
+there was no new release of NDK headers or libraries for Android API levels 6 and 7. Therefore,
+when developing an app targeting Android API level 7, you should use the headers and libraries
+located under {@code android-5/}.</p>
+
+<p>Table 1 shows the correspondence between NDK-supported API levels and Android releases.</p>
+
+<p class="table-caption" id="table1">
+  <strong>Table 1.</strong> NDK-supported API levels and corresponding Android releases.</p>
+<table>
+  <tr>
+    <th scope="col">NDK-supported API level</th>
+    <th scope="col">Android release</th>
+  </tr>
+  <tr>
+    <td>3</td>
+    <td>1.5</td>
+  </tr>
+    <tr>
+    <td>4</td>
+    <td>1.6</td>
+  </tr>
+    <tr>
+    <td>5</td>
+    <td>2.0</td>
+  </tr>
+  <tr>
+    <td>8</td>
+    <td>2.2</td>
+  </tr>
+    <tr>
+    <td>9</td>
+    <td>2.3 through 3.0.x</td>
+  </tr>
+  <tr>
+    <td>12</td>
+    <td>3.1.x</td>
+  </tr>
+  <tr>
+    <td>13</td>
+    <td>3.2</td>
+  </tr>
+  <tr>
+    <td>14</td>
+    <td>4.0 through 4.0.2</td>
+  </tr>
+  <tr>
+    <td>15</td>
+    <td>4.0.3 and 4.0.4</td>
+  </tr>
+    <tr>
+    <td>16</td>
+    <td>4.1 and 4.1.1</td>
+  </tr>
+    <tr>
+    <td>17</td>
+    <td>4.2 and 4.2.2</td>
+  </tr>
+    <tr>
+    <td>18</td>
+    <td>4.3</td>
+  </tr>
+    <tr>
+    <td>19</td>
+    <td>4.4</td>
+  </tr>
+    <tr>
+    <td>21</td>
+    <td>4.4W and 5.0</td>
+</table>
+
+<p>Each new release of NDK headers and libraries for a given Android API level is cumulative; you
+are nearly always safe if you use the most recently released headers when building your app. For
+example, you can use the NDK headers for Android API level 21 for an app targeting API level 16. By doing so, however, you increase your APK's footprint.</p>
+
+<p>
+For more information about Android API levels, see
+<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API Level?</a>.
+</p>
+
+<h2 id="mnu">Major Native API Updates</h2>
+
+<h3 id="a3">Android API level 3</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 1.5 system
+images and above.</p>
+
+<h4>C library</h4>
+<p>The C library headers for Android 1.5 are available through their standard names, such as
+{@code stdlib.h} and {@code stdio.h}. If a header is missing at build time, it's because the
+header is not available on the 1.5 system image.</p>
+
+<h4>C++ library</h4>
+<p>An <em>extremely</em> minimal C++ support API is available. For more
+information on C++ library support, see
+<a href="{@docRoot}ndk/guides/cpp-support.html">C++ Library Support</a>.</p>
+
+<h4>Android-specific log support</h4>
+
+<p>{@code &lt;android/log.h&gt;} contains various definitions that an app can use to send log
+messages to the kernel from native code. For more information about these definitions, see the
+comments in {@code $NDK/platforms/android-3/arch-arm/usr/include/android/log.h}, where {@code $NDK}
+is the root of your NDK installation.</p>
+
+<p>You can write your own wrapper macros to access this functionality. If you wish to perform
+logging, your native module should link to {@code /system/lib/liblog.so}. Implement this
+linking by including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html">
+{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS := -llog
+</pre>
+
+<h4>ZLib compression library</h4>
+<p>You can use the <a href="http://www.zlib.net/manual.html">Zlib compression library</a>
+by including {@code zlib.h} and {@code zconf.h}. You must also link your native
+module against {@code /system/lib/libz.so} by including the following line in your
+<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS := -lz
+</pre>
+
+<h4>Dynamic linker library</h4>
+<p>You can access the Android dynamic linker's {@code dlopen()}, {@code dlsym()}, and
+{@code dlclose()} functions by including {@code dlfcn.h}. You must also link against
+{@code /system/lib/libdl.so} by including the following line in your
+<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS := -ldl
+</pre>
+
+<h3 id="a4">Android API level 4</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 1.6 system
+images and above.</p>
+
+<h4>OpenGL ES 1.x Library</h4>
+<p>The standard OpenGL ES headers {@code gl.h} and {@code glext.h} contain
+the declarations necessary for performing OpenGL ES 1.x rendering calls from native code.</p>
+
+<p>To use these headers, link your native module to {@code /system/lib/libGLESv1_CM.so} by
+including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html">
+{@code Android.mk}</a> file:</p>
+</p>
+
+<pre>
+LOCAL_LDLIBS := -lGLESv1_CM
+</pre>
+<p>All Android-based devices support OpenGL ES 1.0, because Android provides an Open GL 1.0-capable
+software renderer that can be used on devices without GPUs.</p>
+<p>Only Android devices that have the necessary GPU fully support OpenGL ES 1.1. An app can
+query the OpenGL ES version string and extension string to determine whether the current device
+supports the features it needs. For information on how to perform this query, see the description of
+<a href="http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml">{@code glGetString()}</a>
+in the OpenGL specification.</p>
+
+<p>Additionally, you must put a
+<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code
+&lt;uses-feature&gt;}</a> tag in your manifest file to indicate the version of
+<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>
+that your application requires.</p>
+
+<p>The <a href="#egl">EGL APIs</a> are only available starting from API level 9. You can, however,
+use the VM to perform some of the operations that you would get from those APIS. These operations
+include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see
+<a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html">
+Introducing GLSurfaceView</a>.</p>
+
+<p>The san-angeles sample application provides an example of how to perform these operations,
+rendering each frame in native code. This sample is a small Android port of the excellent
+<a href="http://jet.ro/visuals/san-angeles-observation/">San Angeles Observation</a> demo
+program.</p>
+
+<h3 id="a5">Android API level 5</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 2.0 system
+images and above.</p>
+
+<h4>OpenGL ES 2.0 library:</h4>
+<p>The standard OpenGL ES 2.0 headers {@code &lt;GLES2/gl2.h&gt;} and {@code &lt;GLES2/gl2ext.h&gt;}
+contain the declarations needed for performing OpenGL ES 2.0 rendering calls from native code.
+These rendering calls provide the ability to use the GLSL language to define and use vertex and
+fragment shaders.</p>
+
+<p>To use OpenGL ES 2.0, link your native module to {@code /system/lib/libGLESv2.so} by
+including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html">
+{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS := -lGLESv2
+</pre>
+
+<p>Not all devices support OpenGL ES 2.0. An app can query the OpenGL
+ES version string and extension string to determine whether the current device
+supports the features it needs. For information on how to perform this query, see the description of
+<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml">
+{@code glGetString()}</a> in the OpenGL specification.</p>
+
+<p>Additionally, you must put a
+<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code
+&lt;uses-feature&gt;}</a> tag in your manifest file to indicate which version of OpenGL ES your
+application requires. For more information about the OpenGL ES settings for
+{@code &lt;uses-feature&gt;}, see
+<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p>
+
+<p>The hello-gl2 sample application provies a basic example of how to use OpenGL ES 2.0 with the
+NDK.</p>
+
+<p>The <a href="#egl">EGL APIs</a> are only available starting from API level 9. You can, however,
+use the VM to perform some of the operations that you would get from those APIs. These operations
+include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see
+<a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html">
+Introducing GLSurfaceView</a>.</p>
+
+<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 2.0 hardware
+emulation. Running and testing code that uses this API requires a real device with hardware that can
+support OpenGL ES 2.0.</p>
+
+<h3 id="a8">Android API level 8</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 2.2 system
+images and above.</p>
+
+<h4>jnigraphics</h4>
+<p>The {@code jnigraphics} library exposes a C-based interface that allows native code to reliably access
+the pixel buffers of Java bitmap objects. The workflow for using {@code jnigraphics} is as follows:
+</p>
+
+<ol type="1">
+<li>Use {@code AndroidBitmap_getInfo()} to retrieve information from JNI, such as width and height,
+about a given bitmap handle.</li>
+
+<li>Use {@code AndroidBitmap_lockPixels()} to lock the pixel buffer and retrieve a pointer to it.
+Doing so ensures that the pixels do not move until the app calls
+{@code AndroidBitmap_unlockPixels()}.</li>
+
+<li>In native code, modify the pixel buffer as appropriate for its pixel format, width, and other
+characteristics.</li>
+
+<li>Call {@code AndroidBitmap_unlockPixels()} to unlock the buffer.</li>
+</ol>
+
+<p>To use {@code jnigraphics}, include the {@code &lt;bitmap.h&gt;} header in your source code, and
+link against {@code jnigraphics} by including the following line in your
+<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS += -ljnigraphics
+</pre>
+
+<p>Additional details about this feature are in the comments of the {@code bitmap.h} file.
+
+<h3 id="a9">Android API level 9</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 2.3 system
+images and above.</p>
+
+<h4 id="egl"> EGL</h4>
+<p>EGL provides a native platform interface for allocating and managing OpenGLES surfaces.
+For more information about its features, see <a href="http://www.khronos.org/egl">
+EGL Native Platform Interface</a>.</p>
+
+<p>EGL allows you to perform the following operations from native code:</p>
+
+<ul>
+<li>List supported EGL configurations.</li>
+<li>Allocate and release OpenGLES surfaces.</li>
+<li>Swap or flip surfaces.</li>
+</ul>
+
+<p>The following headers provide EGL functionality:</p>
+<ul>
+   <li>{@code EGL/egl.h}: the main EGL API definitions.</li>
+   <li>{@code EGL/eglext.h}: EGL extension-related definitions.</li>
+</ul>
+
+<p>To link against the system's EGL library, add the following line to your
+<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS += -lEGL
+</pre>
+
+<h4 id="osl">OpenSL ES</h4>
+<p>Android native audio handling is based on the Khronos Group OpenSL ES 1.0.1 API.</p>
+
+<p>The standard OpenSL ES headers {@code OpenSLES.h} and {@code OpenSLES_Platform.h} contain
+the declarations necessary for performing audio input and output from the native side of Android.
+The NDK distribution of the OpenSL ES also provides Android-specific extensions. For information
+about these extensions, see the comments in {@code OpenSLES_Android.h} and
+{@code OpenSLES_AndroidConfiguration.h}.</p>
+
+
+<p>The system library {@code libOpenSLES.so} implements the public native audio functions. Link
+against it by adding the following line to your <a href="{@docRoot}ndk/guides/android_mk.html">
+{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS += -lOpenSLES
+</pre>
+
+<p>For more information about the OpenSL ES API, refer to
+{@code $NDK/docs/Additional_library_docs/opensles/index.html}, where {@code $NDK} is your NDK
+installation root directory.</p>
+
+<h4>Android native application APIs</h4>
+<p>Starting from API level 9, you can write an entire Android app with native code, without using
+any Java.</p>
+
+<p class="note"><strong>Note: </strong>Writing your app in native code is not, in itself, enough
+for your app to run in the VM. Moreover, your app must still access most features of the Android
+platform via JNI.</p>
+
+<p>This release provides the following native headers:</p>
+<ul>
+<li>{@code &lt;native_activity.h&gt;}</li>
+<li>{@code &lt;looper.h&gt;}</li>
+<li>{@code &lt;input.h&gt;}</li>
+<li>{@code &lt;keycodes.h&gt;}</li>
+<li>{@code &lt;sensor.h&gt;}</li>
+<li>{@code &lt;rect.h&gt;}</li>
+<li>{@code &lt;window.h&gt;}</li>
+<li>{@code &lt;native_window.h&gt;}</li>
+<li>{@code &lt;native_window_jni.h&gt;}</li>
+<li>{@code &lt;configuration.h&gt;}</li>
+<li>{@code &lt;asset_manager.h&gt;}</li>
+<li>{@code &lt;storage_manager.h&gt;}</li>
+<li>{@code &lt;obb.h&gt;}</li>
+</ul>
+
+<p>For more information about these headers, see the
+<a href="{@docRoot}ndk/reference/index.html">NDK API Reference documentation</a>, as well as
+the comments in the headers, themselves. Also, for more information about the larger topic of
+writing native apps, see <a href="{@docRoot}ndk/guides/concepts.html#naa">
+Native Activities and Applications</a>.
+
+<p>When you include one or more of these headers, you must also link against the
+{@code libandroid.so} library. To link against {@code libandroid.so}, include the following line in
+your <a href="{@docRoot}ndk/guides/android_mk.html"> {@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS += -landroid
+</pre>
+
+<h3 id="a14">Android API level 14</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 4.0 system
+images and above.</p>
+
+<h4>OpenMAX AL</h4>
+<p>Android native multimedia handling is based on Khronos Group OpenMAX AL 1.0.1 API.</p>
+<p>The standard OpenMAX AL headers {@code &lt;OMXAL/OpenMAXAL.h&gt;} and
+{@code &lt;OMXAL/OpenMAXAL_Platform.h&gt;} contain the declarations necessary for performing
+multimedia output from the native side of Android.</p>
+
+<p>The NDK distribution of OpenMAX AL also provides Android-specific extensions. For information
+about these extensions, see the comments in {@code OpenMAXAL_Android.h}.</p>
+
+<p>The system library {@code libOpenMAXAL.so} implements the public native multimedia functions.
+To link against this library, include the following line in your
+<a href="{@docRoot}ndk/guides/android_mk.html"> {@code Android.mk}</a> file:</p>
+
+<pre class="fragment">    LOCAL_LDLIBS += -lOpenMAXAL
+</pre><p>For more information about this topic, see {@code $NDK/docs/openmaxal/index.html},
+where {@code $NDK} is the root directory of your NDK installation.</p>
+
+<h4>OpenSL ES</h4>
+<p>OpenSL ES support for this Android API level adds PCM support. For more information about
+OpenSL ES support in the NDK, see <a href="#osl">OpenSL ES</a>.</p>
+
+<h3 id="a18">Android API level 18</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 4.3 system
+images and above.</p>
+
+<h4>OpenGL ES 3.0</h4>
+
+<p>The standard OpenGL ES 3.0 headers {@code gl3.h} and {@code gl3ext.h} contain the declarations
+needed for performing OpenGL ES 3.0 rendering calls from native code. These rendering calls provide
+the ability to use the GLSL language to define and use vertex and fragment shaders.
+
+<p>To use OpenGL ES 3.0, link your native module against {@code /system/lib/libGLESv3.so} by
+including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html">
+{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS := -lGLESv3
+</pre>
+
+<p>Not all devices support OpenGL ES 3.0. An app can query the OpenGL
+ES version string and extension string to determine whether the current device
+supports the features it needs. For information on how to perform this query, see the description of
+<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml">
+{@code glGetString()}</a> in the OpenGL specification.</p>
+
+<p>Additionally, you must put a
+<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code
+&lt;uses-feature&gt;}</a> tag in your manifest file to indicate which version of OpenGL ES your
+application requires. For more information about the OpenGL ES settings for
+{@code &lt;uses-feature&gt;}, see
+<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p>
+
+<p>The gles3jni sample application provides a basic example of how to use OpenGL ES 3.0 with the
+NDK.</p>
+
+<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 3.0 hardware
+emulation. Running and testing code that uses this API requires a real device with hardware that can
+support OpenGL ES 3.0.</p>
+
+
+<h3 id="a18">Android API level 21</h3>
+<p>The NDK provides the following APIs for developing native code that runs on Android 4.3 system
+images and above.</p>
+
+<h4>OpenGL ES 3.1</h4>
+
+<p>The standard OpenGL ES 3.1 headers {@code gl31.h} and {@code gl3ext.h} contain the declarations
+needed for performing OpenGL ES 3.1 rendering calls from native code. These rendering calls provide
+the ability to use the GLSL language to define and use vertex and fragment shaders.
+
+<p>To use OpenGL ES 3.1, link your native module against {@code /system/lib/libGLESv3.so} by
+including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html">
+{@code Android.mk}</a> file:</p>
+
+<pre>
+LOCAL_LDLIBS := -lGLESv3
+</pre>
+
+<p>Not all devices support OpenGL ES 3.1. An app can query the OpenGL
+ES version string and extension string to determine whether the current device
+supports the features it needs. For information on how to perform this query, see the description of
+<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml">
+{@code glGetString()}</a> in the OpenGL specification.</p>
+
+<p>Additionally, you must put a
+<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code
+&lt;uses-feature&gt;}</a> tag in your manifest file to indicate which version of OpenGL ES your
+application requires. For more information about the OpenGL ES settings for
+{@code &lt;uses-feature&gt;}, see
+<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p>
+
+<p>The gles3jni sample application provides a basic example of how to use OpenGL ES 3.1 with the
+NDK.</p>
+
+<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 3.1 hardware
+emulation. Running and testing code that uses this API requires a real device with hardware that can
+support OpenGL ES 3.1.</p>
+