Observação:esta página se refere ao pacote Camera2. A menos que seu app exija recursos específicos e de baixo nível do Camera2, recomendamos o uso do CameraX. CameraX e Camera2 oferecem suporte ao Android 5.0 (nível 21 da API) e versões mais recentes.
Muitos dispositivos Android modernos têm duas ou mais câmeras na parte frontal, traseira ou em ambos os lados. Cada lente pode ter recursos exclusivos, como captura de burst, controle manual ou rastreamento de movimento. Um app para depositar cheques pode usar apenas a primeira câmera traseira, enquanto um app de mídias sociais pode usar uma câmera frontal por padrão, mas oferecer aos usuários a opção de alternar entre todas as lentes disponíveis. Ele também pode se lembrar das escolhas deles.
Esta página explica como listar as lentes de câmera e os respectivos recursos para que você possa tomar decisões no seu app sobre qual lente usar em uma determinada situação. O snippet de código a seguir recupera uma lista de todas as câmeras e faz a iteração delas:
Kotlin
try {
val cameraIdList = cameraManager.cameraIdList // may be empty
// iterate over available camera devices
for (cameraId in cameraIdList) {
val characteristics = cameraManager.getCameraCharacteristics(cameraId)
val cameraLensFacing = characteristics.get(CameraCharacteristics.LENS_FACING)
val cameraCapabilities = characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)
// check if the selected camera device supports basic features
// ensures backward compatibility with the original Camera API
val isBackwardCompatible = cameraCapabilities?.contains(
CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE) ?: false
...
}
} catch (e: CameraAccessException) {
e.message?.let { Log.e(TAG, it) }
...
}
Java
try {
String[] cameraIdList = cameraManager.getCameraIdList(); // may be empty
// iterate over available camera devices
for (String cameraId : cameraIdList) {
CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(cameraId);
int cameraLensFacing = characteristics.get(CameraCharacteristics.LENS_FACING);
int[] cameraCapabilities =
characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES);
// check if the selected camera device supports basic features
// ensures backward compatibility with the original Camera API
boolean isBackwardCompatible = false;
for (int capability : cameraCapabilities) {
if (capability == CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE) {
isBackwardCompatible = true;
break;
}
}
...
}
} catch (CameraAccessException e) {
Log.e(TAG, e.getMessage());
...
}
A variável cameraLensFacing descreve a direção para a qual a câmera está voltada
em relação à tela do dispositivo e tem um dos seguintes valores:
CameraMetadata.LENS_FACING_FRONTCameraMetadata.LENS_FACING_BACKCameraMetadata.LENS_FACING_EXTERNAL
Para saber mais sobre a configuração voltada para a lente, consulte
CameraCharacteristics.LENS_FACING.
A variável cameraCapabilities do exemplo de código anterior contém
informações sobre recursos diversos, incluindo se a câmera é
capaz de produzir frames padrão como saída (ao contrário de, por exemplo, apenas dados de sensores de profundidade). Você pode procurar se
CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE
é um dos recursos listados da câmera, que é armazenado como uma sinalização em
isBackwardCompatible.
Escolha padrões sensíveis
No app, é provável que você queira abrir uma câmera específica por padrão, se ela estiver disponível. Por exemplo, um app de selfie provavelmente abre a câmera frontal, enquanto um app de realidade aumentada pode começar com a câmera traseira. A função a seguir retorna a primeira câmera voltada para uma determinada direção:
Kotlin
fun getFirstCameraIdFacing(cameraManager: CameraManager,
facing: Int = CameraMetadata.LENS_FACING_BACK): String? {
try {
// Get list of all compatible cameras
val cameraIds = cameraManager.cameraIdList.filter {
val characteristics = cameraManager.getCameraCharacteristics(it)
val capabilities = characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)
capabilities?.contains(
CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE) ?: false
}
// Iterate over the list of cameras and return the first one matching desired
// lens-facing configuration
cameraIds.forEach {
val characteristics = cameraManager.getCameraCharacteristics(it)
if (characteristics.get(CameraCharacteristics.LENS_FACING) == facing) {
return it
}
}
// If no camera matched desired orientation, return the first one from the list
return cameraIds.firstOrNull()
} catch (e: CameraAccessException) {
e.message?.let { Log.e(TAG, it) }
}
}
Java
public String getFirstCameraIdFacing(CameraManager cameraManager, @Nullable Integer facing) {
if (facing == null) facing = CameraMetadata.LENS_FACING_BACK;
String cameraId = null;
try {
// Get a list of all compatible cameras
String[] cameraIdList = cameraManager.getCameraIdList();
// Iterate over the list of cameras and return the first one matching desired
// lens-facing configuration and backward compatibility
for (String id : cameraIdList) {
CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(id);
int[] capabilities = characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES);
for (int capability : capabilities) {
if (capability == CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE
&& characteristics.get(CameraCharacteristics.LENS_FACING).equals(facing)) {
cameraId = id;
break;
}
}
}
// If no camera matches the desired orientation, return the first one from the list
cameraId = cameraIdList[0];
} catch (CameraAccessException e) {
Log.e(TAG, "getFirstCameraIdFacing: " + e.getMessage());
}
return cameraId;
}
Ativar a troca de câmera
Muitos apps de câmera oferecem aos usuários a opção de alternar entre câmeras:
Muitos dispositivos têm várias câmeras voltadas para a mesma direção. Alguns têm câmeras USB externas. Para fornecer aos usuários uma interface que permita alternar entre diferentes câmeras, escolha a primeira câmera disponível para cada configuração possível voltada para as lentes.
Embora não haja uma lógica universal para selecionar a próxima câmera, o código abaixo funciona para a maioria dos casos de uso:
Kotlin
fun filterCompatibleCameras(cameraIds: Array<String>,
cameraManager: CameraManager): List<String> {
return cameraIds.filter {
val characteristics = cameraManager.getCameraCharacteristics(it)
characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)?.contains(
CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE) ?: false
}
}
fun filterCameraIdsFacing(cameraIds: List<String>, cameraManager: CameraManager,
facing: Int): List<String> {
return cameraIds.filter {
val characteristics = cameraManager.getCameraCharacteristics(it)
characteristics.get(CameraCharacteristics.LENS_FACING) == facing
}
}
fun getNextCameraId(cameraManager: CameraManager, currCameraId: String? = null): String? {
// Get all front, back and external cameras in 3 separate lists
val cameraIds = filterCompatibleCameras(cameraManager.cameraIdList, cameraManager)
val backCameras = filterCameraIdsFacing(
cameraIds, cameraManager, CameraMetadata.LENS_FACING_BACK)
val frontCameras = filterCameraIdsFacing(
cameraIds, cameraManager, CameraMetadata.LENS_FACING_FRONT)
val externalCameras = filterCameraIdsFacing(
cameraIds, cameraManager, CameraMetadata.LENS_FACING_EXTERNAL)
// The recommended order of iteration is: all external, first back, first front
val allCameras = (externalCameras + listOf(
backCameras.firstOrNull(), frontCameras.firstOrNull())).filterNotNull()
// Get the index of the currently selected camera in the list
val cameraIndex = allCameras.indexOf(currCameraId)
// The selected camera may not be in the list, for example it could be an
// external camera that has been removed by the user
return if (cameraIndex == -1) {
// Return the first camera from the list
allCameras.getOrNull(0)
} else {
// Return the next camera from the list, wrap around if necessary
allCameras.getOrNull((cameraIndex + 1) % allCameras.size)
}
}
Java
public List<String> filterCompatibleCameras(CameraManager cameraManager, String[] cameraIds) {
final List<String> compatibleCameras = new ArrayList<>();
try {
for (String id : cameraIds) {
CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(id);
int[] capabilities = characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES);
for (int capability : capabilities) {
if (capability == CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE) {
compatibleCameras.add(id);
}
}
}
} catch (CameraAccessException e) {
Log.e(TAG, "filterCompatibleCameras: " + e.getMessage());
}
return compatibleCameras;
}
public List<String> filterCameraIdsFacing(CameraManager cameraManager, List<String> cameraIds, int lensFacing) {
final List<String> compatibleCameras = new ArrayList<>();
try {
for (String id : cameraIds) {
CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(id);
if (characteristics.get(CameraCharacteristics.LENS_FACING) == lensFacing) {
compatibleCameras.add(id);
}
}
} catch (CameraAccessException e) {
Log.e(TAG, "filterCameraIdsFacing: " + e.getMessage());
}
return compatibleCameras;
}
public String getNextCameraId(CameraManager cameraManager, @Nullable String currentCameraId) {
String nextCameraId = null;
try {
// Get all front, back, and external cameras in 3 separate lists
List<String> compatibleCameraIds = filterCompatibleCameras(cameraManager, cameraManager.getCameraIdList());
List<String> backCameras = filterCameraIdsFacing(cameraManager, compatibleCameraIds, CameraMetadata.LENS_FACING_BACK);
List<String> frontCameras = filterCameraIdsFacing(cameraManager, compatibleCameraIds, CameraMetadata.LENS_FACING_FRONT);
List<String>externalCameras = filterCameraIdsFacing(cameraManager, compatibleCameraIds, CameraMetadata.LENS_FACING_EXTERNAL);
// The recommended order of iteration is: all external, first back, first front
List<String> allCameras = new ArrayList<>(externalCameras);
if (!backCameras.isEmpty()) allCameras.add(backCameras.get(0));
if (!frontCameras.isEmpty()) allCameras.add(frontCameras.get(0));
// Get the index of the currently selected camera in the list
int cameraIndex = allCameras.indexOf(currentCameraId);
// The selected camera may not be in the list, for example it could be an
// external camera that has been removed by the user
if (cameraIndex == -1) {
// Return the first camera from the list
nextCameraId = !allCameras.isEmpty() ? allCameras.get(0) : null;
else {
if (!allCameras.isEmpty()) {
// Return the next camera from the list, wrap around if necessary
nextCameraId = allCameras.get((cameraIndex + 1) % allCameras.size());
}
}
} catch (CameraAccessException e) {
Log.e(TAG, "getNextCameraId: " + e.getMessage());
}
return nextCameraId;
}
Esse código funciona para um grande conjunto de dispositivos com muitas configurações
diferentes. Para mais informações sobre como contabilizar casos extremos, consulte CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA.
Criar apps compatíveis
Para apps que ainda usam a API Camera descontinuada, o número de câmeras
que o
Camera.getNumberOfCameras()
retorna depende da implementação do OEM. Se houver várias câmeras lógicas no
sistema, para manter a compatibilidade com versões anteriores do app, esse método vai expor apenas uma
câmera para cada câmera lógica e grupo de câmeras físicas subjacentes.
Use a API Camera2 para ver todas as câmeras.
Para mais informações sobre as orientações da câmera, consulte
Camera.CameraInfo.orientation.
Em geral, use a API
Camera.getCameraInfo()
para consultar todas as orientations
da câmera e expor apenas uma câmera para cada orientação disponível aos usuários que
alternem entre as câmeras.
Acomode todos os tipos de dispositivos
Não presuma que o app sempre é executado em um dispositivo portátil com uma ou duas câmeras. Em vez disso, escolha as câmeras mais adequadas para o app. Se você não precisar de uma câmera específica, selecione a primeira que estiver voltada para a direção desejada. Se uma câmera externa estiver conectada, você pode presumir que o usuário prioriza essa câmera como padrão.