Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

Extensiones de proveedor de CameraX

Los fabricantes de dispositivos pueden implementar la biblioteca de proveedores OEM de CameraX para exponer los efectos específicos del dispositivo a desarrolladores externos a través de la interfaz de extensiones de CameraX. CameraX define la interfaz de extensiones de CameraX para las clases implementadas por el proveedor cargadas en tiempo de ejecución. Esta página describe cómo implementar la biblioteca de proveedores OEM y habilitarla en los dispositivos.

Antes de implementar la biblioteca de proveedores, asegúrese de comprender cómo funciona la biblioteca de soporte de CameraX Jetpack. Para obtener más información sobre CameraX, consulte Descripción general de CameraX . Para obtener más información sobre las extensiones de proveedores, consulte Extensiones de proveedores.

Arquitectura

Arquitectura

Figura 1. Diagrama de arquitectura de extensiones de proveedor

Este diagrama describe la arquitectura de las extensiones del proveedor de CameraX. Las aplicaciones de terceros se pueden crear con la biblioteca de extensiones de CameraX (extensiones de cámara ) y usar la API pública de extensiones de cámara (API de extensiones de cámara ). CameraX define la API de extensiones de cámara y se actualiza cuando se lanza una nueva versión de la biblioteca de extensiones de cámara. Las versiones de la API pública de extensiones de cámara y la biblioteca de extensiones de cámara son las mismas.

A partir de Android 12, las aplicaciones de terceros se pueden compilar con la API de extensiones de Camera2. Para habilitar los modos de extensión admitidos, las aplicaciones pueden crear una sesión de captura de cámara ( CameraExtensionSession ) mediante CameraDevice#createExtensionSession() .

La interfaz de extensiones (interfaz de extensiones ) definida por CameraX permite que tanto la biblioteca de extensiones de cámara de CameraX como la API de extensiones de Camera2 se comuniquen con la biblioteca del proveedor OEM ( stub de extensiones de cámara ). Esto significa que los dispositivos que implementan la biblioteca de proveedores OEM de CameraX también son compatibles con la API de extensiones de Camera2.

Implementación de la biblioteca de proveedores OEM

Estas instrucciones de implementación utilizan la extensión del proveedor de bokeh (retrato) como ejemplo, pero puede aplicarlas a otras extensiones como HDR, retoque facial y extensiones de modo nocturno. Para hacer esto, copie y pegue el código usado para la extensión bokeh y reemplace el nombre de la extensión con la extensión deseada (por ejemplo, reemplace BokehImageCaptureExtenderImpl con HdrImageCaptureExtenderImpl ).

No es necesario que proporcione una implementación para cada efecto. Un efecto sin una implementación de proveedor tiene como valor predeterminado la implementación de CameraX. Si un efecto no está disponible, la implementación predeterminada no habilita el efecto e informa al desarrollador externo que el efecto no está disponible.

Verificación de versión

Al cargar la biblioteca OEM, CameraX verifica que la biblioteca OEM contenga una versión que sea compatible con la versión de la interfaz de extensiones (denominada versión de extensión en este documento). Para determinar la compatibilidad de la versión, CameraX verifica solo las versiones principales y secundarias (por ejemplo, 1.0), pero no verifica la versión del parche porque se usa solo para corregir errores, no para cambios en la interfaz. La versión de extensión requerida para API específicas se indica en este documento. Las API sin una versión de extensión específica son compatibles con la versión de extensión 1.0.

Para verificar la versión, CameraX consulta la interfaz ExtensionVersionImpl . Luego, CameraX usa la versión informada por la biblioteca OEM para determinar la funcionalidad a la que se puede llamar.

Inicialización

CameraX inicia el proceso de inicialización cuando ha determinado la versión de la interfaz de extensiones implementada por la biblioteca OEM. El método InitializerImpl.init le indica a la biblioteca OEM que una aplicación quiere usar extensiones. No se realizan otras llamadas a la biblioteca OEM (aparte de la comprobación de la versión) hasta que se llama a OnExtensionsInitializedCallback con un estado de éxito.

Este método debe implementarse a partir de la versión de extensión 1.1. Para obtener más información, consulte la fuente en InitializerImpl .

Interfaz ExtenderStateListener

CameraX proporciona enlaces en varios lugares de su canalización para permitir que la biblioteca OEM establezca los valores relevantes SessionParameters y CaptureRequest . Para permitir que la biblioteca OEM establezca estos valores en los momentos especificados, implemente la interfaz ExtenderStateListener . Esta interfaz debe implementarse como parte de cualquier extensor, ya sea una vista previa, captura de imagen, bokeh o extensor HDR.

Captura de imagen

Para admitir la extensión para la captura de imágenes , implemente la interfaz ImageCaptureExtender correspondiente (por ejemplo, BokehImageCaptureExtenderImpl o HdrImageCaptureExtenderImpl ).

ImageCaptureExtenderImpl incluye las interfaces necesarias para las extensiones relacionadas con la captura de imágenes.

La interfaz CaptureProcessorImpl debe implementarse para que el procesamiento posterior se realice en la capa de la aplicación. A partir de la versión 1.1 de la interfaz de extensiones, solo se debe admitir el formato de imagen de entrada YUV_420_888 . La interfaz CaptureProcessor no es necesaria si el procesamiento se realiza en la HAL de la cámara.

El siguiente diagrama ilustra el flujo del proceso de captura de imágenes.

Flujo del proceso de captura de imágenes

Figura 2. Diagrama de flujo de captura de imágenes

Ejemplo: BokehImageCaptureExtenderImpl

Para admitir la extensión bokeh para la captura de imágenes, implemente la clase BokehImageCaptureExtenderImpl en el paquete androidx.camera.extensions.impl .

Avance

Para admitir la extensión para la vista previa , implemente la interfaz PreviewExtender correspondiente (por ejemplo, BokehPreviewExtenderImpl o HdrPreviewExtenderImpl ). La interfaz PreviewExtender incluye las interfaces necesarias para las extensiones relacionadas con la vista previa.

Para obtener más información, consulte la fuente en PreviewExtenderImpl .

El procesamiento de imágenes para la extensión de vista previa se puede realizar en la HAL de la cámara o en la capa de la aplicación. Esto está determinado por el valor de ProcessorType , que devuelve PreviewExtenderImpl .

Si se devuelve el tipo PROCESSOR_TYPE_REQUEST_UPDATE_ONLY , el procesamiento se realiza en la HAL a través de claves CaptureRequest . Si se devuelve el tipo PROCESSOR_TYPE_IMAGE_PROCESSOR , la interfaz PreviewImageProcessorImpl realiza el procesamiento en la capa de la aplicación. Esta interfaz opera en un par Image y TotalCaptureResult . A partir de la versión 1.1 de la interfaz de extensiones, solo se debe admitir el formato de imagen de entrada YUV_420_888 .

El siguiente diagrama ilustra el flujo de proceso para la extensión del proveedor de versión preliminar.

Vista previa del diagrama de flujo

Figura 3. Vista previa del diagrama de flujo

Ejemplo: BokehPreviewExtenderImpl

Para admitir bokeh para la vista previa, implemente la clase BokehPreviewExtenderImpl en el paquete androidx.camera.extensions.impl .

Implementación de referencia

Para obtener una implementación de biblioteca de proveedor OEM de referencia, consulte camera-testlib-extensions . Tenga en cuenta que esta implementación realiza traspasos sin implementar realmente los efectos.

Configuración de la biblioteca de proveedores en un dispositivo

La biblioteca de proveedores OEM no está integrada en una aplicación, sino que CameraX la carga desde el dispositivo en tiempo de ejecución. La etiqueta <uses-library> declara que la biblioteca androidx.camera.extensions.impl , que se define en el archivo AndroidManifest.xml , es una dependencia de CameraX y debe cargarse en tiempo de ejecución. Esto permite que las aplicaciones de terceros que usan extensiones de proveedores intenten cargar automáticamente la biblioteca de proveedores OEM. La biblioteca OEM está marcada como opcional para que las aplicaciones puedan ejecutarse en dispositivos que no tienen la biblioteca en el dispositivo.

CameraX maneja este comportamiento automáticamente cuando una aplicación intenta usar una extensión de proveedor siempre que el fabricante del dispositivo coloque la biblioteca OEM en el dispositivo para que la aplicación pueda descubrirla.

Para configurar la biblioteca OEM en un dispositivo, haga lo siguiente:

  1. Agregue un archivo de permisos, requerido por la etiqueta <uses-library> , usando el siguiente formato: /etc/permissions/ ANY_FILENAME .xml . Por ejemplo, /etc/permissions/camera_extensions.xml . Los archivos de este directorio proporcionan una asignación de la biblioteca nombrada en <uses-library> a la ruta de archivo real en el dispositivo.
  2. Utilice el siguiente ejemplo para agregar la información necesaria al archivo.

    • el name debe ser androidx.camera.extensions.impl ya que esa es la biblioteca que busca CameraX.
    • file es la ruta absoluta del archivo que contiene la implementación de las extensiones (por ejemplo, /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>
    

En Android 12 o superior, los dispositivos compatibles con las extensiones CameraX deben tener la propiedad ro.camerax.extensions.enabled establecida en true , lo que permite consultar si un dispositivo admite extensiones. Para hacer esto, agregue la siguiente línea en el archivo de creación del dispositivo:

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

Validación

Para probar su implementación de la biblioteca de proveedores OEM durante la etapa de desarrollo, use la aplicación de ejemplo en androidx-main/camera/integration-tests/extensionstestapp/ , que se ejecuta a través de varias extensiones de proveedores.

Después de completar su implementación, use la herramienta de validación de extensiones de proveedores de CameraX para ejecutar pruebas automáticas y manuales para verificar que la biblioteca de proveedores se implemente correctamente.

Preguntas frecuentes (FAQ)

¿Hay alguna restricción en los niveles de API?

Sí. Esto depende del conjunto de características de la API de Android que requiere la implementación de la biblioteca del proveedor OEM. Por ejemplo, ExtenderStateListener.onPresetSession() usa la llamada SessionConfiguration.setSessionParameters() para establecer un conjunto de etiquetas de referencia. Esta llamada está disponible solo en el nivel de API 28 y superior. Para obtener detalles sobre métodos de interfaz específicos, consulte la documentación de referencia de la API .