O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Extensões do fornecedor CameraX

Os fabricantes de dispositivos podem implementar a biblioteca do fornecedor CameraX OEM para expor efeitos específicos do dispositivo a desenvolvedores de terceiros por meio da interface de extensões CameraX. CameraX define a interface de extensões CameraX para classes implementadas pelo fornecedor carregadas em tempo de execução. Esta página descreve como implementar a biblioteca de fornecedores OEM e habilitá-la nos dispositivos.

Antes de implementar a biblioteca do fornecedor, certifique-se de entender como funciona a biblioteca de suporte do CameraX Jetpack. Para saber mais sobre o CameraX, consulte Visão geral do CameraX . Para obter mais informações sobre extensões de fornecedor, consulte Extensões de fornecedor.

Arquitetura

Arquitetura

Figura 1. Diagrama de arquitetura de extensões do fornecedor

Este diagrama descreve a arquitetura das extensões do fornecedor CameraX. Aplicativos de terceiros podem ser criados na biblioteca de extensões CameraX ( camera-extensions ) e usar a API pública de extensões de câmera ( camera-extensions API ). A API de extensões de câmera é definida pelo CameraX e é atualizada quando uma nova versão da biblioteca de extensões de câmera é lançada. O controle de versão da API pública de extensões de câmera e da biblioteca de extensões de câmera são os mesmos.

A partir do Android 12, aplicativos de terceiros podem ser criados com base na API de extensões Camera2. Para habilitar os modos de extensão compatíveis, os aplicativos podem criar uma sessão de captura de câmera ( CameraExtensionSession ) usando CameraDevice#createExtensionSession() .

A interface de extensões ( extensions-interface ) definida pelo CameraX permite que a biblioteca de extensões de câmera CameraX e a API de extensões Camera2 se comuniquem com a biblioteca do fornecedor OEM ( camera-extensions-stub ). Isso significa que os dispositivos que implementam a biblioteca de fornecedores OEM CameraX também têm suporte para a API de extensões Camera2.

Implementando a biblioteca de fornecedores OEM

Essas instruções de implementação usam a extensão de fornecedor bokeh (retrato) como exemplo, mas você pode aplicá-las a outras extensões, como HDR, retoque facial e extensões de modo noturno. Para fazer isso, copie e cole o código usado para a extensão bokeh e substitua o nome da extensão pela extensão desejada (por exemplo, substituindo BokehImageCaptureExtenderImpl por HdrImageCaptureExtenderImpl ).

Você não é obrigado a fornecer uma implementação para cada efeito. Um efeito sem uma implementação de fornecedor assume como padrão a implementação do CameraX. Se um efeito não estiver disponível, a implementação padrão não habilitará o efeito e informará ao desenvolvedor terceirizado que o efeito não está disponível.

Verificação de versão

Ao carregar a biblioteca OEM, o CameraX verifica se a biblioteca OEM contém uma versão compatível com a versão da interface de extensões (referida como versão de extensão neste documento). Para determinar a compatibilidade da versão, o CameraX verifica apenas as versões principais e secundárias (por exemplo, 1.0), mas não verifica a versão do patch porque é usada apenas para correções de bugs, não para alterações de interface. A versão de extensão necessária para APIs específicas é indicada neste documento. APIs sem uma versão de extensão especificada são compatíveis com a versão de extensão 1.0.

Para verificar a versão, o CameraX consulta a interface ExtensionVersionImpl . O CameraX usa a versão relatada pela biblioteca OEM para determinar a funcionalidade que pode ser chamada.

Inicialização

O CameraX inicia o processo de inicialização quando determina a versão da interface de extensões implementada pela biblioteca OEM. O método InitializerImpl.init sinaliza para a biblioteca OEM que um aplicativo deseja usar extensões. Nenhuma outra chamada para a biblioteca OEM (além da verificação de versão) é feita até OnExtensionsInitializedCallback seja chamado com um estado de sucesso.

Este método deve ser implementado a partir da versão de extensão 1.1. Para obter detalhes, consulte a fonte em InitializerImpl .

Interface ExtenderStateListener

O CameraX fornece ganchos em vários lugares em seu pipeline para permitir que a biblioteca OEM defina valores de SessionParameters e CaptureRequest relevantes. Para permitir que a biblioteca OEM defina esses valores nos horários especificados, implemente a interface ExtenderStateListener . Essa interface deve ser implementada como parte de qualquer extensor, seja um extensor de visualização, captura de imagem, bokeh ou HDR.

Captura de imagem

Para oferecer suporte à extensão para captura de imagem , implemente a interface ImageCaptureExtender correspondente (por exemplo, BokehImageCaptureExtenderImpl ou HdrImageCaptureExtenderImpl ).

ImageCaptureExtenderImpl inclui interfaces necessárias para extensões relacionadas à captura de imagem.

A interface CaptureProcessorImpl deve ser implementada para que o pós-processamento seja feito na camada do aplicativo. A partir da versão 1.1 da interface de extensões, apenas o formato de imagem de entrada YUV_420_888 deve ser suportado. A interface CaptureProcessor não é necessária se o processamento for feito no HAL da câmera.

O diagrama a seguir ilustra o fluxo do processo de captura de imagem.

Fluxo do processo de captura de imagem

Figura 2. Diagrama de fluxo de captura de imagem

Exemplo: BokehImageCaptureExtenderImpl

Para oferecer suporte à extensão bokeh para captura de imagem, implemente a classe BokehImageCaptureExtenderImpl no pacote androidx.camera.extensions.impl .

Visualizar

Para oferecer suporte à extensão para preview , implemente a interface PreviewExtender correspondente (por exemplo, BokehPreviewExtenderImpl ou HdrPreviewExtenderImpl ). A interface PreviewExtender inclui as interfaces necessárias para extensões relacionadas à visualização.

Para obter detalhes, consulte a fonte em PreviewExtenderImpl .

O processamento de imagem para a extensão de visualização pode ser realizado no HAL da câmera ou na camada do aplicativo. Isso é determinado pelo valor de ProcessorType , que é retornado por PreviewExtenderImpl .

Se o tipo PROCESSOR_TYPE_REQUEST_UPDATE_ONLY for retornado, o processamento é executado no HAL por meio de chaves CaptureRequest . Se o tipo PROCESSOR_TYPE_IMAGE_PROCESSOR for retornado, o processamento será executado na camada do aplicativo pela interface PreviewImageProcessorImpl . Essa interface opera em um par Image e TotalCaptureResult . A partir da versão 1.1 da interface de extensões, apenas o formato de imagem de entrada YUV_420_888 deve ser suportado.

O diagrama a seguir ilustra o fluxo do processo para a extensão do fornecedor de visualização.

Visualizar diagrama de fluxo

Figura 3. Diagrama de fluxo de visualização

Exemplo: BokehPreviewExtenderImpl

Para dar suporte ao bokeh para visualização, implemente a classe BokehPreviewExtenderImpl no pacote androidx.camera.extensions.impl .

Implementação de referência

Para obter uma implementação de biblioteca de fornecedor OEM de referência, consulte camera-testlib-extensions . Observe que essa implementação executa passagens sem realmente implementar os efeitos.

Configurando a biblioteca do fornecedor em um dispositivo

A biblioteca do fornecedor OEM não está integrada em um aplicativo, mas é carregada do dispositivo em tempo de execução pelo CameraX. A tag <uses-library> declara que a biblioteca androidx.camera.extensions.impl , que é definida no arquivo AndroidManifest.xml , é uma dependência de CameraX e deve ser carregada em tempo de execução. Isso permite que aplicativos de terceiros que usam extensões de fornecedor tentem carregar automaticamente a biblioteca de fornecedor OEM. A biblioteca OEM é marcada como opcional para que os aplicativos possam ser executados em dispositivos que não possuem a biblioteca no dispositivo.

O CameraX lida com esse comportamento automaticamente quando um aplicativo tenta usar uma extensão de fornecedor, desde que o fabricante do dispositivo coloque a biblioteca OEM no dispositivo para que ela possa ser descoberta pelo aplicativo.

Para configurar a biblioteca OEM em um dispositivo, faça o seguinte:

  1. Adicione um arquivo de permissão, que é exigido pela tag <uses-library> , usando o seguinte formato: /etc/permissions/ ANY_FILENAME .xml . Por exemplo, /etc/permissions/camera_extensions.xml . Os arquivos neste diretório fornecem um mapeamento da biblioteca nomeada em <uses-library> para o caminho real do arquivo no dispositivo.
  2. Use o exemplo abaixo para adicionar as informações necessárias ao arquivo.

    • name deve ser androidx.camera.extensions.impl , pois essa é a biblioteca que o CameraX procura.
    • file é o caminho absoluto do arquivo que contém a implementação das extensões (por exemplo, /system/framework/androidx.camera.extensions.impl.jar ).
    <?xml version="1.0" encoding="utf-8"?>
    <permissions>
        <library name="androidx.camera.extensions.impl"
                 file="OEM_IMPLEMENTED_JAR" />
    </permissions>
    

No Android 12 ou superior, os dispositivos compatíveis com extensões CameraX devem ter a propriedade ro.camerax.extensions.enabled definida como true , que permite consultar se um dispositivo é compatível com extensões. Para fazer isso, adicione a seguinte linha no arquivo de criação do dispositivo:

PRODUCT_VENDOR_PROPERTIES += \
    ro.camerax.extensions.enabled=true \

Validação

Para testar sua implementação da biblioteca de fornecedor OEM durante o estágio de desenvolvimento, use o aplicativo de exemplo em androidx-main/camera/integration-tests/extensionstestapp/ , que é executado por meio de várias extensões de fornecedor.

Depois de concluir sua implementação, use a Ferramenta de validação de extensões de fornecedor CameraX para executar testes automatizados e manuais para verificar se a biblioteca de fornecedor foi implementada corretamente.

Perguntas frequentes (FAQ)

Existem restrições nos níveis de API?

Sim. Isso depende do conjunto de recursos da API do Android exigido pela implementação da biblioteca do fornecedor OEM. Por exemplo, ExtenderStateListener.onPresetSession() usa a chamada SessionConfiguration.setSessionParameters() para definir um conjunto de marcas de linha de base. Essa chamada está disponível apenas na API de nível 28 e superior. Para obter detalhes sobre métodos de interface específicos, consulte a documentação de referência da API .