APIs nativas

Esta página oferece uma visão geral das bibliotecas incluídas no NDK, com links para as partes relevantes da referência da API NDK e para guias (se disponíveis).

Usar APIs nativas

Há duas etapas para usar uma biblioteca fornecida pelo NDK:

  1. Dizer ao sistema de compilação para vincular à biblioteca.

    • Se você estiver usando ndk-build: adicione a biblioteca a LOCAL_LDLIBS do Android.mk. É necessário tirar o lib principal e dizer -l. Por exemplo, para vincular a libfoo e libbar, você escreveria makefile LOCAL_LDLIBS := -lfoo -lbar

      Para saber mais sobre LOCAL_LDLIBS, consulte a documentação do Android.mk.

    • Se você estiver usando CMake: siga as instruções do documento Adicionar APIs NDK do Studio.

  2. #include os cabeçalhos adequados do seu código.

APIs mais recentes que a minSdkVersion do app não podem ser chamadas por padrão. Em vez disso, use-as com dlopen() e dlsym(). Para uma abordagem mais fácil, consulte Como usar APIs mais recentes.

C/C++ principal

Biblioteca C

Os cabeçalhos da biblioteca C11 padrão, como <stdlib.h> e <stdio.h>, estão disponíveis normalmente.

No Android, diferentemente do Linux, não há bibliotecas libpthread ou librt separadas. Essa funcionalidade é incluída diretamente em libc, que não precisa ser vinculada de forma explícita.

Há uma libm separada para funções matemáticas (seguindo a tradição usual do Unix), mas assim como libc, isso é automaticamente vinculado pelos sistemas de build.

A funcionalidade do vinculador dinâmico em <dlfcn.h>, como dlopen(3) e dlsym(3), está disponível, mas é necessário vincular libdl explicitamente.

Biblioteca: libc / libm / libdl

Biblioteca C++

A compatibilidade com C++17 está disponível. Para saber mais sobre a compatibilidade com a biblioteca C++, consulte Compatibilidade com a biblioteca C++.

Gerar registros

<android/log.h> contém APIs para a geração de registros no logcat.

Disponível desde a API de nível 3.

Biblioteca: liblog

Referência: Geração de registros

Rastros

A API de rastreamento nativo <android/trace.h> fornece o equivalente nativo da classe android.os.Trace na linguagem de programação Java. Essa API permite que você rastreie unidades de trabalho nomeadas no seu código programando eventos de rastreamento para o buffer de rastreamento do sistema. Então, é possível coletar e analisar os eventos de rastreamento usando a ferramenta Systrace.

Disponível desde a API de nível 23.

Biblioteca: libandroid

Guia: Rastreamento nativo

Compactação zlib

Você pode usar a biblioteca de compactação Zlib (link em inglês), incluindo <zlib.h> e vinculando a libz.

O NDK sempre inclui os arquivos principais mais recentes da zlib no momento do lançamento, e a libz.a incluída no NDK para vinculação estática é sempre a mesma versão. No entanto, a libz.so para vinculação dinâmica vem do dispositivo e é a versão lançada nele. Isso significa que os cabeçalhos criados não correspondem à versão da zlib no dispositivo. Portanto, os avisos usuais contra fazer suposições sobre os detalhes de implementação são especialmente válidos aqui. Não estamos cientes de nenhum problema com a API pública, mas o layout do struct mudou ao longo do tempo e provavelmente vai continuar fazendo isso. Observe que a nova API nas versões zlib mais recentes não estará disponível em versões do SO anteriores à API. É possível evitar todos esses problemas (ao custo do aumento do tamanho do APK) sempre usando a libz.a estática em vez da libz.so.

Disponível do nível 3 em diante da API, mas consulte a observação acima.

Biblioteca: libz

Gráficos

OpenGL ES 1.0 - 3.2

Os cabeçalhos padrão do OpenGL ES 1.x (<GLES/gl.h> e <GLES/glext.h>), cabeçalhos 2.0 (<GLES2/gl2.h> e <GLES2/gl2ext.h>), cabeçalhos 3.0 (<GLES3/gl3.h> e <GLES3/gl3ext.h>), cabeçalhos 3.1 (<GLES3/gl31.h> e <GLES3/gl3ext.h>) e cabeçalhos 3.2 (<GLES3/gl32.h> e <GLES3/gl3ext.h>) contêm as declarações necessárias para o OpenGL ES.

Para usar o OpenGL ES 1.x, vincule seu módulo nativo a libGLESv1_CM.

Para usar o OpenGL ES 2.0, vincule seu módulo nativo a libGLESv2.

Para usar o OpenGL ES 3.x, vincule seu módulo nativo a libGLESv3.

Todos os dispositivos com Android são compatíveis com OpenGL ES 1.0 e 2.0.

Somente dispositivos Android com a GPU necessária têm suporte a versões mais recentes do OpenGL ES, mas as bibliotecas estão presentes em todos os dispositivos com suporte ao nível da API em que foram inseridos. É seguro vincular às bibliotecas, mas um app precisa consultar a string de extensão e a string da versão do OpenGL ES para determinar se o dispositivo atual é compatível com os recursos necessários. Para saber mais sobre como realizar essa consulta, confira a descrição de glGetString() na especificação do OpenGL.

Além disso, coloque uma tag <uses-feature> no seu arquivo de manifesto para indicar a versão do OpenGL ES necessária.

O OpenGL ES 1.0 está disponível a partir do nível 4 da API.

O OpenGL ES 2.0 está disponível a partir do nível 5 da API.

O OpenGL ES 3.0 está disponível a partir do nível 18 da API.

O OpenGL ES 3.1 está disponível a partir do nível 21 da API.

O OpenGL ES 3.2 está disponível a partir do nível 24 da API.

EGL

A biblioteca EGL oferece uma interface de plataforma nativa por meio dos cabeçalhos <EGL/egl.h> e <EGL/eglext.h> para alocação e gerenciamento de contextos e superfícies do OpenGL ES.

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

  • Listar configurações de EGL com suporte
  • Alocar e lançar superfícies do OpenGL ES.
  • Criar e destruir contextos do OpenGL ES.
  • Trocar ou inverter superfícies

O nível 24 da API incluiu o suporte às extensões EGL_KHR_mutable_render_buffer, ANDROID_create_native_client_buffer e ANDROID_front_buffer_auto_refresh (links em inglês).

Disponível a partir do nível 9 da API.

Biblioteca: libEGL

Guia: Interface de plataforma nativa EGL (em inglês)

Vulkan

Vulkan é uma API multiplataforma de baixa sobrecarga para renderizar gráficos 3D de alta performance. Vulkan é um padrão aberto mantido pelo Khronos Group. O arquivo principal <vulkan/vulkan.h> padrão contém as declarações necessárias para executar chamadas de renderização da Vulkan pelo seu código.

Para acessar exemplos de código, consulte os projetos LunarG VulkanSamples e android-vulkan-tutorials no GitHub.

A biblioteca Vulkan está presente em todos os dispositivos com suporte à API de nível 24 ou mais recente, mas os apps precisam verificar no momento da execução se o suporte ao hardware de GPU necessário está disponível. Os dispositivos sem compatibilidade com a Vulkan retornarão zero dispositivo de vkEnumeratePhysicalDevices (link em inglês).

Disponível a partir do nível 24 da API.

Biblioteca: libvulkan

Guia: Guia da API de gráficos da Vulkan

Bitmaps

A biblioteca libjnigraphics expõe a API que permite acesso aos buffers de pixel dos objetos Java Bitmap. O fluxo de trabalho é o seguinte:

  1. Chame AndroidBitmap_getInfo() para recuperar informações, como largura e altura, sobre um determinado identificador de bitmap.

  2. Chame AndroidBitmap_lockPixels() para bloquear o buffer de pixels e recuperar um ponteiro para ele. Isso garante que os pixels não se movam até que o app chame AndroidBitmap_unlockPixels().

  3. Modifique o buffer de pixels conforme apropriado para seu formato de pixel, largura e outras características.

  4. Chame AndroidBitmap_unlockPixels() para desbloquear o buffer.

Disponível desde a API de nível 8.

Biblioteca: libjnigraphics

Referência: Referência da API Bitmap

API Sync

Disponível a partir do nível 26 da API.

Biblioteca: libsync

Referência: Referência da API Sync

Câmera

As APIs de câmera nativa realizam a captura e o processamento refinados de fotos. Diferentemente da API Java camera2, a API nativa de câmera não é compatível com implementações obsoletas HAL 1.0 de câmera. Ou seja, a lista de câmeras disponíveis na API nativa da câmera não incluirá dispositivos de câmera que tenham o nível de hardware LEGACY.

Disponível a partir do nível 24 da API.

Biblioteca: libcamera2ndk

Referência: Referência da API Camera

Mídia

libmediandk

As APIs Media fornecem interfaces nativas de baixo nível semelhantes a MediaExtractor, MediaCodec e outras APIs Java relacionadas.

Biblioteca: libmediandk

Referência: Referência da API Media

OpenMAX AL

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

Os cabeçalhos OpenMAX AL padrão <OMXAL/OpenMAXAL.h> e <OMXAL/OpenMAXAL_Platform.h> contêm as declarações necessárias para executar a saída de 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 saber mais sobre essas extensões, consulte os comentários em <OMXAL/OpenMAXAL_Android.h>.

Disponível a partir do nível 14 da API.

Biblioteca: libOpenMAXAL

APIs de aplicativo nativo do Android

Para mais informações, consulte a documentação Referência da API do Android NDK.

As APIs incluem:

Biblioteca: libandroid

Biblioteca: libnativewindow para a função de janela nativa mais recente

Referência completa: Referência da API Android NDK

APIs Binder

As APIs Binder permitem criar canais de comunicação entre processos. Essa é a implementação de baixo nível da comunicação entre processos do Android. Sempre que possível, prefira componentes de nível mais alto. No entanto, essa biblioteca está disponível para casos de uso avançados.

Biblioteca: libbinder_ndk

Referência: Binder

APIs de buffer de hardware

Duas APIs nativas permitem que você crie seus pipelines para o gerenciamento de buffer em processo cruzado.

A API de buffer de hardware nativo <android/hardware_buffer.h> permite alocar buffers diretamente para criar pipelines próprios para gerenciamento de buffer em processo cruzado. É possível alocar um AHardwareBuffer e usá-lo para ter um tipo de recurso EGLClientBuffer por meio da extensão eglGetNativeClientBufferANDROID. Você pode transmitir esse buffer para eglCreateImageKHR para criar um tipo de recurso EGLImage, que pode então ser vinculado a uma textura via glEGLImageTargetTexture2DOES nos dispositivos compatíveis (links em inglês). Isso pode ser útil para criar texturas que possam ser compartilhadas em processo cruzado.

A API JNI de buffer de hardware nativo (<android/hardware_buffer_jni.h>) permite ter um objeto HardwareBuffer. Esse é um Parcelable e, portanto, pode ser transportado entre dois processos diferentes. Isso dá ao app capacidades semelhantes a SurfaceFlinger (link em inglês), por exemplo, criar uma fila de buffers própria entre processos sem acessar APIs internas do Android.

Áudio

AAudio

AAudio é a API de áudio nativa compatível atualmente. Ela substituiu a OpenSL ES e oferece melhor suporte a apps de áudio de alta performance que exigem áudio de baixa latência.

Disponível a partir do nível 26 da API.

Biblioteca: libaaudio

Guia: Guia da API AAudio

Referência: Referência da API AAudio

OpenSL ES

OpenSL ES é outra API de áudio nativa que também tem suporte, mas consulte a observação no guia abaixo.

Disponível a partir do nível 9 da API. A API de nível 14 adicionou compatibilidade com PCM.

Biblioteca: libOpenSLES

Guia: Guia da OpenSL ES para Android

API Neural Networks

A API Android Neural Networks (NNAPI) fornece aceleração de hardware aos apps para operações de aprendizado de máquina no dispositivo. A API tem suporte ao modelo de criação, compilação e execução no dispositivo. Os apps não costumam usar NNAPI diretamente. Em vez disso, ela precisa ser chamada por bibliotecas de aprendizado de máquina, frameworks e ferramentas que permitam que os desenvolvedores treinem modelos e os implantem em dispositivos Android.

Disponível a partir do nível 27 da API.

Biblioteca: libneuralnetworks

Guia: Guia de redes neurais

Referência: Referência da API Neural Networks