يوفّر المكوّن الإضافي VkQuality الخاص بمحرك Unity اقتراحات بشأن وقت بدء تشغيل واجهة برمجة التطبيقات للرسومات، مثل Vulkan أو OpenGL ES، لاستخدامها في لعبتك على أجهزة معيّنة.
توصي Vkالجودة بـ Vulkan على مجموعة أجهزة أكثر تقييدًا من قائمة السماح التلقائية لمحرّك Unity. استخدِم VkQuality للاستفادة من مزايا أداء Vulkan مع قصر استخدام Vulkan على أجهزة أحدث ومزودة ببرامج تشغيل أحدث للرسومات، ما يحدّ من تعرّض لعبتك لمشاكل السائق. تقدّم خدمة VkQuality توصيات الجودة فقط، وليس كضمانات، إذ لا يزال من الممكن مواجهة مشاكل السائق على الأجهزة المقترَحة. تدعم VkQuality القوائم المخصّصة التي تتيح لك إضافة اقتراحات للأجهزة أو إزالتها للعبتك.
تفعيل Vulkan في لعبة Unity Engine
تتطلّب خدمة VkQuality أن يتم تفعيل كل من عارضَي OpenGL ES وVulkan في لعبتك في إعدادات مشروع Unity. يمكنك تفعيل برامج العرض باستخدام الخيار Auto Graphics API أو من خلال إعداد واجهات برمجة تطبيقات الرسومات يدويًا.
الحصول على المكوّن الإضافي VkQuality في محرِّك Unity
نزِّل المكوّن الإضافي VkQuality من GitHub. يتوافق المكوّن الإضافي مع Unity 2021 والإصدارات الأحدث. يمكنك استخدام Unity 2021 LTS أو الإصدارات الأحدث لتفعيل Vulkan على نظام Android. تحتوي حزمة المكونات الإضافية على نموذج مشروع أساسي يستخدم المكون الإضافي لضبط واجهة برمجة تطبيقات الرسومات عند بدء التشغيل ثم تعرض سلسلة مجموعة لواجهة برمجة تطبيقات الرسومات النشطة للجهاز.
إدارة قائمة الاقتراحات في VkQuality Vulkan
تشتمل خدمة VkQuality على قائمة اقتراحات تلقائية بالأجهزة المتوافقة. للحصول على معلومات بشأن استخدام قائمة اقتراحات مخصّصة، راجِع قسم استخدام قائمة اقتراحات مخصّصة.
تشمل قائمة الاقتراحات ثلاث فئات:
- القائمة المسموح بها لأجهزة Vulkan
- قائمة السماح باقتراحات وحدة معالجة الرسومات
- قائمة رفض اقتراحات وحدة معالجة الرسومات
تطابق قائمة الأجهزة المسموح بها
تتحقق Vkquality أولاً مما إذا كان الجهاز النشط مضمّنًا في قائمة الأجهزة المسموح بها، وما إذا كان يعمل بالحد الأدنى من إصدار Android وإصدار برنامج تشغيل Vulkan المحدد في قائمة السماح لهذا الجهاز. في حال استيفاء هذه المعايير، تقترح VkQuality خوارزمية Vulkan من خلال عرض قيمة تعداد RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH
.
إذا كان الجهاز مدرجًا في القائمة المسموح بها، ولكنّه يعمل بإصدار نظام التشغيل Android أو إصدار برنامج التشغيل
أقل من الحد الأدنى المحدَّد له في قائمة السماح، يوصي VkQuality
بـ OpenGL ES من خلال عرض RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER
.
مطابقات الاقتراحات بشأن وحدة معالجة الرسومات
إذا لم يتم العثور على أي جهاز مطابق في قائمة السماح للأجهزة، تقيّم VkQuality طراز وحدة معالجة الرسومات وإصدار برنامج التشغيل وفقًا لقوائم السماح والرفض المقترَحة من خلال وحدة معالجة الرسومات. إذا تطابق طراز وحدة معالجة الرسومات وإصدار برنامج التشغيل مع إدخال في قائمة الاقتراحات بشأن وحدة معالجة الرسومات،
تقترح VkQuality استخدام Vulkan من خلال عرض ثابت التعداد RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH
.
في حال تطابق طراز وحدة معالجة الرسومات وإصدار برنامج التشغيل مع أحد الإدخالات في قائمة رفض اقتراحات وحدة معالجة الرسومات،
تقترح أداة VkQuality استخدام OpenGL ES من خلال عرض الرمز RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH
.
الاقتراحات التي لا تتطابق مع المحتوى المطابق
في حال عدم العثور على أي نتائج مطابقة، تقترح VkQuality استخدام Vulkan إذا كان مستوى واجهة برمجة تطبيقات Android للجهاز قيد التشغيل مساويًا لمستوى واجهة برمجة التطبيقات المستقبلي في قائمة الاقتراحات أو أعلى منه. تحتوي قائمة الاقتراحات التلقائية على مستوى مستقبلي لواجهة برمجة التطبيقات يبلغ 36، ما يعني أنّه على الأجهزة غير المطابقة التي تعمل بالمستوى 36 أو أعلى من واجهة برمجة التطبيقات، تعرض واجهة برمجة التطبيقات VkQuality ثابت التعداد RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID
.
إذا لم يتم العثور على أي تطابقات في قائمة السماح للأجهزة أو قوائم اقتراحات وحدة معالجة الرسومات،
وكان مستوى واجهة برمجة التطبيقات للجهاز أقل من مستوى واجهة برمجة التطبيقات Future API،
تقترح أداة VkQuality
OpenGL ES من خلال عرض رمز الاستجابة RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH
.
إضافة ملف أرشيف VkQuality إلى مشروعك
المكوّن الإضافي VkQuality هو ملف VkQuality-1.x.x.aar
في الدليل Assets/Android/Plugins
لأرشيف الحزم الذي تم تنزيله. يتطابق رقم الإصدار الفعلي لملف .aar مع رقم إصدار اسم أرشيف الحزمة. لتثبيت المكوّن الإضافي، قم بتنفيذ الخطوات التالية:
- انسخ ملف .aar إلى دليل
Assets/Android/Plugins
لمشروعك. (أنشئ الدليل الفرعيAndroid
وPlugins
المطلوبَين في حال عدم توفّرهما).
![ملف Vkquality .aar في دليل المشروع المطلوب.](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unityassets.png?authuser=6&hl=ar)
- حدد ملف المكوّن الإضافي
VkQuality-1.x.x
في التسلسل الهرمي لمشروع Unity لإظهار إعدادات الاستيراد في جزء أداة الفحص. تأكّد من وضع علامة في المربّع نظام Android الأساسي.
![الشكل 2. إعدادات استيراد النظام الأساسي للمكوّن الإضافي VkQuality](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unityplugin.png?authuser=6&hl=ar)
استخدام نشاط مخصّص للاتصال بـ VkQuality
على عكس المكونات الإضافية النموذجية لمحرك Unity، يجب تنفيذ VkQuality للحصول على توصية واجهة برمجة التطبيقات للرسومات قبل إعداد محرك Unity. بعد ذلك، يمكنك استخدام ميزة وسيطات سطر الأوامر في مشغّل Unity لضبط واجهة برمجة التطبيقات للرسومات استنادًا إلى اقتراح VkQuality. على نظام التشغيل Android، يتطلب ضبط وسيطات سطر الأوامر تجاوز السلوك التلقائي UnityPlayerActivity من خلال إنشاء نشاط مخصّص.
إذا كانت لعبتك تستخدم نشاطًا مخصّصًا، اطّلِع على القسم إضافة VkQuality إلى نشاط مخصّص حالي. لإنشاء نشاط مخصص جديد للعبتك، راجع إضافة نشاط مخصص إلى مشروع Unity، والذي يليه.
إضافة نشاط مخصّص إلى مشروع محرّك Unity
تم تضمين مثال لنشاط مخصّص يستخدم VkQuality في حزمة
المكوّنات الإضافية في Assets/Plugins/Android/VkQualityTestActivity.java
.
لتخصيص الملف واستخدامه في لعبتك، عليك اتّباع الخطوات التالية:
- انسخ ملف
VkQualityTestActivity.java
إلى دليلAssets/Plugins/Android
. - أعِد تسميته إلى اسم مناسب للعبتك (على سبيل المثال،
MyGameActivity.java
). - افتح الملف في محرِّر نصوص.
- عليك تغيير اسم الفئة من
VkQualityTestActivity
إلى الاسم الذي منحته للملف (على سبيل المثال،MyGameActivity.java
). - غيِّر اسم الحزمة من
com.google.android.games.VkQualityTest
لمطابقة قيمة حقل Package Name (اسم الحزمة) في فئة Unity Project Settings Player ضمن إعدادات أخرى (على سبيل المثال،com.mycompany.mygame
). - احفظ الملف وأغلقه.
أضف ملف بيان مخصصًا يشير إلى نشاطك المخصص، واطلب من Unity استخدام ملف البيان المخصص:
- انسخ الملف
AndroidManifest.xml
من الدليلAssets/Plugins/Android
لحزمة المكونات الإضافية إلى دليلAsset/Plugins/Android
لمشروعك. - افتح الملف في محرِّر نصوص.
- غيِّر قيمة الإعداد
activity android:name
منcom.google.android.games.VkQualityTest.VkQualityTestActivity
إلى أسماء الحِزم والأنشطة التي استخدمتها في الخطوات السابقة (مثلcom.mycompany.mygame.MyGameActivity
). - احفظ الملف وأغلقه.
- افتح نافذة إعدادات Unity واختَر إعدادات Player. وسِّع قسم إعدادات النشر وضَع علامة في مربّع الاختيار البيان الرئيسي المخصَّص.
![الشكل 3. خيار البيان الرئيسي المخصّص في إعدادات Unity Player](https://developer.android.com/static/images/games/engines/unity/unity-vkquality-unitymanifest.png?authuser=6&hl=ar)
تم إعداد مشروعك لاستخدام النشاط المخصّص الذي يستدعي VkQuality عند بدء التشغيل ويختار Vulkan أو OpenGL ES بناءً على توصية VkQuality.
إضافة VkQuality إلى نشاط مخصّص حالي
إذا كانت لعبتك تتضمّن نشاطًا مخصَّصًا يتجاوز الإعداد التلقائي
UnityPlayerActivity
، يمكنك دمج اقتراحات VkQuality من خلال إضافة
الرمز التالي:
أولاً، أضف عبارة استيراد VkQuality إلى قائمة عمليات الاستيراد أعلى ملف النشاط المخصص:
Kotlin
import com.google.android.games.vkquality.VKQuality;
Java
import com.google.android.games.vkquality.VKQuality;
بعد ذلك، أنشِئ بعض الثوابت في نص فئة Activity
الخاصة بخيارات واجهة برمجة التطبيقات للرسومات:
Kotlin
companion object { private const val OVERRIDE_NONE = 0 private const val OVERRIDE_GLES = 1 private const val OVERRIDE_VULKAN = 2
Java
private static final int OVERRIDE_NONE = 0; private static final int OVERRIDE_GLES = 1; private static final int OVERRIDE_VULKAN = 2;
أنشئ متغيّرًا لتتبّع اختيار واجهة برمجة التطبيقات:
Kotlin
private var apiOverride = OVERRIDE_NONE
Java
private int apiOverride = OVERRIDE_NONE;
أضِف الدالة التالية إلى فئة Activity
:
Kotlin
private fun CheckVkQuality() { val vkQuality = VKQuality(this) val startResult = vkQuality.StartVkQuality("") if (startResult == VKQuality.INIT_SUCCESS) { // In the current release, we can assume GetVkQuality is // ready as soon as StartVkQuality has returned success. val getResult = vkQuality.GetVkQuality() LogVkQualityResult(getResult) apiOverride = when (getResult) { VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH, VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH, VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID -> OVERRIDE_VULKAN VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE, VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER, VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH, VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH -> OVERRIDE_GLES else -> OVERRIDE_GLES } vkQuality.StopVkQuality() } else { Log.e("VKQUALITY", "VkQuality start failed with result: $startResult") } }
Java
private void CheckVkQuality() { VKQuality vkQuality = new VKQuality(this); // An empty string specifies use of the default // built-in device list file. int startResult = vkQuality.StartVkQuality(""); if (startResult == VKQuality.INIT_SUCCESS) { // In the current release, we can assume GetVkQuality is // ready as soon as StartVkQuality has returned success. int getResult = vkQuality.GetVkQuality(); switch (getResult) { case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH: case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH: case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID: apiOverride = OVERRIDE_VULKAN; break; case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE: case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER: case VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH: case VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH: default: apiOverride = OVERRIDE_GLES; break; } vkQuality.StopVkQuality(); } else { Log.e("VKQUALITY", "VkQuality start failed with result: " + startResult); } }
استدعِ الدالة CheckVkQuality
من أعلى دالة التجاوز onCreate()
قبل استدعاء تنفيذ الفئة الأساسية:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { CheckVkQuality() super.onCreate(savedInstanceState) }
Java
@Override protected void onCreate(Bundle savedInstanceState) { CheckVkQuality(); super.onCreate(savedInstanceState); }
وأخيرًا، أضِف قيمة تجاوز الدالة updateUnityCommandLineArguments()
التي تستخدم القيمة apiOverride
لتمرير وسيطة سطر أوامر إلى Unity Engine لتحديد واجهة برمجة تطبيقات الرسومات المراد استخدامها:
Kotlin
override fun updateUnityCommandLineArguments(cmdLine: String): String { if (apiOverride == OVERRIDE_VULKAN) { Log.i("VKQUALITY", "Passing -force-vulkan") return appendCommandLineArgument(cmdLine, "-force-vulkan") } else if (apiOverride == OVERRIDE_GLES) { Log.i("VKQUALITY", "Passing -force-gles") return appendCommandLineArgument(cmdLine, "-force-gles") } Log.i("VKQUALITY", "No override passed") // let Unity pick the Graphics API based on PlayerSettings return cmdLine } private fun appendCommandLineArgument(cmdLine: String, arg: String?): String { return if (arg == null || arg.isEmpty()) cmdLine else if (cmdLine == null || cmdLine.isEmpty()) arg else "$cmdLine $arg" }
Java
@Override protected String updateUnityCommandLineArguments(String cmdLine) { if (apiOverride == OVERRIDE_VULKAN) { Log.i("VKQUALITY", "Passing -force-vulkan"); return appendCommandLineArgument(cmdLine, "-force-vulkan"); } else if (apiOverride == OVERRIDE_GLES) { Log.i("VKQUALITY", "Passing -force-gles"); return appendCommandLineArgument(cmdLine, "-force-gles"); } Log.i("VKQUALITY", "No override passed"); // let Unity pick the Graphics API based on PlayerSettings return cmdLine; } private String appendCommandLineArgument(String cmdLine, String arg) { if (arg == null || arg.isEmpty()) return cmdLine; else if (cmdLine == null || cmdLine.isEmpty()) return arg; else return cmdLine + " " + arg; }
يستدعي نشاطك المخصّص الآن VkQuality عند بدء التشغيل ويختار Vulkan أو OpenGL ES بناءً على اقتراح VkQuality.
استخدام قائمة اقتراحات مخصّصة
حدِّد ملف قائمة اقتراحات مخصّصة من خلال إدخال اسم الملف
الذي يحتوي على القائمة إلى StartVkQuality()
بدلاً من تمرير سلسلة فارغة:
Kotlin
val startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq")
Java
int startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq");
تبحث خدمة Vkquality أولاً عن الملف في دليل وحدة التخزين الداخلية لتطبيقك. إذا لم يكن الملف في وحدة التخزين الداخلية، ستحاول VkQuality تحميل
الملف من أصول حزمة التطبيق. إذا لم يكن الملف في أي من الموقعين، فإن VkQuality تعرض قيمة التعداد ERROR_MISSING_DATA_FILE
.
لإنشاء ملف قائمة اقتراحات مخصّص، استخدِم أداة Vkquality List Editor الموجودة في مستودع GitHub. توجد وثائق الأداة في README.