Referência da estrutura camera3_device_ops

configure_streams:

Somente CAMERA_DEVICE_API_VERSION_3_0:

Redefina o pipeline de processamento do dispositivo da câmera HAL e configure novos streams de entrada e saída. Essa chamada substitui qualquer configuração de transmissão atual pelos fluxos definidos na stream_list. Esse método será chamado pelo menos uma vez após initialize() antes de uma solicitação ser enviada com process_capture_request() .

A stream_list precisa conter pelo menos uma stream com capacidade de saída e não pode conter mais de uma stream com capacidade de entrada.

A stream_list pode conter streams que também estão no conjunto de streams atualmente ativo (da chamada anterior para configure_stream()). Esses streams já terão valores válidos para uso, max_buffers e o ponteiro privado.

Se essa transmissão já tiver os buffers registrados, register_stream_buffers() não será chamada novamente para a transmissão, e os buffers da transmissão poderão ser incluídos imediatamente nas solicitações de entrada.

Se o HAL precisar mudar a configuração de um stream existente devido à nova configuração, ele poderá reescrever os valores de usage e/ou max_buffers durante a chamada de configuração.

O framework vai detectar essa mudança, realocar os buffers de stream e chamar register_stream_buffers() novamente antes de usar os buffers desse stream em uma solicitação.

Se um stream ativo não estiver incluído em stream_list, o HAL poderá remover com segurança todas as referências a esse stream. Ele não será reutilizado em uma chamada configure() posterior pelo framework, e todos os buffers gralloc serão liberados depois que a chamada configure_streams() retornar.

A estrutura stream_list é de propriedade do framework e pode não ser acessada após a conclusão da chamada. O endereço de uma estrutura camera3_stream_t individual vai continuar válido para acesso pelo HAL até o fim da primeira chamada configure_stream(), que não inclui mais camera3_stream_t no argumento stream_list. O HAL não pode mudar valores na estrutura de stream fora do ponteiro particular, exceto os membros de uso e max_buffers durante a chamada configure_streams() em si.

Se a transmissão for nova, os campos usage, max_buffer e private pointer da estrutura da transmissão serão definidos como 0. O dispositivo HAL precisa definir esses campos antes que a chamada configure_streams() seja retornada. Esses campos são usados pelo framework e pelo módulo gralloc da plataforma para alocar os buffers gralloc para cada stream.

Antes que os buffers de um novo stream possam ser incluídos em uma solicitação de captura, o framework vai chamar register_stream_buffers() com esse stream. No entanto, o framework não precisa registrar buffers para todas as transmissões antes de enviar uma solicitação. Isso permite a inicialização rápida de, por exemplo, uma transmissão de visualização, com a alocação de outras transmissões que acontecem mais tarde ou simultaneamente.

---

Somente CAMERA_DEVICE_API_VERSION_3_1:

Redefina o pipeline de processamento do dispositivo da câmera HAL e configure novos streams de entrada e saída. Essa chamada substitui qualquer configuração de transmissão atual pelos fluxos definidos na stream_list. Esse método será chamado pelo menos uma vez após initialize() antes de uma solicitação ser enviada com process_capture_request() .

A stream_list precisa conter pelo menos uma stream com capacidade de saída e não pode conter mais de uma stream com capacidade de entrada.

A stream_list pode conter streams que também estão no conjunto de streams atualmente ativo (da chamada anterior para configure_stream()). Esses streams já terão valores válidos para uso, max_buffers e o ponteiro privado.

Se essa transmissão já tiver os buffers registrados, register_stream_buffers() não será chamada novamente para a transmissão, e os buffers da transmissão poderão ser incluídos imediatamente nas solicitações de entrada.

Se o HAL precisar mudar a configuração de um stream existente devido à nova configuração, ele poderá reescrever os valores de usage e/ou max_buffers durante a chamada de configuração.

O framework vai detectar essa mudança, realocar os buffers de stream e chamar register_stream_buffers() novamente antes de usar os buffers desse stream em uma solicitação.

Se um stream ativo não estiver incluído em stream_list, o HAL poderá remover com segurança todas as referências a esse stream. Ele não será reutilizado em uma chamada configure() posterior pelo framework, e todos os buffers gralloc serão liberados depois que a chamada configure_streams() retornar.

A estrutura stream_list é de propriedade do framework e pode não ser acessada após a conclusão da chamada. O endereço de uma estrutura camera3_stream_t individual vai continuar válido para acesso pelo HAL até o fim da primeira chamada configure_stream(), que não inclui mais camera3_stream_t no argumento stream_list. O HAL não pode mudar valores na estrutura de stream fora do ponteiro particular, exceto os membros de uso e max_buffers durante a chamada configure_streams() em si.

Se o stream for novo, os campos max_buffer e ponteiro privado da estrutura do stream serão definidos como 0. O uso será definido como as flags de uso do consumidor. O dispositivo HAL precisa definir esses campos antes que a chamada configure_streams() seja retornada. Esses campos são usados pelo framework e pelo módulo gralloc da plataforma para alocar os buffers gralloc para cada stream.

Antes que os buffers de um novo stream possam ser incluídos em uma solicitação de captura, o framework vai chamar register_stream_buffers() com esse stream. No entanto, o framework não precisa registrar buffers para todas as transmissões antes de enviar uma solicitação. Isso permite a inicialização rápida de, por exemplo, uma transmissão de visualização, com a alocação de outras transmissões que acontecem mais tarde ou simultaneamente.

---

>= CAMERA_DEVICE_API_VERSION_3_2:

Redefina o pipeline de processamento do dispositivo da câmera HAL e configure novos streams de entrada e saída. Essa chamada substitui qualquer configuração de transmissão atual pelos fluxos definidos na stream_list. Esse método será chamado pelo menos uma vez após initialize() antes de uma solicitação ser enviada com process_capture_request() .

A stream_list precisa conter pelo menos uma stream com capacidade de saída e não pode conter mais de uma stream com capacidade de entrada.

A stream_list pode conter streams que também estão no conjunto de streams atualmente ativo (da chamada anterior para configure_stream()). Esses streams já terão valores válidos para uso, max_buffers e o ponteiro privado.

Se o HAL precisar mudar a configuração de um stream existente devido à nova configuração, ele poderá reescrever os valores de usage e/ou max_buffers durante a chamada de configuração.

O framework vai detectar essa mudança e pode realocar os buffers de fluxo antes de usar os buffers desse fluxo em uma solicitação.

Se um stream ativo não estiver incluído em stream_list, o HAL poderá remover com segurança todas as referências a esse stream. Ele não será reutilizado em uma chamada configure() posterior pelo framework, e todos os buffers gralloc serão liberados depois que a chamada configure_streams() retornar.

A estrutura stream_list é de propriedade do framework e pode não ser acessada após a conclusão da chamada. O endereço de uma estrutura camera3_stream_t individual vai continuar válido para acesso pelo HAL até o fim da primeira chamada configure_stream(), que não inclui mais camera3_stream_t no argumento stream_list. O HAL não pode mudar valores na estrutura de stream fora do ponteiro particular, exceto os membros de uso e max_buffers durante a chamada configure_streams() em si.

Se o stream for novo, os campos max_buffer e ponteiro privado da estrutura do stream serão definidos como 0. O uso será definido como as flags de uso do consumidor. O dispositivo HAL precisa definir esses campos antes que a chamada configure_streams() seja retornada. Esses campos são usados pelo framework e pelo módulo gralloc da plataforma para alocar os buffers gralloc para cada stream.

Os buffers recém-alocados podem ser incluídos em uma solicitação de captura a qualquer momento pelo framework. Quando um buffer gralloc é retornado ao framework com process_capture_result (e o respectivo release_fence foi sinalizado), o framework pode liberar ou reutilizar o buffer a qualquer momento.

---

Condições prévias:

O framework só vai chamar esse método quando nenhuma captura estiver sendo processada. Ou seja, todos os resultados foram retornados ao framework, todos os buffers de entrada e saída em andamento foram retornados e as cercas de sincronização de lançamento foram sinalizadas pelo HAL. O framework não enviará novas solicitações para captura enquanto a chamada configure_streams() estiver em andamento.

Postconditions:

O dispositivo HAL precisa se configurar para fornecer a taxa de quadros de saída máxima possível, considerando os tamanhos e formatos dos streams de saída, conforme documentado nos metadados estáticos do dispositivo da câmera.

Requisitos de desempenho:

Essa chamada deve ser pesada e possivelmente levar várias centenas de milissegundos para ser concluída, já que pode exigir a redefinição e a reconfiguração do sensor de imagem e do pipeline de processamento da câmera. No entanto, o dispositivo HAL precisa tentar minimizar o atraso de reconfiguração para minimizar as pausas visíveis ao usuário durante as mudanças no modo operacional do aplicativo (como a mudança de captura de fotos para gravação de vídeo).

O HAL precisa retornar desta chamada em 500 ms e em 1000 ms.

Valores de retorno:

0: na configuração de streaming bem-sucedida

-EINVAL: se a configuração do stream solicitada for inválida. Alguns exemplos de configurações de transmissão inválidas incluem:

• Incluir mais de uma transmissão com capacidade de entrada (INPUT ou BIDIRECTIONAL)
• Não incluir streams com capacidade de saída (OUTPUT ou BIDIRECTIONAL)
• Incluir transmissões com formatos ou tamanhos incompatíveis.
• Incluir muitos fluxos de saída de um determinado formato.
• Configuração de rotação sem suporte (aplica-se apenas a dispositivos com versão >= CAMERA_DEVICE_API_VERSION_3_3)
• Os tamanhos/formatos de transmissão não atendem aos requisitos de camera3_stream_configuration_t->operation_mode para o modo que não é NORMAL ou o operation_mode solicitado não tem suporte do HAL. (aplicável apenas a dispositivos com versão >= CAMERA_DEVICE_API_VERSION_3_3)

O framework que envia uma configuração de stream inválida não é uma operação normal, já que as configurações de stream são verificadas antes da configuração. Uma configuração inválida significa que há um bug no código do framework ou uma incompatibilidade entre os metadados estáticos do HAL e os requisitos nos streams.

-ENODEV: se ocorreu um erro fatal e o dispositivo não está mais operacional. Somente close() pode ser chamado pelo framework depois que esse erro é retornado.

Definição na linha 2769 do arquivo camera3.h .

construct_default_request_settings:

Crie configurações de captura para casos de uso padrão da câmera.

O dispositivo precisa retornar um buffer de configurações configurado para atender ao caso de uso solicitado, que precisa ser um dos enumeradores CAMERA3_TEMPLATE_* Todos os campos de controle de solicitação precisam ser incluídos.

O HAL mantém a propriedade dessa estrutura, mas o ponteiro para a estrutura precisa ser válido até que o dispositivo seja fechado. O framework e o HAL não podem modificar o buffer depois que ele é retornado por essa chamada. O mesmo buffer pode ser retornado para chamadas subsequentes do mesmo modelo ou de outros modelos.

Requisitos de desempenho:

Essa precisa ser uma chamada que não bloqueia. O HAL precisa retornar dessa chamada em 1ms e em 5ms.

Valores de retorno:

Metadados válidos: na criação bem-sucedida de um buffer de configurações padrão.

NULL: em caso de um erro fatal. Depois que isso for retornado, apenas o método close() poderá ser chamado pelo framework.

Definição na linha 2859 do arquivo camera3.h .

despejo:

Mostra o estado de depuração do dispositivo da câmera. Ele será chamado pelo framework quando o serviço de câmera for solicitado para um dump de depuração, o que acontece ao usar a ferramenta dumpsys ou ao capturar um bugreport.

O descritor de arquivo transmitido pode ser usado para gravar texto de depuração usando dprintf() ou write(). O texto precisa estar apenas na codificação ASCII.

Requisitos de desempenho:

Essa precisa ser uma chamada que não bloqueia. O HAL precisa retornar desta chamada em 1ms e em 10ms. Essa chamada precisa evitar deadlocks, já que pode ser chamada a qualquer momento durante a operação da câmera. Todas as primitivas de sincronização usadas (como bloqueios de mutex ou semáforos) precisam ser adquiridas com um tempo limite.

Definição na linha 2971 do arquivo camera3.h .

flush:

Limpe todas as capturas em processo e todos os buffers no pipeline no dispositivo. O framework vai usar isso para despejar todo o estado o mais rápido possível para se preparar para uma chamada configure_streams() .

Nenhum buffer é necessário para ser retornado com sucesso. Portanto, todos os buffers mantidos no momento de flush() (preenchidos ou não) podem ser retornados com CAMERA3_BUFFER_STATUS_ERROR. O HAL ainda pode retornar buffers válidos (CAMERA3_BUFFER_STATUS_OK) durante essa chamada, desde que eles sejam preenchidos.

Todas as solicitações atualmente no HAL devem ser retornadas o mais rápido possível. As solicitações que não estão em processo precisam retornar erros imediatamente. Todos os blocos de hardware interrompíveis precisam ser interrompidos, e todos os blocos ininterruptíveis precisam ser aguardandos.

A função flush() pode ser chamada simultaneamente a process_capture_request() , com a expectativa de que a função process_capture_request retorne rapidamente e que a solicitação enviada nessa chamada process_capture_request seja tratada como todas as outras solicitações em andamento. Devido a problemas de simultaneidade, é possível que, do ponto de vista do HAL, uma process_capture_request() chamada possa ser iniciada depois que o flush foi invocado, mas ainda não retornou. Se essa chamada acontecer antes do retorno de flush() , o HAL vai tratar a nova solicitação de captura como outras solicitações pendentes em andamento (consulte a instrução 4 abaixo).

Mais especificamente, o HAL precisa seguir os requisitos abaixo para vários casos:

1. Para capturas que são muito tardias para que o HAL possa cancelar/parar e que serão concluídas normalmente pelo HAL. Ou seja, o HAL pode enviar shutter/notify e process_capture_result e buffers normalmente.
2. Para solicitações pendentes que não fizeram nenhum processamento, o HAL precisa chamar notify CAMERA3_MSG_ERROR_REQUEST e retornar todos os buffers de saída com process_capture_result no estado de erro (CAMERA3_BUFFER_STATUS_ERROR). O HAL não pode colocar a cerca de liberação em um estado de erro. Em vez disso, as cercas de liberação precisam ser definidas como as cercas de aquisição transmitidas pelo framework ou -1 se elas já tiverem sido aguardadas pelo HAL. Esse também é o caminho a seguir para todas as capturas em que o HAL já chamou notify() com CAMERA3_MSG_SHUTTER, mas não vai produzir metadados/buffers válidos. Depois de CAMERA3_MSG_ERROR_REQUEST, para um determinado frame, apenas process_capture_results com buffers em CAMERA3_BUFFER_STATUS_ERROR são permitidos. Não são permitidos notificações ou process_capture_result com metadados não nulos.

3. Para solicitações pendentes parcialmente concluídas que não têm todos os buffers de saída ou talvez não tenham metadados, o HAL deve seguir abaixo:

   3.1. Chamada de notificação com CAMERA3_MSG_ERROR_RESULT se alguns dos metadados de resultado esperados (ou seja, um ou mais metadados parciais) não estiverem disponíveis para a captura.

   3.2. Chame notify com CAMERA3_MSG_ERROR_BUFFER para cada buffer que não será produzido para a captura.

   3.3 Chamar notify com CAMERA3_MSG_SHUTTER com o carimbo de data/hora da captura antes que qualquer buffer/metadado seja retornado com process_capture_result.

   3.4 Para capturas que vão produzir alguns resultados, o HAL não pode chamar CAMERA3_MSG_ERROR_REQUEST, porque isso indica uma falha completa.

   3.5. Os buffers/metadados válidos precisam ser transmitidos para a estrutura normalmente.

   3.6. Os buffers com falha precisam ser retornados ao framework, conforme descrito no caso 2. No entanto, os buffers com falha não precisam seguir a ordem estrita dos buffers válidos e podem estar fora de ordem em relação aos buffers válidos. Por exemplo, se os buffers A, B, C, D e E forem enviados, e D e E falharem, então A, E, B, D e C é uma ordem de retorno aceitável.

   3.7. Para metadados totalmente ausentes, chamar CAMERA3_MSG_ERROR_RESULT é suficiente. Não é necessário chamar process_capture_result com metadados NULL ou equivalentes.

4. Se um flush() for invocado enquanto uma invocação process_capture_request() estiver ativa, essa chamada de processo precisará retornar assim que possível. Além disso, se uma chamada process_capture_request() for feita depois que flush() for invocado, mas antes que flush() seja retornado, a solicitação de captura fornecida pela chamada tardia process_capture_request será tratada como uma solicitação pendente no caso 2 acima.

flush() só retorna quando não há mais buffers ou solicitações pendentes no HAL. O framework pode chamar configure_streams, já que o estado do HAL está inativo, ou emitir novas solicitações.

É suficiente oferecer suporte apenas para casos de resultados totalmente bem-sucedidos e totalmente malsucedidos. No entanto, é altamente recomendável oferecer suporte aos casos de falha parcial, já que isso pode ajudar a melhorar a performance geral da chamada de flush.

Requisitos de desempenho:

O HAL precisa retornar dessa chamada em 100 ms e em 1000 ms. Essa chamada não pode ser bloqueada por mais tempo do que a latência do pipeline (consulte S7 para a definição).

Informações da versão:

Disponível apenas se a versão do dispositivo for >= CAMERA_DEVICE_API_VERSION_3_1.

Valores de retorno:

0: em um flush bem-sucedido do HAL da câmera.

-EINVAL: se a entrada estiver com formato incorreto (o dispositivo não é válido).

-ENODEV: se o dispositivo da câmera encontrou um erro grave. Depois que esse erro é retornado, apenas o método close() pode ser chamado pelo framework.

Definição na linha 3077 do arquivo camera3.h .

get_metadata_vendor_tag_ops:

Acesse métodos para consultar informações da tag de metadados da extensão do fornecedor. O HAL precisa preencher todos os métodos de operação de tag do fornecedor ou deixar as operações inalteradas se nenhuma tag do fornecedor for definida.

A definição de vendor_tag_query_ops_t pode ser encontrada em system/media/camera/include/system/camera_metadata.h.

>= CAMERA_DEVICE_API_VERSION_3_2: OBSOLETA. Essa função foi descontinuada e precisa ser definida como NULL pelo HAL. Implemente get_vendor_tag_ops em camera_common.h em vez disso.

Definição na linha 2950 do arquivo camera3.h .

initialize:

Inicialização única para transmitir ponteiros de função de callback do framework para o HAL. Será chamado uma vez após uma chamada open() bem-sucedida, antes que qualquer outra função seja chamada na estrutura camera3_device_ops .

Requisitos de desempenho:

Essa precisa ser uma chamada que não bloqueia. O HAL precisa retornar dessa chamada em 5 ms e em 10 ms.

Valores de retorno:

0: na inicialização bem-sucedida

-ENODEV: se a inicialização falhar. Depois disso, apenas o close() pode ser chamado pelo framework.

Definição na linha 2530 do arquivo camera3.h .

process_capture_request:

Enviar uma nova solicitação de captura para o HAL. O HAL não deve retornar desta chamada até que esteja pronto para aceitar a próxima solicitação para processamento. Apenas uma chamada para process_capture_request() será feita por vez pelo framework, e todas as chamadas serão da mesma linha de execução. A próxima chamada para process_capture_request() será feita assim que uma nova solicitação e os buffers associados estiverem disponíveis. Em um cenário de visualização normal, isso significa que a função será chamada novamente pelo framework quase instantaneamente.

O processamento real da solicitação é assíncrono, com os resultados da captura sendo retornados pelo HAL pela chamada process_capture_result(). Essa chamada exige que os metadados do resultado estejam disponíveis, mas os buffers de saída podem simplesmente fornecer limites de sincronização para aguardar. Espera-se que várias solicitações sejam transmitidas de uma só vez para manter a taxa de frames de saída completa.

O framework mantém a propriedade da estrutura de solicitação. Ele só é válido durante essa chamada. O dispositivo HAL precisa fazer cópias das informações que precisa reter para o processamento da captura. O HAL é responsável por esperar e fechar as cercas dos buffers e retornar os identificadores de buffer para o framework.

O HAL precisa gravar o descritor de arquivo para a cerca de sincronização de lançamento do buffer de entrada em input_buffer->release_fence, se input_buffer não for nulo. Se o HAL retornar -1 para a cerca de sincronização de liberação do buffer de entrada, o framework poderá reutilizar o buffer de entrada imediatamente. Caso contrário, o framework vai esperar na cerca de sincronização antes de reabastecer e reutilizar o buffer de entrada.

>= CAMERA_DEVICE_API_VERSION_3_2:

Os buffers de entrada/saída fornecidos pelo framework em cada solicitação podem ser novos (nunca vistos pelo HAL).

---

Considerações sobre performance:

O processamento de um novo buffer precisa ser extremamente leve, e não pode haver degradação de frame rate ou jitter de frame.

Essa chamada precisa retornar rápido o suficiente para garantir que a taxa de frames solicitada possa ser mantida, especialmente para casos de streaming (configurações de qualidade pós-processamento definidas como RÁPIDO). O HAL precisa retornar essa chamada em um intervalo de frame e retornar dessa chamada em quatro intervalos de frame.

Valores de retorno:

0: início bem-sucedido do processamento da solicitação de captura

-EINVAL: se a entrada estiver com formato incorreto (as configurações são NULL quando não permitidas, há 0 buffers de saída etc.) e o processamento de captura não puder ser iniciado. As falhas durante o processamento de solicitações precisam ser tratadas chamando camera3_callback_ops_t.notify() . Em caso de erro, o framework vai manter a responsabilidade pelos limites dos buffers de stream e pelos identificadores de buffer. O HAL não deve fechar os limites nem retornar esses buffers com process_capture_result.

-ENODEV: se o dispositivo da câmera encontrou um erro grave. Depois que esse erro é retornado, apenas o método close() pode ser chamado pelo framework.

Definição na linha 2928 do arquivo camera3.h .

register_stream_buffers:

>= CAMERA_DEVICE_API_VERSION_3_2:

USO SUSPENSO. Ele não será chamado e precisa ser definido como NULL.

<= CAMERA_DEVICE_API_VERSION_3_1:

Registre buffers para um determinado stream com o dispositivo HAL. Esse método é chamado pelo framework depois que um novo stream é definido por configure_streams e antes que os buffers desse stream sejam incluídos em uma solicitação de captura. Se o mesmo stream for listado em uma chamada configure_streams() subsequente, o register_stream_buffers não será chamado novamente para esse stream.

O framework não precisa registrar buffers para todos os streams configurados antes de enviar a primeira solicitação de captura. Isso permite a inicialização rápida para visualização (ou casos de uso semelhantes) enquanto outros streams ainda estão sendo alocados.

Esse método tem como objetivo permitir que o dispositivo HAL mapeie ou prepare os buffers para uso posterior. Os buffers transmitidos já estarão bloqueados para uso. No final da chamada, todos os buffers precisam estar prontos para serem retornados ao stream. O argumento buffer_set é válido apenas durante a duração dessa chamada.

Se o formato do stream foi definido como HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, o HAL da câmera precisa inspecionar os buffers transmitidos aqui para determinar qualquer informação de formato de pixel privada da plataforma.

Requisitos de desempenho:

Essa precisa ser uma chamada que não bloqueia. O HAL precisa retornar dessa chamada em 1ms e em 5ms.

Valores de retorno:

0: no registro bem-sucedido dos novos buffers de transmissão

-EINVAL: se o stream_buffer_set não se referir a um stream ativo válido ou se a matriz de buffers for inválida.

-ENOMEM: se houve uma falha no registro dos buffers. O framework precisa considerar que todos os buffers de transmissão não estão registrados e pode tentar fazer o registro novamente mais tarde.

-ENODEV: se houver um erro fatal e o dispositivo não estiver mais operacional. Somente close() pode ser chamado pelo framework depois que esse erro é retornado.

Definição na linha 2823 do arquivo camera3.h .

Definição na linha 3080 do arquivo camera3.h .