ממשק API של תוספי CameraX

CameraX מספק Extensions API לגישה לתוספים שיצרני המכשירים הטמיעו במכשירי Android שונים. כאן מפורטים מצבי התוספים שנתמכים.

כאן מפורטים המכשירים שתומכים בתוספים.

ארכיטקטורת התוספים

בתמונה הבאה מוצגת הארכיטקטורה של תוספי המצלמה.

איור 1. ארכיטקטורת Camera Extensions

אפליקציית CameraX יכולה להשתמש בתוספים דרך CameraX Extensions API. ‫CameraX Extensions API מנהל את השאילתות לתוספים זמינים, מגדיר סשן של מצלמה עם תוספים ומתקשר עם ספריית OEM של Camera Extensions. כך האפליקציה יכולה להשתמש ביכולות כמו מצב לילה, HDR, מצב אוטומטי, אפקט בוקה או ריטוש פנים.

הפעלת תוסף לצילום תמונות ולתצוגה מקדימה

לפני שמשתמשים ב-Extensions API, צריך לאחזר מכונה של ExtensionsManager באמצעות השיטה ExtensionsManager#getInstanceAsync(Context, CameraProvider). כך תוכלו לשלוח שאילתות לגבי מידע על זמינות התוסף. ואז לאחזר תוסף שמופעל על ידי CameraSelector. מצב התוסף יופעל על תרחישי השימוש של צילום תמונות ותצוגה מקדימה כשקוראים ל-method‏ bindToLifecycle()‎ כשהתוסף CameraSelector מופעל.

כדי להטמיע את התוסף לתרחישי השימוש של צילום תמונות ותצוגה מקדימה, עיינו בדוגמת הקוד הבאה:

// import androidx.camera.extensions.ExtensionMode
// import androidx.camera.extensions.ExtensionsManager

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val lifecycleOwner = this

    val cameraProviderFuture = ProcessCameraProvider.getInstance(applicationContext)
    cameraProviderFuture.addListener({
        // Obtain an instance of a process camera provider.
        // The camera provider provides access to the set of cameras associated with the device.
        // The camera obtained from the provider will be bound to the activity lifecycle.
        val cameraProvider = cameraProviderFuture.get()

        val extensionsManagerFuture =
            ExtensionsManager.getInstanceAsync(applicationContext, cameraProvider)
        extensionsManagerFuture.addListener({
            // Obtain an instance of the extensions manager.
            // The extensions manager enables a camera to use extension capabilities available on
            // the device.
            val extensionsManager = extensionsManagerFuture.get()

            // Select the camera.
            val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA

            // Query if extension is available.
            // Not all devices will support extensions or might only support a subset of
            // extensions.
            if (extensionsManager.isExtensionAvailable(cameraSelector, ExtensionMode.NIGHT)) {
                // Unbind all use cases before enabling different extension modes.
                try {
                    cameraProvider.unbindAll()

                    // Retrieve a night extension enabled camera selector.
                    val nightCameraSelector =
                        extensionsManager.getExtensionEnabledCameraSelector(
                            cameraSelector,
                            ExtensionMode.NIGHT
                        )

                    // Bind image capture and preview use cases with the extension enabled camera
                    // selector.
                    val imageCapture = ImageCapture.Builder().build()
                    val preview = Preview.Builder().build()
                    // Connect the preview to receive the surface the camera outputs the frames
                    // to. This will allow displaying the camera frames in either a TextureView
                    // or SurfaceView. The SurfaceProvider can be obtained from the PreviewView.
                    preview.setSurfaceProvider(surfaceProvider)

                    // Returns an instance of the camera bound to the lifecycle.
                    // Use this camera object to control various operations with the camera.
                    // Example: flash, zoom, focus metering etc.
                    val camera = cameraProvider.bindToLifecycle(
                        lifecycleOwner,
                        nightCameraSelector,
                        imageCapture,
                        preview
                    )
                } catch (e: Exception) {
                    Log.e(TAG, "Use case binding failed", e)
                }
            }
        }, ContextCompat.getMainExecutor(this))
    }, ContextCompat.getMainExecutor(this))
}

השבתת התוסף

כדי להשבית את התוספים של הספק, מבטלים את הקישור של כל תרחישי השימוש ומקשרים מחדש את תרחישי השימוש של צילום התמונות והתצוגה המקדימה באמצעות בורר מצלמה רגיל. לדוגמה, אפשר להגדיר מחדש את המצלמה האחורית באמצעות CameraSelector.DEFAULT_BACK_CAMERA.

פניות קשורות

ממשק ה-API של תוספי CameraX מוטמע בספרייה camera-extensions. התוספים תלויים במודולים העיקריים של CameraX‏ (core,‏ camera2,‏ lifecycle).

מגניב

dependencies {
  def camerax_version = "1.2.0-rc01"
  implementation "androidx.camera:camera-core:${camerax_version}"
  implementation "androidx.camera:camera-camera2:${camerax_version}"
  implementation "androidx.camera:camera-lifecycle:${camerax_version}"
  //the CameraX Extensions library
  implementation "androidx.camera:camera-extensions:${camerax_version}"
    ...
}

Kotlin

dependencies {
  val camerax_version = "1.2.0-rc01"
  implementation("androidx.camera:camera-core:${camerax_version}")
  implementation("androidx.camera:camera-camera2:${camerax_version}")
  implementation("androidx.camera:camera-lifecycle:${camerax_version}")
  // the CameraX Extensions library
  implementation("androidx.camera:camera-extensions:${camerax_version}")
    ...
}

הסרת ה-API הקודם

עם ה-Extensions API החדש שפורסם ב-1.0.0-alpha26, ה-Extensions API הקודם שפורסם באוגוסט 2019 הוצא משימוש. החל מגרסה 1.0.0-alpha28, ממשק ה-API של התוספים הקודמים הוסר מהספרייה. אפליקציות שמשתמשות ב-Extensions API החדש צריכות עכשיו לרכוש CameraSelector עם תוספים ולהשתמש בו כדי לקשר את תרחישי השימוש.

אם אתם משתמשים בגרסה הקודמת של Extensions API, אתם צריכים לעבור לגרסה החדשה כדי שהאפליקציה תמשיך לפעול עם הגרסאות הבאות של CameraX.

מקורות מידע נוספים

איפה אפשר למצוא מידע נוסף על CameraX?

Codelab

  • תחילת העבודה עם CameraX

    • דוגמת קוד

    אפליקציה לדוגמה של תוספי CameraX

    מקורות מידע נוספים

    תוספים של ספק CameraX

    כלי האימות של CameraX Vendor Extensions