Catatan: Halaman ini merujuk ke paket Camera2. Kecuali aplikasi Anda memerlukan fitur tingkat rendah tertentu dari Camera2, sebaiknya gunakan CameraX. CameraX dan Camera2 mendukung Android 5.0 (level API 21) dan versi yang lebih baru.
Kamera dan pratinjau kamera tidak selalu dalam orientasi yang sama di Android perangkat.
Kamera berada pada posisi tetap pada suatu perangkat, terlepas dari apakah perangkat tersebut adalah ponsel, tablet, atau komputer. Saat orientasi perangkat berubah, perubahan orientasi kamera.
Akibatnya, aplikasi kamera umumnya mengasumsikan hubungan tetap antara orientasi perangkat dan rasio aspek pratinjau kamera. Ketika seorang ponsel dalam orientasi potret, pratinjau kamera diasumsikan lebih tinggi daripada lebarnya. Saat ponsel (dan kamera) diputar ke lanskap, pratinjau kamera diharapkan lebih lebar daripada tingginya.
Namun, asumsi ini dibantah oleh faktor bentuk baru, seperti perangkat foldable perangkat, dan mode tampilan seperti multi-aplikasi dan multi-tampilan. Perangkat foldable mengubah ukuran tampilan dan rasio aspek tanpa berubah orientasi. Mode multi-aplikasi membatasi aplikasi kamera ke sebagian menskalakan pratinjau kamera, apa pun orientasi perangkat. Mode multi-tampilan memungkinkan penggunaan layar sekunder yang mungkin tidak dalam orientasi yang sama dengan tampilan utama.
Orientasi kamera
Tujuan Definisi Kompatibilitas Android menetapkan bahwa sensor gambar kamera "HARUS diorientasikan sehingga panjang kamera sejajar dengan dimensi panjang layar. Artinya, ketika saat perangkat dipegang dalam orientasi lanskap, kamera HARUS mengambil gambar dalam orientasi lanskapnya. Ini berlaku terlepas dari orientasi; yaitu, berlaku untuk perangkat utama lanskap serta perangkat utama potret-mode."
Pengaturan kamera ke layar memaksimalkan area tampilan kamera jendela bidik di aplikasi kamera. Selain itu, sensor gambar biasanya menghasilkan datanya dalam lanskap, dengan rasio aspek yang paling umum adalah 4:3.
Orientasi alami sensor kamera adalah lanskap. Pada gambar 1, sensor dari kamera yang menghadap ke depan (kamera menunjuk ke arah yang sama dengan layar) diputar 270 derajat relatif terhadap ponsel untuk mematuhi Definisi Kompatibilitas Android.
Untuk mengekspos rotasi sensor ke aplikasi, metode
camera2 API mencakup
SENSOR_ORIENTATION
. Untuk sebagian besar ponsel dan tablet, perangkat melaporkan orientasi sensor
270 derajat untuk kamera depan dan 90 derajat (sudut pandang dari
belakang perangkat) untuk kamera belakang, yang menyejajarkan tepi panjang
sensor dengan tepi panjang perangkat. Kamera laptop umumnya melaporkan
orientasi sensor 0 atau 180 derajat.
Karena sensor gambar kamera menghasilkan output berupa data (buffer gambar) pada
orientasi alami sensor (lanskap), buffer gambar harus diputar
jumlah derajat yang ditentukan oleh SENSOR_ORIENTATION untuk pratinjau kamera
muncul tegak lurus dalam orientasi alami perangkat. Untuk kamera depan,
rotasinya berlawanan arah jarum jam; untuk kamera belakang, searah jarum jam.
Misalnya, untuk kamera depan pada gambar 1, buffer gambar yang dihasilkan sensor kamera akan terlihat seperti ini:
Gambar harus diputar 270 derajat berlawanan arah jarum jam agar pratinjau orientasinya sesuai dengan orientasi perangkat:
Kamera belakang akan menghasilkan buffering gambar dengan orientasi yang sama
seperti buffer di atas, tetapi SENSOR_ORIENTATION adalah 90 derajat. Hasilnya,
buffer diputar 90 derajat searah jarum jam.
Rotasi perangkat
Rotasi perangkat adalah jumlah derajat rotasi perangkat dari orientasi. Misalnya, ponsel dalam orientasi lanskap memiliki perangkat rotasi 90 atau 270 derajat, tergantung pada arah rotasi.
Buffer gambar sensor kamera harus diputar dengan jumlah derajat yang sama dengan rotasi perangkat (selain derajat orientasi sensor) untuk pratinjau kamera agar terlihat tegak.
Penghitungan orientasi
Orientasi yang tepat dari pratinjau kamera mempertimbangkan sensor orientasi dan rotasi perangkat.
Rotasi buffer gambar sensor secara keseluruhan dapat dihitung menggunakan formula berikut:
rotation = (sensorOrientationDegrees - deviceOrientationDegrees * sign + 360) % 360
dengan sign adalah 1 untuk kamera depan, -1 untuk kamera belakang.
Untuk kamera depan, buffer gambar diputar berlawanan arah jarum jam (dari orientasi alami sensor). Untuk kamera belakang, sensor buffer gambar diputar searah jarum jam.
Ekspresi deviceOrientationDegrees * sign + 360 mengonversi rotasi perangkat
dari berlawanan arah jarum jam untuk kamera belakang (misalnya,
mengubah 270 derajat berlawanan arah jarum jam menjadi 90 derajat searah jarum jam). Modulus
menskalakan hasilnya hingga kurang dari 360 derajat (misalnya, menskalakan 540
derajat rotasi ke 180).
API yang berbeda melaporkan rotasi perangkat secara berbeda:
Display#getRotation()memberikan rotasi perangkat berlawanan arah jarum jam (dari sudut pandang pengguna penayangan). Nilai ini dimasukkan ke dalam rumus di atas sebagaimana adanya.OrientationEventListener#onOrientationChanged()mengembalikan rotasi perangkat searah jarum jam (dari sudut pandang pengguna). Menegasikan nilai untuk digunakan dalam formula di atas.
Kamera depan
Berikut adalah buffer gambar yang dihasilkan oleh sensor kamera pada gambar 2:
Buffer harus diputar 270 derajat berlawanan arah jarum jam untuk menyesuaikan sensor orientasi (lihat Orientasi kamera di atas):
Kemudian {i>buffer<i} diputar tambahan 90 derajat berlawanan arah jarum jam untuk memperhitungkan rotasi perangkat, sehingga menghasilkan orientasi yang benar dari pratinjau kamera di gambar 2:
Berikut ini kamera yang diputar ke kanan ke orientasi lanskap:
Berikut buffer gambar:
Buffer harus diputar 270 derajat berlawanan arah jarum jam untuk menyesuaikan sensor orientasi:
Kemudian {i>buffer<i} diputar 270 derajat lainnya berlawanan arah jarum jam untuk memperhitungkan rotasi perangkat:
Kamera belakang
Kamera yang menghadap ke belakang biasanya memiliki orientasi sensor 90 derajat (seperti dilihat dari bagian belakang perangkat). Saat mengorientasikan pratinjau kamera, buffer gambar sensor diputar searah jarum jam berdasarkan jumlah rotasi sensor (bukan berlawanan arah jarum jam seperti kamera depan), lalu gambar buffer diputar berlawanan arah jarum jam berdasarkan jumlah rotasi perangkat.
Berikut adalah buffer gambar dari sensor kamera pada gambar 4:
Buffer harus diputar 90 derajat searah jarum jam untuk menyesuaikan sensor orientasi:
Kemudian, buffer diputar 270 derajat berlawanan arah jarum jam untuk memperhitungkan perangkat rotasi:
Rasio aspek
Rasio aspek tampilan akan berubah saat orientasi perangkat berubah, tetapi juga saat perangkat foldable dapat dilipat dan dibentangkan, saat ukuran jendela diubah menjadi multi-aplikasi lingkungan aplikasi, dan saat aplikasi dibuka di tampilan sekunder.
Buffer gambar sensor kamera harus diorientasikan dan diskalakan agar sesuai dengan orientasi dan rasio aspek elemen UI jendela bidik sebagai UI secara dinamis mengubah orientasi—dengan atau tanpa perubahan perangkat orientasi.
Pada faktor bentuk baru atau di lingkungan multi-aplikasi atau multi-tampilan, jika aplikasi berasumsi bahwa pratinjau kamera memiliki orientasi yang sama dengan perangkat (potret atau lanskap) pratinjau Anda mungkin tidak diorientasikan dengan benar, diskalakan salah, atau keduanya.
Pada Gambar 5, aplikasi keliru mengasumsikan bahwa perangkat diputar 90 kali derajat berlawanan arah jarum jam; Jadi, aplikasi memutar pratinjau dengan jumlah yang sama.
Pada gambar 6, aplikasi tidak menyesuaikan rasio aspek buffer gambar ke memungkinkannya melakukan penskalaan dengan benar agar sesuai dengan dimensi baru UI pratinjau kamera .
Aplikasi kamera berorientasi tetap biasanya mengalami masalah pada perangkat foldable dan perangkat layar besar lainnya seperti laptop:
Dalam gambar 7, UI aplikasi kamera miring karena orientasi aplikasi dibatasi untuk potret saja. Gambar jendela bidik diorientasikan dengan benar relatif terhadap sensor kamera.
Mode potret inset
Aplikasi kamera yang tidak mendukung mode multi-aplikasi
(resizeableActivity="false")
dan membatasi orientasinya
(screenOrientation="portrait")
atau screenOrientation="landscape")
dapat ditempatkan dalam mode potret inset di perangkat layar besar untuk
pratinjau kamera.
Aplikasi khusus potret dalam mode potret inset (inset) dalam mode potret orientasi meskipun rasio aspek tampilan adalah lanskap. Aplikasi khusus lanskap memiliki tampilan lebar dalam orientasi lanskap rasio aspek tampilan adalah potret. Gambar kamera diputar untuk menyejajarkan dengan UI aplikasi, yang dipangkas agar sesuai dengan rasio aspek pratinjau kamera, dan kemudian diskalakan untuk mengisi pratinjau.
Mode potret inset dipicu saat rasio aspek gambar kamera sensor dan rasio aspek aktivitas utama aplikasi tidak cocok.
Pada gambar 8, aplikasi kamera khusus potret telah diputar untuk menampilkan UI di layar laptopnya. Aplikasi ini memiliki tampilan lebar karena perbedaannya dalam rasio aspek antara aplikasi potret dan tampilan lanskap. Kamera gambar pratinjau telah diputar untuk mengimbangi rotasi UI aplikasi (karena mode potret inset), dan gambar telah dipangkas dan diskalakan agar sesuai dengan orientasi potret, yang mengurangi ruang pandang.
Putar, pangkas, skalakan
Mode potret inset dipanggil untuk aplikasi kamera khusus potret pada layar yang memiliki rasio aspek lanskap:
Aplikasi memiliki tampilan lebar dalam orientasi potret:
Gambar kamera diputar 90 derajat untuk menyesuaikan reorientasi aplikasi:
Gambar dipangkas sesuai rasio aspek pratinjau kamera, lalu diskalakan untuk isi pratinjau (ruang pandang dikurangi):
Pada perangkat foldable, orientasi sensor kamera bisa berupa potret saat rasio aspek tampilan adalah lanskap:
Karena pratinjau kamera diputar untuk menyesuaikan orientasi sensor, gambar diorientasikan dengan benar dalam jendela bidik, tetapi aplikasi khusus potret adalah miring.
Mode potret inset hanya perlu membuat tampilan lebar aplikasi dalam orientasi potret untuk mengorientasikan pratinjau aplikasi dan kamera dengan benar:
API
Mulai dari Android 12 (API level 31), aplikasi juga dapat secara eksplisit mengontrol potret inset
melalui
SCALER_ROTATE_AND_CROP
properti CaptureRequest
.
Nilai defaultnya adalah
SCALER_ROTATE_AND_CROP_AUTO,
yang memungkinkan sistem untuk memanggil
mode potret inset.
SCALER_ROTATE_AND_CROP_90
adalah perilaku mode potret inset seperti yang dijelaskan di atas.
Tidak semua perangkat mendukung semua nilai SCALER_ROTATE_AND_CROP. Untuk mendapatkan daftar
nilai yang didukung, referensi
CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES
CameraX
Library Jetpack CameraX membuat pembuatan jendela bidik kamera yang mengakomodasi orientasi sensor dan rotasi perangkat adalah tugas sederhana.
Elemen tata letak PreviewView
membuat pratinjau kamera, yang secara
otomatis menyesuaikan orientasi sensor,
rotasi perangkat, dan penskalaan. PreviewView mempertahankan rasio aspek
gambar kamera dengan menerapkan
FILL_CENTER
, yang menempatkan gambar di tengah, tetapi mungkin akan memangkasnya agar sesuai dengan dimensi
dari PreviewView. Untuk membuat gambar kamera menjadi tampilan lebar, tetapkan jenis skala ke
FIT_CENTER
Untuk mempelajari dasar-dasar pembuatan pratinjau kamera dengan PreviewView, lihat
Mengimplementasikan pratinjau.
Untuk contoh implementasi yang lengkap, lihat
CameraXBasic
repositori di GitHub.
Jendela Bidik Kamera
Mirip dengan kasus penggunaan Pratinjau, CameraViewfinder library ini menyediakan serangkaian alat untuk menyederhanakan pembuatan pratinjau kamera. Modul ini tidak bergantung pada CameraX Core, sehingga Anda dapat mengintegrasikannya dengan lancar ke dalam codebase Camera2 yang sudah ada.
Daripada menggunakan
Surface
secara langsung, Anda dapat menggunakan
CameraViewfinder
untuk menampilkan feed kamera untuk Camera2.
CameraViewfinder secara internal menggunakan TextureView atau SurfaceView
untuk menampilkan feed kamera, dan menerapkan transformasi yang diperlukan pada
menampilkan jendela bidik dengan benar.
Hal ini termasuk koreksi rasio aspek, skala, dan rotasi.
Untuk meminta platform dari objek CameraViewfinder, Anda harus
membuat ViewfinderSurfaceRequest.
Permintaan ini berisi persyaratan untuk resolusi permukaan dan perangkat kamera
informasi dari CameraCharacteristics.
Menelepon requestSurfaceAsync()
mengirimkan permintaan ke penyedia platform, yang dapat berupa TextureView atau
SurfaceView dan mendapatkan ListenableFuture dari Surface.
Menelepon markSurfaceSafeToRelease()
memberi tahu penyedia platform bahwa platform tidak diperlukan dan terkait
resource dapat dilepaskan.
Kotlin
fun startCamera(){
val previewResolution = Size(width, height)
val viewfinderSurfaceRequest =
ViewfinderSurfaceRequest(previewResolution, characteristics)
val surfaceListenableFuture =
cameraViewfinder.requestSurfaceAsync(viewfinderSurfaceRequest)
Futures.addCallback(surfaceListenableFuture, object : FutureCallback<Surface> {
override fun onSuccess(surface: Surface) {
/* create a CaptureSession using this surface as usual */
}
override fun onFailure(t: Throwable) { /* something went wrong */}
}, ContextCompat.getMainExecutor(context))
}
Java
void startCamera(){
Size previewResolution = new Size(width, height);
ViewfinderSurfaceRequest viewfinderSurfaceRequest =
new ViewfinderSurfaceRequest(previewResolution, characteristics);
ListenableFuture<Surface> surfaceListenableFuture =
cameraViewfinder.requestSurfaceAsync(viewfinderSurfaceRequest);
Futures.addCallback(surfaceListenableFuture, new FutureCallback<Surface>() {
@Override
public void onSuccess(Surface result) {
/* create a CaptureSession using this surface as usual */
}
@Override public void onFailure(Throwable t) { /* something went wrong */}
}, ContextCompat.getMainExecutor(context));
}
SurfaceView
SurfaceView adalah
pendekatan langsung dalam membuat pratinjau kamera jika pratinjau tersebut belum
memerlukan pemrosesan
dan tidak dianimasikan.
SurfaceView akan otomatis memutar buffering gambar sensor kamera agar sesuai
orientasi tampilan, yang memperhitungkan orientasi sensor dan perangkat
kunci. Namun, buffer gambar diskalakan agar sesuai dengan SurfaceView
dimensi tanpa pertimbangan rasio aspek.
Anda harus memastikan bahwa rasio aspek buffer gambar cocok dengan aspek
SurfaceView, yang dapat Anda capai dengan menskalakan konten
dari SurfaceView dalam konfigurasi
onMeasure()
berikut:
(Kode sumber computeRelativeRotation() ada dalam
Rotasi relatif di bawah.)
Kotlin
override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
val width = MeasureSpec.getSize(widthMeasureSpec)
val height = MeasureSpec.getSize(heightMeasureSpec)
val relativeRotation = computeRelativeRotation(characteristics, surfaceRotationDegrees)
if (previewWidth > 0f && previewHeight > 0f) {
/* Scale factor required to scale the preview to its original size on the x-axis. */
val scaleX =
if (relativeRotation % 180 == 0) {
width.toFloat() / previewWidth
} else {
width.toFloat() / previewHeight
}
/* Scale factor required to scale the preview to its original size on the y-axis. */
val scaleY =
if (relativeRotation % 180 == 0) {
height.toFloat() / previewHeight
} else {
height.toFloat() / previewWidth
}
/* Scale factor required to fit the preview to the SurfaceView size. */
val finalScale = min(scaleX, scaleY)
setScaleX(1 / scaleX * finalScale)
setScaleY(1 / scaleY * finalScale)
}
setMeasuredDimension(width, height)
}
Java
@Override
void onMeasure(int widthMeasureSpec, int heightMeasureSpec) {
int width = MeasureSpec.getSize(widthMeasureSpec);
int height = MeasureSpec.getSize(heightMeasureSpec);
int relativeRotation = computeRelativeRotation(characteristics, surfaceRotationDegrees);
if (previewWidth > 0f && previewHeight > 0f) {
/* Scale factor required to scale the preview to its original size on the x-axis. */
float scaleX = (relativeRotation % 180 == 0)
? (float) width / previewWidth
: (float) width / previewHeight;
/* Scale factor required to scale the preview to its original size on the y-axis. */
float scaleY = (relativeRotation % 180 == 0)
? (float) height / previewHeight
: (float) height / previewWidth;
/* Scale factor required to fit the preview to the SurfaceView size. */
float finalScale = Math.min(scaleX, scaleY);
setScaleX(1 / scaleX * finalScale);
setScaleY(1 / scaleY * finalScale);
}
setMeasuredDimension(width, height);
}
Untuk mengetahui detail selengkapnya tentang cara menerapkan SurfaceView sebagai pratinjau kamera, lihat
Orientasi kamera.
TextureView
TextureView berperforma lebih rendah daripada
SurfaceView—dan lebih banyak pekerjaan—tetapi TextureView memberi Anda hasil maksimum
mengontrol pratinjau kamera.
TextureView memutar buffering gambar sensor berdasarkan orientasi sensor, tetapi
tidak menangani rotasi perangkat atau penskalaan pratinjau.
Penskalaan dan rotasi dapat dienkode dalam
Transformasi Matriks. Untuk mempelajari cara
menskalakan dan memutar TextureView dengan benar, lihat
Mendukung platform yang dapat diubah ukurannya di aplikasi kamera Anda
Rotasi relatif
Rotasi relatif sensor kamera adalah jumlah rotasi yang diperlukan untuk sejajarkan output sensor kamera dengan orientasi perangkat.
Rotasi relatif digunakan oleh komponen seperti SurfaceView dan TextureView
untuk menentukan faktor penskalaan x dan y untuk gambar pratinjau. Ini juga digunakan untuk
menentukan rotasi buffer gambar sensor.
Tujuan
CameraCharacteristics
dan
Class Surface memungkinkan penghitungan
rotasi relatif sensor kamera:
Kotlin
/**
* Computes rotation required to transform the camera sensor output orientation to the
* device's current orientation in degrees.
*
* @param characteristics The CameraCharacteristics to query for the sensor orientation.
* @param surfaceRotationDegrees The current device orientation as a Surface constant.
* @return Relative rotation of the camera sensor output.
*/
public fun computeRelativeRotation(
characteristics: CameraCharacteristics,
surfaceRotationDegrees: Int
): Int {
val sensorOrientationDegrees =
characteristics.get(CameraCharacteristics.SENSOR_ORIENTATION)!!
// Reverse device orientation for back-facing cameras.
val sign = if (characteristics.get(CameraCharacteristics.LENS_FACING) ==
CameraCharacteristics.LENS_FACING_FRONT
) 1 else -1
// Calculate desired orientation relative to camera orientation to make
// the image upright relative to the device orientation.
return (sensorOrientationDegrees - surfaceRotationDegrees * sign + 360) % 360
}
Java
/**
* Computes rotation required to transform the camera sensor output orientation to the
* device's current orientation in degrees.
*
* @param characteristics The CameraCharacteristics to query for the sensor orientation.
* @param surfaceRotationDegrees The current device orientation as a Surface constant.
* @return Relative rotation of the camera sensor output.
*/
public int computeRelativeRotation(
CameraCharacteristics characteristics,
int surfaceRotationDegrees
){
Integer sensorOrientationDegrees =
characteristics.get(CameraCharacteristics.SENSOR_ORIENTATION);
// Reverse device orientation for back-facing cameras.
int sign = characteristics.get(CameraCharacteristics.LENS_FACING) ==
CameraCharacteristics.LENS_FACING_FRONT ? 1 : -1;
// Calculate desired orientation relative to camera orientation to make
// the image upright relative to the device orientation.
return (sensorOrientationDegrees - surfaceRotationDegrees * sign + 360) % 360;
}
Metrik jendela aplikasi
Ukuran layar tidak boleh digunakan untuk menentukan dimensi kamera jendela bidik; aplikasi kamera mungkin berjalan di sebagian layar, baik dalam mode multi-aplikasi di perangkat seluler atau mode bebas dari ChromeOS.
WindowManager#getCurrentWindowMetrics()
(ditambahkan di level API 30) menampilkan ukuran jendela aplikasi, bukan
ukuran layar. Metode library Jetpack WindowManager
WindowMetricsCalculator#computeCurrentWindowMetrics()
dan
WindowInfoTracker#currentWindowMetrics()
menyediakan dukungan serupa dengan kompatibilitas mundur dengan API level 14.
Rotasi 180 derajat
Rotasi perangkat 180 derajat (misalnya, dari orientasi alami ke
orientasi alami terbalik) tidak memicu
onConfigurationChanged()
. Akibatnya, pratinjau kamera mungkin terbalik.
Untuk mendeteksi rotasi 180 derajat, terapkan
DisplayListener
dan periksa rotasi perangkat
dengan panggilan ke
Display#getRotation()
di
onDisplayChanged()
.
Referensi eksklusif
Sebelum Android 10, hanya aktivitas yang paling terlihat dalam multi-aplikasi
lingkungan dalam status RESUMED. Hal ini membingungkan pengguna karena
sistem tidak memberikan indikasi aktivitas mana yang dilanjutkan.
Android 10 (API level 29) memperkenalkan multi-resume dengan semua aktivitas yang terlihat
dalam status RESUMED. Aktivitas yang terlihat tetap dapat memasuki PAUSED
jika, misalnya, aktivitas transparan berada di atas aktivitas atau
aktivitas tidak dapat difokuskan, seperti dalam mode picture-in-picture (lihat
Dukungan picture-in-picture).
Aplikasi yang menggunakan kamera, mikrofon, atau fitur eksklusif atau
resource singleton pada level API 29 atau yang lebih tinggi harus mendukung multi-resume. Sebagai
misalnya, jika tiga aktivitas yang dilanjutkan ingin menggunakan kamera, hanya satu yang dapat
untuk mengakses sumber
daya eksklusif ini. Setiap aktivitas harus mengimplementasikan
onDisconnected()
untuk mengetahui akses preemptive ke kamera dengan prioritas yang lebih tinggi
aktivitas Anda.
Untuk informasi selengkapnya, lihat Multi-resume.
Referensi lainnya
- Untuk contoh Camera2, lihat aplikasi Camera2Basic di GitHub.
- Untuk mempelajari kasus penggunaan pratinjau CameraX, lihat CameraX Mengimplementasikan pratinjau.
- Untuk contoh implementasi pratinjau kamera CameraX, lihat CameraXBasic repositori di GitHub.
- Untuk mengetahui informasi tentang pratinjau kamera di ChromeOS, lihat Orientasi kamera.
- Untuk informasi tentang pengembangan perangkat foldable, lihat Pelajari perangkat foldable.