آشنایی با چرخه حیات بهبود رسانه در حالت «بیت‌مپ»

‫Media Enhancement API یک راهکار هوش مصنوعی درون‌دستگاهی با تأخیر کم و حافظ حریم خصوصی ارائه می‌دهد که از شتاب سخت‌افزاری برای ارائه بهبودهای رسانه‌ای با کیفیت بالا بدون افزایش حجم APK استفاده می‌کند. برای اطلاعات بیشتر، آشنایی با قابلیت‌های بهبود رسانه را ببینید.

حالت Bitmap ایستا (EnhancementMode.BITMAP) برای پردازش تصویر ایستا و رمزگشایی‌شده طراحی شده است.

عملکرد در حالت «بیت‌مپ» مستلزم این است که سیستم‌عامل داده‌های پیکسل فشرده‌نشده را سریال‌سازی کند و آن را از حافظه واحد پردازش مرکزی ازطریق گذرگاه سیستم به حافظه واحد پردازش گرافیکی کپی کند و قاب پردازش‌شده را ازطریق کپی معکوس برگرداند. این مدل برای اجرای تک‌فریم بهینه‌سازی شده است و با جاری‌سازی هم‌زمان ویدیو سازگار نیست.

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

  1. پیکربندی گزینه‌ها: شیء EnhancementOptions ایجاد کنید و مطمئن شوید enhancementMode روی EnhancementMode.BITMAP تنظیم شده باشد.
  2. ایجاد جلسه: از پوشاننده createSessionAsync که قبلاً تعریف کردیم برای ایجاد EnhancementSession استفاده کنید. این شیء سنگین است، بنابراین آن را فقط درصورت نیاز ایجاد کنید.
  3. پردازش تصویر: جلسه، بیت‌مپ ورودی، و گزینه‌های مدنظرتان را فراخوانی کنید.
  4. مدیریت نتیجه: تابع تعلیق درصورت موفقیت، یک Bitmap جدید و بهبودیافته برمی‌گرداند یا درصورت شکست، یک استثنا ایجاد می‌کند.
  5. رها کردن جلسه: نکته مهم این است که وقتی کارتان تمام شد، session.release() را فراخوانی کنید تا منابع GPU آزاد شوند.

‫EnhancementSession یک شیء بافت سنگین است که خط لوله حافظه GPU یا NPU پایدار را حفظ می‌کند. این API حافظه دسترسی تصادفی ویدیویی (VRAM) اختصاصی و دستگیره‌های سیستم بومی را اختصاص می‌دهد. برای جلوگیری از نشت شدید حافظه و ازکارافتادن‌های احتمالی 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)
}

اجرای خط لوله نقشه بیتی در ViewModel

برای ادغام کردن خط لوله بهبود در معماری برنامه‌تان، از ViewModel برای مدیریت چرخه حیات جلسه استفاده کنید. این رویکرد تضمین می‌کند که منابع سنگین GPU هنگام پاک شدن 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()
    }
}

بار کردن تدریجی تصاویر در شبکه‌های کُند

در شبکه‌های کند، برنامه‌تان می‌تواند به‌جای فایل با وضوح کامل، نسخه کوچک‌تر و فشرده‌تر تصویر را بارگیری کند. سپس برنامه‌تان می‌تواند از حالت «بیت‌مپ» برای ارتقای مقیاس و رفع تاری تصویر در دستگاه استفاده کند. تصویر بهبودیافته جایگزین بارگیری با وضوح کامل می‌شود، بنابراین کاربران تصویر واضح‌تری را بدون انتقال فایل بزرگ می‌بینند.

زمان استفاده از این الگو

این الگو زمانی مناسب است که همه موارد زیر درست باشد:

  • دستگاه پشتیبانی می‌شود: isDeviceSupportedAsync() مقدار true را برمی‌گرداند. این میانای برنامه‌سازی کاربردی به Android نسخه ۱۱ (سطح میانای برنامه‌سازی کاربردی ۳۰) یا بالاتر نیاز دارد و برای دستگاه‌های رده ممتاز بهینه‌سازی شده است.
  • تصویر بزرگ‌تر از اندازه بارگیری‌شده‌اش نمایش داده می‌شود: برای مثال، تصویر کوچکی که به‌صورت تمام‌صفحه نشان داده می‌شود. اگر تصویر در اندازه ریزعکس باقی بماند، مقیاس‌افزایی مزیت قابل‌مشاهده کمی اضافه می‌کند.
  • واحد بهبود قبلاً نصب شده است: isModuleInstalledAsync() true را برمی‌گرداند. نصب واحد، فایل‌های مدل را ازطریق شبکه بارگیری می‌کند. اگر کاربر ازقبل اتصال کندی دارد، نصب را شروع نکنید.

اگر هرکدام از این شرایط برآورده نشد، تصویر بارگیری‌شده را بدون بهبود نمایش دهید.

پیاده‌سازی الگو

الگو به‌صورت زیر عمل می‌کند:

  1. نمایش تصویر با وضوح پایین: تصویر کوچک را به‌محض بارگیری شدن پرداز کنید.
  2. بهبود در پس‌زمینه: اگر موتور بهبود آماده است، تصویر را در حالت «بیت‌مپ» با فعال کردن مقیاس‌افزایی و رفع تاری پردازش کنید.
  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 از ابعاد ورودی ثابت استفاده می‌کند. تصاویر با وضوح پایین را در یک اندازه ثابت درخواست کنید تا برنامه‌تان بتواند از یک جلسه واحد در تصاویر استفاده مجدد کند.
  • ذخیره کردن نتیجه بهبودیافته در حافظه نهان: بیت‌مپ بهبودیافته را در حافظه نهان تصویر ذخیره کنید تا برنامه‌تان دوباره همان تصویر را پردازش نکند. اگر فراپیمایی را فعال کنید، بیت‌مپ بهبودیافته بزرگ‌تر از بیت‌مپ ورودی است. اندازه حافظه نهان را برای نگاشت‌های بیتی بزرگ‌تر تنظیم کنید.