Android NDK Stable APIs:
Android NDK稳定API：
========================
This is the list of stable APIs/ABIs exposed by the Android NDK.
这是Android NDK暴露的稳定API/ABI列表
I. Purpose:
一、目的：
-----------
Each API corresponds to a set of headers files, and a shared library file that contains the corresponding implementation, and which must be linked against by your native code.
每个API对应一组头文件，以及包含对应实现的动态库，它必须被你的原生代码链接。
For example, to use system library "Foo", you would include a header like <foo.h> in your code, then tell the build system that your native module needs to link to /system/lib/libfoo.so at load-time by adding the following line to your Android.mk file:
例如，为了使用系统库“Foo”，你会在你的代码中包含头文件如<foo.h>，然后通过添加以下行到你的Android.mk文件以告诉构建系统你的原生模块需要在加载期链接到/system/lib/libfoo.so：
LOCAL_LDLIBS := -lfoo
Note that the build system automatically links the C library, the Math library and the C++ support library to your native code, there is no need to list them in a LOCAL_LDLIBS line.
注意构建系统自动链接C库，数学库以及C++支持库到你的原生代码，所以没必要在LOCAL_LDLIBS配置行中列出它们。
There are several "API Levels" defined. Each API level corresponds to a given Android system platform release. The following levels are currently supported:
定义了几个API级别。每个API级别对应一个给定的Android系统平台发布版。以下级别是当前支持的：
android-3 -> Official Android 1.5 system images
android-3 -> 官方Android 1.5系统镜像
android-4 -> Official Android 1.6 system images
android-4 -> 官方Android 1.6系统镜像
android-5 -> Official Android 2.0 system images
android-5 -> 官方Android 2.0系统镜像
android-6 -> Official Android 2.0.1 system images
android-6 -> 官方Android 2.0.1系统镜像
android-7 -> Official Android 2.1 system images
android-7 -> 官方Android 2.1系统镜像
android-8 -> Official Android 2.2 system images
android-8 -> 官方Android 2.2系统镜像
android-9 -> Official Android 2.3 system images
android-9 -> 官方Android 2.3系统镜像
Note that android-6 and android-7 are the same as android-5 for the NDK, i.e. they provide exactly the same native ABIs!
注意android-6和android-7对应的NDK和android-5相同，即它们提供完全相同的原生ABI！
IMPORTANT:
The headers corresponding to a given API level are now located under $NDK/platforms/android-<level>/arch-arm/usr/include
重要：
对应给定API级别的头文件现在位于$NDK/platforms/android-<level>/arch-arm/usr/include目录下
II. Android-3 Stable Native APIs:
二、Android-3稳定原生API：
---------------------------------
All the APIs listed below are available for developing native code that runs on Android 1.5 system images and above.
下面列出的所有API对于开发运行在Android 1.5系统镜像和更高的原生代码可用。
The C Library:
C库：
--------------
The C library headers, as they are defined on Android 1.5 are available through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header is not there at build time, it's because its implementation is not available on a 1.5 system image.
C库头文件，正如它们在Android 1.5所定义的那样通过它们的标准名称（<stdlib.h>、<stdio.h>等等）可用。如果一个头文件在构建期不在那里，是因为它的实现在1.5系统镜像上不可用。
The build system automatically links your native modules to the C library, you don't need to add it to LOCAL_LDLIBS.
构建系统自动地链接你的原生方法到C库，你不需要添加它到LOCAL_LDLIBS。
Note that the Android C library includes support for pthread (<pthread.h>), so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time extensions (-lrt on typical Linux distributions).
注意Android C库包含对pthread（<pthread.h>）的支持，所以LOCAL_LIBS := -lpthread是不需要的。对于实时扩展（在典型Linux分发版中的-lrt）同样不需要。
** VERY IMPORTANT NOTE: ******************************************************
非常重要的注意事项：
The kernel-specific headers in <linux/...> and <asm/...> are not considered stable at this point. Avoid including them directly because some of them are likely to change in future releases of the platform. This is especially true for anything related to specific
hardware definitions.
<linux/...>和<asm/...>的内核特定头文件此时还不认为是稳定的。避免直接包含它们，因为它们中有一些可能在未来的平台发布版中将会被修改。对于与特定硬件定义相关的任何东西尤其如此。
******************************************************************************
The Math Library:
数学库：
-----------------
<math.h> is available, and the math library is automatically linked to your native modules at build time, so there is no need to list "-lm" through LOCAL_LDLIBS.
<math.h>可用，而且数学库在构建期自动地链接到你的原生模块，所以不需要通过LOCAL_LDLIBS列出-lm。
C++ Library:
C++库
------------
An *extremely* minimal C++ support API is available. For Android 1.5, this is currently limited to the following headers:
一个极其小的C++支持API可用。对于Android 1.5，它当前被限制为以下的头文件：
<cstddef>
<new>
<utility>
<stl_pair.h>
They may not contain all definitions required by the standard. Notably, support for C++ exceptions and RTTI is not available with Android 1.5 system images.
它们可能包含标准所需的所有定义。值得注意的是，C++异常和RTTI（注：Runtime Type Information，运行时类型信息）对于Android 1.5系统镜像不可用。
The C++ support library (-lstdc++) is automatically linked to your native modules too, so there is no need to list it through LOCAL_LDLIBS
C++支持库（-lstdc++）也被自动链接到你的原生模块，所以没必要通过LOCAL_LDLIBS列出它。
Android-specific Log Support:
Android特定的日志支持：
-----------------------------
<android/log.h> contains various definitions that can be used to send log messages to the kernel from your native code. Please have a look at its content in (build/platforms/android-3/common/include/android/log.h), which contain many informative comments on
how to use it.
<android/log.h>包含不同的定义，可以用于从你的原生代码中发送日志消息到内核。请看看它的内容（build/platforms/android-3/common/include/android/log.h），它包含关于许多如何使用它的有用信息的注释。
You should be able to write helpful wrapper macros for your own usage to access this facility.
你应该有能力书写有用的封装宏供你自己使用以访问这个工具。
If you use it, your native module should link to /system/lib/liblog.so with:
如果你使用到它，你的原生模块应该用以下方法链接到/system/lib/liblog.so：
LOCAL_LDLIBS := -llog
ZLib Compression Library:
ZLib压缩库：
-------------------------
<zlib.h> and <zconf.h> are available and can be used to use the ZLib compression library. Documentation for it is at the ZLib page:
<zlib.h>和<zconf.h>可用，可以通过它们使用ZLib压缩库。相关文档在ZLib页面：
http://www.zlib.net/manual.html
If you use it, your native module should link to /system/lib/libz.so with:
如果你使用它，你的原生模块应该用以下方法链接到/system/lib/libz.so：
LOCAL_LDLIBS := -lz
Dynamic Linker Library:
动态链接器库
-----------------------
<dlfcn.h> is available and can be used to use the dlopen()/dlsym()/dlclose() functions provided by the Android dynamic linker. You will need to link against /system/lib/libdl.so with:
<dlfcn.h>可用，可以通过它使用由Android动态链接器提供的dlopen()/dlsym()/dlclose()函数。你将需要用以下方法链接到/system/lib/libdl.so：
LOCAL_LDLIBS := -ldl
III. Android-4 Stable Native APIs:
三、Android-4稳定原生API：
----------------------------------
All the APIs listed below are available for developing native code that runs on Android 1.6 system images and above,
以下列出的所有API对于开发运行在Android 1.6系统镜像和以上的原生代码可用。
The OpenGL ES 1.x Library:
OpenGL ES 1.x库：
--------------------------
The standard OpenGL ES headers <GLES/gl.h> and <GLES/glext.h> contain the declarations needed to perform OpenGL ES 1.x rendering calls from native code.
标准OpenGL ES头文件<GLES/gl.h>和<GLES/glext.h>包含从原生代码中执行OpenGL ES 1.x渲染调用所需的声明。
If you use them, your native module should link to /system/lib/libGLESv1_CM.so as in:
如果你需要它们，你的原生模块应该像这样链接到/system/lib/libGLESv1_CM.so
LOCAL_LDLIBS := -lGLESv1_CM.so
The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs. Please note that:
这里1.x指的是OpenGL ES API的版本1.0和1.1.请注意：
- OpenGL ES 1.0 is supported on *all* Android-based devices.
- 所有基于Android的设备支持OpenGL ES 1.0。
- OpenGL ES 1.1 is fully supported only on specific devices that have the corresponding GPU.
- 只有拥有相应GPU的特定设备才完全支持OpenGL ES 1.1。
This is because Android comes with a 1.0-capable software renderer that can be used on GPU-less devices.
这是因为Android来自拥有1.0能力的软件渲染器，可以用于缺少GPU的设备。（注：OpenGL是系统级函数库，不同于一般的应用库，它只是一组严格规定的API，既可以调用驱动程序进行硬件加速，也可以用纯软件的方法实现。OpenGL ES是OpenGL for Embedded Systems的缩写，不同于glx、wgl和agl，它是供嵌入式设备使用的经过重新设计的标准化接口，而非扩展接口）
Developers should query the OpenGL ES version string and extension string to know if the current device supports the features they need. See the description of glGetString() in the specification to see how to do that:
开发者应该查询OpenGL ES版本字符串和扩展字符串以得知当前的设备是否支持所需要的特性。参考规范中的glGetString()描述以查看如何做到这一点：
http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml
Additionally, developers must put a <uses-feature> tag in their manifest file to indicate which version of OpenGL ES their application requires. See the documentation linked below for details:
另外，开发者必须在他们的清单文件中放置一个<uses-feature>标签以表明它们的程序需要哪个版本的OpenGL ES。详细请参考以下文档链接：
http://developer.android.com/guide/topics/manifest/uses-feature-element.html
Please note that, at the moment, native headers and libraries for the EGL APIs are *not* available. EGL is used to perform surface creation and flipping (instead of rendering). The corresponding operations must be performed in your VM application instead, for
example with a GLSurfaceView, as described here:
请注意，现在，EGL API的原生头文件和库不可用。EGL用于执行表面创建和翻转（而非渲染）。对应的操作必须改为在你的虚拟机应用程序中执行，例如使用GLSurfaceView，像这里介绍的那样：
http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html
The "san-angeles" sample application shows how you can do that, while rendering each frame in native code. This is a small Android port of the excellent "San Angeles Observation" demo program. For more information about it, see:
san-angeles例子应用程序展示你如何在原生代码中渲染每一帧以做到那点。这是绝妙的“San Angeles观察”演示程序的小型Android移植版。更多相关信息请参考：
http://jet.ro/visuals/san-angeles-observation/
IV. Android-5 Stable Native APIs:
四、Android-5稳定原生API：
----------------------------------
All the APIs listed below are available for developing native code that runs on Android 2.0 system images and above.
下面列出的所有APi对于开发运行于Android 2.0系统镜像和以上的原生代码可用。
The OpenGL ES 2.0 Library:
OpenGL ES 2.0库：
--------------------------
The standard OpenGL ES 2.0 headers <GLES2/gl2.h> and <GLES2/gl2ext.h> contain the declarations needed to perform OpenGL ES 2.0 rendering calls from native code. This includes the ability to define and use vertex and fragment shaders using the GLSL language.
标准的OpenGL ES 2.0头文件<GLES2/gl2.h>和<GLES2/gl2ext.h>包含从原生代码中执行OpenGL ES 2.0渲染调用所需的声明。它包含通过GLSL语言定义和使用顶点和碎片渲染器的能力。
If you use them, your native module should link to /system/lib/libGLESv2.so as in:
如果你使用它们，你的原生模块应该像这样链接到/system/lib/libGLESv2.so：
LOCAL_LDLIBS := -lGLESv2.so
Not all devices support OpenGL ES 2.0, developers should thus query the implementation's version and extension strings, and put a <uses-feature> tag in their Android manifest. See Section III above for details.
不是所有设备都支持OpenGL ES 2.0，因此开发者应该查询实现的版本和扩展字符串，并且把<uses-feature>标签放进它们的Android清单中。详细请参考上面的第三节。
Please note that, at the moment, native headers and libraries for the EGL APIs are *not* available. EGL is used to perform surface creation and flipping (instead of rendering). The corresponding operations must be performed in your VM application instead, for
example with a GLSurfaceView, as described here:
请注意，现在，EGL API的原生头文件和库不可用。EGL用于执行表面创建和翻转（而非渲染），相应的操作必须改为在你的虚拟机应用程序中执行，例如使用GLSurfaceView，这如这里描述的那样：
http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html
The "hello-gl2" sample application demonstrate this. It is used to draw a very simple triangle with the help of a vertex and fragment shaders.
hello-gl2例子程序展示这点。它用于在定点和碎片渲染器的帮助下绘画非常简单的三角形。
IMPORTANT NOTE:
The Android emulator does not support OpenGL ES 2.0 hardware emulation at this time. Running and testing code that uses this API requires a real device with such capabilities.
重要注意事项：
目前Android模拟器不支持OpenGL ES 2.0硬件模拟。使用这个API的代码的运行和测试需要拥有这种能力的真实机器。
IV. Android-8 Stable Native APIs:
四、Android-8稳定原生API：
----------------------------------
All the APIs listed below are available for developing native code that runs on Android 2.2 system images and above.
下面列出的所有API对于开发运行于Android 2.2系统镜像和以上的原生代码可用。
The 'jnigraphics' Library:
jnigraphics库
--------------------------
This is a tiny library that exposes a stable, C-based, interface that allows native code to reliably access the pixel buffers of Java bitmap objects.
这是一个小型库，暴露稳定的，基于C的接口，允许原生代码可靠地访问Java位图对象的像素缓冲器。
To use it, include the <android/bitmap.h> header in your source code, and and link to the jnigraphics library as in:
为了使用它，在你的源代码中包含<android/bitmap.h>头文件，并且像这样链接到jnigraphics库：
LOCAL_LDLIBS += -ljnigraphics
For details, read the source header at the following location:
详细请阅读以下位置的源头文件：
build/platforms/android-8/arch-arm/usr/include/android/bitmap.h
Briefly, typical usage should look like:
简单说，典型的用法看起来应该是这样：
1/ Use AndroidBitmap_getInfo() to retrieve information about a given bitmap handle from JNI (e.g. its width/height/pixel format)
1、使用AndroidBitmap_getInfo()从JNI中取出关于给定位图句柄的信息（例如它的宽、高、像素格式）
2/ Use AndroidBitmap_lockPixels() to lock the pixel buffer and retrieve a pointer to it. This ensures the pixels will not move until AndroidBitmap_unlockPixels() is called.
2、使用AndroidBitmap_lockPixels()锁定像素缓冲器，并且获得指向它的指针。这确保像素将不会被改动，直至AndroidBitmap_unlockPixels()被调用。
3/ Modify the pixel buffer, according to its pixel format, width, stride, etc.., in native code.
3、在原生代码中，根据它的像素格式、宽、步长等等，修改像素缓冲器。
4/ Call AndroidBitmap_unlockPixels() to unlock the buffer.
4、调用AndroidBitmap_unlockPixels()解除缓冲器的锁定。
V. Android-9 Stable Native APIs:
五、Android-9稳定原生API
--------------------------------
All the APIs listed below are available for developing native code that runs on Android > 2.2 system images and above.
下面列出的所有API对于开发运行在Android大于2.2的系统镜像和以上的原生代码可用。
The OpenSL ES native audio Library:
OpenSL ES原生音频库：
-----------------------------------
Android native audio is based on Khronos Group OpenSL ES? 1.0.1.
Android原生音频库是基于Khronos Group OpenSL ES 1.0.1。
The standard OpenSL ES headers <SLES/OpenSLES.h> and <SLES/OpenSLES_Platform.h> contain the declarations needed to perform audio input and output from the native side of Android.
标准的OpenSL ES头文件<SLES/OpenSLES.h>和<SLES/OpenSLES_Platform.h>包含从Android的原生方执行音频输入和输出所需的声明。
NOTE: Despite the fact that the current OpenSL ES specification uses <OpenSLES.h> to include these headers, Khronos is currently modifying the document to recommend <SLES/OpenSLES.h> instead, hence the later approach was adopted for Android.
注意：尽管事实上当前OpenSL ES规范使用<OpenSLES.h>包含这些头文件，但是现在Khronos修改文档并建议用<SLES/OpenSLES.h>取代之，因此Android采用后者的方案。