【翻译】(14)Stable APIs

-----------------

英文文档见android-ndk-r5b的documentation.html

属于Android Native Development Kit (NDK)的一部分

见http://developer.android.com/sdk/ndk/（需要代理）

翻译仅个人见解

-----------------

 

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（注：CM是一个profile标识符，意思是Common，还有一个profile叫CL，意思是Common-Lite，详细请搜索官方文档http://www.khronos.org/registry/gles/specs/1.1/es_cm_spec_1.1.12.pdf）

 

  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采用后者的方案。

 

This API level also provides Android-specific extensions, see the content of <SLES/OpenSLES_Android.h> and <SLES/OpenSLES_AndroidConfiguration.h> for details.

 

这个API级别还提供Android特定的扩展，详细请参见<SLES/OpenSLES_Android.h>和<SLES/OpenSLES_AndroidConfiguration.h>的内容

 

The system library named "libOpenSLES.so" implements the public native audio functions. Use the following to link your modules against it:

 

称为libOpenSLES.so的系统库实现公共原生音频函数。使用以下方法把你的模块链接它：

 

    LOCAL_LDLIBS += -lOpenSLES

 

The Android native application APIs:

 

Android原生应用程序API：

------------------------------------

 

Starting from API level 9, it is possible to entirely write an Android application with native code (i.e. without any Java). That does not mean that your code does not run inside a VM though, and most of the features of the platform will still need to be accessed through JNI.

 

从API级别9开始，可以完全用原生代码书写Android应用程序（即不需要任何Java代码）。但并不意味着你的代码不是运行在虚拟机中，平台的大多数特性仍需要通过JNI来访问。

 

For more information about this topic, please read the dedicated document named docs/NATIVE-ACTIVITY.html (TODO: WRITE DOC).

 

关于这个话题的更多信息，请阅读名为docs/NATIVE-ACTIVITY.html专用文档（待完成：写文档）

 

The following headers correspond to these new native APIs (see comments inside them for more details):

 

以下头文件对应这些新的原生API（更详细请参见它们里面的注释）

 

  <android/native_activity.h>

 

        Activity lifecycle management (and general entry point)

 

        活动生命周期管理(以及常规入口点)

 

  <android/looper.h>

  <android/input.h>

  <android/keycodes.h>

  <android/sensor.h>

 

        To Listen to input events and sensors directly from native code.

 

        从原生代码中直接监听输入事件和传感器。

 

  <android/rect.h>

  <android/window.h>

  <android/native_window.h>

  <android/native_window_jni.h>

 

        Window management, including the ability to lock/unlock the pixel buffer to draw directly into it.

 

窗口管理，包含锁定和解锁像素缓冲器的能力以方便直接绘画它。

 

  <android/configuration.h>

  <android/asset_manager.h>

  <android/storage_manager.h>

  <android/obb.h>

        Direct (read-only) access to assets embedded in your .apk. or the Opaque Binary Blob (OBB) files, a new feature of Android X.X that allows one to distribute large amount of application data outside of the .apk (useful for game assets, for example).

 

        直接（只读）访问嵌入到你的.apk或不透明二进制块（OBB）（注：可能是指一种文件格式）中的资源，一种Android X.X的新特性，允许开发者在.apk外部分发大数据量的应用程序数据（例如对游戏资源有用）（注：因为Android保存.apk的地方一般不能放太多数据，大文件一般存放在sd卡中）

 

All the corresponding functions are provided by the "libandroid.so" library version that comes with API level 9. To use it, use the following:

 

从API级别9开始所有对应的函数由libandroid.so库版本提供。要使用它，使用以下行：

 

    LOCAL_LDLIBS += -landroid