فهم دورة حياة تحسين الوسائط في "وضع الصورة النقطية"

توفّر واجهة Media Enhancement API حلاً للذكاء الاصطناعي على الجهاز فقط، يتميز بوقت استجابة منخفض ويحافظ على الخصوصية، ويستفيد من تسريع الأجهزة لتقديم تحسينات عالية الجودة للوسائط بدون زيادة حجم حزمة APK. لمزيد من المعلومات، يُرجى الاطّلاع على التعرّف على إمكانات تحسين الوسائط.

تم تصميم وضع "الصورة النقطية الثابتة" (EnhancementMode.BITMAP) لمعالجة الصور الثابتة التي تم فك ترميزها.

يتطلّب التشغيل في وضع "صورة نقطية" من نظام التشغيل تسلسل بيانات وحدات البكسل غير المضغوطة ونسخها من ذاكرة وحدة المعالجة المركزية (CPU) عبر ناقل النظام إلى ذاكرة وحدة معالجة الرسومات (GPU)، مع عرض الإطار الذي تمت معالجته من خلال نسخة عكسية. تم تحسينه لتنفيذ الإطارات الفردية، وهو غير متوافق مع بث الفيديو في الوقت الفعلي.

يتضمن سير العمل هذا إنشاء جلسة ومعالجة صورة نقطية واحدة بها، ثم التعامل مع النتيجة. تتناول أمثلة الرموز من الأقسام السابقة حالة الاستخدام هذه بالتفصيل.

  1. ضبط الخيارات: أنشئ عنصر EnhancementOptions، مع التأكّد من ضبط enhancementMode على EnhancementMode.BITMAP.
  2. إنشاء جلسة: استخدِم برنامج تضمين createSessionAsync الذي حدّدناه سابقًا لإنشاء EnhancementSession. هذا كائن ثقيل، لذا أنشئه فقط عند الحاجة.
  3. معالجة الصورة: يمكنك استدعاء الجلسة وصورة الإدخال النقطية والخيارات التي تريدها.
  4. التعامل مع النتيجة: تُرجع دالة التعليق صورة نقطية جديدة ومحسّنة في حال النجاح أو تُظهر استثناءً في حال الفشل.
  5. إنهاء الجلسة: من المهم استدعاء session.release() عند الانتهاء من استخدام الموارد لإخلاء موارد وحدة معالجة الرسومات.

‫EnhancementSession هو عنصر سياق ثقيل يحافظ على مسار ذاكرة GPU أو NPU ثابت. ويخصّص ذاكرة وصول عشوائي (RAM) مخصّصة للفيديو ومؤشرات النظام الأصلية. لتجنُّب حدوث تسرُّب كبير في الذاكرة وأعطال محتملة في "OutOfMemoryError"، يجب الالتزام بمبادئ مراحل النشاط التالية:

  1. إنشاء مثيل كسول: لا تنشئ جلسة حتى يبدأ المستخدم إجراء تحسين.
  2. إعادة الاستخدام الاستراتيجية: يمكنك الاحتفاظ بنسخة واحدة من الجلسة وإعادة استخدامها عند معالجة صور متعددة بإعدادات متطابقة (الأبعاد والخيارات المفعَّلة).
  3. Prompt teardown: Invoke session.release() immediately when visual tasks terminate to free shared hardware resources.

بدء تشغيل محرّك التحسين

تنسّق هذه الطريقة عملية تحقّق من خطوتين. ويتحقّق من توافق أجهزة الجهاز مع التسريع، ثم يضمن توفّر وحدات تعلُّم الآلة المطلوبة.

يؤدي تنفيذ هذه الخطوة كشرط أساسي إلى منع حدوث أخطاء في الإعداد أثناء التشغيل من خلال التحقّق من الإمكانات قبل أن يحاول تطبيقك معالجة الوسائط.

class MediaSetupViewModel(application: Application) : AndroidViewModel(application) {
    private val enhancementClient = Enhancement.getClient(application)
    fun initializeEnhancementEngine() {
        viewModelScope.launch {
            try {
                // 1. Verify hardware capability
                val isSupported = enhancementClient.isDeviceSupportedAsync()
                if (!isSupported) {
                    notifyUiDeviceIncompatible()
                    return@launch
                }
                // 2. Verify and download the Google Play services ML modules
                val isInstalled = enhancementClient.isModuleInstalledAsync()
                if (!isInstalled) {
                    notifyUiDownloadingModels()
                    enhancementClient.installModule().await()
                }
                notifyUiEngineReady()
            } catch (e: Exception) {

                // Handle potential errors during session creation or image processing.
                handleInitializationError(e)
            }
        }
    }
}

إنشاء برامج تضمين لعمليات الجلسات والصور النقطية

استخدِم برامج تضمين الكوروتين في Kotlin لتحويل عمليات الاستدعاء المستندة إلى المهام إلى دوال تعليق عادية، ما يتيح تنفيذًا أكثر تنظيمًا وتسلسلاً.

// Wraps the task-based createSession callback into a suspending function.
suspend fun EnhancementClient.createSessionAsync(
    options: EnhancementOptions,
    executor: Executor
): EnhancementSession = withContext(Dispatchers.Main) {
    suspendCancellableCoroutine { continuation ->

        // EnhancementSessionCallback handles session success or failure.
        val callback = object : EnhancementSessionCallback {
            override fun onSessionCreated(session: EnhancementSession) {
                continuation.resume(session)
            }
            override fun onSessionCreationFailed(status: Status) {
                continuation.resumeWithException(
                    Exception("Session creation failed: ${status.statusMessage} (${status.statusCode})")
                )
            }
            override fun onSessionDestroyed() {}
            override fun onSessionDisconnected(status: Status) {}
        }

        // Handles errors during the initial request trigger.
        this@createSessionAsync.createSession(options, callback).addOnFailureListener(executor) { e ->
            if (continuation.isActive) {
                continuation.resumeWithException(e)
            }
        }
    }
}

// Wraps this process in a suspending function for cleaner execution.
suspend fun EnhancementSession.processBitmapAsync(
    bitmap: Bitmap,
    options: EnhancementOptions
): Bitmap = suspendCancellableCoroutine { continuation ->

    // EnhancementCallback returns the processed bitmap or an error code.
    val callback = object : EnhancementCallback {
        override fun onBitmapProcessed(enhancedBitmap: Bitmap) {
            continuation.resume(enhancedBitmap)
        }
        override fun onError(statusCode: Int) {
            continuation.resumeWithException(
                Exception("Bitmap processing failed with status code: $statusCode")
            )
        }
        override fun onSurfaceProcessed(timestamp: Long) {}
    }
    this.process(bitmap, options, callback)
}

تنفيذ مسار bitmap في ViewModel

لدمج مسار التحسين في بنية تطبيقك، استخدِم ViewModel لإدارة مراحل نشاط الجلسة. يضمن هذا النهج تحرير موارد وحدة معالجة الرسومات الثقيلة عند مسح ViewModel.

// Define a data class to hold image information.
data class ImageInfo(val bitmap: Bitmap)
// Define a UI state class to hold loading status, errors, and enhanced image.
data class EnhancementUiState(
    val isLoading: Boolean = false,
    val enhancementError: String? = null,
    val enhancedImage: ImageInfo? = null
)

class EnhancementViewModel(application: Application) : AndroidViewModel(application) {

    // Backing field for UI state, initialized with default values.
    private val _uiState = MutableStateFlow(EnhancementUiState())
    // Publicly exposed UI state flow for observation.
    val uiState: StateFlow<EnhancementUiState> = _uiState.asStateFlow()

// Initialize client to interact with the Media Enhancement service.
    private val enhancementClient: EnhancementClient = Enhancement.getClient(application)

// Single-thread executor for processing background enhancement tasks.
    private val enhancementExecutor = Executors.newSingleThreadExecutor()

// Track session state to enable reuse across multiple processing calls.
    private var enhancementSession: EnhancementSession? = null
    private var sessionOptions: EnhancementOptions? = null

// Primary function to trigger the enhancement workflow for a provided bitmap.
    fun enhanceImage(bitmap: Bitmap) {
        viewModelScope.launch(Dispatchers.IO) {
            _uiState.update { it.copy(isLoading = true, enhancementError = null) }
            try {
                // Define enhancement options (for example, enable upscale, tonemapping) based
                // on bitmap dimensions.
                val options = EnhancementOptions(
                    bitmap.width,
                    bitmap.height,
                    EnhancementMode.BITMAP,
                    isTonemappingEnabled = true,
                    isDeblurAndDenoisePhotoEnabled = true,
                    isUpscalePhotoEnabled = false,
                )
                // 1. Establish the session lazily on demand. A session is configured for
                // specific input dimensions, so replace it when the bitmap size changes.
                if (enhancementSession == null ||
                    sessionOptions?.width != options.width ||
                    sessionOptions?.height != options.height
                ) {
                    enhancementSession?.release()
                    enhancementSession = null
                    enhancementSession = enhancementClient.createSessionAsync(options, enhancementExecutor)
                    sessionOptions = options
                }
                val session = enhancementSession ?: throw IllegalStateException("Session unavailable.")
                // 2. Dispatch image through the neural pipeline
                val enhancedBitmap = session.processBitmapAsync(bitmap, options)
                // 3. Render output to UI
                _uiState.update {
                    it.copy(enhancedImage = ImageInfo(bitmap = enhancedBitmap))
                }
            } catch (e: Exception) {
                _uiState.update { it.copy(enhancementError = e.message) }
            } finally {

// Ensure loading state is reset regardless of the outcome.
                _uiState.update { it.copy(isLoading = false) }
            }
        }
    }
    override fun onCleared() {
        // 4. Critical: Release native GPU hardware resources
        enhancementSession?.release()
        enhancementSession = null
        enhancementExecutor.shutdown()
        super.onCleared()
    }
}

تحميل الصور تدريجيًا على الشبكات البطيئة

على الشبكات البطيئة، يمكن لتطبيقك تنزيل نسخة أصغر حجمًا وأكثر ضغطًا من الصورة بدلاً من الملف ذي الدقة الكاملة. يمكن لتطبيقك بعد ذلك استخدام وضع Bitmap لزيادة دقة الصورة وإزالة التمويه منها على الجهاز. تحل الصورة المحسّنة محل الصورة الكاملة الدقة التي يتم تنزيلها، وبالتالي يرى المستخدمون صورة أكثر وضوحًا بدون الحاجة إلى نقل ملف كبير.

حالات استخدام هذا النمط

يكون هذا النمط مناسبًا في الحالات التالية:

  • الجهاز متوافق: تعرض السمة isDeviceSupportedAsync() القيمة true. تتطلّب واجهة برمجة التطبيقات هذه الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات) أو إصدارًا أحدث، وهي محسَّنة للأجهزة من الفئة المميّزة.
  • يتم عرض الصورة بحجم أكبر من حجمها الذي تم تنزيلها به: على سبيل المثال، صورة صغيرة يتم عرضها بملء الشاشة. إذا بقيت الصورة بحجم الصورة المصغّرة، لن يضيف تحسين جودة الصورة أي فائدة مرئية.
  • وحدة التحسين مثبَّتة حاليًا: تعرض الدالة isModuleInstalledAsync() القيمة true. يؤدي تثبيت الوحدة إلى تنزيل ملفات النماذج عبر الشبكة. إذا كان المستخدم متصلاً بشبكة بطيئة، لا تبدأ عملية التثبيت.

إذا لم يتم استيفاء أي من هذه الشروط، يتم عرض الصورة التي تم تنزيلها بدون تحسين.

تنفيذ النمط

يعمل النمط على النحو التالي:

  1. عرض الصورة ذات الدقة المنخفضة: يمكنك عرض الصورة الصغيرة فور تنزيلها.
  2. التحسين في الخلفية: إذا كان محرّك التحسين جاهزًا، تتم معالجة الصورة في وضع "الصورة النقطية" (Bitmap) مع تفعيل ميزتَي "زيادة الدقة" (Upscaling) و"إزالة التمويه" (Deblurring).
  3. استبدال النتيجة: استبدِل الصورة المعروضة بالصورة النقطية المحسّنة. يؤدي التلاشي المتقاطع القصير إلى جعل التبديل أقل وضوحًا.

تعالج فئة ProgressiveImageEnhancer التالية صورة واحدة في كل مرة وتعيد استخدام جلسة واحدة للصور ذات الحجم نفسه. إذا تعذّر التحسين، ستعرض دالة enhance() القيمة null لكي يستمر تطبيقك في عرض الصورة ذات الدقة المنخفضة. تستخدم الفئة برامج تضمين createSessionAsync وprocessBitmapAsync المحدّدة في إنشاء برامج تضمين لعمليات الجلسات والصور النقطية.

ثبِّت الوحدة مسبقًا، كما هو موضّح في بدء تشغيل محرّك التحسين. إذا عاد "isDeviceSupportedAsync()" و"isModuleInstalledAsync()" إلى "true"، اتصل بـ "enhance()".

class ProgressiveImageEnhancer(
    private val enhancementClient: EnhancementClient,
    private val executor: Executor,
) {
    // Callers can request enhancements concurrently, but they all share one
    // session, so process one image at a time.
    private val mutex = Mutex()
    private var session: EnhancementSession? = null
    private var sessionOptions: EnhancementOptions? = null

    // Enhancement is optional for this pattern, so return null instead of
    // throwing. The caller can keep the low-resolution image without extra
    // error handling.
    suspend fun enhance(lowResBitmap: Bitmap): Bitmap? = mutex.withLock {
        val options = EnhancementOptions(
            width = lowResBitmap.width,
            height = lowResBitmap.height,
            enhancementMode = EnhancementMode.BITMAP,
            isDeblurAndDenoisePhotoEnabled = true,
            isUpscalePhotoEnabled = true,
        )
        try {
            getOrCreateSession(options).processBitmapAsync(lowResBitmap, options)
        } catch (e: CancellationException) {
            // A cancelled request (for example, the user scrolled away) isn't
            // an enhancement failure, so let the caller's scope handle it.
            throw e
        } catch (e: Exception) {
            null
        }
    }

    // Sessions are expensive to create and are configured for specific input
    // dimensions, so reuse the current one until the image size changes.
    private suspend fun getOrCreateSession(options: EnhancementOptions): EnhancementSession {
        val currentSession = session
        val currentOptions = sessionOptions
        if (currentSession != null &&
            currentOptions != null &&
            currentOptions.width == options.width &&
            currentOptions.height == options.height
        ) {
            return currentSession
        }
        releaseSession()
        return enhancementClient.createSessionAsync(options, executor).also {
            session = it
            sessionOptions = options
        }
    }

    // A session holds GPU memory until it's released, so free it as soon as
    // the images it enhances are no longer on screen. Taking the lock first
    // waits for any in-progress enhancement, so a session that's still being
    // created isn't leaked.
    suspend fun release() = mutex.withLock { releaseSession() }

    private fun releaseSession() {
        session?.release()
        session = null
        sessionOptions = null
    }
}

عند استخدام هذا النمط، اتّبِع الإرشادات التالية:

  • طلب حجم متّسق: يستخدم EnhancementSession أبعاد إدخال ثابتة. اطلب صورًا منخفضة الدقة بحجم واحد متّسق لكي يتمكّن تطبيقك من إعادة استخدام جلسة واحدة في جميع الصور.
  • تخزين النتيجة المحسّنة مؤقتًا: يمكنك تخزين الصورة النقطية المحسّنة في ذاكرة التخزين المؤقت للصور حتى لا يعالج تطبيقك الصورة نفسها مرة أخرى. في حال تفعيل الترقية، تكون الصورة النقطية المحسّنة أكبر من الصورة النقطية المُدخلة. اضبط حجم ذاكرة التخزين المؤقت للصور النقطية الأكبر حجمًا.