Référence de structure camera3_capture_result
#include < camera3.h >
Champs de données | |
| uint32_t | Numéro de cadre |
| const camera_metadata_t * | résultat |
| uint32_t | num_output_buffers |
| const camera3_stream_buffer_t * | tampons_de sortie |
| const camera3_stream_buffer_t * | tampon_entrée |
| uint32_t | résultat_partial |
Description détaillée
camera3_capture_result_t :
Le résultat d’une seule capture/retraitement par le périphérique HAL de la caméra. Ceci est envoyé au framework de manière asynchrone avec process_capture_result(), en réponse à une seule demande de capture envoyée au HAL avec process_capture_request(). Plusieurs appels process_capture_result() peuvent être effectués par le HAL pour chaque requête.
Chaque appel, tous avec le même numéro de trame, peut contenir un sous-ensemble des tampons de sortie et/ou les métadonnées du résultat. Les métadonnées ne peuvent être fournies qu'une seule fois pour un numéro de trame donné ; tous les autres appels doivent définir les métadonnées du résultat sur NULL.
La structure de résultat contient les métadonnées de sortie de cette capture et l'ensemble des tampons de sortie qui ont été/seront remplis pour cette capture. Chaque tampon de sortie peut être accompagné d'une clôture de synchronisation de version que le framework attendra avant de lire, au cas où le tampon n'aurait pas encore été rempli par le HAL.
>= CAMERA_DEVICE_API_VERSION_3_2 :
Les métadonnées peuvent être fournies plusieurs fois pour un seul numéro de trame. Le cadre accumulera l’ensemble de résultats final en combinant chaque résultat partiel dans l’ensemble de résultats total.
Si un tampon d'entrée est donné dans une requête, le HAL doit le renvoyer dans l'un des appels process_capture_result, et l'appel peut consister simplement à renvoyer le tampon d'entrée, sans métadonnées ni tampons de sortie ; les clôtures de synchronisation doivent être gérées de la même manière que pour les tampons de sortie.
Considérations relatives aux performances :
Les applications recevront également ces résultats partiels immédiatement, donc l'envoi de résultats partiels est une optimisation des performances fortement recommandée pour éviter la latence totale du pipeline avant d'envoyer les résultats pour ce qui est connu très tôt dans le pipeline.
Un cas d'utilisation typique pourrait consister à calculer l'état AF à mi-chemin du pipeline ; en renvoyant immédiatement l'état au framework, on obtient une augmentation des performances de 50% et une réactivité perçue de l'autofocus.
Documentation de terrain
| uint32_t numéro_cadre |
Le numéro de trame est un entier incrémentiel défini par le framework dans la demande soumise pour identifier de manière unique cette capture. Il est également utilisé pour identifier la demande dans les notifications asynchrones envoyées à camera3_callback_ops_t.notify() .
| const camera3_stream_buffer_t * input_buffer |
>= CAMERA_DEVICE_API_VERSION_3_2 :
Handle du tampon du flux d’entrée pour cette capture. Il se peut qu'il ne soit pas encore consommé au moment où HAL appelle process_capture_result(); le framework attendra les clôtures de synchronisation de publication fournies par le HAL avant de réutiliser le tampon.
Le HAL doit gérer les clôtures de synchronisation de la même manière qu'ils le font pour les output_buffers.
Un seul tampon d’entrée peut être envoyé par requête. De la même manière que pour les tampons de sortie, l’ordre des tampons d’entrée renvoyés doit être géré par la HAL.
Considérations relatives aux performances :
Le tampon d'entrée doit être renvoyé le plus tôt possible. Si le HAL prend en charge les clôtures de synchronisation, il peut appeler process_capture_result pour le restituer avec les clôtures de synchronisation définies de manière appropriée. Si les clôtures de synchronisation ne sont pas prises en charge, le tampon ne peut être renvoyé que lorsqu'il est consommé, ce qui peut prendre beaucoup de temps ; le HAL peut choisir de copier ce tampon d'entrée pour que le tampon revienne plus tôt.
| uint32_t num_output_buffers |
Nombre de tampons de sortie renvoyés dans cette structure de résultat. Doit être inférieur ou égal au nombre de demandes de capture correspondantes. Si ce nombre est inférieur au nombre de tampons dans la demande de capture, au moins un appel supplémentaire à process_capture_result avec le même frame_number doit être effectué pour renvoyer les tampons de sortie restants au framework. Cela ne peut être nul que si la structure inclut des métadonnées de résultat valides ou si un tampon d'entrée est renvoyé dans ce résultat.
| const camera3_stream_buffer_t * output_buffers |
Handles pour les tampons du flux de sortie pour cette capture. Il se peut qu'ils ne soient pas encore remplis au moment où HAL appelle process_capture_result(); le framework attendra les clôtures de synchronisation de publication fournies par le HAL avant de lire les tampons.
La HAL doit définir la clôture de synchronisation de libération du tampon de flux sur un fd de synchronisation valide, ou sur -1 si le tampon a déjà été rempli.
Si le HAL rencontre une erreur lors du traitement du tampon et que le tampon n'est pas rempli, le champ d'état du tampon doit être défini sur CAMERA3_BUFFER_STATUS_ERROR. Si le HAL n'a pas attendu sur la clôture d'acquisition avant de rencontrer l'erreur, la clôture d'acquisition doit être copiée dans la clôture de libération, pour permettre au framework d'attendre sur la clôture avant de réutiliser le tampon.
La clôture d'acquisition doit être définie sur -1 pour tous les tampons de sortie. Si num_output_buffers vaut zéro, cela peut être NULL. Dans ce cas, au moins un appel process_capture_result supplémentaire doit être effectué par le HAL pour fournir les tampons de sortie.
Lorsque process_capture_result est appelé avec un nouveau tampon pour une trame, tous les tampons des trames précédentes pour ce flux correspondant doivent avoir déjà été livrés (les clôtures n'ont pas besoin d'être encore signalées).
>= CAMERA_DEVICE_API_VERSION_3_2 :
Les tampons Gralloc pour une trame peuvent être envoyés au framework avant la notification SHUTTER correspondante.
Considérations relatives aux performances :
Les tampons fournis au framework ne seront pas distribués à la couche application tant qu'un horodatage de début d'exposition n'aura pas été reçu via un appel SHUTTER notify(). Il est fortement recommandé d'envoyer cet appel le plus tôt possible.
| uint32_t partiel_result |
>= CAMERA_DEVICE_API_VERSION_3_2 :
Afin de profiter des résultats partiels, le HAL doit définir les métadonnées statiques android.request.partialResultCount sur le nombre de résultats partiels qu'il enverra pour chaque trame.
Chaque nouveau résultat de capture avec un résultat partiel doit définir ce champ (partial_result) sur une valeur inclusive distincte comprise entre 1 et android.request.partialResultCount.
Les HAL ne souhaitant pas profiter de cette fonctionnalité ne doivent pas définir un android.request.partialResultCount ou partial_result sur une valeur autre que 1.
Cette valeur doit être définie sur 0 lorsqu'un résultat de capture contient uniquement des tampons et aucune métadonnée.
| const camera_metadata_t * résultat |
Les métadonnées du résultat pour cette capture. Celui-ci contient des informations sur les paramètres de capture finaux, l'état du matériel de capture et de post-traitement, l'état des algorithmes 3A, s'ils sont activés, et la sortie de toutes les unités statistiques activées.
Un seul appel à process_capture_result() avec un frame_number donné peut inclure les métadonnées du résultat. Tous les autres appels pour le même frame_number doivent le définir sur NULL.
S'il y a eu une erreur lors de la production des métadonnées du résultat, le résultat doit être un tampon de métadonnées vide et notify() doit être appelé avec ERROR_RESULT.
>= CAMERA_DEVICE_API_VERSION_3_2 :
Plusieurs appels à process_capture_result() avec un frame_number donné peuvent inclure les métadonnées du résultat.
Les métadonnées partielles soumises ne doivent inclure aucune clé de métadonnées renvoyée dans un résultat partiel précédent pour une trame donnée. Chaque nouveau résultat partiel pour cette image doit également définir une valeur partial_result distincte.
Si notify a été appelé avec ERROR_RESULT, tous les autres résultats partiels pour cette trame sont ignorés par le framework.
La documentation de cette structure a été générée à partir du fichier suivant :
- matériel/libhardware/include/hardware/ camera3.h