I. Visão geral
A classe CameraDevice é uma representação de uma única câmera conectada a um dispositivo Android, permitindo um controle refinado sobre a captura de imagens e o pós-processamento em altas taxas de quadros. Para acessar um dispositivo de câmera, um aplicativo deve declarar a permissão de câmera em seu manifesto. Um determinado dispositivo de câmera pode fornecer vários níveis de suporte definidos em CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL. Se o dispositivo for compatível com o nível LEGADO, o dispositivo da câmera estará no modo de compatibilidade com versões anteriores com suporte mínimo da API camera2. Se o dispositivo suportar o nível LIMITED, o conjunto de recursos exposto pelo Camera2 é aproximadamente equivalente ao antigo Camera API, embora com uma interface mais limpa e eficiente. Se um dispositivo suportar o nível EXTERNAL, o dispositivo é uma câmera removível que fornece funcionalidade semelhante, mas um pouco menos, ao nível LIMITED. Os dispositivos que implementam o suporte FULL ou LEVEL3 fornecem funcionalidade muito melhorada em relação às APIs de câmera mais antigas. Se seu aplicativo requer um dispositivo de nível completo para funcionar corretamente, declare o recurso "android.hardware.camera.level.full" em seu manifesto.
2. Método
/** Obtém o ID do dispositivo da câmera. Isso corresponde ao ID fornecido para CameraManager.openCamera para instanciar este dispositivo de câmera. Esse ID pode ser usado para consultar propriedades fixas do dispositivo de câmera por meio de CameraManager.getCameraCharacteristics. Esse método pode ser chamado mesmo se o dispositivo estiver desligado ou encontrar um erro fatal. @return O ID do dispositivo da câmera */ public abstract String getId();
/**
Crie um CaptureRequest.Builder para novas solicitações de captura, inicializadas com o modelo do caso de uso de destino. Essas configurações são escolhidas como as melhores opções para um determinado dispositivo de câmera, portanto, não é recomendável reutilizar a mesma solicitação para diferentes dispositivos de câmera; crie um construtor específico para esse dispositivo e modelo e substitua as configurações conforme necessário.
Parâmetro:
templateType - Uma enumeração que seleciona o caso de uso para esta solicitação. Nem todos os dispositivos oferecem suporte a todos os tipos de modelo. Consulte a documentação de cada tipo de modelo para obter detalhes.
Retorno:
Um construtor para capturar a solicitação, inicializado com configurações padrão para este modelo e nenhum fluxo de saída
Lança:
IllegalArgumentException – se o dispositivo não suportar o templateType.
CameraAccessException – se o dispositivo da câmera não estiver mais conectado ou encontrar um erro fatal
IllegalStateException – se o dispositivo da câmera estiver fechado
*/
public abstract CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType)
lança CameraAccessException;
/**
Crie um CaptureRequest.Builder para novas solicitações de captura, inicializadas com o modelo do caso de uso de destino. Esse método permite que os clientes passem IDs de câmeras físicas que podem ser usadas para personalizar solicitações de câmeras físicas específicas. Essas configurações são selecionadas como as melhores opções para um determinado dispositivo lógico de câmera. Se IDs de câmeras físicas adicionais forem passadas, elas também usarão o mesmo modelo de configurações. Os clientes podem modificar ainda mais as configurações individuais da câmera chamando CaptureRequest.Builder.setPhysicalCameraKey.
As configurações de câmera física individual se aplicam apenas a sessões de câmera inicializadas com a configuração de saída de ID de câmera física correspondente OutputConfiguration.setPhysicalCameraId, e o mesmo destino de saída também é anexado à solicitação por meio de CaptureRequest.Builder.addTarget.
Se uma configuração de câmera física válida for anexada, a saída de qualquer fluxo de câmera lógica será indefinida.
Parâmetros:
templateType - Uma enumeração que seleciona o caso de uso para esta solicitação. Nem todos os dispositivos oferecem suporte a todos os tipos de modelo. Consulte a documentação de cada tipo de modelo para obter detalhes. physicalCameraIdSet – uma matriz de IDs de câmeras físicas que podem ser usadas para personalizar solicitações de câmeras físicas específicas.
Retorno:
Construtor para capturar a solicitação, inicializado com configurações padrão para este modelo e sem fluxo de saída
Lança:
IllegalArgumentException – se templateType não for compatível com este dispositivo ou um dos parâmetros de id físico corresponder ao id lógico da câmera.
CameraAccessException – se o dispositivo da câmera não estiver mais conectado ou encontrar um erro fatal
IllegalStateException – se o dispositivo da câmera estiver fechado
*/
@NonNull
public CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType,
Set<String> physicalCameraIdSet) throws CameraAccessException {
throw new UnsupportedOperationException("As subclasses devem substituir este método");
}
/**
Cria uma nova {@link CameraCaptureSession} usando um objeto auxiliar {@link SessionConfiguration} que agrega todos os parâmetros compatíveis.
Uma sessão de captura ativa determina as superfícies de saída potenciais de um dispositivo de câmera para cada solicitação de captura. Uma determinada solicitação pode usar toda ou apenas parte da saída. Depois que uma CameraCaptureSession é criada, as solicitações podem ser enviadas usando {@link CameraCaptureSession#capture capture}, {@link CameraCaptureSession#captureBurst captureBurst}, {@link CameraCaptureSession#setRepeatingRequest setRepeatingRequest} ou {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}
*/
public void createCaptureSession(SessionConfiguration config) throws
CameraAccessException {
throw new UnsupportedOperationException("Sem implementação padrão");
}
/**
Inicializa uma sessão de captura de câmera avançada estendida específica do dispositivo.
As sessões de extensão podem ser usadas para habilitar modos de operação específicos do dispositivo, como CameraExtensionCharacteristics.EXTENSION_NIGHT ou CameraExtensionCharacteristics.EXTENSION_HDR. Esses modos são menos flexíveis do que a API de câmera completa, mas fornecem acesso a algoritmos de processamento mais complexos que podem capturar rajadas de vários quadros para produzir uma única imagem de saída. Para consultar as extensões disponíveis neste dispositivo, chame CameraExtensionCharacteristics.getSupportedExtensions(). Esse método também acionará a configuração do pipeline de processamento interno para visualização aprimorada estendida e captura de imagens estáticas de vários quadros. Essa abordagem também acionará a configuração do processamento interno para estender o pipeline para visualização aprimorada e captura de imagens estáticas de vários quadros.
Se já existir uma CameraCaptureSession anterior quando este método for chamado, a sessão anterior não poderá aceitar novas solicitações de captura e será fechada. Quaisquer solicitações de captura em andamento emitidas em uma sessão anterior serão concluídas antes que a sessão seja encerrada.
A CameraExtensionSession ficará ativa até que o cliente chame CameraExtensionSession.close() ou crie uma nova sessão de captura de câmera. Em ambos os casos, todos os recursos internos serão liberados, as solicitações repetidas continuamente cessarão e todas as solicitações de captura de vários quadros pendentes serão liberadas.
Observe que CameraExtensionSession atualmente oferece suporte a até dois formatos de superfície de captura de vários quadros: todas as extensões oferecem suporte a ImageFormat.JPEG, enquanto ImageFormat.YUV_420_888 pode ou não ser compatível. Os clientes devem usar CameraExtensionCharacteristics.getExtensionSupportedSizes(int, int) para consultar o suporte ao formato de captura de vários quadros. Para solicitações repetidas, CameraExtensionSession suporta apenas android.graphics.SurfaceTexture como saída. Os clientes podem consultar resoluções com suporte para saídas de solicitação repetida usando getExtensionSupportedSizes(..., Class).
A inicialização requer pelo menos uma superfície de saída válida para repetição ou uma saída válida para solicitações únicas de alta qualidade registradas no parâmetro de saída do parâmetro de configuração estendido. A inicialização aceitará até duas superfícies de saída válidas, uma para repetição e outra para uma única solicitação. Outras superfícies sem suporte passadas para ExtensionSessionConfiguration farão com que um IllegalArgumentException seja gerado.
*/
public void createExtensionSession(
@NonNull ExtensionSessionConfiguration extensionConfiguration)
throws CameraAccessException {
throw new UnsupportedOperationException("Sem implementação padrão");
}
/**
Crie um {@link CaptureRequest.Builder} para um novo reprocessamento {@link CaptureRequest} de {@link TotalCaptureResult}.
@param inputResult O resultado da captura da imagem de saída ou uma das imagens de saída da imagem de entrada reprocessada usada para gerar esta solicitação de captura.
@throws IllegalArgumentException se inputResult for nulo
@throws CameraAccessException se o dispositivo da câmera não estiver mais conectado ou encontrar um erro fatal
@throws IllegalStateException se o dispositivo da câmera estiver fechado
*/
@NonNull
public abstract CaptureRequest.Builder createReprocessCaptureRequest(
@NonNull TotalCaptureResult inputResult) lança CameraAccessException;
/**
Obtém o modo de limite de áudio da câmera global aplicado atualmente.
Os aplicativos podem usar esse método para recuperar as configurações de restrição de áudio da câmera em todo o sistema descritas em setCameraAudioRestriction.
Retorno:
A configuração de modo silencioso atual em todo o sistema
Lança:
CameraAccessException – se o dispositivo da câmera não estiver mais conectado ou encontrar um erro fatal
IllegalStateException – se o dispositivo da câmera estiver desligado
*/
public @CAMERA_AUDIO_RESTRICTION int getCameraAudioRestriction() throws CameraAccessException {
throw new UnsupportedOperationException("As subclasses devem substituir este método");
}
/**
Defina o modo de limite de áudio ao usar este CameraDevice.
Alguns hardwares de câmera, como dispositivos que suportam estabilização ótica de imagem, são sensíveis à vibração do dispositivo e as gravações de vídeo podem ser corrompidas por sons inesperados. Os aplicativos podem usar esse método para suprimir a vibração ou o som de toques, alertas ou notificações. Outras vibrações ou sons, como reprodução de mídia ou acessibilidade, não são silenciados.
O Modo Silencioso é uma configuração de todo o sistema. Quando vários objetos CameraDevice definem modos diferentes, o sistema selecionará a união de todos os modos definidos por um CameraDevice. Os aplicativos também podem usar getCameraAudioRestriction para consultar o modo de silêncio da câmera atual em todo o sistema.
Quando o CameraDevice for fechado ou o aplicativo for desconectado da câmera, a configuração de mudo para este CameraDevice será removida automaticamente.
Parâmetros:
mode – Uma enumeração que seleciona o modo de restrição de áudio para este dispositivo de câmera.
Lança:
IllegalArgumentException - se o modo não for suportado
CameraAccessException - se o dispositivo da câmera não estiver mais conectado ou encontrar um erro fatal
IllegalStateException - se o dispositivo da câmera estiver fechado
*/
public void setCameraAudioRestriction(
@CAMERA_AUDIO_RESTRICTION int mode) throws CameraAccessException {
throw new UnsupportedOperationException("As subclasses devem substituir este método");
}
/**
Verifique se o dispositivo da câmera suporta um {@link SessionConfiguration} específico.
Este método executa uma verificação de tempo de execução no determinado {@link SessionConfiguration}.
O resultado confirma que {@link CameraDevice#createCaptureSession( android.hardware.camera2.params.SessionConfiguration)} pode ser usado com sucesso com a configuração de sessão aprovada .
Esse método pode ser chamado a qualquer momento antes, durante e depois de uma sessão de captura de atividade. Isso não deve afetar o comportamento normal da câmera de forma alguma e deve ser significativamente mais rápido do que criar uma sessão de captura regular ou restrita.
Embora esse método seja mais rápido do que criar uma nova sessão de captura, não se destina a ser usado para explorar todo o espaço de combinações de fluxo com suporte. A combinação de transmissão obrigatória disponível
{@link android.hardware.camera2.params.MandatoryStreamCombination} é mais adequada para essa finalidade.
Observe que os parâmetros de sessão são ignorados e não há necessidade de chamar {@link SessionConfiguration#setSessionParameters}.
@return Retorna {true} se o dispositivo da câmera suportar a configuração de sessão fornecida, caso contrário, retorna {false}.
@throw UnsupportedOperationException se o dispositivo da câmera não suportar operações de consulta
@throw IllegalArgumentException se a configuração da sessão for inválida
@CameraAccessException se o dispositivo da câmera não estiver mais conectado ou tiver encontrado um erro fatal
@IllegalStateException se o dispositivo da câmera estiver fechado
*/
public boolean isSessionConfigurationSupported( @NonNull SessionConfiguration sessionConfig) throws CameraAccessException { throw new UnsupportedOperationException("As subclasses devem substituir este método"); }
/**
Feche a conexão com este dispositivo de câmera o mais rápido possível.
Imediatamente após esta chamada, todas as chamadas para o dispositivo de câmera ou interface de sessão ativa lançarão uma IllegalStateException, exceto chamadas para close(). Assim que o dispositivo estiver totalmente fechado, o retorno de chamada CameraDevice.StateCallback.onClosed será chamado e a câmera estará livre para reabrir.
Após esta chamada, exceto a chamada CameraDevice.StateCallback.onClosed final, nenhum retorno de chamada do dispositivo ou sessão ativa ocorrerá, e quaisquer solicitações de captura enviadas restantes serão descartadas como se CameraCaptureSession.abortCaptures tivesse sido chamado, a menos que não haja sucesso ou falha retorno de chamada é chamado.
A câmera precisa ser fechada depois que não estiver mais em uso, caso contrário, sempre ocupará os recursos da câmera, inutilizando outros aplicativos que usam a câmera. Um momento mais apropriado para desligar a câmera é no método onPause () do Activity.
*/
public abstract void close();
3. Classe interna StateCallback
1. Visão Geral
StateCallback Um objeto de retorno de chamada usado para receber atualizações sobre o estado do dispositivo da câmera. Uma instância de retorno de chamada deve ser fornecida ao método {@link CameraManager#openCamera} para abrir um dispositivo de câmera.
Essas atualizações de status incluem notificações quando o dispositivo termina de inicializar (permitindo chamadas para {@link #createCaptureSession}), notificações quando o dispositivo é desconectado ou desligado e notificações sobre erros inesperados do dispositivo.
Eventos sobre o progresso de {@link CaptureRequest CaptureRequests} específicos são fornecidos por meio de {@link CameraCaptureSession.CaptureCallback} para {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst}, {@link CameraCaptureSession#setRepeatingRequest} ou {@ link CameraCaptureSession#setRepeatingRequest} ou {@link CameraCaptureSession#setRepeatingRequest
}
, link CameraCaptureSession#setRepeatingBurst}.
2. Constante
/** onError pode relatar um código de erro indicando que o dispositivo da câmera já está em uso. Este erro pode ser gerado quando a abertura de uma câmera falha porque a câmera está sendo usada por um cliente de API de câmera de prioridade mais alta. Veja: onError */ public static final int ERROR_CAMERA_IN_USE = 1;
/**
Um código de erro que pode ser relatado por onError indicando que o dispositivo de câmera não pôde ser aberto porque há muitos outros dispositivos de câmera abertos.
Foi atingido um limite do número de câmeras abertas em todo o sistema, nenhum outro dispositivo de câmera pode ser aberto até que a instância anterior seja fechada.
Este erro é gerado quando a abertura da câmera falha.
Veja: onError
*/
public static final int ERROR_MAX_CAMERAS_IN_USE = 2;
/** onError Um código de erro que pode ser relatado indicando que o dispositivo da câmera não pôde ser aberto devido à política do dispositivo. Veja: android.app.admin.DevicePolicyManager.setCameraDisabled(android.content.ComponentName, boolean), onError */ public static final int ERROR_CAMERA_DISABLED = 3;
/**
Um código de erro que pode ser relatado por onError indicando que o dispositivo da câmera encontrou um erro fatal.
O dispositivo da câmera precisa ser ligado novamente antes de poder ser usado novamente.
Veja: onError
*/
public static final int ERROR_CAMERA_DEVICE = 4;
/**
Um código de erro que pode ser relatado por onError indicando que o serviço de câmera encontrou um erro fatal.
O dispositivo Android pode precisar ser desligado e reiniciado para restaurar a funcionalidade da câmera ou pode haver um problema de hardware contínuo.
A recuperação pode ser tentada fechando o CameraDevice e o CameraManager e tentando obter todos os recursos novamente do zero.
Veja: onError
*/
public static final int ERROR_CAMERA_SERVICE = 5;
3. Método
/**
Método chamado quando o dispositivo da câmera terminou de abrir.
Neste ponto, o dispositivo de câmera está pronto para uso e {@link CameraDevice#createCaptureSession} pode ser chamado para configurar a primeira sessão de captura.
@param camera Opened camera device
*/
public abstract void onOpened(@NonNull CameraDevice camera); // deve ser implementado
/**
Método chamado quando o dispositivo da câmera foi fechado via close.
Qualquer tentativa futura de chamar métodos neste CameraDevice lançará um IllegalStateException.
A implementação padrão desse método não faz nada.
Parâmetros:
@param camera – dispositivo de câmera fechado
*/
public void onClosed(@NonNull CameraDevice camera) {
// Implementação vazia padrão
}
/**
Método chamado quando o dispositivo da câmera não está mais disponível.
Este retorno de chamada pode ser chamado em vez de onOpened se a abertura da câmera falhar.
Qualquer tentativa de chamar métodos neste CameraDevice lançará uma CameraAccessException. Uma desconexão pode ocorrer devido a uma alteração na política de segurança ou permissões; desconexão física de um dispositivo de câmera removível; ou um cliente de API de câmera de prioridade mais alta que requer uma câmera.
O retorno de chamada de captura ainda pode ser chamado após chamar esse método ou um novo buffer de imagem passado para a saída da atividade.
A implementação padrão registra notificações sobre desconexões no syslog.
Depois que isso acontecer, você deve limpar a câmera desligando-a, pois ela só pode ser restaurada ligando-a novamente. Para a maioria dos casos de uso, isso acontecerá quando as câmeras estiverem disponíveis novamente.
Parâmetros:
@param camera – o dispositivo desconectado
*/
public abstract void onDisconnected(@NonNull CameraDevice camera); //Deve ser implementado
/**
Método chamado quando o dispositivo da câmera encontra um erro crítico.
Este retorno de chamada pode ser chamado em vez de onOpened se a abertura da câmera falhar.
Isso indica algum tipo de falha no dispositivo da câmera ou no serviço da câmera. Qualquer tentativa futura de chamar métodos neste CameraDevice lançará uma CameraAccessException com o motivo CAMERA_ERROR.
Os retornos de chamada de captura completa ou fluxo de câmera ainda podem ser chamados após o recebimento desse erro.
Depois que isso acontecer, você deve desligar a câmera e fazer a limpeza. Outras tentativas de recuperação são específicas do código de erro.
Parâmetros:
@param camera – o dispositivo relatando o erro
@param error – código de erro.
*/
public abstract void onError(@NonNull CameraDevice camera, @ErrorCode int error); // deve ser implementado