فراتر از ویژگی‌های تکی: تضمین ترکیب ویژگی‌ها با CameraX 1.5

اپلیکیشن‌های دوربین مدرن با ویژگی‌های قدرتمند و همپوشانی تعریف می‌شوند. کاربران انتظار دارند که ویدیو را با HDR خیره‌کننده ضبط کنند، حرکات روان را با سرعت 60 فریم در ثانیه ثبت کنند و با استفاده از Preview Stabilization (لرزش‌گیر پیش‌نمایش) فیلم‌هایی بسیار روان و بدون لرزش بگیرند - که اغلب همه این‌ها به طور همزمان انجام می‌شود.

As developers, we know the reality is more complicated. How can you guarantee that a specific device actually supports a given combination? Until now, enabling multiple features was often a gamble. You could check for individual feature support, but combining them could lead to undefined behavior or, worse, a failed camera session. This uncertainty forces developers to be conservative, which prevents users on capable devices from accessing the best possible experience.

برای مثال، تعداد بسیار کمی از دستگاه‌های رده بالا به طور قابل اعتمادی از HDR و ویدیوی 60 فریم بر ثانیه به طور همزمان پشتیبانی می‌کنند. در نتیجه، اکثر برنامه‌ها از فعال کردن همزمان هر دو خودداری می‌کنند تا از تجربه کاربری ضعیف در اکثر تلفن‌ها جلوگیری کنند.

برای حل این مشکل، ما در CameraX گروه ویژگی‌ها را معرفی می‌کنیم - یک API جدید که برای از بین بردن این حدس و گمان طراحی شده است. اکنون می‌توانید قبل از پیکربندی دوربین، استعلام کنید که آیا ترکیب خاصی از ویژگی‌ها پشتیبانی می‌شود یا خیر، یا به سادگی اولویت‌های خود را به CameraX بگویید و اجازه دهید بهترین ترکیب پشتیبانی شده را برای شما فعال کند.

برای کسانی که تازه با CameraX آشنا شده‌اند

Before we dive into the new Feature Group API, let's quickly recap what CameraX is. CameraX is a Jetpack support library, built to help you make camera app development easier. It provides a consistent and easy-to-use API surface that works across most Android devices, with backward-compatibility to Android 6.0 (API level 23). If you are new to CameraX, we recommend checking out the official documentation and trying the codelab to get started.

آنچه می‌توانید با API گروه ویژگی‌ها بسازید

دیگر نیازی نیست روی ترکیب ویژگی‌ها قمار کنید و می‌توانید با اطمینان بهترین تجربه‌های ممکن دوربین - مانند HDR همزمان و فیلمبرداری 60 فریم بر ثانیه را روی سخت‌افزار توانمند (مثلاً Pixel 10 Pro) - ارائه دهید، در حالی که به طرز زیبایی از خطاها در دستگاه‌هایی که نمی‌توانند از این ترکیب پشتیبانی کنند، جلوگیری می‌کنید.

با استفاده از API گروه ویژگی‌ها، می‌توانید:

• رابط‌های کاربری پویا و هوشمندتری بسازید: تنظیمات رابط کاربری خود را بر اساس پشتیبانی سخت‌افزاری بلادرنگ، هوشمندانه فعال یا غیرفعال کنید. برای مثال، اگر کاربری HDR را فعال کند، می‌توانید فوراً گزینه ۶۰ فریم بر ثانیه را در صورتی که این ترکیب در آن دستگاه پشتیبانی نمی‌شود، غیرفعال کنید.

• ارائه حالت "کیفیت بالا" قابل اعتماد: دوربین را با فهرستی اولویت‌بندی‌شده از ویژگی‌های مورد نظر پیکربندی کنید. CameraX به‌طور خودکار بهترین ترکیب پشتیبانی‌شده را برای هر دستگاه مشخص پیدا و فعال می‌کند و نتیجه‌ای عالی را بدون منطق پیچیده و مختص دستگاه تضمین می‌کند.
• جلوگیری از خرابی‌های جلسه دوربین: با تأیید پشتیبانی از قبل، از تلاش دوربین برای پیکربندی یک ترکیب پشتیبانی نشده جلوگیری می‌کنید، منبع مشترک خرابی‌ها را از بین می‌برید و یک تجربه کاربری روان ارائه می‌دهید.

نحوه کار: اجزای اصلی

این API جدید حول محور ویژگی‌های کلیدی اضافه شده به SessionConfig و CameraInfo متمرکز شده است.

1. GroupableFeature : This API introduces a set of predefined groupable features, such as HDR_HLG10 , FPS_60 , PREVIEW_STABILIZATION , and IMAGE_ULTRA_HDR . Due to computational limitations, only a specific set of features can be grouped with the high degree of reliability this API provides. We are actively working to expand this list and will introduce support for more features in future releases.
   
2. پارامترهای جدید SessionConfig : این کلاس که برای شروع یک جلسه دوربین استفاده می‌شود، اکنون دو پارامتر جدید را می‌پذیرد:
   • requiredFeatureGroup : Use this for features that must be supported for the configuration to succeed - ideal for features that a user explicitly enables, such as toggling an 'HDR' switch. To ensure a deterministic and consistent experience, the bindToLifecycle call will throw an IllegalArgumentException if the requested combination is not supported, rather than silently ignoring a feature request. The CameraInfo#isFeatureGroupSupported API (details below) should be used to query this result beforehand.
   • preferredFeatureGroup : از این برای ویژگی‌هایی که مطلوب اما اختیاری هستند استفاده کنید، به عنوان مثال وقتی می‌خواهید حالت پیش‌فرض "کیفیت بالا" را پیاده‌سازی کنید. شما لیستی از ویژگی‌های مورد نظر خود را که بر اساس اولویت‌هایتان مرتب شده‌اند ، ارائه می‌دهید و CameraX به طور خودکار ترکیب با بالاترین اولویتی را که دستگاه پشتیبانی می‌کند، فعال می‌کند.
3. CameraInfo#isFeatureGroupSupported() : This is the core query method for explicitly checking if a feature group is supported, well-suited for providing only supported feature options to users in your app UI. You pass it a SessionConfig , and it returns a boolean indicating whether the combination is supported. If you intend to bind a SessionConfig with required features, you should use this API first to ensure it is supported.

پیاده‌سازی در عمل

بیایید نگاهی به نحوه استفاده از این اجزا برای ایجاد یک تجربه بهتر با دوربین بیندازیم.

سناریو ۱: حالت کیفیت بالا با «بهترین تلاش»

اگر می‌خواهید بهترین ویژگی‌های ممکن را به طور پیش‌فرض فعال کنید، می‌توانید یک لیست اولویت‌بندی شده را به preferredFeatureGroup ارائه دهید. در این مثال، ما به CameraX می‌گوییم که HDR، سپس 60 FPS و در نهایت Preview Stabilization را در اولویت قرار دهد. CameraX پیچیدگی بررسی تمام ترکیب‌های ممکن و انتخاب بهترین موردی که دستگاه پشتیبانی می‌کند را مدیریت می‌کند.

برای مثال، اگر دستگاهی بتواند HDR و 60 FPS را با هم مدیریت کند اما نتواند از Preview Stabilization استفاده کند، CameraX دو مورد اول را فعال کرده و مورد سوم را حذف می‌کند. به این ترتیب، بدون نوشتن بررسی‌های پیچیده و مختص دستگاه، بهترین تجربه ممکن را خواهید داشت.

cameraProvider.bindToLifecycle(

    lifecycleOwner,

    cameraSelector,

    SessionConfig(

        useCases = listOf(preview, videoCapture),

        // The order of features in this list determines their priority. 

        // CameraX will enable the best-supported combination based on these

        // priorities: HDR_HLG10 > FPS_60 > Preview Stabilization.  

        preferredFeatureGroup =

           listOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION),

    ).apply {

        // (Optional) Get a callback with the enabled features

        // to update your UI. 

        setFeatureSelectionListener { selectedFeatures ->

            updateUiIndicators(selectedFeatures)

        }

    }

)

برای این قطعه کد، CameraX تلاش می‌کند تا ترکیب‌های ویژگی را به ترتیب اولویت زیر فعال کند و اولین موردی را که دستگاه به طور کامل پشتیبانی می‌کند، انتخاب می‌کند:

1. HDR + 60 فریم بر ثانیه + تثبیت‌کننده پیش‌نمایش
2. HDR + 60 فریم بر ثانیه
3. HDR + تثبیت‌کننده پیش‌نمایش
4. اچ‌دی‌آر
5. ۶۰ فریم بر ثانیه + تثبیت‌کننده پیش‌نمایش
6. ۶۰ فریم بر ثانیه
7. پیش‌نمایش تثبیت‌کننده
8. هیچ یک از ویژگی‌های فوق

سناریو ۲: ساخت یک رابط کاربری واکنش‌گرا

برای ایجاد یک رابط کاربری که به انتخاب‌های کاربر پاسخ می‌دهد و از انتخاب ترکیبی از ویژگی‌های پشتیبانی نشده توسط کاربران جلوگیری می‌کند، می‌توانید مستقیماً درخواست پشتیبانی کنید. تابع زیر بررسی می‌کند که کدام ویژگی‌ها با انتخاب‌های فعلی کاربر ناسازگار هستند و به شما امکان می‌دهد عناصر رابط کاربری مربوطه را غیرفعال کنید.

/**

 * Returns a list of features that are NOT supported in combination

 * with the currently selected features.

 */

fun getUnsupportedFeatures(

    currentFeatures: Set<GroupableFeature>

): Set<GroupableFeature> {

    val unsupportedFeatures = mutableSetOf<GroupableFeature>()

    val appFeatureOptions = setOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION)


    // Iterate over every available feature option in your app. 

    appFeatureOptions.forEach { featureOption ->

        // Skip features the user has already selected. 

        if (currentFeatures.contains(featureOption)) return@forEach


        // Check if adding this new feature is supported. 

        val isSupported = cameraInfo.isFeatureGroupSupported(

            SessionConfig(

                useCases = useCases,

                // Check the new feature on top of existing ones.

                requiredFeatureGroup = currentFeatures + featureOption

            )

        )


        if (!isSupported) {

            unsupportedFeatures.add(featureOption)

        }

    }


    return unsupportedFeatures

}

سپس می‌توانید این منطق را به ViewModel یا کنترلر UI خود متصل کنید تا به ورودی کاربر واکنش نشان دهد و دوربین را با پیکربندی تضمین‌شده برای کار، دوباره متصل کند.

// Invoked when user turns some feature on/off.

fun onFeatureChange(currentFeatures: Set<GroupableFeature>) {

    // Identify features that are unsupported with the current selection.

    val unsupportedFeatures = getUnsupportedFeatures(currentFeatures)



    // Update app UI so that users can't enable them.

    updateDisabledFeatures(unsupportedFeatures)



    // Since the UI now only allows selecting supported feature combinations, 

    // `currentFeatures` is always valid. This allows setting

    // `requiredFeatureGroup` directly, without needing to re-check for

    // support or set a feature selection listener.  

    cameraProvider.bindToLifecycle(

        lifecycleOwner,

        cameraSelector,

        SessionConfig(

            useCases = listOf(preview, videoCapture),

            requiredFeatureGroup = currentFeatures,

        )

    )

}

برای مشاهده این مفاهیم در یک برنامه کاربردی، می‌توانید برنامه آزمایشی داخلی ما را بررسی کنید. این برنامه، پیاده‌سازی کاملی از هر دو سناریوی «بهترین تلاش» و «رابط کاربری واکنشی» که در بالا مورد بحث قرار گرفت را ارائه می‌دهد.

لطفاً توجه داشته باشید: این یک برنامه آزمایشی است و یک نمونه پشتیبانی‌شده رسمی نیست. اگرچه مرجع بسیار خوبی برای API گروه ویژگی‌ها است، اما برای استفاده در محیط عملیاتی بهینه‌سازی نشده است.

همین امروز شروع کنید

API گروه ویژگی‌ها ابهام کار با قابلیت‌های پیشرفته دوربین را از بین می‌برد. با ارائه یک روش قطعی برای جستجوی پشتیبانی از ویژگی‌ها، می‌توانید با اطمینان خاطر برنامه‌های دوربین قدرتمندتر و قابل اعتمادتری بسازید.

این API به صورت آزمایشی در CameraX 1.5 موجود است و قرار است در نسخه 1.6 کاملاً پایدار شود و پشتیبانی و بهبودهای بیشتری در راه است.

برای کسب اطلاعات بیشتر، مستندات رسمی را بررسی کنید. ما بی‌صبرانه منتظریم ببینیم شما چه چیزی ایجاد می‌کنید و مشتاقانه منتظر بازخورد شما هستیم. لطفاً نظرات خود را به اشتراک بگذارید و هرگونه مشکل را از طریق کانال‌های زیر گزارش دهید:

• گروه بحث توسعه‌دهندگان CameraX
• اشکال را اینجا ثبت کنید