APIs nativas do Android NDK

O Android NDK oferece um conjunto de cabeçalhos nativos e arquivos de biblioteca compartilhada que cresceram gradualmente com os sucessivos lançamentos de novos níveis para a Android API. Esta página explica esses cabeçalhos e arquivos e mapeia-os a níveis específicos da Android API.

Visão geral

Há duas etapas básicas para se habilitar o aplicativo a usar as bibliotecas que o NDK oferece:

  1. Inclua no seu código os cabeçalhos associados às bibliotecas que deseja usar.
  2. Informe o sistema de compilação de que seu módulo nativo precisa se vincular às bibliotecas em tempo de carregamento. Por exemplo, para vincular a /system/lib/libfoo.so, adicione a linha a seguir ao arquivo Android.mk:
  3. LOCAL_LDLIBS := -lfoo
    

    Para listar diversas bibliotecas, use um espaço como delimitador. Para saber mais como usar a variável LOCAL_LDLIBS, consulte Android.mk.

Para as APIs de todos os níveis, o sistema de compilação vincula-se automaticamente às bibliotecas C padrão, às bibliotecas C++ padrão, a extensões de tempo real e a pthread. Não é necessário incluí-las ao definir a variável LOCAL_LDLIBS. Para obter mais informações sobre as bibliotecas C e C++, consulte Android API de nível 3.

Muitas vezes, o NDK oferece novos cabeçalhos e bibliotecas para novas versões do Android. Esses arquivos ficam em $NDK/platforms/android-<level>/<abi>/usr/include. Quando o NDK não tem um novo grupo de cabeçalhos e bibliotecas específico para um nível da Android API, significa que o aplicativo direcionado a esse nível deve usar os ativos mais recentes do NDK. Por exemplo, não houve nova versão dos cabeçalhos nem das bibliotecas do NDK para as Android APIs de nível 6 e 7. Portanto, ao desenvolver um aplicativo voltado à Android API de nível 7, você deve usar os cabeçalhos e bibliotecas localizados em android-5/.

A Tabela 1 mostra a correspondência entre os níveis da API suportados pelo NDK e as versões do Android.

Tabela 1. Níveis da API suportados pelo NDK e versões do Android correspondentes.

Nível da API suportado pelo NDK Versão do Android
3 1.5
4 1.6
5 2.0
8 2.2
9 2.3 até 3.0.x
12 3.1.x
13 3.2
14 4.0 até 4.0.2
15 4.0.3 e 4.0.4
16 4.1 e 4.1.1
17 4.2 e 4.2.2
18 4.3
19 4.4
21 4.4W e 5.0

Cada nova versão dos cabeçalhos e das bibliotecas do NDK para determinado nível da Android API é cumulativa: você quase sempre terá bons resultados se usar os cabeçalhos lançados mais recentemente ao compilar o seu aplicativo. Por exemplo, é possível usar os cabeçalhos do NDK para a Android API de nível 21 em um aplicativo voltado à API de nível 16. Porém, fazendo isso, aumenta-se a área de ocupação do APK.

Para obter mais informações sobre os níveis da Android API, consulte O que é um nível de API?.

Principais atualizações da API nativa

Android API de nível 3

O NDK fornece as seguintes APIs para desenvolver código nativo que seja executado em imagens do sistema do Android 1.5 e posteriores.

Biblioteca C

Os cabeçalhos da biblioteca C para Android 1.5 são disponibilizados com seu nome padrão, como stdlib.h e stdio.h. Se um cabeçalho estiver ausente em tempo de compilação, isso acontece porque ele não está disponível nas imagens do sistema do 1.5.

Biblioteca C++

Há disponível uma API de compatibilidade com C++ extremamente mínima. Para obter mais informações sobre a compatibilidade com a biblioteca C++, consulte Compatibilidade com a biblioteca C++.

Compatibilidade com registros específicos do Android

<android/log.h> contém diversas definições que um aplicativo pode usar para enviar mensagens de registro ao kernel a partir do código nativo. Para obter mais informações sobre essas definições, veja os comentários em $NDK/platforms/android-3/arch-arm/usr/include/android/log.h, em que $NDK é a raiz da instalação do NDK.

Você pode gravar macros de invólucro próprios para acessar esse recurso. Se quiser fazer registros, seu módulo nativo deve se vincular a /system/lib/liblog.so. Implemente esse vínculo incluindo a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS := -llog

Biblioteca de compressão ZLib

Você pode usar a biblioteca de compressão ZLib inclusive zlib.h e zconf.h. Além disso, você deve vincular seu módulo nativo a /system/lib/libz.so inclusive a seguinte linha no arquivo Android.mk:

LOCAL_LDLIBS := -lz

Biblioteca do vinculador dinâmico

Você pode acessar as funções dlopen(), dlsym() e dlclose() do vinculador dinâmico do Android inclusive dlfcn.h. Você ainda deve vincular a /system/lib/libdl.so inclusive a seguinte linha no arquivo Android.mk:

LOCAL_LDLIBS := -ldl

Android API de nível 4

O NDK fornece as seguintes APIs para desenvolver código nativo executado em imagens do sistema do Android 1.6 e em posteriores.

Biblioteca do OpenGL ES 1.x

Os cabeçalhos gl.h e glext.h padrão do OpenGL ES contêm as declarações necessárias para realizar as chamadas de renderização do OpenGL ES 1.x a partir do código nativo.

Para usá-los, vincule seu módulo nativo a /system/lib/libGLESv1_CM.so inclusive a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS := -lGLESv1_CM

Todos os dispositivos baseados em Android são compatíveis com OpenGL ES 1.0, porque o Android fornece um renderizador de software preparado para Open GL 1.0 que pode ser usado em dispositivos sem GPUs.

Somente dispositivos Android que têm o GPU necessário oferecem compatibilidade integral com OpenGL ES 1.1. Um aplicativo pode consultar a string de versão e a de extensão do OpenGL ES para determinar se o dispositivo atual aceita os recursos de que o aplicativo precisa. Para obter informações sobre como realizar essa consulta, consulte a descrição de glGetString() na especificação do OpenGL.

Além disso, você deve colocar uma tag <uses-feature> no seu arquivo de manifesto para indicar a versão do OpenGL ES de que seu aplicativo precisa.

As APIs EGL só estão disponíveis a partir da API de nível 9. No entanto, é possível usar a VM para realizar algumas das operações que se obteria com essas APIs. Essas operações abrangem a criação e inversão de superfícies. Para ver um exemplo de como usar GLSurfaceView, consulte Introdução ao GLSurfaceView.

O exemplo de aplicativo san-angeles fornece uma demonstração de como realizar essas operações, renderizando cada quadro no código nativo. Esse exemplo é uma pequena porta do Android do excelente programa de demonstração San Angeles Observation.

Android API de nível 5

O NDK fornece as seguintes APIs para desenvolver código nativo que seja executado em imagens do sistema do Android 2.0 e posteriores.

Biblioteca do OpenGL ES 2.0:

Os cabeçalhos <GLES2/gl2.h> e <GLES2/gl2ext.h> padrão do OpenGL ES 2.0 contém as declarações necessárias para realizar chamadas de renderização do OpenGL ES 2.0 com código nativo. Essas chamadas de renderização fornece a capacidade de usar a linguagem GLSL para definir e usar sombreadores de vértice e fragmento.

Para usar o OpenGL ES 2.0, vincule seu módulo nativo a /system/lib/libGLESv2.so inclusive a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS := -lGLESv2

Nem todos os dispositivos oferecem compatibilidade com o OpenGL ES 2.0. Um aplicativo pode consultar a string de versão e a de extensão do OpenGL ES para determinar se o dispositivo atual é compatível com os recursos de que o aplicativo precisa. Para obter informações sobre como realizar essa consulta, consulte a descrição de glGetString() na especificação do OpenGL.

Além disso, você deve colocar uma tag <uses-feature> no seu arquivo de manifesto para indicar que versão do OpenGL ES o seu aplicativo precisa. Para saber mais sobre as configurações do OpenGL ES para <uses-feature>, consulte OpenGL ES.

O exemplo de aplicativo hello-gl2 fornece uma demonstração básica de como usar o OpenGL ES 2.0 com o NDK.

As APIs EGL só estão disponíveis a partir da API de nível 9. No entanto, é possível usar a VM para realizar algumas das operações que se obteria com essas APIs. Essas operações abrangem a criação e inversão de superfícies. Para ver um exemplo de como usar GLSurfaceView, consulte Introdução ao GLSurfaceView.

Observação: O emulador Android não é compatível com a emulação de hardware do OpenGL ES 2.0. Executar e testar código que usa essa API exige um dispositivo real com hardware que possa suportar o OpenGL ES 2.0.

Android API de nível 8

O NDK fornece as seguintes APIs para desenvolver código nativo executado em imagens do sistema do Android 2.2 e em posteriores.

jnigraphics

A biblioteca jnigraphics expõe uma interface baseada em C que permite que o código nativo acesse os buffers de pixel dos objetos bitmap do Java de forma segura. O fluxo de trabalho para usar jnigraphics é o seguinte:

  1. Use AndroidBitmap_getInfo() para recuperar informações do JNI, como largura e altura, sobre determinado identificador de bitmap.
  2. Use AndroidBitmap_lockPixels() para bloquear o buffer de pixel e obter um ponteiro para ele. Fazer isso garante que os pixels não se movam até que o aplicativo chame AndroidBitmap_unlockPixels().
  3. No código nativo, modifique o buffer de pixel conforme a necessidade quanto ao formato, à largura e a outras características do pixel.
  4. Chame AndroidBitmap_unlockPixels() para desbloquear o buffer.

Para usar jnigraphics, inclua o cabeçalho <bitmap.h> no código-fonte e vincule-o a jnigraphics inclusive a linha a seguir ao arquivo Android.mk:

LOCAL_LDLIBS += -ljnigraphics

Você pode encontrar mais detalhes sobre esse recurso nos comentários do arquivo bitmap.h.

Android API de nível 9

O NDK fornece as seguintes APIs para desenvolver código nativo que seja executado em imagens do sistema do Android 2.3 e posteriores.

EGL

O EGL fornece uma interface de plataforma nativa para alocar e gerenciar superfícies do OpenGL ES. Para saber mais sobre seus recursos, consulte Interface de plataforma nativa do EGL.

O EGL permite realizar as seguintes operações a partir do código nativo:

  • Listar configurações de EGL compatíveis.
  • Alocar e lançar superfícies do OpenGL ES.
  • Trocar ou inverter superfícies.

Os cabeçalhos a seguir fornecem os recursos do EGL:

  • EGL/egl.h: as principais definições da API EGL.
  • EGL/eglext.h: definições relacionadas à extensão de EGL.

Para criar vínculo com a biblioteca EGL do sistema, adicione a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS += -lEGL

OpenSL ES

O gerenciamento de áudio nativo do Android se baseia na API do Open SL ES 1.0.1 do Khronos Group.

Os cabeçalhos OpenSLES.h e OpenSLES_Platform.h padrão do OpenSL ES contêm as declarações necessárias para se realizar entrada e saída de áudio no lado nativo do Android. A distribuição do OpenSL ES do NDK também fornece extensões específicas do Android. Para saber mais sobre essas extensões, leia os comentários em OpenSLES_Android.h e OpenSLES_AndroidConfiguration.h.

A biblioteca libOpenSLES.so do sistema implementa as funções públicas de áudio nativo. Estabeleça vínculo com ela adicionado a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS += -lOpenSLES

Para saber mais sobre a API do OpenSL ES, consulte $NDK/docs/Additional_library_docs/opensles/index.html, em que $NDK é o diretório raiz de instalação do NDK.

APIs de aplicativo nativo Android

A partir da API de nível 9, é possível programar um aplicativo Android somente com código nativo, sem usar Java.

Observação: Programar o aplicativo com código nativo não é, em si, suficiente para que o aplicativo seja executado na VM. Além disso, o aplicativo ainda precisa acessar a maioria dos recursos da plataforma Android via JNI.

Essa versão fornece os seguintes cabeçalhos nativos:

  • <native_activity.h>
  • <looper.h>
  • <input.h>
  • <keycodes.h>
  • <sensor.h>
  • <rect.h>
  • <window.h>
  • <native_window.h>
  • <native_window_jni.h>
  • <configuration.h>
  • <asset_manager.h>
  • <storage_manager.h>
  • <obb.h>

Para saber mais sobre esses cabeçalhos, consulte a documentação de referência da NDK API, além dos comentários nos próprios cabeçalhos. Além disso, para obter mais detalhes sobre o abrangente assunto de programar aplicativos nativos, consulte Atividades e aplicativos nativos.

Ao incluir um ou mais desses cabeçalhos, você também deve vinculá-lo(s) à biblioteca libandroid.so. Para vincular à libandroid.so, inclua a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS += -landroid

Android API de nível 14

O NDK fornece as seguintes APIs para desenvolver código nativo executado em imagens do sistema do Android 4.0 e em posteriores.

OpenMAX AL

O gerenciamento de multimídia nativa do Android baseia-se na API do OpenMAX AL 1.0.1 do Khronos Group.

Os cabeçalhos <OMXAL/OpenMAXAL.h> e <OMXAL/OpenMAXAL_Platform.h> padrão do OpenMAX AL contêm as declarações necessárias para se realizar saída multimídia do lado nativo do Android.

A distribuição do OpenMAX AL do NDK também fornece extensões específicas do Android. Para obter informações sobre essas extensões, leia os comentários em OpenMAXAL_Android.h.

A biblioteca libOpenMAXAL.so do sistema implementa as funções públicas de multimídia nativa. Para vincular a essa biblioteca, inclua a seguinte linha no arquivo Android.mk:

    LOCAL_LDLIBS += -lOpenMAXAL

Para saber mais sobre esse assunto, consulte $NDK/docs/openmaxal/index.html, em que $NDK é o diretório raiz da instalação do NDK.

OpenSL ES

O OpenSL ES oferece compatibilidade para esse nível da Android API adicionar suporte a PCM. Para saber mais sobre a compatibilidade com OpenSL ES do NDK, consulte OpenSL ES.

Android API de nível 18

O NDK fornece as seguintes APIs para desenvolver código nativo que seja executado em imagens do sistema do Android 4.3 e posteriores.

OpenGL ES 3.0

Os cabeçalhos gl3.h e gl3ext.h padrão do OpenGL ES 3.0 contêm as declarações necessárias para se realizar as chamadas de renderização do OpenGL ES 3.0 a partir do código nativo. Essas chamadas de renderização fornecem a capacidade de usar a linguagem GLSL para definir e usar sombreadores de vértice e fragmento.

Para usar o OpenGL ES 3.0, vincule seu módulo nativo a /system/lib/libGLESv3.so inclusive a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS := -lGLESv3

Nem todos os dispositivos oferecem compatibilidade com OpenGL ES 3.0. Um aplicativo pode consultar a string de versão e a de extensão do OpenGL ES para determinar se o dispositivo atual é compatível com os recursos de que o aplicativo precisa. Para obter informações sobre como realizar essa consulta, consulte a descrição de glGetString() na especificação do OpenGL.

Além disso, você deve colocar uma tag <uses-feature> no seu arquivo de manifesto para indicar que versão do OpenGL ES o seu aplicativo precisa. Para saber mais sobre as configurações do OpenGL ES para <uses-feature>, consulte OpenGL ES.

O exemplo de aplicativo gles3jni fornece uma demonstração básica de como usar o OpenGL ES 3.0 com o NDK.

Observação: O emulador Android não é compatível com a emulação de hardware do OpenGL ES 3.0. Executar e testar código que usa essa API exige um dispositivo real com hardware compatível com o OpenGL ES 3.0.

Android API de nível 21

O NDK fornece as seguintes APIs para desenvolver código nativo que seja executado em imagens do sistema do Android 4.3 e posteriores.

OpenGL ES 3.1

Os cabeçalhos gl31.h e gl3ext.h padrão do OpenGL ES 3.1 contêm as declarações necessárias para realizar as chamadas de renderização do OpenGL ES 3.1 a partir do código nativo. Essas chamadas de renderização fornecem a capacidade de usar a linguagem GLSL para definir e usar sombreadores de vértice e fragmento.

Para usar o OpenGL ES 3.1, vincule seu módulo nativo a /system/lib/libGLESv3.so incluindo a seguinte linha ao arquivo Android.mk:

LOCAL_LDLIBS := -lGLESv3

Nem todos os dispositivos oferecem compatibilidade com OpenGL ES 3.1. Um aplicativo pode consultar a string de versão e a de extensão do OpenGL ES para determinar se o dispositivo atual é compatível com os recursos de que o aplicativo precisa. Para obter informações sobre como realizar essa consulta, consulte a descrição de glGetString() na especificação do OpenGL.

Além disso, você deve colocar uma tag <uses-feature> no seu arquivo de manifesto para indicar que versão do OpenGL ES o seu aplicativo precisa. Para saber mais sobre as configurações do OpenGL ES para <uses-feature>, consulte OpenGL ES.

O exemplo de aplicativo gles3jni fornece uma demonstração básica de como usar o OpenGL ES 3.1 com o NDK.

Observação: O emulador Android não é compatível com a emulação de hardware do OpenGL ES 3.1. Executar e testar código que usa essa API exige um dispositivo real com hardware que possa suportar o OpenGL ES 3.1.