Referencia de la estructura camera3_device_ops

configure_streams:

Solo CAMERA_DEVICE_API_VERSION_3_0:

Restablece la canalización de procesamiento del dispositivo de la cámara HAL y configura nuevas transmisiones de entrada y salida. Esta llamada reemplaza cualquier configuración de transmisión existente por las transmisiones definidas en stream_list. Se llamará a este método al menos una vez después de initialize() antes de que se envíe una solicitud con process_capture_request() .

stream_list debe contener al menos una transmisión compatible con la salida y no puede contener más de una transmisión compatible con la entrada.

stream_list puede contener flujos que también están en el conjunto de flujos activo actualmente (de la llamada anterior a configure_stream()). Estos flujos ya tendrán valores válidos para el uso, max_buffers y el puntero privado.

Si ya se registraron los búferes de esa transmisión, no se volverá a llamar a register_stream_buffers() para la transmisión, y los búferes de la transmisión se pueden incluir de inmediato en las solicitudes de entrada.

Si el HAL necesita cambiar la configuración de un flujo existente debido a la configuración nueva, es posible que reescriba los valores de uso o max_buffers durante la llamada de configuración.

El framework detectará ese cambio y, luego, reasignará los búferes de flujo y volverá a llamar a register_stream_buffers() antes de usar los búferes de ese flujo en una solicitud.

Si no se incluye un flujo activo en stream_list, el HAL puede quitar de forma segura cualquier referencia a ese flujo. El framework no lo reutilizará en una llamada configure() posterior, y todos los búferes de gralloc para él se liberarán después de que se devuelva la llamada configure_streams() .

El framework es propietario de la estructura stream_list y es posible que no se pueda acceder a ella una vez que se complete esta llamada. La dirección de una estructura camera3_stream_t individual seguirá siendo válida para que la HAL pueda acceder a ella hasta el final de la primera llamada a configure_stream(), que ya no incluirá esa camera3_stream_t en el argumento stream_list. Es posible que el HAL no cambie los valores en la estructura de flujo fuera del puntero privado, excepto los miembros de uso y max_buffers durante la llamada a configure_streams() .

Si la transmisión es nueva, los campos de uso, max_buffer y puntero privado de la estructura de la transmisión se establecerán en 0. El dispositivo HAL debe establecer estos campos antes de que se devuelva la llamada a configure_streams() . Luego, el framework y el módulo gralloc de la plataforma usan estos campos para asignar los búferes de gralloc para cada transmisión.

Antes de que un flujo nuevo pueda incluir sus búferes en una solicitud de captura, el framework llamará a register_stream_buffers() con ese flujo. Sin embargo, el framework no es necesario para registrar búferes para todas las transmisiones antes de enviar una solicitud. Esto permite un inicio rápido de (por ejemplo) una transmisión de vista previa, con la asignación de otras transmisiones que se realizan más tarde o de forma simultánea.

---

Solo CAMERA_DEVICE_API_VERSION_3_1:

Restablece la canalización de procesamiento del dispositivo de la cámara HAL y configura nuevas transmisiones de entrada y salida. Esta llamada reemplaza cualquier configuración de transmisión existente por las transmisiones definidas en stream_list. Se llamará a este método al menos una vez después de initialize() antes de que se envíe una solicitud con process_capture_request() .

stream_list debe contener al menos una transmisión compatible con la salida y no puede contener más de una transmisión compatible con la entrada.

stream_list puede contener flujos que también están en el conjunto de flujos activo actualmente (de la llamada anterior a configure_stream()). Estos flujos ya tendrán valores válidos para el uso, max_buffers y el puntero privado.

Si ya se registraron los búferes de esa transmisión, no se volverá a llamar a register_stream_buffers() para la transmisión, y los búferes de la transmisión se pueden incluir de inmediato en las solicitudes de entrada.

Si el HAL necesita cambiar la configuración de un flujo existente debido a la configuración nueva, es posible que reescriba los valores de uso o max_buffers durante la llamada de configuración.

El framework detectará ese cambio y, luego, reasignará los búferes de flujo y volverá a llamar a register_stream_buffers() antes de usar los búferes de ese flujo en una solicitud.

Si no se incluye un flujo activo en stream_list, el HAL puede quitar de forma segura cualquier referencia a ese flujo. El framework no lo reutilizará en una llamada configure() posterior, y todos los búferes de gralloc para él se liberarán después de que se devuelva la llamada configure_streams() .

El framework es propietario de la estructura stream_list y es posible que no se pueda acceder a ella una vez que se complete esta llamada. La dirección de una estructura camera3_stream_t individual seguirá siendo válida para que la HAL pueda acceder a ella hasta el final de la primera llamada a configure_stream(), que ya no incluirá esa camera3_stream_t en el argumento stream_list. Es posible que el HAL no cambie los valores en la estructura de flujo fuera del puntero privado, excepto los miembros de uso y max_buffers durante la llamada a configure_streams() .

Si la transmisión es nueva, los campos max_buffer y de puntero privado de la estructura de la transmisión se establecerán en 0. El uso se establecerá en las marcas de uso del consumidor. El dispositivo HAL debe establecer estos campos antes de que se devuelva la llamada a configure_streams() . Luego, el framework y el módulo gralloc de la plataforma usan estos campos para asignar los búferes de gralloc para cada transmisión.

Antes de que un flujo nuevo pueda incluir sus búferes en una solicitud de captura, el framework llamará a register_stream_buffers() con ese flujo. Sin embargo, el framework no es necesario para registrar búferes para todas las transmisiones antes de enviar una solicitud. Esto permite un inicio rápido de (por ejemplo) una transmisión de vista previa, con la asignación de otras transmisiones que se realizan más tarde o de forma simultánea.

---

>= CAMERA_DEVICE_API_VERSION_3_2:

Restablece la canalización de procesamiento del dispositivo de la cámara HAL y configura nuevas transmisiones de entrada y salida. Esta llamada reemplaza cualquier configuración de transmisión existente por las transmisiones definidas en stream_list. Se llamará a este método al menos una vez después de initialize() antes de que se envíe una solicitud con process_capture_request() .

stream_list debe contener al menos una transmisión compatible con la salida y no puede contener más de una transmisión compatible con la entrada.

stream_list puede contener flujos que también están en el conjunto de flujos activo actualmente (de la llamada anterior a configure_stream()). Estos flujos ya tendrán valores válidos para el uso, max_buffers y el puntero privado.

Si el HAL necesita cambiar la configuración de un flujo existente debido a la configuración nueva, es posible que reescriba los valores de uso o max_buffers durante la llamada de configuración.

El framework detectará ese cambio y, luego, podrá reasignar los búferes de flujo antes de usar los búferes de ese flujo en una solicitud.

Si no se incluye un flujo activo en stream_list, el HAL puede quitar de forma segura cualquier referencia a ese flujo. El framework no lo reutilizará en una llamada configure() posterior, y todos los búferes de gralloc para él se liberarán después de que se devuelva la llamada configure_streams() .

El framework es propietario de la estructura stream_list y es posible que no se pueda acceder a ella una vez que se complete esta llamada. La dirección de una estructura camera3_stream_t individual seguirá siendo válida para que la HAL pueda acceder a ella hasta el final de la primera llamada a configure_stream(), que ya no incluirá esa camera3_stream_t en el argumento stream_list. Es posible que el HAL no cambie los valores en la estructura de flujo fuera del puntero privado, excepto los miembros de uso y max_buffers durante la llamada a configure_streams() .

Si la transmisión es nueva, los campos max_buffer y de puntero privado de la estructura de la transmisión se establecerán en 0. El uso se establecerá en las marcas de uso del consumidor. El dispositivo HAL debe establecer estos campos antes de que se devuelva la llamada a configure_streams() . Luego, el framework y el módulo gralloc de la plataforma usan estos campos para asignar los búferes de gralloc para cada transmisión.

El framework puede incluir en una solicitud de captura en cualquier momento los búferes asignados recientemente. Una vez que se muestra un búfer de gralloc al framework con process_capture_result (y se indicó su respectiva barrera de liberación), el framework puede liberarlo o reutilizarlo en cualquier momento.

---

Condiciones previas:

El framework solo llamará a este método cuando no se estén procesando capturas. Es decir, se devolvieron todos los resultados al framework, y se devolvieron todos los búferes de entrada y salida en curso, y el sistema HAL indicó sus cercas de sincronización de lanzamiento. El framework no enviará solicitudes nuevas de captura mientras esté en curso la llamada a configure_streams() .

Postconditions:

El dispositivo HAL debe configurarse para proporcionar la velocidad de fotogramas de salida máxima posible según los tamaños y formatos de las transmisiones de salida, como se documenta en los metadatos estáticos del dispositivo de la cámara.

Requisitos de rendimiento:

Se espera que esta llamada sea pesada y que pueda tardar varios cientos de milisegundos en completarse, ya que es posible que deba restablecerse y reconfigurarse el sensor de imagen y la canalización de procesamiento de la cámara. Sin embargo, el dispositivo HAL debe intentar minimizar la demora de reconfiguración para minimizar las pausas visibles para el usuario durante los cambios de modo operativo de la aplicación (como cambiar de captura de imágenes fijas a grabación de video).

El HAL debería mostrarse después de 500 ms y, luego, después de 1,000 ms.

Valores de retorno:

0: Si la configuración de la transmisión se realiza correctamente

-EINVAL: Si la configuración de transmisión solicitada no es válida. Estos son algunos ejemplos de parámetros de configuración de transmisiones no válidos:

• Incluir más de 1 transmisión compatible con entradas (INPUT o BIDIRECTIONAL)
• No incluye ninguna transmisión compatible con salidas (OUTPUT o BIDIRECTIONAL)
• Incluye transmisiones con formatos no admitidos o un tamaño no admitido para ese formato.
• Incluir demasiadas transmisiones de salida de un formato determinado
• Configuración de rotación no admitida (solo se aplica a dispositivos con la versión >= CAMERA_DEVICE_API_VERSION_3_3)
• Los tamaños o formatos de transmisión no cumplen con los requisitos de camera3_stream_configuration_t->operation_mode para el modo que no es NORMAL, o el HAL no admite el operation_mode solicitado. (solo se aplica a dispositivos con la versión >= CAMERA_DEVICE_API_VERSION_3_3)

Ten en cuenta que el framework que envía una configuración de transmisión no válida no es un funcionamiento normal, ya que las configuraciones de transmisión se verifican antes de configurarlas. Una configuración no válida significa que hay un error en el código del framework o que hay una discrepancia entre los metadatos estáticos del HAL y los requisitos de las transmisiones.

-ENODEV: Si se produjo un error grave y el dispositivo ya no funciona. El framework solo puede llamar a close() correctamente después de que se muestra este error.

Definición en la línea 2769 del archivo camera3.h .

construct_default_request_settings:

Crea parámetros de configuración de captura para casos de uso de cámaras estándar.

El dispositivo debe mostrar un búfer de configuración que esté configurado para cumplir con el caso de uso solicitado, que debe ser una de las enums CAMERA3_TEMPLATE_* Se deben incluir todos los campos de control de la solicitud.

El HAL retiene la propiedad de esta estructura, pero el puntero a la estructura debe ser válido hasta que se cierre el dispositivo. Es posible que el framework y el HAL no modifiquen el búfer una vez que esta llamada lo devuelva. Se puede mostrar el mismo búfer para llamadas posteriores a la misma plantilla o a otras plantillas.

Requisitos de rendimiento:

Esta debe ser una llamada sin bloqueo. El HAL debería mostrarse después de 1 ms y, luego, después de 5 ms.

Valores de retorno:

Metadatos válidos: Cuando se crea correctamente un búfer de configuración predeterminado.

NULL: En caso de un error grave. Después de que se muestra esto, el framework solo puede llamar correctamente al método close().

Definición en la línea 2859 del archivo camera3.h .

volcado:

Imprime el estado de depuración del dispositivo de la cámara. El framework llamará a esta función cuando se le solicite al servicio de la cámara un volcado de depuración, lo que sucede cuando se usa la herramienta dumpsys o cuando se captura un informe de errores.

El descriptor de archivo que se pasa se puede usar para escribir texto de depuración con dprintf() o write(). El texto debe estar solo en codificación ASCII.

Requisitos de rendimiento:

Esta debe ser una llamada sin bloqueo. El HAL debe mostrarse desde esta llamada en 1 ms. Esta llamada debe evitar interbloqueos, ya que se puede llamar en cualquier momento durante el funcionamiento de la cámara. Cualquier primitiva de sincronización que se use (como bloqueos de mutex o semáforos) debe adquirirse con un tiempo de espera.

Definición en la línea 2971 del archivo camera3.h .

flush:

Borra todas las capturas en proceso y todos los búferes de la canalización en el dispositivo determinado. El framework usará esto para volcar todo el estado lo más rápido posible para prepararse para una llamada a configure_streams() .

No se requiere que se devuelvan correctamente los búferes, por lo que cada búfer retenido en el momento de flush() (ya sea que se haya completado correctamente o no) puede mostrarse con CAMERA3_BUFFER_STATUS_ERROR. Ten en cuenta que el HAL aún puede mostrar búferes válidos (CAMERA3_BUFFER_STATUS_OK) durante esta llamada, siempre que se completen correctamente.

Se espera que todas las solicitudes que se encuentran actualmente en el sistema HAL se devuelvan lo antes posible. Las solicitudes que no están en proceso deben mostrar errores de inmediato. Se deben detener los bloqueos de hardware interrumpibles y se deben esperar los bloqueos no interrumpibles.

Se puede llamar a flush() de forma simultánea a process_capture_request() , con la expectativa de que process_capture_request se muestre rápidamente y que la solicitud enviada en esa llamada se trate como todas las demás solicitudes en curso. Debido a problemas de simultaneidad, es posible que, desde el punto de vista de HAL, se inicie una llamada a process_capture_request() después de que se invoque el volcado, pero aún no se muestre. Si se produce una llamada de este tipo antes de que se muestre flush() , el HAL debe tratar la nueva solicitud de captura como otras solicitudes pendientes en curso (consulta el punto 4 a continuación).

Más específicamente, el HAL debe cumplir con los siguientes requisitos para varios casos:

1. Para las capturas que son demasiado tarde para que el sistema HAL las cancele o detenga, y que el sistema HAL completará de forma normal, es decir, el sistema HAL puede enviar el obturador/notificación y process_capture_result y los búferes como de costumbre.
2. En el caso de las solicitudes pendientes que no hayan realizado ningún procesamiento, el sistema HAL debe llamar a notify CAMERA3_MSG_ERROR_REQUEST y mostrar todos los búferes de salida con process_capture_result en el estado de error (CAMERA3_BUFFER_STATUS_ERROR). El sistema HAL no debe colocar la barrera de liberación en un estado de error. En su lugar, las barreras de liberación deben establecerse en las barreras de adquisición que pasa el framework o en -1 si el sistema HAL ya las esperó. Esta también es la ruta de acceso que se debe seguir para las capturas para las que el HAL ya llamó a notify() con CAMERA3_MSG_SHUTTER, pero no producirá metadatos ni búferes válidos. Después de CAMERA3_MSG_ERROR_REQUEST, para un fotograma determinado, solo se permiten process_capture_results con búferes en CAMERA3_BUFFER_STATUS_ERROR. No se permiten más notificaciones ni process_capture_result con metadatos no nulos.

3. En el caso de las solicitudes pendientes completadas parcialmente que no tendrán todos los búferes de salida o que quizás no tengan metadatos, el HAL debe seguir a continuación:

   3.1. Llama a notify con CAMERA3_MSG_ERROR_RESULT si algunos de los metadatos del resultado esperado (es decir, uno o más metadatos parciales) no estarán disponibles para la captura.

   3.2. Llama a notify con CAMERA3_MSG_ERROR_BUFFER para cada búfer que no se producirá para la captura.

   3.3 Llama a notify con CAMERA3_MSG_SHUTTER con la marca de tiempo de captura antes de que se devuelvan los búferes o metadatos con process_capture_result.

   3.4 Para las capturas que producirán algunos resultados, el HAL no debe llamar a CAMERA3_MSG_ERROR_REQUEST, ya que eso indica una falla completa.

   3.5. Los búferes o metadatos válidos se deben pasar al framework como de costumbre.

   3.6. Los búferes con errores se deben devolver al framework como se describe en el caso 2. Sin embargo, los búferes con errores no tienen que seguir el orden estricto que siguen los búferes válidos y pueden estar fuera de orden con respecto a los búferes válidos. Por ejemplo, si se envían los búferes A, B, C, D y E, y D y E fallan, A, E, B, D y C es un orden de devolución aceptable.

   3.7. Para los metadatos que faltan por completo, es suficiente llamar a CAMERA3_MSG_ERROR_RESULT. No es necesario llamar a process_capture_result con metadatos NULL o equivalentes.

4. Si se invoca una flush() mientras hay una invocación de process_capture_request() activa, esa llamada de proceso debería mostrarse lo antes posible. Además, si se realiza una llamada a process_capture_request() después de invocar a flush() , pero antes de que se muestre flush() , la solicitud de captura proporcionada por la llamada tardía a process_capture_request debe tratarse como una solicitud pendiente en el caso 2 anterior.

flush() solo debe mostrarse cuando no haya más búferes o solicitudes pendientes en el HAL. El framework puede llamar a configure_streams (como el estado de HAL ahora está inactivo) o puede emitir solicitudes nuevas.

Ten en cuenta que es suficiente admitir solo casos de resultados completamente correctos y completamente incorrectos. Sin embargo, es muy recomendable admitir los casos de fallas parciales, ya que podría ayudar a mejorar el rendimiento general de la llamada de limpieza.

Requisitos de rendimiento:

El HAL debería mostrarse desde esta llamada en 100 ms y debe mostrarse desde esta llamada en 1, 000 ms. Además, esta llamada no debe bloquearse más que la latencia de la canalización (consulta el artículo S7 para obtener una definición).

Información de la versión:

Solo está disponible si la versión del dispositivo es >= CAMERA_DEVICE_API_VERSION_3_1.

Valores de retorno:

0: Cuando se borra correctamente el HAL de la cámara.

-EINVAL: Si la entrada tiene un formato incorrecto (el dispositivo no es válido).

-ENODEV: Si el dispositivo de la cámara encontró un error grave. Después de que se muestra este error, el framework solo puede llamar correctamente al método close().

Definición en la línea 3077 del archivo camera3.h .

get_metadata_vendor_tag_ops:

Obtén métodos para consultar información de la etiqueta de metadatos de la extensión del proveedor. El HAL debe completar todos los métodos de operación de la etiqueta del proveedor o dejar las operaciones sin cambios si no se definen etiquetas del proveedor.

La definición de vendor_tag_query_ops_t se puede encontrar en system/media/camera/include/system/camera_metadata.h.

>= CAMERA_DEVICE_API_VERSION_3_2: OBSOLETO. Esta función dejó de estar disponible y el sistema HAL debe establecerla en NULL. En su lugar, implementa get_vendor_tag_ops en camera_common.h .

Definición en la línea 2950 del archivo camera3.h .

initialize:

Es una inicialización única para pasar punteros de funciones de devolución de llamada del framework al HAL. Se llamará una vez después de una llamada correcta a open(), antes de que se llame a cualquier otra función en la estructura camera3_device_ops .

Requisitos de rendimiento:

Esta debe ser una llamada sin bloqueo. El HAL debería mostrarse desde esta llamada en 5 ms y debe mostrarse desde esta llamada en 10 ms.

Valores de retorno:

0: Cuando la inicialización se realiza correctamente

-ENODEV: Si falla la inicialización. Después de esto, el framework solo puede llamar a close() de forma correcta.

Definición en la línea 2530 del archivo camera3.h .

process_capture_request:

Envía una nueva solicitud de captura al sistema HAL. El HAL no debe mostrarse desde esta llamada hasta que esté listo para aceptar la siguiente solicitud que se procesará. El framework realizará una sola llamada a process_capture_request() a la vez, y todas las llamadas serán del mismo subproceso. La próxima llamada a process_capture_request() se realizará en cuanto haya una solicitud nueva y sus búferes asociados disponibles. En una situación de vista previa normal, esto significa que el framework volverá a llamar a la función casi de inmediato.

El procesamiento real de la solicitud es asíncrono, y el HAL muestra los resultados de la captura a través de la llamada process_capture_result(). Esta llamada requiere que los metadatos del resultado estén disponibles, pero los búferes de salida pueden simplemente proporcionar cercas de sincronización para esperar. Se espera que varias solicitudes estén en curso a la vez para mantener la velocidad de fotogramas de salida completa.

El framework retiene la propiedad de la estructura de la solicitud. Solo se garantiza que sea válido durante esta llamada. El dispositivo HAL debe crear copias de la información que necesita retener para el procesamiento de captura. El sistema HAL es responsable de esperar y cerrar las cercas de los búferes y devolver los controladores de búfer al framework.

El HAL debe escribir el descriptor de archivo para la cerca de sincronización de liberación del búfer de entrada en input_buffer->release_fence, si input_buffer no es nulo. Si el sistema HAL muestra -1 para la cerca de sincronización de liberación del búfer de entrada, el framework puede volver a usar el búfer de entrada de inmediato. De lo contrario, el framework esperará en la cerca de sincronización antes de volver a llenar y reutilizar el búfer de entrada.

>= CAMERA_DEVICE_API_VERSION_3_2:

Los búferes de entrada y salida que proporciona el framework en cada solicitud pueden ser nuevos (el HAL nunca los vio antes).

---

Consideraciones sobre el rendimiento:

El manejo de un nuevo búfer debe ser muy ligero y no debe haber degradación de la velocidad de fotogramas ni jitter de fotogramas.

Esta llamada debe mostrarse lo suficientemente rápido como para garantizar que se pueda mantener la velocidad de fotogramas solicitada, especialmente en los casos de transmisión (configuración de calidad de procesamiento posterior establecida en RÁPIDO). El HAL debe mostrar esta llamada en un intervalo de 1 fotograma y debe mostrarse desde esta llamada en 4 intervalos de fotogramas.

Valores de retorno:

0: Cuando se inicia correctamente el procesamiento de la solicitud de captura

-EINVAL: Si la entrada tiene un formato incorrecto (la configuración es NULL cuando no está permitida, hay 0 búferes de salida, etcétera) y no se puede iniciar el procesamiento de captura. Los errores durante el procesamiento de la solicitud se deben controlar llamando a camera3_callback_ops_t.notify() . En caso de que se produzca este error, el framework retendrá la responsabilidad de los cierres de los búferes de transmisión y los controladores de búferes. El sistema HAL no debe cerrar los cierres ni mostrar estos búferes con process_capture_result.

-ENODEV: Si el dispositivo de la cámara encontró un error grave. Después de que se muestra este error, el framework solo puede llamar correctamente al método close().

Definición en la línea 2928 del archivo camera3.h .

register_stream_buffers:

>= CAMERA_DEVICE_API_VERSION_3_2:

OBSOLETO. No se llamará a esta función y se debe establecer en NULL.

<= CAMERA_DEVICE_API_VERSION_3_1:

Registra búferes para una transmisión determinada con el dispositivo HAL. El framework llama a este método después de que configure_streams define un flujo nuevo y antes de que se incluyan los búferes de ese flujo en una solicitud de captura. Si el mismo flujo aparece en una llamada posterior a configure_streams() , no se volverá a llamar a register_stream_buffers para ese flujo.

El framework no necesita registrar búferes para todas las transmisiones configuradas antes de enviar la primera solicitud de captura. Esto permite un inicio rápido para la vista previa (o casos de uso similares) mientras se siguen asignando otras transmisiones.

El objetivo de este método es permitir que el dispositivo HAL asigne o prepare los búferes para usarlos más adelante. Los búferes que se pasen ya estarán bloqueados para su uso. Al final de la llamada, todos los búferes deben estar listos para mostrarse en la transmisión. El argumento buffer_set solo es válido durante esta llamada.

Si el formato de transmisión se configuró como HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, el HAL de la cámara debe inspeccionar los búferes pasados aquí para determinar si hay información de formato de píxeles privada de la plataforma.

Requisitos de rendimiento:

Esta debe ser una llamada sin bloqueo. El HAL debería mostrarse después de 1 ms y, luego, después de 5 ms.

Valores de retorno:

0: Cuando se registra correctamente el nuevo búfer de transmisión

-EINVAL: Si stream_buffer_set no hace referencia a un flujo activo válido o si el array de búferes no es válido.

-ENOMEM: Si se produjo un error en el registro de los búferes. El framework debe considerar que todos los búferes de transmisión no están registrados y puede intentar volver a registrarse más adelante.

-ENODEV: Si hay un error grave y el dispositivo ya no funciona. El framework solo puede llamar a close() correctamente después de que se muestra este error.

Definición en la línea 2823 del archivo camera3.h .

Definición en la línea 3080 del archivo camera3.h .