تنفيذ معاينة

عند إضافة معاينة إلى تطبيقك، استخدِم PreviewView، وهو View يمكن اقتصاصه وتغيير حجمه وتدويره ليتم عرضه بشكل صحيح.

يتم بث معاينة الصورة على سطح داخل PreviewView عندما تصبح الكاميرا نشطة.

استخدام PreviewView

يتضمن تنفيذ معاينة لـ CameraX باستخدام PreviewView الخطوات التالية، والتي يتم تناولها في الأقسام اللاحقة:

1. يمكنك ضبط CameraXConfig.Provider اختياريًا.
2. أضِف PreviewView إلى التنسيق.
3. طلب ProcessCameraProvider
4. عند إنشاء View، ابحث عن ProcessCameraProvider.
5. اختَر كاميرا واربط دورة الحياة وحالات الاستخدام.

هناك بعض القيود على استخدام "PreviewView". عند استخدام PreviewView، لا يمكنك إجراء أي مما يلي:

• أنشئ SurfaceTexture لضبطه على TextureView وPreview.SurfaceProvider.
• استرِدّ SurfaceTexture من TextureView واضبطه على Preview.SurfaceProvider.
• احصل على Surface من SurfaceView واضبطه على Preview.SurfaceProvider.

في حال حدوث أي من هذه الحالات، يتوقف Preview عن بث الإطارات إلى PreviewView.

إضافة PreviewView إلى التنسيق

يعرض النموذج التالي PreviewView في تنسيق:

<FrameLayout
    android:id="@+id/container">
        <androidx.camera.view.PreviewView
            android:id="@+id/previewView" />
</FrameLayout>

طلب CameraProvider

يوضّح الرمز التالي كيفية طلب CameraProvider:

// import androidx.camera.lifecycle.ProcessCameraProvider
// import com.google.common.util.concurrent.ListenableFuture

class MainActivity : ComponentActivity() {
    private lateinit var cameraProviderFuture: ListenableFuture<ProcessCameraProvider>
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        cameraProviderFuture = ProcessCameraProvider.getInstance(this)
    }
}
Preview.kt

التحقّق من توفّر CameraProvider

بعد طلب CameraProvider، تأكَّد من نجاح عملية الإعداد عند إنشاء العرض. يوضّح الرمز التالي كيفية إجراء ذلك:

cameraProviderFuture.addListener(
    Runnable {
        val cameraProvider = cameraProviderFuture.get()
        bindPreview(cameraProvider)
    },
    ContextCompat.getMainExecutor(this)
)
Preview.kt

للاطّلاع على مثال على دالة bindPreview المستخدَمة في هذا النموذج، يمكنك مراجعة الرمز البرمجي المقدَّم في القسم التالي.

اختيار كاميرا وربط دورة الحياة وحالات الاستخدام

بعد إنشاء CameraProvider وتأكيده، اتّبِع الخطوات التالية:

1. أنشئ Preview.
2. حدِّد خيار الكاميرا LensFacing المطلوب.
3. اربط الكاميرا المحدّدة وأي حالات استخدام بدورة الحياة.
4. اربط Preview بـ PreviewView.

يوضّح الرمز التالي مثالاً على ذلك:

fun bindPreview(cameraProvider: ProcessCameraProvider) {
    var preview: Preview = Preview.Builder()
        .build()

    var cameraSelector: CameraSelector = CameraSelector.Builder()
        .requireLensFacing(CameraSelector.LENS_FACING_BACK)
        .build()

    preview.setSurfaceProvider(previewView.getSurfaceProvider())

    var camera = cameraProvider.bindToLifecycle(this as LifecycleOwner, cameraSelector, preview)
}
Preview.kt

يُرجى العِلم أنّ bindToLifecycle() يعرض عنصر Camera. لمزيد من المعلومات حول التحكّم في مخرجات الكاميرا، مثل التكبير/التصغير والتعرّض للضوء، يُرجى الاطّلاع على مخرجات الكاميرا.

لقد انتهيت الآن من تنفيذ معاينة الكاميرا. أنشئ تطبيقك وتأكد من ظهور المعاينة في تطبيقك وتعمل على النحو الذي تريده.

عناصر تحكّم إضافية في PreviewView

توفّر واجهة CameraX PreviewView بعض واجهات برمجة التطبيقات الإضافية لضبط سمات مثل:

• وضع التنفيذ لعرض أحداث البث المباشر للمعاينة
• نوع المقياس لصورة المعاينة

وضع التنفيذ

يمكن لـ "PreviewView" استخدام أحد الأوضاع التالية لعرض بث معاينة على الهدف "View":

• PERFORMANCE هو الوضع التلقائي. يستخدم PreviewView SurfaceView لعرض بث الفيديو، ولكنه يعود إلى TextureView في حالات معيّنة. يحتوي SurfaceView على سطح رسم مخصّص، والذي من المرجّح أن يتم تنفيذه باستخدام تراكب الأجهزة من خلال مُركِّب الأجهزة الداخلي، خاصةً في حال عدم توفّر عناصر في واجهة المستخدم أخرى (مثل الأزرار) أعلى فيديو المعاينة. من خلال العرض باستخدام تراكب الأجهزة، تتجنّب إطارات الفيديو مسار وحدة معالجة الرسومات، ما قد يقلّل من استهلاك الطاقة في المنصة ووقت الاستجابة.

• COMPATIBLE في هذا الوضع، يستخدم PreviewView TextureView، والذي على عكس SurfaceView، لا يحتوي على سطح رسم مخصّص. نتيجةً لذلك، يتم عرض الفيديو مع المزج ليتمكّن من الظهور. خلال هذه الخطوة الإضافية، يمكن للتطبيق إجراء معالجة إضافية، مثل تغيير حجم الفيديوهات وتدويرها بدون قيود.

استخدِم PreviewView.setImplementationMode() لاختيار وضع التنفيذ المناسب لتطبيقك. إذا لم يكن وضع PERFORMANCE التلقائي مناسبًا لتطبيقك، توضّح عينة التعليمات البرمجية التالية كيفية ضبط وضع COMPATIBLE:

// viewFinder is a PreviewView instance.
viewFinder.implementationMode = PreviewView.ImplementationMode.COMPATIBLE
Preview.kt

نوع المقياس

عندما تختلف درجة دقة الفيديو في النسخة الحصرية عن أبعاد هدفك PreviewView، يجب أن يتلاءم محتوى الفيديو مع العرض إما من خلال الاقتصاص أو إضافة أشرطة سوداء (مع الحفاظ على نسبة العرض إلى الارتفاع الأصلية). توفّر PreviewView ScaleTypes التالية لهذا الغرض:

• FIT_CENTER وFIT_START وFIT_END لإضافة أشرطة سوداء. يتم تغيير حجم محتوى الفيديو بالكامل (إما للأعلى أو للأسفل) إلى أقصى حجم ممكن يمكن عرضه في PreviewView المستهدف. ومع ذلك، على الرغم من أن إطار الفيديو الكامل مرئي، فقد يكون جزء من الشاشة فارغًا. استنادًا إلى نوع المقياس الذي تختاره من بين هذه الأنواع الثلاثة، تتم محاذاة إطار الفيديو مع وسط العرض المستهدف أو بدايته أو نهايته.

• FILL_CENTER وFILL_START وFILL_END للاقتصاص إذا لم يتطابق الفيديو مع نسبة العرض إلى الارتفاع PreviewView، سيظهر جزء فقط من المحتوى، ولكن سيملأ الفيديو كامل مساحة PreviewView.

نوع المقياس التلقائي الذي تستخدمه واجهة CameraX هو FILL_CENTER. استخدِم PreviewView.setScaleType() لضبط نوع المقياس الأكثر ملاءمةً لتطبيقك. تضبط عينة التعليمات البرمجية التالية نوع المقياس FIT_CENTER:

// viewFinder is a PreviewView instance.
viewFinder.scaleType = PreviewView.ScaleType.FIT_CENTER
Preview.kt

تتألف عملية عرض فيديو من الخطوات التالية:

1. تغيير حجم الفيديو:
   • بالنسبة إلى أنواع المقاييس FIT_*، يمكنك تغيير حجم الفيديو باستخدام min(dst.width/src.width, dst.height/src.height).
   • بالنسبة إلى أنواع المقاييس FILL_*، يمكنك تغيير حجم الفيديو باستخدام max(dst.width/src.width, dst.height/src.height).
2. محاذاة الفيديو الذي تم تغيير حجمه مع الوجهة PreviewView:
   • بالنسبة إلى FIT_CENTER/FILL_CENTER، يجب محاذاة الفيديو الذي تم تغيير حجمه والوجهة PreviewView إلى الوسط.
   • بالنسبة إلى FIT_START/FILL_START، يجب محاذاة الفيديو الذي تم تغيير حجمه والوجهة PreviewView بالنسبة إلى الزاوية العلوية اليمنى لكل منهما.
   • بالنسبة إلى FIT_END/FILL_END، يجب محاذاة الفيديو الذي تم تغيير حجمه والوجهة PreviewView بالنسبة إلى الزاوية السفلية اليسرى لكل منهما.

على سبيل المثال، إليك فيديو مصدر بدقة 640x480 ووجهة بدقة 1920x1080 PreviewView:

تعرض الصورة التالية عملية تغيير حجم FIT_START / FIT_CENTER / FIT_END:

إليك كيفية سير العملية:

1. يتم تغيير حجم إطار الفيديو (مع الحفاظ على نسبة العرض إلى الارتفاع الأصلية) باستخدام min(1920/640, 1080/480) = 2.25 للحصول على إطار فيديو متوسط بدقة 1440x1080.
2. محاذاة إطار الفيديو بدقة 1440x1080 مع PreviewView بدقة 1920x1080
   • بالنسبة إلى "FIT_CENTER"، يجب محاذاة إطار الفيديو مع وسط نافذة "PreviewView". أعمدة البداية والنهاية التي يبلغ حجمها 240 بكسل في PreviewView فارغة.
   • بالنسبة إلى FIT_START، يجب محاذاة إطار الفيديو مع بداية (الزاوية العلوية اليمنى) نافذة PreviewView. أعمدة البكسل الـ 480 الأخيرة في "PreviewView" فارغة.
   • بالنسبة إلى FIT_END، يجب محاذاة إطار الفيديو مع نهاية (الزاوية السفلية اليسرى) نافذة PreviewView. أول 480 عمود بكسل في PreviewView فارغة.

تعرض الصورة التالية عملية تغيير حجم FILL_START / FILL_CENTER / FILL_END:

إليك كيفية سير العملية:

1. يمكنك تغيير حجم إطار الفيديو باستخدام max(1920/640, 1080/480) = 3 للحصول على إطار فيديو متوسط بدقة 1920x1440 (وهو أكبر من حجم PreviewView).
2. اقتصاص إطار الفيديو بدقة 1920x1440 ليناسب نافذة PreviewView بدقة 1920x1080
   • بالنسبة إلى FILL_CENTER، يمكنك اقتصاص 1920x1080 من وسط الفيديو الذي تم تغيير حجمه إلى 1920x1440. لا تظهر الأسطر الـ 180 العلوية والسفلية من الفيديو.
   • بالنسبة إلى FILL_START، يجب اقتصاص 1920x1080 من بداية الفيديو الذي تم تغيير حجمه إلى 1920x1440. لا تظهر آخر 360 سطرًا من الفيديو.
   • بالنسبة إلى FILL_END، يمكنك اقتصاص 1920x1080 من نهاية الفيديو الذي تم تغيير حجمه إلى 1920x1440. لا تظهر أول 360 سطرًا من الفيديو.

مراجع إضافية

لمزيد من المعلومات حول CameraX، يمكنك الاطّلاع على المراجع الإضافية التالية.

درس تطبيقي حول الترميز

بدء استخدام CameraX

عيّنة تعليمات برمجية

نماذج تطبيقات CameraX