API natives

Cette page présente les bibliothèques incluses dans le NDK, avec des liens vers les parties pertinentes de la documentation de référence de l'API NDK et vers les guides pertinents.

Utiliser des API natives

L'utilisation d'une bibliothèque fournie par le NDK repose sur deux étapes :

  1. Demandez au système de compilation de s'associer à la bibliothèque.

    • Si vous utilisez ndk-build, ajoutez la bibliothèque à LOCAL_LDLIBS dans le fichier Android.mk. Notez que la première mention lib est supprimée et remplacée par -l. Par exemple, pour créer une association avec libfoo et libbar, vous devez écrire : makefile LOCAL_LDLIBS := -lfoo -lbar

      Pour en savoir plus sur LOCAL_LDLIBS, consultez la documentation Android.mk.

    • Si vous utilisez CMake, suivez les instructions de la documentation Ajouter des API NDK dans Studio.

  2. Ajoutez (#include) les en-têtes appropriés de votre code.

Notez que les API plus récentes que le minSdkVersion de votre application ne peuvent pas être appelées par défaut. Vous devez les utiliser via dlopen() et dlsym(). Pour une approche plus simple, consultez la page Utiliser des API plus récentes.

Code C/C++ de base

Bibliothèque C

Les en-têtes de bibliothèque C11 standards tels que <stdlib.h> et <stdio.h> sont disponibles comme d'habitude.

Notez qu'il n'existe pas de bibliothèque libpthread ou librt distincte sur Android, contrairement à Linux. Cette fonctionnalité est incluse directement dans libc, qui n'a pas besoin d'être explicitement associé.

Il existe un élément libm distinct pour les fonctions mathématiques (qui respecte la tradition Unix habituelle), mais comme libc, il est automatiquement associé par les systèmes de compilation.

La fonctionnalité de liaison dynamique de <dlfcn.h>, telle que dlopen(3) et dlsym(3), est disponible, mais vous devez l'associer explicitement à libdl.

Bibliothèque : libc/libm/libdl

Bibliothèque C++

La compatibilité C++ 17 est disponible. Pour en savoir plus sur la compatibilité des bibliothèques C++, consultez la section Compatibilité avec les bibliothèques C++.

Journalisation

<android/log.h> contient des API permettant la journalisation dans logcat.

Cette API est disponible à partir du niveau d'API 3.

Bibliothèque : liblog

Référence : Journalisation

Traçage

L'API de traçage native <android/trace.h> fournit l'équivalent natif de la classe android.os.Trace dans le langage de programmation Java. Cette API vous permet de tracer les unités de travail nommées dans le code en écrivant des événements de traçage dans le tampon de traçage système. Vous pouvez ensuite collecter et analyser les événements de traçage à l'aide de l'outil Systrace.

Cette API est disponible à partir du niveau d'API 23.

Bibliothèque : libandroid

Guide : Traçage natif

Compression zlib

Pour utiliser la bibliothèque de compression Zlib, ajoutez <zlib.h> et associez-le à libz.

Le NDK inclut toujours les derniers fichiers d'en-tête zlib au moment de la publication, et le libz.a inclus dans le NDK pour la liaison statique correspond toujours à la même version, mais le libz.so pour la liaison dynamique provient de l'appareil, et ce, quelle que soit la version qui a été publiée sur cet appareil. Cela signifie en particulier que les en-têtes avec lesquels vous avez compilé votre build ne correspondent pas à la version de zlib sur l'appareil. Par conséquent, les avertissements habituels interdisant toute hypothèse concernant les détails de l'implémentation sont particulièrement valables ici. Nous n'avons connaissance d'aucun problème lié à l'API publique, mais la mise en page struct en particulier a changé au fil du temps et continuera probablement ainsi. Notez que la nouvelle API des versions ultérieures de zlib ne sera évidemment pas disponible sur les versions d'OS antérieures à l'API. Il est possible d'éviter tous ces problèmes (mais cela augmente la taille de l'APK) en utilisant toujours le libz.a statique au lieu de libz.so.

Cette API est disponible à partir du niveau d'API 3 (voir la remarque ci-dessus).

Bibliothèque : libz

Graphiques

OpenGL ES 1.0 à 3.2

Les en-têtes OpenGL ES 1.x standards (<GLES/gl.h> et <GLES/glext.h>), les en-têtes 2.0 (<GLES2/gl2.h> et <GLES2/gl2ext.h>), les en-têtes 3.0 (<GLES3/gl3.h> et <GLES3/gl3ext.h>), les en-têtes 3.1 (<GLES3/gl31.h> et <GLES3/gl3ext.h>) et les en-têtes 3.2 (<GLES3/gl32.h> et <GLES3/gl3ext.h>) contiennent les déclarations nécessaires pour OpenGL ES.

Pour utiliser OpenGL ES 1.x, associez votre module natif à libGLESv1_CM.

Pour utiliser OpenGL ES 2.0, associez votre module natif à libGLESv2.

Pour utiliser OpenGL ES 3.x, associez votre module natif à libGLESv3.

Tous les appareils Android sont compatibles avec OpenGL ES 1.0 et 2.0.

Seuls les appareils Android disposant du GPU nécessaire sont entièrement compatibles avec les versions ultérieures d'OpenGL ES. Toutefois, les bibliothèques se trouvent sur tous les appareils compatibles avec le niveau d'API où elles ont été ajoutées. L'association avec les bibliothèques peut être effectuée sans risque, mais l'application doit interroger la chaîne de version et la chaîne d'extension OpenGL ES pour déterminer si l'appareil actuel est compatible avec les fonctionnalités dont elle a besoin. Pour en savoir plus sur l'exécution de cette requête, consultez la description de glGetString() dans la spécification OpenGL.

En outre, vous devez ajouter une balise <uses-feature> dans le fichier manifeste pour indiquer la version d'OpenGL ES dont vous avez besoin.

OpenGL ES 1.0 est disponible depuis le niveau d'API 4.

OpenGL ES 2.0 est disponible depuis le niveau d'API 5.

OpenGL ES 3.0 est disponible depuis le niveau d'API 18.

OpenGL ES 3.1 est disponible depuis le niveau d'API 21.

OpenGL ES 3.2 est disponible depuis le niveau d'API 24.

EGL

EGL fournit une interface de plate-forme native via les en-têtes <EGL/egl.h> et <EGL/eglext.h> pour l'allocation et la gestion des contextes et des surfaces OpenGL ES.

EGL vous permet d'effectuer les opérations suivantes à partir du code natif :

  • Répertorier les configurations EGL compatibles
  • Allouer et libérer les surfaces OpenGL ES
  • Créer et détruire des contextes OpenGL ES
  • Changer de surface ou les inverser

Les extensions EGL_KHR_mutable_render_buffer, ANDROID_create_native_client_buffer et ANDROID_front_buffer_auto_refresh sont acceptées à partir du niveau d'API 24.

Cette API est disponible à partir du niveau d'API 9.

Bibliothèque : libEGL

Guide : Plate-forme native de l'interface EGL

Vulkan

Vulkan est une API multiplate-forme simple permettant un rendu 3D hautes performances. Vulkan est une norme ouverte gérée par le groupe Khronos. Le fichier d'en-tête <vulkan/vulkan.h> standard contient les déclarations nécessaires pour effectuer des appels de rendu Vulkan à partir de votre code.

Pour obtenir des exemples de code, consultez les projets VulkanSamples et android-vulkan-tutorials de LunarG sur GitHub.

La bibliothèque Vulkan est présente sur tous les appareils compatibles avec le niveau d'API 24 ou ultérieur, mais les applications doivent vérifier au moment de l'exécution que la compatibilité matérielle nécessaire pour les GPU est disponible. Les appareils non compatibles avec Vulkan ne renvoient aucun appareil depuis vkEnumeratePhysicalDevices.

Cette API est disponible à partir du niveau d'API 24.

Bibliothèque : libvulkan

Guide : Guide de l'API de graphiques Vulkan

Bitmaps

La bibliothèque libjnigraphics expose l'API qui permet d'accéder aux tampons de pixel des objets Bitmap Java. Le workflow se déroule comme suit :

  1. Appelez AndroidBitmap_getInfo() pour récupérer des informations, telles que la largeur et la hauteur, sur un handle bitmap donné.

  2. Appelez AndroidBitmap_lockPixels() pour verrouiller le tampon de pixel et extraire un pointeur vers celui-ci. De cette manière, les pixels ne seront pas déplacés tant que l'application n'aura pas appelé AndroidBitmap_unlockPixels().

  3. Modifiez le tampon de pixel selon son format de pixel, sa largeur et d'autres caractéristiques.

  4. Appelez AndroidBitmap_unlockPixels() pour déverrouiller le tampon.

Cette API est disponible à partir du niveau d'API 8.

Bibliothèque : libjnigraphics

Référence : Documentation de référence de l'API Bitmap

API de synchronisation

Cette API est disponible à partir du niveau d'API 26.

Bibliothèque : libsync

Référence : Documentation de référence de l'API de synchronisation

Appareil photo

Les API d'appareil photo natives permettent d'effectuer des prises de vue et des traitements de photos ultraprécis. Contrairement à l'API Java Camera2, l'API Appareil photo native n'est pas compatible avec les implémentations HAL 1.0 d'appareil photo, qui ont été abandonnées. En d'autres termes, la liste des appareils photo disponibles dans l'API Appareil photo native n'affiche pas les appareils dont le niveau de matériel est ancien.

Cette API est disponible à partir du niveau d'API 24.

Bibliothèque : libcamera2ndk

Référence : Documentation de référence de l'API Appareil photo

Contenus multimédias

libmediandk

Les API multimédias fournissent des interfaces natives de bas niveau semblables à MediaExtractor, MediaCodec et à d'autres API Java associées.

Bibliothèque : libmediandk

Référence : Documentation de référence des API multimédias

OpenMAX AL

La gestion des contenus multimédias natifs Android est basée sur l'API OpenMAX AL 1.0.1 du groupe Khronos.

Les en-têtes OpenMAX AL <OMXAL/OpenMAXAL.h> et <OMXAL/OpenMAXAL_Platform.h> contiennent les déclarations nécessaires pour effectuer une sortie multimédia du côté natif d'Android.

La distribution NDK d'OpenMAX AL fournit également des extensions spécifiques à Android. Pour en savoir plus sur ces extensions, consultez les commentaires dans <OMXAL/OpenMAXAL_Android.h>.

Cette API est disponible à partir du niveau d'API 14.

Bibliothèque : libOpenMAXAL

API d'applications natives Android

Pour en savoir plus, consultez la documentation de référence de l'API du NDK Android.

Voici les éléments compris dans les API :

Bibliothèque : libandroid

Bibliothèque : libnativewindow pour une fonctionnalité de fenêtre native plus récente

Documentation de référence complète : Documentation de référence de l'API du NDK Android

API de tampon matériel

Deux API natives vous permettent de créer vos propres pipelines pour la gestion des tampons interprocessus.

L'API de tampon matériel native <android/hardware_buffer.h> vous permet d'allouer directement des tampons pour créer vos propres pipelines de gestion des tampons interprocessus. Vous pouvez allouer un AHardwareBuffer et l'utiliser pour obtenir un type de ressource EGLClientBuffer via l'extension eglGetNativeClientBufferANDROID. Vous pouvez transmettre ce tampon à eglCreateImageKHR pour créer un type de ressource EGLImage, qui pourra ensuite être associé à une texture via glEGLImageTargetTexture2DOES sur les appareils compatibles. Cela peut être utile pour créer des textures à partager entre plusieurs processus.

L'API JNI de tampon matériel native (<android/hardware_buffer_jni.h>) vous permet d'obtenir un objet HardwareBuffer, qui est un objet divisible en parcelles et qui peut donc être transporté entre deux processus différents. Votre application dispose de fonctionnalités semblables à celles de SurfaceFlinger, telles que la création de votre propre file d'attente de tampons entre les processus sans accéder aux API internes d'Android.

Son

AAudio

AAudio est l'API audio native actuellement compatible. Elle remplace OpenSL ES et offre une meilleure compatibilité avec les applications audio hautes performances nécessitant un contenu audio à faible latence.

Cette API est disponible à partir du niveau d'API 26.

Bibliothèque : libaaudio

Guide : Guide de l'API AAudio

Référence : Documentation de référence de l'API AAudio

OpenSL ES

OpenSL ES est une autre API audio native également compatible, mais consultez la remarque au niveau du guide ci-dessous.

Cette API est disponible à partir du niveau d'API 9. PCM est compatible depuis le niveau d'API 14.

Bibliothèque : libOpenSLES

Guide : Guide OpenSL ES pour Android

API Neural Networks

L'API Neural Networks (NNAPI) fournit aux applications l'accélération matérielle pour les opérations de machine learning sur l'appareil. Elle permet de créer, de compiler et d'exécuter des modèles sur l'appareil. Les applications n'utilisent généralement pas directement NNAPI. Cette API est conçue pour être appelée par des bibliothèques, des frameworks et des outils de machine learning qui permettent aux développeurs d'entraîner leurs modèles et de les déployer sur des appareils Android.

Cette API est disponible à partir du niveau d'API 27.

Bibliothèque : libneuralnetworks

Guide : Guide de l'API Neural Networks

Référence : Documentation de référence de l'API Neural Networks