Camera2 擴充功能 API

注意:本頁面所述是指 Camera2 套件。除非應用程式需要 Camera2 的特定低階功能,否則建議使用 CameraX。CameraX 和 Camera2 均支援 Android 5.0 (API 級別 21) 以上版本。

Camera2 提供 Extensions API,可用於存取裝置製造商在不同 Android 裝置上實作的擴充功能。如需支援的擴充功能模式清單,請參閱「相機擴充功能」。

如需支援擴充功能的裝置清單,請參閱「支援的裝置」。

擴充功能架構

下圖顯示相機擴充功能的架構。

圖 1 相機擴充功能架構

Camera2 應用程式可透過 Camera2 API 使用擴充功能。Camera2 API 可用於查詢可用擴充功能、設定擴充功能相機工作階段,以及與 Camera Extensions OEM 程式庫通訊。這可讓應用程式使用「夜晚」、「高動態範圍」、「自動」、「散景」或「修容」等擴充功能。

測試相機裝置與 Camera2 Extensions API 的相容性

下列程式碼片段會檢查裝置是否支援 Camera2 Extensions API。並非所有裝置都支援擴充功能,或裝置可能支援部分擴充功能。程式碼片段會傳回支援相機擴充功能的相容相機 ID 清單。

private fun getExtensionCameraIds(cameraManager: CameraManager): List<String> =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        cameraManager.cameraIdList.filter { cameraId ->
            val characteristics = cameraManager.getCameraCharacteristics(cameraId)
            val extensionCharacteristics =
                cameraManager.getCameraExtensionCharacteristics(cameraId)
            val capabilities =
                characteristics.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)
            extensionCharacteristics.supportedExtensions.isNotEmpty() &&
                capabilities?.contains(
                    CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE
                ) ?: false
        }
    } else emptyList()

使用 Camera2 Extensions API 建立 CameraExtensionSession

在相容裝置上使用 Camera2 Extensions API,即可存取特定相機擴充功能。下列程式碼片段示範如何建立 CameraExtensionSession,以便在現有的 Camera2 應用程式中使用夜間拍攝模式。

private val captureCallbacks = object : CameraExtensionSession.ExtensionCaptureCallback() {
    // Implement Capture Callbacks.
}
private val extensionSessionStateCallback = object : CameraExtensionSession.StateCallback() {
    override fun onConfigured(session: CameraExtensionSession) {
        cameraExtensionSession = session
        try {
            val captureRequest =
                cameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW).apply {
                    addTarget(previewSurface)
                }.build()
            session.setRepeatingRequest(
                captureRequest,
                Dispatchers.IO.asExecutor(),
                captureCallbacks
            )
        } catch (e: CameraAccessException) {
            Snackbar.make(
                previewView,
                "Failed to preview capture request",
                Snackbar.LENGTH_SHORT
            ).show()
            requireActivity().finish()
        }
    }

    override fun onClosed(session: CameraExtensionSession) {
        super.onClosed(session)
        cameraDevice.close()
    }

    override fun onConfigureFailed(session: CameraExtensionSession) {
        Snackbar.make(
            previewView,
            "Failed to start camera extension preview",
            Snackbar.LENGTH_SHORT
        ).show()
        requireActivity().finish()
    }
}

private fun startExtensionSession() {
    val outputConfig = arrayListOf(
        OutputConfiguration(stillImageReader.surface),
        OutputConfiguration(previewSurface)
    )
    val extensionConfiguration = ExtensionSessionConfiguration(
        CameraExtensionCharacteristics.EXTENSION_NIGHT,
        outputConfig,
        Dispatchers.IO.asExecutor(),
        extensionSessionStateCallback
    )
    cameraDevice.createExtensionSession(extensionConfiguration)
}

其他資源

詳情請參閱 CameraExtensionCharacteristics,並查看公開的 Camera2 Extensions API 範例。