Esta página detalha as diferenças de versão em Camera HALs, APIs e testes de Compatibility Test Suite (CTS) associados. Ele também abrange várias alterações arquitetônicas feitas para fortalecer e proteger a estrutura da câmera no Android 7.0, a mudança para Treble no Android 8.0 e as atualizações que os fornecedores devem fazer para oferecer suporte a essas alterações em suas implementações de câmera.
Terminologia
Os seguintes termos são usados nesta página:
- API da câmera1
- A estrutura da câmera no nível do aplicativo em dispositivos Android 4.4 e anteriores, exposta por meio da classe
android.hardware.Camera
. - API2 da câmera
- A estrutura da câmera no nível do aplicativo em dispositivos Android 5.0 e superiores, exposta por meio do pacote
android.hardware.camera2
. - Câmara HAL
- A camada do módulo de câmera implementada por fornecedores de SoC. As estruturas públicas no nível do aplicativo são construídas sobre o HAL da câmera.
- Câmera HAL3.1
- Versão do dispositivo de câmera HAL lançado com Android 4.4.
- Câmera HAL3.2
- Versão do dispositivo de câmera HAL lançado com Android 5.0.
- Câmera API1 CTS
- Conjunto de testes CTS de câmera executados sobre a API1 da câmera.
- Câmera API2 CTS
- Conjunto adicional de testes CTS de câmera que são executados sobre o Camera API2.
- agudos
- Separa a implementação do fornecedor (software de nível inferior específico do dispositivo escrito por fabricantes de silício) da estrutura do sistema operacional Android por meio de uma nova interface do fornecedor.
- HIDL
- Linguagem de definição de interface HAL introduzida com Treble e usada para especificar a interface entre um HAL e seus usuários.
- VTS
- Conjunto de teste do fornecedor introduzido juntamente com o Treble.
APIs da câmera
O Android inclui as seguintes APIs de câmera.
API da câmera1
O Android 5.0 foi descontinuado Camera API1, que continua a ser descontinuado à medida que o desenvolvimento de novas plataformas se concentra na Camera API2. No entanto, o período de eliminação será longo e os lançamentos do Android continuarão a oferecer suporte aos aplicativos Camera API1 por algum tempo. Especificamente, o suporte continua para:
- Interfaces API1 da câmera para aplicativos. Os aplicativos de câmera criados com base na Camera API1 devem funcionar da mesma forma que em dispositivos que executam versões anteriores do Android.
- Versões da câmera HAL. Inclui suporte para câmera HAL1.0.
API2 da câmera
A estrutura Camera API2 expõe o controle de câmera de nível inferior para o aplicativo, incluindo fluxos eficientes de burst/streaming de cópia zero e controles por quadro de exposição, ganho, ganhos de balanço de branco, conversão de cores, redução de ruído, nitidez e muito mais. Para obter detalhes, assista ao vídeo de visão geral do Google I/O .
Android 5.0 e superior inclui Camera API2; no entanto, os dispositivos com Android 5.0 e superior podem não oferecer suporte a todos os recursos Camera API2. A propriedade android.info.supportedHardwareLevel
que os aplicativos podem consultar por meio das interfaces Camera API2 relata um dos seguintes níveis de suporte:
-
LEGACY
: Esses dispositivos expõem recursos a aplicativos por meio das interfaces Camera API2 que são aproximadamente os mesmos recursos expostos a aplicativos por meio das interfaces Camera API1. O código de estruturas herdadas converte conceitualmente as chamadas Camera API2 em chamadas Camera API1; os dispositivos herdados não oferecem suporte aos recursos Camera API2, como controles por quadro. -
LIMITED
: Esses dispositivos suportam alguns recursos da API2 da câmera (mas não todos) e devem usar o Camera HAL 3.2 ou superior. -
FULL
: Esses dispositivos oferecem suporte a todos os principais recursos do Camera API2 e devem usar o Camera HAL 3.2 ou superior e o Android 5.0 ou superior. -
LEVEL_3
: Esses dispositivos suportam reprocessamento YUV e captura de imagem RAW, juntamente com configurações de fluxo de saída adicionais. -
EXTERNAL
: Esses dispositivos são semelhantes aos dispositivosLIMITED
com algumas exceções; por exemplo, algumas informações do sensor ou da lente podem não ser relatadas ou ter taxas de quadros menos estáveis. Este nível é usado para câmeras externas, como webcams USB.
Os recursos individuais são expostos por meio da propriedade android.request.availableCapabilities
nas interfaces Camera API2. Os dispositivos FULL
requerem os recursos MANUAL_SENSOR
e MANUAL_POST_PROCESSING
, entre outros. A capacidade RAW
é opcional mesmo para dispositivos FULL
. Os dispositivos LIMITED
podem anunciar qualquer subconjunto desses recursos, incluindo nenhum deles. No entanto, o recurso BACKWARD_COMPATIBLE
sempre deve ser definido.
O nível de hardware compatível do dispositivo, bem como os recursos específicos da Camera API2 compatíveis, estão disponíveis como os seguintes sinalizadores de recursos para permitir a filtragem do Google Play de aplicativos de câmera Camera API2.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
Requisitos CTS
Os dispositivos que executam o Android 5.0 e superior devem passar nos testes de câmera Camera API1 CTS, Camera API2 CTS e CTS Verifier.
Os dispositivos que não apresentam uma implementação de Camera HAL3.2 e não são capazes de suportar todas as interfaces Camera API2 ainda devem passar nos testes Camera API2 CTS. No entanto, o dispositivo é executado no modo Camera API2 LEGACY
(no qual as chamadas Camera API2 são mapeadas conceitualmente para chamadas Camera API1), portanto, quaisquer testes de Camera API2 CTS relacionados a recursos ou capacidades além da Camera API1 são ignorados automaticamente.
Em dispositivos legados, os testes Camera API2 CTS que são executados usam as interfaces e recursos públicos Camera API1 existentes sem novos requisitos. Os bugs expostos (e que causam uma falha CTS API2 da câmera) são bugs já presentes no Camera HAL existente do dispositivo e, portanto, seriam encontrados pelos aplicativos Camera API1 existentes. Não esperamos muitos bugs dessa natureza (no entanto, esses bugs devem ser corrigidos para passar nos testes Camera API2 CTS).
Requisitos VTS
Os dispositivos que executam o Android 8.0 e superior com implementações HAL vinculadas devem passar nos testes Camera VTS .
Endurecimento da estrutura da câmera
Para fortalecer a segurança da estrutura de mídia e câmera, o Android 7.0 move o serviço de câmera para fora do mediaserver. A partir do Android 8.0, cada HAL de câmera vinculado é executado em um processo separado do serviço de câmera. Os fornecedores podem precisar fazer alterações no HAL da câmera, dependendo das versões de API e HAL em uso. As seções a seguir detalham as alterações arquitetônicas no AP1 e AP2 para HAL1 e HAL3, bem como os requisitos gerais.
Mudanças de arquitetura para API1
A gravação de vídeo API1 pode assumir que a câmera e o codificador de vídeo vivem no mesmo processo. Ao usar API1 em:
- HAL3, onde o serviço de câmera usa BufferQueue para passar buffers entre processos, nenhuma atualização do fornecedor é necessária.
- HAL1, que suporta a passagem de metadados em buffers de vídeo, os fornecedores devem atualizar o HAL para usar
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
não é mais suportado no Android 7.0.)
Mudanças de arquitetura para API2
Para API2 em HAL1 ou HAL3, BufferQueue passa buffers para que esses caminhos continuem funcionando. A arquitetura Android 7.0 para API2 em:
- O HAL1 não é afetado pela mudança do serviço de câmera e nenhuma atualização do fornecedor é necessária.
- HAL3 é afetado, mas nenhuma atualização do fornecedor é necessária:
Requisitos adicionais
As alterações arquitetônicas feitas para proteger a mídia e a segurança da estrutura da câmera incluem os seguintes requisitos de dispositivo adicionais.
- Em geral. Os dispositivos requerem largura de banda adicional devido ao IPC, o que pode afetar casos de uso de câmeras sensíveis ao tempo, como gravação de vídeo em alta velocidade. Os fornecedores podem medir o impacto real executando
android.hardware.camera2.cts.PerformanceTest
e o aplicativo Google Camera para gravação de vídeo em alta velocidade de 120/240 FPS. Os dispositivos também requerem uma pequena quantidade de RAM adicional para criar o novo processo. - Passe metadados em buffers de vídeo ( somente HAL1 ). Se HAL1 armazena metadados em vez de dados de quadro YUV reais em buffers de vídeo, o HAL deve usar
kMetadataBufferTypeNativeHandleSource
como o tipo de buffer de metadados e passarVideoNativeHandleMetadata
em buffers de vídeo. (kMetadataBufferTypeCameraSource
não tem mais suporte no Android 7.0.) ComVideoNativeHandleMetadata
, as estruturas de câmera e mídia são capazes de passar os buffers de vídeo entre os processos serializando e desserializando os identificadores nativos corretamente. - O endereço de manipulação do buffer nem sempre armazena o mesmo buffer ( somente HAL3 ). Para cada solicitação de captura, o HAL3 obtém endereços de manipuladores de buffer. O HAL não pode usar os endereços para identificar os buffers porque os endereços podem armazenar outro manipulador de buffer após o HAL retornar o buffer. Você deve atualizar o HAL para usar identificadores de buffer para identificar os buffers. Por exemplo, o HAL recebe um endereço de identificador de buffer A, que armazena o identificador de buffer A. Depois que o HAL retorna o identificador de buffer A, o endereço de identificador de buffer A pode armazenar o identificador de buffer B na próxima vez que o HAL o receber.
- Atualize as políticas do SELinux para o cameraserver. Se as políticas do SELinux específicas do dispositivo concederem permissões de servidor de mídia para executar a câmera, você deverá atualizar as políticas do SELinux para conceder as permissões apropriadas ao servidor de câmera. Desencorajamos a replicação das políticas do SELinux do mediaserver para o cameraserver (já que o mediaserver e o cameraserver geralmente requerem recursos diferentes no sistema). O Cameraserver deve ter apenas as permissões necessárias para executar as funcionalidades da câmera e todas as permissões desnecessárias relacionadas à câmera no mediaserver devem ser removidas.
- Separação entre Camera HAL e cameraserver. O Android 8.0 e superior também separam o HAL da câmera fichário em um processo diferente do cameraserver. O IPC passa por interfaces definidas por HIDL .
Validação
Para todos os dispositivos que incluem uma câmera e executam o Android 7.0, verifique a implementação executando o Android 7.0 CTS. Embora o Android 7.0 não inclua novos testes CTS que verificam alterações no serviço da câmera, os testes CTS existentes falham se você não tiver feito as atualizações indicadas acima.
Para todos os dispositivos que incluem uma câmera e executam o Android 8.0 e superior, verifique a implementação do fornecedor executando o VTS.
Histórico da versão HAL da câmera
Para obter uma lista de testes disponíveis para avaliar o Android Camera HAL, consulte a Lista de verificação de teste do Camera HAL .
Android 10
O Android 10 apresenta as seguintes atualizações.
API da câmera
- Aprimoramentos de várias câmeras que permitem que câmeras físicas sejam usadas individualmente ou por meio de câmeras lógicas correspondentes, ocultando IDs de câmeras físicas. Consulte Suporte para várias câmeras .
- Capacidade de verificar se uma configuração de sessão específica é suportada sem a sobrecarga de desempenho de criar uma nova sessão. Consulte
CameraDevice
. - Capacidade de recuperar configurações de fluxo recomendadas para um determinado caso de uso para tornar o cliente mais eficiente em termos de energia e desempenho. Consulte
getRecommendedStreamConfigurationMap
. - Suporte para o formato de imagem JPEG de profundidade . Para obter mais detalhes, consulte a especificação de profundidade dinâmica .
- Suporte para o formato de imagem HEIC . Consulte Imagem HEIF .
- Melhorias de privacidade. Certas chaves são necessárias para que o cliente tenha permissões
CAMERA
antes que possam ser recuperadas deCameraCharacteristics
. ConsultegetKeysNeedingPermission
.
Câmara HAL
As seguintes versões do Camera HAL são atualizadas no Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: as informações estáticas da câmera para um ID de câmera física que suporta um dispositivo de câmera lógico. Consulte Suporte para várias câmeras . -
isStreamCombinationSupported
: este método oferece suporte a uma API pública que ajuda os clientes a consultar se uma configuração de sessão é compatível. Consulte API para consultar combinações de fluxo .
ICameraDeviceSession
-
isReconfigurationNeeded
: Método que informa à estrutura da câmera se a reconfiguração completa do fluxo é necessária para possíveis novos valores de parâmetro de sessão. Isso ajuda a evitar atrasos desnecessários na reconfiguração da câmera. Consulte Consulta de reconfiguração de sessão . - APIs de gerenciamento de buffer HAL : essas APIs permitem que o HAL da câmera solicite buffers da estrutura da câmera somente quando necessário, em vez de acoplar cada solicitação de captura com seus buffers associados em todo o pipeline da câmera, resultando em economia de memória potencialmente significativa.
-
signalStreamFlush
: Sinaliza para o HAL que o serviço de câmera está prestes a executarconfigureStreams_3_5
e que o HAL deve retornar todos os buffers de fluxos designados. -
configureStreams_3_5
: Semelhante aICameraDevice3.4.configureStreams
, mas além disso, o contadorstreamConfigCounter
é fornecido para verificar uma condição de corrida entre as chamadasconfigureStreams_3_5
esignalStreamFlush
.
-
Atualizações para ICameraDeviceCallback
:
-
requestStreamBuffers
: Retorno de chamada síncrono que o HAL da câmera chama para solicitar buffers ao servidor da câmera. ConsulterequestStreamBuffers
. -
returnStreamBuffers
: Retorno de chamada síncrono para o HAL da câmera para retornar os buffers de saída ao servidor da câmera. ConsultereturnStreamBuffers
.
3.4
As seguintes chaves são adicionadas aos metadados da câmera no Android 10.
- Formatos de imagem
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Tags de metadados da câmera
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capacidades
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Valores para a chave
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Configurações dinâmicas de fluxo de profundidade disponíveis
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Configurações de fluxo HEIC disponíveis
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
módulo de câmera
As seguintes versões do módulo de câmera são atualizadas no Android 10.
2.5
- Adiciona o método
notifyDeviceStateChange
para que os dispositivos notifiquem o HAL da câmera quando alterações físicas, como dobras, afetam a câmera e o roteamento.
2.4
- Os dispositivos iniciados com API de nível 29 ou superior DEVEM relatar
true
paraisTorchModeSupported
.
Android 9
A versão do Android 9 apresenta as seguintes atualizações para a interface API2 e HAL da câmera.
API da câmera
- Apresenta a API multicâmera para oferecer melhor suporte a dispositivos com várias câmeras voltadas para a mesma direção, permitindo recursos como bokeh e zoom contínuo. Isso permite que os aplicativos visualizem várias câmeras em um dispositivo como uma unidade lógica (câmera lógica). As solicitações de captura também podem ser enviadas para dispositivos de câmera individuais englobados por uma câmera lógica. Consulte Suporte para várias câmeras .
- Apresenta parâmetros de sessão. Os parâmetros de sessão são um subconjunto dos parâmetros de captura disponíveis que podem causar graves atrasos de processamento quando modificados. Esses custos podem ser mitigados se os clientes passarem seus valores iniciais durante a inicialização da sessão de captura. Consulte Parâmetros da sessão .
- Adiciona chaves de dados de estabilização ótica (OIS) para estabilização e efeitos no nível do aplicativo. Veja
STATISTICS_OIS_SAMPLES
. - Adiciona suporte a flash externo. Veja
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Adiciona uma intenção de rastreamento de movimento em
CAPTURE_INTENT
. ConsulteCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Substitui
LENS_RADIAL_DISTORTION
e adicionaLENS_DISTORTION
em seu lugar. - Adiciona modos de correção de distorção em
CaptureRequest
. VejaDISTORTION_CORRECTION_MODE
. - Adiciona suporte para câmeras USB/UVC externas em dispositivos compatíveis. Consulte
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Câmara HAL
3.4
Atualizações para ICameraDeviceSession
-
configureStreams_3_4
: Adiciona suporte parasessionParameters
e câmeras lógicas. -
processCaptureRequest_3_4
: Adiciona suporte para incluir IDs de câmeras físicas na estrutura do stream.
Atualizações para ICameraDeviceCallback
-
processCaptureResult_3_4
: Adiciona metadados físicos da câmera nos resultados da captura.
3.3
As seguintes chaves são adicionadas aos metadados da câmera no Android 9.
- Capacidades
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Tags de metadados da câmera
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
A versão do Android 8.0 apresenta o Treble. Com o Treble, as implementações HAL da câmera do fornecedor devem ser vinculadas . O Android 8.0 também contém estes aprimoramentos importantes para o serviço de câmera:
- Superfícies compartilhadas: Habilita várias superfícies compartilhando o mesmo
OutputConfiguration
- API do sistema para modos de câmera personalizados
-
onCaptureQueueEmpty
Consulte as seções abaixo para obter mais informações sobre esses recursos.
Superfícies compartilhadas
Esse recurso permite que apenas um conjunto de buffers acione duas saídas, como visualização e codificação de vídeo, o que reduz o consumo de energia e memória. Para oferecer suporte a esse recurso, os fabricantes de dispositivos precisam garantir que suas implementações de câmera HAL e gralloc HAL possam criar buffers gralloc que são usados por vários consumidores diferentes (como o compositor/GPU de hardware e o codificador de vídeo), em vez de apenas um consumidor. O serviço de câmera passa os sinalizadores de uso do consumidor para a câmera HAL e gralloc HAL; eles precisam alocar os tipos corretos de buffers ou o HAL da câmera precisa retornar um erro informando que essa combinação de consumidores não é suportada.
Consulte a documentação do desenvolvedor enableSurfaceSharing
para obter detalhes adicionais.
API do sistema para modos de câmera personalizados
A API de câmera pública define dois modos de operação: gravação de alta velocidade normal e restrita. Eles têm uma semântica bastante diferente; por exemplo, o modo de alta velocidade é limitado a no máximo duas saídas específicas ao mesmo tempo. Vários OEMs manifestaram interesse em definir outros modos personalizados para recursos específicos de hardware. Nos bastidores, o modo é apenas um número inteiro passado para configure_streams
. Consulte: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
Esse recurso inclui uma chamada de API do sistema que os aplicativos de câmera OEM podem usar para habilitar um modo personalizado. Esses modos devem começar no valor inteiro 0x8000 para evitar conflitos com modos futuros adicionados à API pública.
Para oferecer suporte a esse recurso, os OEMs precisam apenas adicionar o novo modo ao HAL, acionado por esse número inteiro passado para o HAL em configure_streams e, em seguida, fazer com que seu aplicativo de câmera personalizado use a API do sistema.
O nome do método é android.hardware.camera2.CameraDevice#createCustomCaptureSession
. Veja: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
O objetivo dessa API é reduzir a latência das alterações de controle, como zoom, mantendo a fila de solicitações o mais vazia possível. onCaptureQueueEmpty
não requer trabalho HAL; foi puramente uma adição do lado da estrutura. Os aplicativos que desejam aproveitá-lo precisam adicionar um ouvinte a esse retorno de chamada e responder adequadamente. Geralmente, isso ocorre enviando outra solicitação de captura para o dispositivo da câmera.
Interface HIDL da câmera
A interface Camera HIDL é uma revisão completa da interface Camera HAL que usa APIs definidas por HIDL estáveis. Todos os recursos e capacidades de câmera introduzidos nas versões legadas mais recentes 3.4 e 2.4 (para o módulo de câmera) também fazem parte das definições HIDL.
3.4
Pequenas adições aos metadados suportados e alterações no suporte data_space:
- Adicione os metadados estáticos
ANDROID_SENSOR_OPAQUE_RAW_SIZE
como obrigatórios se o formatoRAW_OPAQUE
for compatível. - Adicione os metadados estáticos
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
como obrigatórios se qualquer formato RAW for suportado. - Alterne o campo
camera3_stream_t data_space
para uma definição mais flexível, usando a definição da versão 0 da codificação de espaço de dados. - Adições de metadados gerais que estão disponíveis para uso em HALv3.2 ou mais recente:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Revisão secundária do HAL de capacidade expandida:
- Atualizações da API de reprocessamento OPAQUE e YUV.
- Suporte básico para buffers de saída de profundidade.
- Adição do campo
data_space
acamera3_stream_t
. - Adição do campo de rotação a
camera3_stream_t
. - Adição do modo de operação de configuração de fluxo camera3 a
camera3_stream_configuration_t
.
3.2
Revisão secundária do HAL de capacidade expandida:
- Substitui
get_metadata_vendor_tag_ops
. Em vez disso, useget_vendor_tag_ops
emcamera_common.h
. - Substitui
register_stream_buffers
. Todos os buffers gralloc fornecidos pela estrutura para HAL emprocess_capture_request
podem ser novos a qualquer momento. - Adicionar suporte de resultado parcial.
process_capture_result
pode ser chamado várias vezes com um subconjunto dos resultados disponíveis antes que o resultado completo esteja disponível. - Adicione o modelo manual a
camera3_request_template
. Os aplicativos podem usar este modelo para controlar as configurações de captura diretamente. - Refaça as especificações bidirecionais e de fluxo de entrada.
- Altere o caminho de retorno do buffer de entrada. O buffer é retornado em
process_capture_result
em vez deprocess_capture_request
.
3.1
Revisão secundária do HAL de capacidade expandida:
-
configure_streams
passa sinalizadores de uso do consumidor para o HAL. - flush para descartar todas as solicitações/buffers em andamento o mais rápido possível.
3.0
Primeira revisão do HAL de capacidade expandida:
- Mudança de versão principal, pois a ABI é completamente diferente. Nenhuma alteração nos recursos de hardware necessários ou modelo operacional de 2.0.
- Solicitação de entrada retrabalhada e interfaces de fila de fluxo: chamadas de estrutura para HAL com a próxima solicitação e buffers de fluxo já retirados da fila. O suporte à estrutura de sincronização está incluído, necessário para implementações eficientes.
- Gatilhos movidos para solicitações, a maioria das notificações para resultados.
- Consolidou todos os retornos de chamada na estrutura em uma estrutura e todos os métodos de configuração em uma única chamada
initialize()
. - Configuração de fluxo feita em uma única chamada para simplificar o gerenciamento de fluxo. Fluxos bidirecionais substituem a construção
STREAM_FROM_STREAM
. - Semântica de modo limitado para dispositivos de hardware mais antigos/limitados.
2.0
Versão inicial do HAL de capacidade expandida (Android 4.2) [camera2.h]:
- Suficiente para implementar a API
android.hardware.Camera
existente. - Permite a fila ZSL na camada de serviço da câmera.
- Não testado para novos recursos, como controle de captura manual, captura Bayer RAW, reprocessamento de dados RAW, etc.
1,0
HAL inicial da câmera do Android (Android 4.0) [camera.h]:
- Convertido da camada de abstração C++ CameraHardwareInterface.
- Suporta
android.hardware.Camera
API.
Histórico da versão do módulo da câmera
Esta seção contém informações de versão do módulo para o módulo de hardware da câmera, com base em camera_module_t.common.module_api_version
. Os dois dígitos hexadecimais mais significativos representam a versão principal e os dois menos significativos representam a versão secundária.
2.4
Esta versão do módulo de câmera adiciona as seguintes alterações de API:
- Suporte ao modo tocha. A estrutura pode ativar o modo de tocha para qualquer dispositivo de câmera que possua uma unidade de flash, sem abrir um dispositivo de câmera. O dispositivo de câmera tem uma prioridade maior para acessar a unidade de flash do que o módulo de câmera; a abertura de um dispositivo de câmera desliga a tocha se ela tiver sido habilitada por meio da interface do módulo. Quando há algum conflito de recursos, como
open()
é chamado para abrir um dispositivo de câmera, o módulo HAL da câmera deve notificar o framework através do retorno de chamada de status do modo de tocha que o modo de tocha foi desligado. - Suporte para câmera externa (por exemplo, câmera USB hot-plug). As atualizações da API especificam que as informações estáticas da câmera estão disponíveis somente quando a câmera está conectada e pronta para uso em câmeras hot-plug externas. As chamadas para obter informações estáticas são chamadas inválidas quando o status da câmera não é
CAMERA_DEVICE_STATUS_PRESENT
. O framework conta apenas com callbacks de mudança de status do dispositivo para gerenciar a lista de câmeras externas disponíveis. - Dicas de arbitragem da câmera. Adiciona suporte para indicar explicitamente o número de dispositivos de câmera que podem ser abertos e usados simultaneamente. Para especificar combinações válidas de dispositivos, os campos
resource_cost
econflicting_devices
sempre devem ser definidos na estruturacamera_info
retornada pela chamadaget_camera_info
. - Método de inicialização do módulo. Chamado pelo serviço de câmera depois que o módulo HAL é carregado para permitir a inicialização única do HAL. Ele é chamado antes de qualquer outro método de módulo ser invocado.
2.3
Esta versão do módulo de câmera adiciona suporte a dispositivos HAL de câmera herdada aberta. A estrutura pode usá-lo para abrir o dispositivo de câmera como um dispositivo HAL de versão HAL inferior se o mesmo dispositivo puder oferecer suporte a várias versões de API de dispositivo. A chamada aberta do módulo de hardware padrão ( common.methods->open
) continua a abrir o dispositivo de câmera com a versão suportada mais recente, que também é a versão listada em camera_info_t.device_version
.
2.2
Esta versão do módulo de câmera adiciona suporte de tag de fornecedor do módulo e torna obsoleto o antigo vendor_tag_query_ops
que anteriormente só era acessível com um dispositivo aberto.
2.1
Esta versão do módulo de câmera adiciona suporte para retornos de chamada assíncronos à estrutura do módulo HAL da câmera, que é usado para notificar a estrutura sobre alterações no estado do módulo da câmera. Os módulos que fornecem um método set_callbacks()
válido devem relatar pelo menos este número de versão.
2.0
Os módulos de câmera que relatam esse número de versão implementam a segunda versão da interface HAL do módulo de câmera. Os dispositivos de câmera que podem ser abertos por meio deste módulo podem suportar a versão 1.0 ou a versão 2.0 da interface HAL do dispositivo de câmera. O campo device_version
de camera_info é sempre válido; o campo static_camera_characteristics
de camera_info
é válido se o campo device_version
for 2.0 ou superior.
1,0
Os módulos de câmera que relatam esses números de versão implementam a interface HAL do módulo de câmera inicial. Todos os dispositivos de câmera que podem ser abertos por meio deste módulo suportam apenas a versão 1 do dispositivo de câmera HAL. Os campos device_version
e static_camera_characteristics
de camera_info
não são válidos. Somente a API android.hardware.Camera
pode ser suportada por este módulo e seus dispositivos.
Esta página detalha as diferenças de versão em Camera HALs, APIs e testes de Compatibility Test Suite (CTS) associados. Ele também abrange várias alterações arquitetônicas feitas para fortalecer e proteger a estrutura da câmera no Android 7.0, a mudança para Treble no Android 8.0 e as atualizações que os fornecedores devem fazer para oferecer suporte a essas alterações em suas implementações de câmera.
Terminologia
Os seguintes termos são usados nesta página:
- API da câmera1
- A estrutura da câmera no nível do aplicativo em dispositivos Android 4.4 e anteriores, exposta por meio da classe
android.hardware.Camera
. - API2 da câmera
- A estrutura da câmera no nível do aplicativo em dispositivos Android 5.0 e superiores, exposta por meio do pacote
android.hardware.camera2
. - Câmara HAL
- A camada do módulo de câmera implementada por fornecedores de SoC. As estruturas públicas no nível do aplicativo são construídas sobre o HAL da câmera.
- Câmera HAL3.1
- Versão do dispositivo de câmera HAL lançado com Android 4.4.
- Câmera HAL3.2
- Versão do dispositivo de câmera HAL lançado com Android 5.0.
- Câmera API1 CTS
- Conjunto de testes CTS de câmera executados sobre a API1 da câmera.
- Câmera API2 CTS
- Conjunto adicional de testes CTS de câmera que são executados sobre o Camera API2.
- agudos
- Separa a implementação do fornecedor (software de nível inferior específico do dispositivo escrito por fabricantes de silício) da estrutura do sistema operacional Android por meio de uma nova interface do fornecedor.
- HIDL
- Linguagem de definição de interface HAL introduzida com Treble e usada para especificar a interface entre um HAL e seus usuários.
- VTS
- Conjunto de teste do fornecedor introduzido juntamente com o Treble.
APIs da câmera
O Android inclui as seguintes APIs de câmera.
API da câmera1
O Android 5.0 foi descontinuado Camera API1, que continua a ser descontinuado à medida que o desenvolvimento de novas plataformas se concentra na Camera API2. No entanto, o período de eliminação será longo e os lançamentos do Android continuarão a oferecer suporte aos aplicativos Camera API1 por algum tempo. Especificamente, o suporte continua para:
- Interfaces API1 da câmera para aplicativos. Os aplicativos de câmera criados com base na Camera API1 devem funcionar da mesma forma que em dispositivos que executam versões anteriores do Android.
- Versões da câmera HAL. Inclui suporte para câmera HAL1.0.
API2 da câmera
A estrutura Camera API2 expõe o controle de câmera de nível inferior para o aplicativo, incluindo fluxos eficientes de burst/streaming de cópia zero e controles por quadro de exposição, ganho, ganhos de balanço de branco, conversão de cores, redução de ruído, nitidez e muito mais. Para obter detalhes, assista ao vídeo de visão geral do Google I/O .
Android 5.0 e superior inclui Camera API2; no entanto, os dispositivos com Android 5.0 e superior podem não oferecer suporte a todos os recursos Camera API2. A propriedade android.info.supportedHardwareLevel
que os aplicativos podem consultar por meio das interfaces Camera API2 relata um dos seguintes níveis de suporte:
-
LEGACY
: Esses dispositivos expõem recursos a aplicativos por meio das interfaces Camera API2 que são aproximadamente os mesmos recursos expostos a aplicativos por meio das interfaces Camera API1. O código de estruturas herdadas converte conceitualmente as chamadas Camera API2 em chamadas Camera API1; os dispositivos herdados não oferecem suporte aos recursos Camera API2, como controles por quadro. -
LIMITED
: Esses dispositivos suportam alguns recursos da API2 da câmera (mas não todos) e devem usar o Camera HAL 3.2 ou superior. -
FULL
: Esses dispositivos oferecem suporte a todos os principais recursos do Camera API2 e devem usar o Camera HAL 3.2 ou superior e o Android 5.0 ou superior. -
LEVEL_3
: Esses dispositivos suportam reprocessamento YUV e captura de imagem RAW, juntamente com configurações de fluxo de saída adicionais. -
EXTERNAL
: Esses dispositivos são semelhantes aos dispositivosLIMITED
com algumas exceções; por exemplo, algumas informações do sensor ou da lente podem não ser relatadas ou ter taxas de quadros menos estáveis. Este nível é usado para câmeras externas, como webcams USB.
Os recursos individuais são expostos por meio da propriedade android.request.availableCapabilities
nas interfaces Camera API2. Os dispositivos FULL
requerem os recursos MANUAL_SENSOR
e MANUAL_POST_PROCESSING
, entre outros. A capacidade RAW
é opcional mesmo para dispositivos FULL
. Os dispositivos LIMITED
podem anunciar qualquer subconjunto desses recursos, incluindo nenhum deles. No entanto, o recurso BACKWARD_COMPATIBLE
sempre deve ser definido.
O nível de hardware compatível do dispositivo, bem como os recursos específicos da Camera API2 compatíveis, estão disponíveis como os seguintes sinalizadores de recursos para permitir a filtragem do Google Play de aplicativos de câmera Camera API2.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
Requisitos CTS
Os dispositivos que executam o Android 5.0 e superior devem passar nos testes de câmera Camera API1 CTS, Camera API2 CTS e CTS Verifier.
Os dispositivos que não apresentam uma implementação de Camera HAL3.2 e não são capazes de suportar todas as interfaces Camera API2 ainda devem passar nos testes Camera API2 CTS. No entanto, o dispositivo é executado no modo Camera API2 LEGACY
(no qual as chamadas Camera API2 são mapeadas conceitualmente para chamadas Camera API1), portanto, quaisquer testes de Camera API2 CTS relacionados a recursos ou capacidades além da Camera API1 são ignorados automaticamente.
Em dispositivos legados, os testes Camera API2 CTS que são executados usam as interfaces e recursos públicos Camera API1 existentes sem novos requisitos. Os bugs expostos (e que causam uma falha CTS API2 da câmera) são bugs já presentes no Camera HAL existente do dispositivo e, portanto, seriam encontrados pelos aplicativos Camera API1 existentes. Não esperamos muitos bugs dessa natureza (no entanto, esses bugs devem ser corrigidos para passar nos testes Camera API2 CTS).
Requisitos VTS
Os dispositivos que executam o Android 8.0 e superior com implementações HAL vinculadas devem passar nos testes Camera VTS .
Endurecimento da estrutura da câmera
Para fortalecer a segurança da estrutura de mídia e câmera, o Android 7.0 move o serviço de câmera para fora do mediaserver. A partir do Android 8.0, cada HAL de câmera vinculado é executado em um processo separado do serviço de câmera. Os fornecedores podem precisar fazer alterações no HAL da câmera, dependendo das versões de API e HAL em uso. As seções a seguir detalham as alterações arquitetônicas no AP1 e AP2 para HAL1 e HAL3, bem como os requisitos gerais.
Mudanças de arquitetura para API1
A gravação de vídeo API1 pode assumir que a câmera e o codificador de vídeo vivem no mesmo processo. Ao usar API1 em:
- HAL3, onde o serviço de câmera usa BufferQueue para passar buffers entre processos, nenhuma atualização do fornecedor é necessária.
- HAL1, que suporta a passagem de metadados em buffers de vídeo, os fornecedores devem atualizar o HAL para usar
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
não é mais suportado no Android 7.0.)
Mudanças de arquitetura para API2
Para API2 em HAL1 ou HAL3, BufferQueue passa buffers para que esses caminhos continuem funcionando. A arquitetura Android 7.0 para API2 em:
- O HAL1 não é afetado pela mudança do serviço de câmera e nenhuma atualização do fornecedor é necessária.
- HAL3 é afetado, mas nenhuma atualização do fornecedor é necessária:
Requisitos adicionais
As alterações arquitetônicas feitas para proteger a mídia e a segurança da estrutura da câmera incluem os seguintes requisitos de dispositivo adicionais.
- Em geral. Devices require additional bandwidth due to IPC, which may affect time-sensitive camera use cases such as high-speed video recording. Vendors can measure actual impact by running
android.hardware.camera2.cts.PerformanceTest
and the Google Camera app for 120/240 FPS high-speed video recording. Devices also require a small amount of additional RAM to create the new process. - Pass metadata in video buffers ( HAL1 only ). If HAL1 stores metadata instead of real YUV frame data in video buffers, the HAL must use
kMetadataBufferTypeNativeHandleSource
as the metadata buffer type and passVideoNativeHandleMetadata
in video buffers. (kMetadataBufferTypeCameraSource
is no longer supported on Android 7.0.) WithVideoNativeHandleMetadata
, camera and media frameworks are able to pass the video buffers between processes by serializing and deserializing the native handles properly. - Buffer handle address doesn't always store the same buffer ( HAL3 only ). For each capture request, HAL3 gets addresses of buffer handles. HAL can't use the addresses to identify buffers because the addresses may store another buffer handle after HAL returns the buffer. You must update the HAL to use buffer handles to identify the buffers. For example, HAL receives a buffer handle address A, which stores buffer handle A. After HAL returns buffer handle A, buffer handle address A may store buffer handle B next time the HAL receives it.
- Update SELinux policies for cameraserver. If device-specific SELinux policies give mediaserver permissions to run the camera, you must update the SELinux policies to give cameraserver proper permissions. We discourage replicating the mediaserver's SELinux policies for cameraserver (as mediaserver and cameraserver generally require different resources in the system). Cameraserver should have only the permissions needed to perform camera functionalities and any unnecessary camera-related permissions in mediaserver should be removed.
- Separation between Camera HAL and cameraserver. Android 8.0 and higher additionally separate the binderized Camera HAL in a process different from cameraserver. IPC goes through HIDL-defined interfaces.
Validação
For all devices that include a camera and run Android 7.0, verify the implementation by running Android 7.0 CTS. Although Android 7.0 doesn't include new CTS tests that verify camera service changes, existing CTS tests fail if you haven't made the updates indicated above.
For all devices that include a camera and run Android 8.0 and higher, verify the vendor implementation by running VTS.
Camera HAL version history
For a list of tests available for evaluating the Android Camera HAL, see the Camera HAL Testing Checklist .
Android 10
Android 10 introduces the following updates.
Camera API
- Multi-camera improvements that allow physical cameras to be used individually or through corresponding logical cameras by hiding physical camera IDs. See Multi-Camera Support .
- Ability to check whether a particular session configuration is supported without the performance overhead of creating a new session. See
CameraDevice
. - Ability to retrieve recommended stream configurations for a given use case to make the client more power efficient and performant. See
getRecommendedStreamConfigurationMap
. - Support for the depth JPEG image format . For further details, see the Dynamic Depth specification .
- Support for the HEIC Image format . See HEIF Imaging .
- Privacy improvements. Certain keys are required for the client to have
CAMERA
permissions before they can be retrieved fromCameraCharacteristics
. SeegetKeysNeedingPermission
.
Camera HAL
The following Camera HAL versions are updated in Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: The static camera information for a physical camera ID backing a logical camera device. See Multi-Camera Support . -
isStreamCombinationSupported
: This method supports a public API that helps clients query if a session configuration is supported. See API to query stream combinations .
ICameraDeviceSession
-
isReconfigurationNeeded
: Method that tells the camera framework whether complete stream reconfiguration is required for possible new session parameter values. This helps avoid unnecessary camera reconfiguration delays. See Session reconfiguration query . - HAL buffer management APIs : These APIs allow the camera HAL to request buffers from the camera framework only when required instead of coupling each capture request with its associated buffers throughout the camera pipeline, resulting in potentially significant memory savings.
-
signalStreamFlush
: Signals to the HAL that the camera service is about to performconfigureStreams_3_5
and that the HAL must return all buffers of designated streams. -
configureStreams_3_5
: Similar toICameraDevice3.4.configureStreams
, but in addition, thestreamConfigCounter
counter is provided to check for a race condition between theconfigureStreams_3_5
andsignalStreamFlush
calls.
-
Updates to ICameraDeviceCallback
:
-
requestStreamBuffers
: Synchronous callback that the camera HAL calls to ask the camera server for buffers. SeerequestStreamBuffers
. -
returnStreamBuffers
: Synchronous callback for the camera HAL to return output buffers to the camera server. SeereturnStreamBuffers
.
3.4
The following keys are added to camera metadata in Android 10.
- Image formats
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Camera metadata tags
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Values for the
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
key-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Available dynamic depth stream configurations
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Available HEIC stream configurations
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Camera module
The following camera module versions are updated in Android 10.
2.5
- Adds the
notifyDeviceStateChange
method for devices to notify the camera HAL when physical changes, such as folding, affect camera and routing.
2.4
- Devices launching with API level 29 or higher MUST report
true
forisTorchModeSupported
.
Android 9
The Android 9 release introduces the following updates to the camera API2 and HAL interface.
Camera API
- Introduces the multi-camera API to better support devices with multiple cameras facing in the same direction, enabling features such as bokeh and seamless zoom. This allows apps to view multiple cameras on a device as one logical unit (logical camera). Capture requests can also be sent to individual camera devices encompassed by one logical camera. See Multi-Camera Support .
- Introduces session parameters. Session parameters are a subset of the available capture parameters that can cause severe processing delays when modified. These costs can be mitigated if clients pass their initial values during capture session initialization. See Session Parameters .
- Adds optical stabilization (OIS) data keys for app-level stabilization and effects. See
STATISTICS_OIS_SAMPLES
. - Adds external flash support. See
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Adds a motion tracking intent in
CAPTURE_INTENT
. SeeCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Deprecates
LENS_RADIAL_DISTORTION
and addsLENS_DISTORTION
in its place. - Adds distortion correction modes in
CaptureRequest
. SeeDISTORTION_CORRECTION_MODE
. - Adds support for external USB/UVC cameras on supported devices. See
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Camera HAL
3.4
Updates to ICameraDeviceSession
-
configureStreams_3_4
: Adds support forsessionParameters
and logical cameras. -
processCaptureRequest_3_4
: Adds support for including physical camera IDs in stream structure.
Updates to ICameraDeviceCallback
-
processCaptureResult_3_4
: Adds physical camera metadata in capture results.
3.3
The following keys are added to camera metadata in Android 9.
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Camera metadata tags
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
The Android 8.0 release introduces Treble. With Treble, vendor Camera HAL implementations must be binderized . Android 8.0 also contains these key enhancements to the Camera service:
- Shared surfaces: Enable multiple surfaces sharing the same
OutputConfiguration
- System API for custom camera modes
-
onCaptureQueueEmpty
See the sections below for more information on these features.
Shared surfaces
This feature enables only one set of buffers to drive two outputs, such as preview and video encoding, which lowers power and memory consumption. To support this feature, device manufacturers need to ensure their camera HAL and gralloc HAL implementations can create gralloc buffers that are used by multiple different consumers (such as the hardware composer/GPU and the video encoder), instead of just one consumer. The camera service passes the consumer usage flags to the camera HAL and the gralloc HAL; they need to either allocate the right kinds of buffers, or the camera HAL needs to return an error that this combination of consumers isn't supported.
See the enableSurfaceSharing
developer documentation for additional details.
System API for custom camera modes
The public camera API defines two operating modes: normal and constrained high-speed recording. They have fairly different semantics; for example, high-speed mode is limited to at most two specific outputs at once. Various OEMs have expressed interest in defining other custom modes for hardware-specific capabilities. Under the hood, the mode is just an integer passed to configure_streams
. See: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
This feature includes a system API call that OEM camera apps can use to enable a custom mode. These modes must start at integer value 0x8000 to avoid conflicting with future modes added to the public API.
To support this feature, OEMs merely need to add the new mode to their HAL, triggered by this integer passed to the HAL on configure_streams, and then have their custom camera app use the system API.
The method name is android.hardware.camera2.CameraDevice#createCustomCaptureSession
. See: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
The purpose of this API is to reduce the latency of control changes like zoom by keeping the request queue as empty as possible. onCaptureQueueEmpty
requires no HAL work; it was purely a framework-side addition. Applications that want to take advantage of it need to add a listener to that callback and respond appropriately. Generally that's by sending another capture request to the camera device.
Camera HIDL interface
The Camera HIDL interface is a complete overhaul of the Camera HAL interface that uses stable HIDL-defined APIs. All features and camera capabilities introduced in the most recent legacy versions 3.4 and 2.4 (for the camera module) are also part of the HIDL definitions.
3.4
Minor additions to supported metadata and changes to data_space support:
- Add
ANDROID_SENSOR_OPAQUE_RAW_SIZE
static metadata as mandatory ifRAW_OPAQUE
format is supported. - Add
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
static metadata as mandatory if any RAW format is supported. - Switch
camera3_stream_t data_space
field to a more flexible definition, using the version 0 definition of dataspace encoding. - General metadata additions which are available to use for HALv3.2 or newer:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Minor revision of expanded-capability HAL:
- OPAQUE and YUV reprocessing API updates.
- Basic support for depth output buffers.
- Addition of
data_space
field tocamera3_stream_t
. - Addition of rotation field to
camera3_stream_t
. - Addition of camera3 stream configuration operation mode to
camera3_stream_configuration_t
.
3.2
Minor revision of expanded-capability HAL:
- Deprecates
get_metadata_vendor_tag_ops
. Useget_vendor_tag_ops
incamera_common.h
instead. - Deprecates
register_stream_buffers
. All gralloc buffers provided by framework to HAL inprocess_capture_request
may be new at any time. - Add partial result support.
process_capture_result
may be called multiple times with a subset of the available results before the full result is available. - Add manual template to
camera3_request_template
. Applications may use this template to control the capture settings directly. - Rework the bidirectional and input stream specifications.
- Change the input buffer return path. The buffer is returned in
process_capture_result
instead ofprocess_capture_request
.
3.1
Minor revision of expanded-capability HAL:
-
configure_streams
passes consumer usage flags to the HAL. - flush call to drop all in-flight requests/buffers as fast as possible.
3.0
First revision of expanded-capability HAL:
- Major version change since the ABI is completely different. No change to the required hardware capabilities or operational model from 2.0.
- Reworked input request and stream queue interfaces: Framework calls into HAL with next request and stream buffers already dequeued. Sync framework support is included, necessary for efficient implementations.
- Moved triggers into requests, most notifications into results.
- Consolidated all callbacks into framework into one structure, and all setup methods into a single
initialize()
call. - Made stream configuration into a single call to simplify stream management. Bidirectional streams replace the
STREAM_FROM_STREAM
construct. - Limited mode semantics for older/limited hardware devices.
2.0
Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:
- Sufficient for implementing existing
android.hardware.Camera
API. - Allows for ZSL queue in camera service layer.
- Not tested for any new features such as manual capture control, Bayer RAW capture, reprocessing of RAW data, etc.
1.0
Initial Android camera HAL (Android 4.0) [camera.h]:
- Converted from C++ CameraHardwareInterface abstraction layer.
- Supports
android.hardware.Camera
API.
Camera module version history
This section contains module versioning information for the Camera hardware module, based on camera_module_t.common.module_api_version
. The two most significant hex digits represent the major version, and the two least significant represent the minor version.
2.4
This camera module version adds the following API changes:
- Torch mode support. The framework can turn on torch mode for any camera device that has a flash unit, without opening a camera device. The camera device has a higher priority accessing the flash unit than the camera module; opening a camera device turns off the torch if it had been enabled through the module interface. When there are any resource conflicts, such as
open()
is called to open a camera device, the camera HAL module must notify the framework through the torch mode status callback that the torch mode has been turned off. - External camera (for example, USB hot-plug camera) support. The API updates specify the camera static info is available only when camera is connected and ready to use for external hot-plug cameras. Calls to get static info are invalid calls when camera status isn't
CAMERA_DEVICE_STATUS_PRESENT
. The framework counts solely on device status change callbacks to manage the available external camera list. - Camera arbitration hints. Adds support for explicitly indicating the number of camera devices that can be simultaneously opened and used. To specify valid combinations of devices, the
resource_cost
andconflicting_devices
fields should always be set in thecamera_info
structure returned by theget_camera_info
call. - Module initialization method. Called by the camera service after the HAL module is loaded to allow for one-time initialization of the HAL. It is called before any other module methods are invoked.
2.3
This camera module version adds open legacy camera HAL device support. The framework can use it to open the camera device as lower device HAL version HAL device if the same device can support multiple device API versions. The standard hardware module open call ( common.methods->open
) continues to open the camera device with the latest supported version, which is also the version listed in camera_info_t.device_version
.
2.2
This camera module version adds vendor tag support from the module, and deprecates the old vendor_tag_query_ops
that were previously only accessible with a device open.
2.1
This camera module version adds support for asynchronous callbacks to the framework from the camera HAL module, which is used to notify the framework about changes to the camera module state. Modules that provide a valid set_callbacks()
method must report at least this version number.
2.0
Camera modules that report this version number implement the second version of the camera module HAL interface. Camera devices openable through this module may support either version 1.0 or version 2.0 of the camera device HAL interface. The device_version
field of camera_info is always valid; the static_camera_characteristics
field of camera_info
is valid if the device_version
field is 2.0 or higher.
1.0
Camera modules that report these version numbers implement the initial camera module HAL interface. All camera devices openable through this module support only version 1 of the camera device HAL. The device_version
and static_camera_characteristics
fields of camera_info
aren't valid. Only the android.hardware.Camera
API can be supported by this module and its devices.
This page details version differences in Camera HALs, APIs, and associated Compatibility Test Suite (CTS) tests. It also covers several architectural changes made to harden and secure the camera framework in Android 7.0, the switch to Treble in Android 8.0, and the updates vendors must make to support these changes in their camera implementations.
Terminology
The following terms are used on this page:
- Camera API1
- The app-level camera framework on Android 4.4 and lower devices, exposed through the
android.hardware.Camera
class. - Camera API2
- The app-level camera framework on Android 5.0 and higher devices, exposed through the
android.hardware.camera2
package. - Camera HAL
- The camera module layer implemented by SoC vendors. The app-level public frameworks are built on top of the camera HAL.
- Camera HAL3.1
- Version of the camera device HAL released with Android 4.4.
- Camera HAL3.2
- Version of the camera device HAL released with Android 5.0.
- Camera API1 CTS
- Set of camera CTS tests that run on top of Camera API1.
- Camera API2 CTS
- Additional set of camera CTS tests that run on top of Camera API2.
- Treble
- Separates the vendor implementation (device-specific, lower-level software written by silicon manufacturers) from the Android OS framework through a new vendor interface.
- HIDL
- HAL interface definition language introduced with Treble and used to specify the interface between a HAL and its users.
- VTS
- Vendor test suite introduced alongside Treble.
Camera APIs
Android includes the following camera APIs.
Camera API1
Android 5.0 deprecated Camera API1, which continues to be phased out as new platform development focuses on Camera API2. However, the phase-out period will be lengthy, and Android releases will continue to support Camera API1 apps for some time. Specifically, support continues for:
- Camera API1 interfaces for apps. Camera apps built on top of Camera API1 should work as they do on devices running lower Android release versions.
- Camera HAL versions. Includes support for Camera HAL1.0.
Camera API2
The Camera API2 framework exposes lower-level camera control to the app, including efficient zero-copy burst/streaming flows and per-frame controls of exposure, gain, white balance gains, color conversion, denoising, sharpening, and more. For details, watch the Google I/O video overview .
Android 5.0 and higher includes Camera API2; however, devices running Android 5.0 and higher may not support all Camera API2 features. The android.info.supportedHardwareLevel
property that apps can query through the Camera API2 interfaces reports one of the following support levels:
-
LEGACY
: These devices expose capabilities to apps through the Camera API2 interfaces that are approximately the same capabilities as those exposed to apps through the Camera API1 interfaces. The legacy frameworks code conceptually translates Camera API2 calls into Camera API1 calls; legacy devices don't support Camera API2 features such as per-frame controls. -
LIMITED
: These devices support some Camera API2 capabilities (but not all) and must use Camera HAL 3.2 or higher. -
FULL
: These devices support all of the major capabilities of Camera API2 and must use Camera HAL 3.2 or higher and Android 5.0 or higher. -
LEVEL_3
: These devices support YUV reprocessing and RAW image capture, along with additional output stream configurations. -
EXTERNAL
: These devices are similar toLIMITED
devices with some exceptions; for example, some sensor or lens information may not be reported or have less stable frame rates. This level is used for external cameras such as USB webcams.
Individual capabilities are exposed through the android.request.availableCapabilities
property in the Camera API2 interfaces. FULL
devices require the MANUAL_SENSOR
and MANUAL_POST_PROCESSING
capabilities, among others. The RAW
capability is optional even for FULL
devices. LIMITED
devices can advertise any subset of these capabilities, including none of them. However, the BACKWARD_COMPATIBLE
capability must always be defined.
The supported hardware level of the device, as well as the specific Camera API2 capabilities it supports, are available as the following feature flags to allow Google Play filtering of Camera API2 camera apps.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
CTS requirements
Devices running Android 5.0 and higher must pass the Camera API1 CTS, Camera API2 CTS, and CTS Verifier camera tests.
Devices that don't feature a Camera HAL3.2 implementation and aren't capable of supporting the full Camera API2 interfaces must still pass the Camera API2 CTS tests. However, the device runs in Camera API2 LEGACY
mode (in which the Camera API2 calls are conceptually mapped to Camera API1 calls) so any Camera API2 CTS tests related to features or capabilities beyond Camera API1 are automatically skipped.
On legacy devices, Camera API2 CTS tests that are run use the existing public Camera API1 interfaces and capabilities with no new requirements. Bugs that are exposed (and that cause a Camera API2 CTS failure) are bugs already present in the device's existing Camera HAL, and thus would be found by existing Camera API1 apps. We don't expect many bugs of this nature (however, any such bugs must be fixed to pass the Camera API2 CTS tests).
VTS requirements
Devices running Android 8.0 and higher with binderized HAL implementations must pass the Camera VTS tests .
Camera framework hardening
To harden media and camera framework security, Android 7.0 moves camera service out of mediaserver. Starting with Android 8.0, each binderized Camera HAL runs in a process separate from camera service. Vendors may need to make changes in the camera HAL depending on the API and HAL versions in use. The following sections detail architectural changes in AP1 and AP2 for HAL1 and HAL3, as well as general requirements.
Architectural changes for API1
API1 video recording may assume camera and video encoder live in the same process. When using API1 on:
- HAL3, where camera service uses BufferQueue to pass buffers between processes, no vendor update is necessary.
- HAL1, which supports passing metadata in video buffers, vendors must update the HAL to use
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
is no longer supported in Android 7.0.)
Architectural changes for API2
For API2 on HAL1 or HAL3, BufferQueue passes buffers so those paths continue to work. The Android 7.0 architecture for API2 on:
- HAL1 isn't affected by the cameraservice move, and no vendor update is necessary.
- HAL3 is affected, but no vendor update is necessary:
Additional requirements
The architectural changes made for hardening media and camera framework security include the following additional device requirements.
- General. Devices require additional bandwidth due to IPC, which may affect time-sensitive camera use cases such as high-speed video recording. Vendors can measure actual impact by running
android.hardware.camera2.cts.PerformanceTest
and the Google Camera app for 120/240 FPS high-speed video recording. Devices also require a small amount of additional RAM to create the new process. - Pass metadata in video buffers ( HAL1 only ). If HAL1 stores metadata instead of real YUV frame data in video buffers, the HAL must use
kMetadataBufferTypeNativeHandleSource
as the metadata buffer type and passVideoNativeHandleMetadata
in video buffers. (kMetadataBufferTypeCameraSource
is no longer supported on Android 7.0.) WithVideoNativeHandleMetadata
, camera and media frameworks are able to pass the video buffers between processes by serializing and deserializing the native handles properly. - Buffer handle address doesn't always store the same buffer ( HAL3 only ). For each capture request, HAL3 gets addresses of buffer handles. HAL can't use the addresses to identify buffers because the addresses may store another buffer handle after HAL returns the buffer. You must update the HAL to use buffer handles to identify the buffers. For example, HAL receives a buffer handle address A, which stores buffer handle A. After HAL returns buffer handle A, buffer handle address A may store buffer handle B next time the HAL receives it.
- Update SELinux policies for cameraserver. If device-specific SELinux policies give mediaserver permissions to run the camera, you must update the SELinux policies to give cameraserver proper permissions. We discourage replicating the mediaserver's SELinux policies for cameraserver (as mediaserver and cameraserver generally require different resources in the system). Cameraserver should have only the permissions needed to perform camera functionalities and any unnecessary camera-related permissions in mediaserver should be removed.
- Separation between Camera HAL and cameraserver. Android 8.0 and higher additionally separate the binderized Camera HAL in a process different from cameraserver. IPC goes through HIDL-defined interfaces.
Validação
For all devices that include a camera and run Android 7.0, verify the implementation by running Android 7.0 CTS. Although Android 7.0 doesn't include new CTS tests that verify camera service changes, existing CTS tests fail if you haven't made the updates indicated above.
For all devices that include a camera and run Android 8.0 and higher, verify the vendor implementation by running VTS.
Camera HAL version history
For a list of tests available for evaluating the Android Camera HAL, see the Camera HAL Testing Checklist .
Android 10
Android 10 introduces the following updates.
Camera API
- Multi-camera improvements that allow physical cameras to be used individually or through corresponding logical cameras by hiding physical camera IDs. See Multi-Camera Support .
- Ability to check whether a particular session configuration is supported without the performance overhead of creating a new session. See
CameraDevice
. - Ability to retrieve recommended stream configurations for a given use case to make the client more power efficient and performant. See
getRecommendedStreamConfigurationMap
. - Support for the depth JPEG image format . For further details, see the Dynamic Depth specification .
- Support for the HEIC Image format . See HEIF Imaging .
- Privacy improvements. Certain keys are required for the client to have
CAMERA
permissions before they can be retrieved fromCameraCharacteristics
. SeegetKeysNeedingPermission
.
Camera HAL
The following Camera HAL versions are updated in Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: The static camera information for a physical camera ID backing a logical camera device. See Multi-Camera Support . -
isStreamCombinationSupported
: This method supports a public API that helps clients query if a session configuration is supported. See API to query stream combinations .
ICameraDeviceSession
-
isReconfigurationNeeded
: Method that tells the camera framework whether complete stream reconfiguration is required for possible new session parameter values. This helps avoid unnecessary camera reconfiguration delays. See Session reconfiguration query . - HAL buffer management APIs : These APIs allow the camera HAL to request buffers from the camera framework only when required instead of coupling each capture request with its associated buffers throughout the camera pipeline, resulting in potentially significant memory savings.
-
signalStreamFlush
: Signals to the HAL that the camera service is about to performconfigureStreams_3_5
and that the HAL must return all buffers of designated streams. -
configureStreams_3_5
: Similar toICameraDevice3.4.configureStreams
, but in addition, thestreamConfigCounter
counter is provided to check for a race condition between theconfigureStreams_3_5
andsignalStreamFlush
calls.
-
Updates to ICameraDeviceCallback
:
-
requestStreamBuffers
: Synchronous callback that the camera HAL calls to ask the camera server for buffers. SeerequestStreamBuffers
. -
returnStreamBuffers
: Synchronous callback for the camera HAL to return output buffers to the camera server. SeereturnStreamBuffers
.
3.4
The following keys are added to camera metadata in Android 10.
- Image formats
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Camera metadata tags
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Values for the
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
key-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Available dynamic depth stream configurations
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Available HEIC stream configurations
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Camera module
The following camera module versions are updated in Android 10.
2.5
- Adds the
notifyDeviceStateChange
method for devices to notify the camera HAL when physical changes, such as folding, affect camera and routing.
2.4
- Devices launching with API level 29 or higher MUST report
true
forisTorchModeSupported
.
Android 9
The Android 9 release introduces the following updates to the camera API2 and HAL interface.
Camera API
- Introduces the multi-camera API to better support devices with multiple cameras facing in the same direction, enabling features such as bokeh and seamless zoom. This allows apps to view multiple cameras on a device as one logical unit (logical camera). Capture requests can also be sent to individual camera devices encompassed by one logical camera. See Multi-Camera Support .
- Introduces session parameters. Session parameters are a subset of the available capture parameters that can cause severe processing delays when modified. These costs can be mitigated if clients pass their initial values during capture session initialization. See Session Parameters .
- Adds optical stabilization (OIS) data keys for app-level stabilization and effects. See
STATISTICS_OIS_SAMPLES
. - Adds external flash support. See
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Adds a motion tracking intent in
CAPTURE_INTENT
. SeeCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Deprecates
LENS_RADIAL_DISTORTION
and addsLENS_DISTORTION
in its place. - Adds distortion correction modes in
CaptureRequest
. SeeDISTORTION_CORRECTION_MODE
. - Adds support for external USB/UVC cameras on supported devices. See
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Camera HAL
3.4
Updates to ICameraDeviceSession
-
configureStreams_3_4
: Adds support forsessionParameters
and logical cameras. -
processCaptureRequest_3_4
: Adds support for including physical camera IDs in stream structure.
Updates to ICameraDeviceCallback
-
processCaptureResult_3_4
: Adds physical camera metadata in capture results.
3.3
The following keys are added to camera metadata in Android 9.
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Camera metadata tags
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
The Android 8.0 release introduces Treble. With Treble, vendor Camera HAL implementations must be binderized . Android 8.0 also contains these key enhancements to the Camera service:
- Shared surfaces: Enable multiple surfaces sharing the same
OutputConfiguration
- System API for custom camera modes
-
onCaptureQueueEmpty
See the sections below for more information on these features.
Shared surfaces
This feature enables only one set of buffers to drive two outputs, such as preview and video encoding, which lowers power and memory consumption. To support this feature, device manufacturers need to ensure their camera HAL and gralloc HAL implementations can create gralloc buffers that are used by multiple different consumers (such as the hardware composer/GPU and the video encoder), instead of just one consumer. The camera service passes the consumer usage flags to the camera HAL and the gralloc HAL; they need to either allocate the right kinds of buffers, or the camera HAL needs to return an error that this combination of consumers isn't supported.
See the enableSurfaceSharing
developer documentation for additional details.
System API for custom camera modes
The public camera API defines two operating modes: normal and constrained high-speed recording. They have fairly different semantics; for example, high-speed mode is limited to at most two specific outputs at once. Various OEMs have expressed interest in defining other custom modes for hardware-specific capabilities. Under the hood, the mode is just an integer passed to configure_streams
. See: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
This feature includes a system API call that OEM camera apps can use to enable a custom mode. These modes must start at integer value 0x8000 to avoid conflicting with future modes added to the public API.
To support this feature, OEMs merely need to add the new mode to their HAL, triggered by this integer passed to the HAL on configure_streams, and then have their custom camera app use the system API.
The method name is android.hardware.camera2.CameraDevice#createCustomCaptureSession
. See: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
The purpose of this API is to reduce the latency of control changes like zoom by keeping the request queue as empty as possible. onCaptureQueueEmpty
requires no HAL work; it was purely a framework-side addition. Applications that want to take advantage of it need to add a listener to that callback and respond appropriately. Generally that's by sending another capture request to the camera device.
Camera HIDL interface
The Camera HIDL interface is a complete overhaul of the Camera HAL interface that uses stable HIDL-defined APIs. All features and camera capabilities introduced in the most recent legacy versions 3.4 and 2.4 (for the camera module) are also part of the HIDL definitions.
3.4
Minor additions to supported metadata and changes to data_space support:
- Add
ANDROID_SENSOR_OPAQUE_RAW_SIZE
static metadata as mandatory ifRAW_OPAQUE
format is supported. - Add
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
static metadata as mandatory if any RAW format is supported. - Switch
camera3_stream_t data_space
field to a more flexible definition, using the version 0 definition of dataspace encoding. - General metadata additions which are available to use for HALv3.2 or newer:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Minor revision of expanded-capability HAL:
- OPAQUE and YUV reprocessing API updates.
- Basic support for depth output buffers.
- Addition of
data_space
field tocamera3_stream_t
. - Addition of rotation field to
camera3_stream_t
. - Addition of camera3 stream configuration operation mode to
camera3_stream_configuration_t
.
3.2
Minor revision of expanded-capability HAL:
- Deprecates
get_metadata_vendor_tag_ops
. Useget_vendor_tag_ops
incamera_common.h
instead. - Deprecates
register_stream_buffers
. All gralloc buffers provided by framework to HAL inprocess_capture_request
may be new at any time. - Add partial result support.
process_capture_result
may be called multiple times with a subset of the available results before the full result is available. - Add manual template to
camera3_request_template
. Applications may use this template to control the capture settings directly. - Rework the bidirectional and input stream specifications.
- Change the input buffer return path. The buffer is returned in
process_capture_result
instead ofprocess_capture_request
.
3.1
Minor revision of expanded-capability HAL:
-
configure_streams
passes consumer usage flags to the HAL. - flush call to drop all in-flight requests/buffers as fast as possible.
3.0
First revision of expanded-capability HAL:
- Major version change since the ABI is completely different. No change to the required hardware capabilities or operational model from 2.0.
- Reworked input request and stream queue interfaces: Framework calls into HAL with next request and stream buffers already dequeued. Sync framework support is included, necessary for efficient implementations.
- Moved triggers into requests, most notifications into results.
- Consolidated all callbacks into framework into one structure, and all setup methods into a single
initialize()
call. - Made stream configuration into a single call to simplify stream management. Bidirectional streams replace the
STREAM_FROM_STREAM
construct. - Limited mode semantics for older/limited hardware devices.
2.0
Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:
- Sufficient for implementing existing
android.hardware.Camera
API. - Allows for ZSL queue in camera service layer.
- Not tested for any new features such as manual capture control, Bayer RAW capture, reprocessing of RAW data, etc.
1.0
Initial Android camera HAL (Android 4.0) [camera.h]:
- Converted from C++ CameraHardwareInterface abstraction layer.
- Supports
android.hardware.Camera
API.
Camera module version history
This section contains module versioning information for the Camera hardware module, based on camera_module_t.common.module_api_version
. The two most significant hex digits represent the major version, and the two least significant represent the minor version.
2.4
This camera module version adds the following API changes:
- Torch mode support. The framework can turn on torch mode for any camera device that has a flash unit, without opening a camera device. The camera device has a higher priority accessing the flash unit than the camera module; opening a camera device turns off the torch if it had been enabled through the module interface. When there are any resource conflicts, such as
open()
is called to open a camera device, the camera HAL module must notify the framework through the torch mode status callback that the torch mode has been turned off. - External camera (for example, USB hot-plug camera) support. The API updates specify the camera static info is available only when camera is connected and ready to use for external hot-plug cameras. Calls to get static info are invalid calls when camera status isn't
CAMERA_DEVICE_STATUS_PRESENT
. The framework counts solely on device status change callbacks to manage the available external camera list. - Camera arbitration hints. Adds support for explicitly indicating the number of camera devices that can be simultaneously opened and used. To specify valid combinations of devices, the
resource_cost
andconflicting_devices
fields should always be set in thecamera_info
structure returned by theget_camera_info
call. - Module initialization method. Called by the camera service after the HAL module is loaded to allow for one-time initialization of the HAL. It is called before any other module methods are invoked.
2.3
This camera module version adds open legacy camera HAL device support. The framework can use it to open the camera device as lower device HAL version HAL device if the same device can support multiple device API versions. The standard hardware module open call ( common.methods->open
) continues to open the camera device with the latest supported version, which is also the version listed in camera_info_t.device_version
.
2.2
This camera module version adds vendor tag support from the module, and deprecates the old vendor_tag_query_ops
that were previously only accessible with a device open.
2.1
This camera module version adds support for asynchronous callbacks to the framework from the camera HAL module, which is used to notify the framework about changes to the camera module state. Modules that provide a valid set_callbacks()
method must report at least this version number.
2.0
Camera modules that report this version number implement the second version of the camera module HAL interface. Camera devices openable through this module may support either version 1.0 or version 2.0 of the camera device HAL interface. The device_version
field of camera_info is always valid; the static_camera_characteristics
field of camera_info
is valid if the device_version
field is 2.0 or higher.
1.0
Camera modules that report these version numbers implement the initial camera module HAL interface. All camera devices openable through this module support only version 1 of the camera device HAL. The device_version
and static_camera_characteristics
fields of camera_info
aren't valid. Only the android.hardware.Camera
API can be supported by this module and its devices.