أنواع مساحات العرض

توضّح هذه الصفحة الأنواع المختلفة من مساحات العرض التي يمكن استخدامها لتشغيل الفيديو باستخدام Media3، وكيفية اختيار النوع المناسب لحالة الاستخدام. لمزيد من المعلومات حول عناصر Surface في Android، يمكنك الاطّلاع على مستندات الرسومات هذه.

ضبط مساحة العرض

تتوفّر أربع نقاط دخول للوصلة Player من أجل ربط ناتج الفيديو ببعض Surface:

• void setVideoSurface(@Nullable Surface surface)
• void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void setVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void setVideoTextureView(@Nullable TextureView textureView)

تتوفّر أيضًا طرق مختلفة لمحو السجلّ:

• void clearVideoSurface()
• void clearVideoSurface(@Nullable Surface surface)
• void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void clearVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void clearVideoTextureView(@Nullable TextureView textureView)

اختَر نوع مساحة عرض لـ PlayerView

تتيح لك السمة surface_type الخاصة بالعنصر PlayerView ضبط نوع مساحة العرض المستخدَمة لتشغيل الفيديو. القيم المسموح بها هي:

• surface_view (SurfaceView)
• texture_view (TextureView)
• ‫spherical_gl_surface_view (SphericalGLSurfaceView) - لتشغيل فيديوهات كروية
• ‫video_decoder_gl_surface_view (VideoDecoderGLSurfaceView): عرض الفيديو باستخدام أدوات العرض الإضافية
• ‫none: مخصّص لتشغيل الصوت فقط ويجب استخدامه لتجنُّب إنشاء مساحة عرض لأنّ ذلك قد يكون مكلفًا.

إذا كان العرض مخصّصًا لتشغيل الفيديو العادي، يجب استخدام surface_view أو texture_view. تتفوّق SurfaceView على TextureView في تشغيل الفيديوهات من خلال المزايا التالية:

• انخفاض كبير في استهلاك الطاقة على العديد من الأجهزة
• توقيت أكثر دقة للّقطات، ما يؤدي إلى تشغيل الفيديو بسلاسة أكبر
• إمكانية إخراج فيديوهات HDR بجودة أعلى على الأجهزة المؤهَّلة
• إمكانية إخراج المحتوى المحمي بموجب إدارة الحقوق الرقمية بشكل آمن
• إمكانية عرض محتوى الفيديو بكامل دقة الشاشة على أجهزة Android TV التي تزيد من دقة طبقة واجهة المستخدم

لذلك، يجب تفضيل SurfaceView على TextureView كلما أمكن ذلك. يجب استخدام TextureView فقط إذا لم يلبي SurfaceView احتياجاتك. أحد الأمثلة على ذلك هو الحالات التي تتطلّب عرض رسوم متحركة سلسة أو تمرير سطح الفيديو قبل الإصدار 7.0 من نظام التشغيل Android (المستوى 24 من واجهة برمجة التطبيقات)، كما هو موضّح في الملاحظات التالية. في هذه الحالة، من الأفضل استخدام TextureView فقط عندما تكون قيمة SDK_INT أقل من 24 (Android 7.0)، واستخدام SurfaceView في الحالات الأخرى.

ملاحظة: لم تتم مزامنة عرض SurfaceView بشكل صحيح مع الرسوم المتحركة للعرض إلى أن تم إصدار Android 7.0 (المستوى 24 من واجهة برمجة التطبيقات). في الإصدارات السابقة، كان عدم المزامنة بشكل سليم يؤدي إلى تأثيرات غير مرغوب فيها عند وضع SurfaceView في حاوية قابلة للتمرير أو عند تحريكها. تضمّنت التأثيرات غير المرغوب فيها تأخُّرًا طفيفًا في ظهور محتوى العرض مقارنةً بموضع ظهوره المفترض، وتحوّل العرض إلى اللون الأسود عند تحريكه. لتحقيق سلاسة في عرض الصور المتحركة أو التمرير السريع للفيديو قبل الإصدار 7.0 من نظام التشغيل Android، استخدِم TextureView بدلاً من SurfaceView.

ملاحظة: يرتبط عمر مساحة العرض الخاصة بعنصر SurfaceView بمدى ظهور العرض، بينما يرتبط عمر مساحة العرض الخاصة بعنصر TextureView بعملية ربط النافذة وفصلها. لذلك، في واجهات المستخدم التي تتضمّن ميزة التمرير وتستخدم SurfaceView، قد يستغرق بدء التشغيل وقتًا أطول لأنّ مساحة العرض تصبح متاحة بعد فترة قصيرة. بدءًا من Android 14، تستخدم PlayerView SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) لتجنُّب هذا السلوك. إذا كان تطبيقك يستخدم SurfaceView مباشرةً (بدون PlayerView)، قد تحتاج إلى تفعيل هذا الوضع. قبل الإصدار 14 من نظام التشغيل Android، كان من الممكن حلّ مشكلة إتلاف السطح من خلال ترجمة طرق العرض خارج الشاشة عند إعادة تدويرها.

ملاحظة: تعمل بعض أجهزة Android TV على تشغيل طبقة واجهة المستخدم بدقة أقل من الدقة الكاملة للشاشة، ويتم تحسينها لعرضها للمستخدم. على سبيل المثال، يمكن تشغيل طبقة واجهة المستخدم بدقة 1080p على تلفزيون Android TV مزوّد بشاشة بدقة 4K. على هذه الأجهزة، يجب استخدام SurfaceView لعرض المحتوى بكامل دقة الشاشة. يمكن الاستعلام عن الدقة الكاملة للشاشة (في وضع العرض الحالي) باستخدام Util.getCurrentDisplayModeSize. يمكن طلب دقة طبقة واجهة المستخدم باستخدام واجهة برمجة التطبيقات Display.getSize في Android.

ملاحظة: إذا كنت تستخدم PlayerView داخل AndroidView، لا يمكننا ضمان التوافق لأنّ PlayerView لم يتم تصميمه مع أخذ Compose في الاعتبار. من المشاكل الشائعة في SDK_INT == 34 هو Surface ممدود أو مقصوص أو مسرَّب لا يتطابق مع الحاوية الرئيسية (AspectRatioFrameLayout) بشكل صحيح. يمكنك تفعيل حلّ بديل لـ Compose من خلال استدعاء PlayerView.setEnableComposeSurfaceSyncWorkaround، ولكن تجدر الإشارة إلى أنّه يتسبّب في حدوث مشاكل في عمليات الانتقال المشتركة المستندة إلى XML.

اختيار نوع سطح في Compose

في Compose، يستخدم حلّ التشغيل التفاعلي العنصر المركّب AndroidView لتضمين SurfaceView وTextureView. إنّ العنصرَين القابلَين للإنشاء اللذين يتوافقان مع ذلك هما AndroidExternalSurface وAndroidEmbeddedExternalSurface من androidx.compose.foundation. ومع ذلك، توفّر فئات الوكيل واجهة برمجة تطبيقات تحدّ من إمكانية الوصول إلى طرق العرض الأساسية. وتحتاج Player إلى طرق العرض هذه للتعامل مع دورة حياة كاملة للعرض (الإنشاء وتعديلات الحجم).

في الوحدة media3-ui-compose، يمكنك العثور على عناصر ContentFrame وPlayerSurface البرمجية القابلة للإنشاء التي تربط Player بـ Surface بطريقة تراعي مراحل النشاط. أنواع الأسطح في هذه الحالة هي:

• androidx.media3.ui.compose.SURFACE_TYPE_SURFACE_VIEW
• androidx.media3.ui.compose.SURFACE_TYPE_TEXTURE_VIEW

لا يوجد نوع none، لأنّ ذلك سيؤدي إلى عدم تضمين العنصر القابل للإنشاء في شجرة واجهة المستخدم Compose.