تحديد مشاكل واجهة برمجة التطبيقات (AGI) وحلّها

يشرح هذا الموضوع طريقة إصلاح المشاكل الشائعة عند استخدام أداة فحص وحدة معالجة الرسومات في نظام التشغيل Android (AGI) .

إعادة ضبط إعدادات AGI

تخزِّن أداة AGI إعداداتها في ملف ~/.agic. تؤدي إزالة هذا الملف إلى حذف جميع إعدادات AGI، بما في ذلك قائمة عمليات التتبُّع التي تم فتحها مؤخرًا ونتائج التحقّق من صحة الجهاز.

تعذُّر استخدام ميزة "مؤشر جودة الهواء" (AGI) على بعض الأجهزة

يُرجى التأكّد من أنّ الإعداد يستوفي جميع المتطلبات.

يمكن أن يساعدك ما يلي أيضًا:

  • أوقِف أي برنامج قد يتفاعل مع الجهاز عبر ADB، مثل "استوديو Android".

  • فعِّل الخيار Stay awake (ضمن "خيارات المطوّرين على Android") لمنع المشاكل التي تحدث عند إطفاء شاشة الجهاز بسبب وضع السكون.

لا يُبلغ محلّل النظام عن نشاط وحدة معالجة الرسومات في ألعاب OpenGL ES.

في الوقت الحالي، لا يمكن استخدام سوى عدّادات وحدة معالجة الرسومات عند تتبُّع تطبيق OpenGL ES. معلومات نشاط وحدة معالجة الرسومات لتطبيقات OpenGL ES قيد التطوير النشط.

تعذُّر عمل محلّل الإطار في بعض ألعاب Vulkan

يجب التأكّد أولاً من أنّ لعبتك تستخدم Vulkan بشكل صحيح. استخدِم طبقة التحقق من Vulkan وتأكَّد من أنّ لعبتك لا تعرض أي أخطاء أو تحذيرات.

إذا كان هناك أي خطأ في عملية التحقق من Vulkan، فليس من المتوقع أن يعمل محلّل إطار AGI.

تعذَّر تشغيل اللعبة عند إنشاء سجلّ محلّل إطارات

إذا تم تشغيل اللعبة بنجاح بدون أداة AGI ولكن يتعذّر تشغيلها عند إنشاء تتبُّع الملف الشخصي للإطار، قد تُجري اللعبة عملية مختلفة أثناء سلسلة بدء التشغيل. في هذه الحالة، عليك تحديد اسم العملية المراد تتبعها في حقل "اسم العملية" في خيارات التتبع.

لتحديد هذه المشكلة، يمكنك التحقق من مخرجات Logcat أثناء إنشاء عملية تتبُّع والتحقّق مما إذا كانت هناك عملية مختلفة قد بدأت أم لا:

# Clear the logcat output
adb logcat -c

## Use AGI to attempt to create a frame profile trace

Look at the logcat output to identify the processes that are running AGI. 

adb logcat | grep "this process name"
I GAPID   : gapii [gapii/cc/spy.cpp:109] this process name: com.example.mygame
I GAPID   : gapii [gapii/cc/spy.cpp:109] this process name: com.example.mygame:GameProcess

تحتوي معظم الألعاب على عملية واحدة فقط، ويوضح المثال أعلاه ما يمكن توقعه للعبة التي تتضمن أكثر من عملية واحدة.

تبدأ اللعبة في عملية رئيسية باسم com.example.mygame، ثم يتم تسجيل عملية جديدة اسمها com.example.mygame:GameProcess. إذا حدث العرض الفعلي للعبة في العملية الثانية، يجب إعلام AGI بأنّ هذه هي العملية التي تريد تتبُّعها. يمكنك إجراء ذلك من خلال إدخال اسم العملية في الحقل Process name ضمن مربّع حوار خيار التتبُّع.

تعذّر تشغيل اللعبة بعد استخدام AGI

وفي حال لم يتم إنهاء عملية التتبُّع بشكل صحيح، قد تترك أداة AGI بعض إعدادات Android في حالة قد تؤدي إلى إيقاف عمليات التشغيل اللاحقة للتطبيق. وفي ما يلي الإعدادات:

  • الإعدادات ذات الصلة بطبقات Vulkan:

    • enable_gpu_debug_layers

    • gpu_debug_app

    • gpu_debug_layers

    • gpu_debug_layer_app

  • الإعدادات المتعلقة بمحرّك ANGLE:

    • angle_debug_package

    • angle_gl_driver_selection_values

    • angle_gl_driver_selection_pkgs

إذا واجه تطبيقك أي مشاكل بعد استخدام AGI، يمكنك محاولة محو هذه الإعدادات باستخدام أوامر adb التالية:

# Vulkan layers
adb shell settings delete global enable_gpu_debug_layers
adb shell settings delete global gpu_debug_app
adb shell settings delete global gpu_debug_layers
adb shell settings delete global gpu_debug_layer_app
# ANGLE
adb shell settings delete global angle_debug_package
adb shell settings delete global angle_gl_driver_selection_values
adb shell settings delete global angle_gl_driver_selection_pkgs

تبدو لعبتك مختلفة عند تشغيلها من خلال AGI أثناء إنشاء تتبُّع للملف الشخصي لإطار.

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

تلتقط AGI مكالمات Vulkan. بالنسبة إلى ألعاب OpenGL ES، تعتمد أداة AGI على ANGLE لترجمة OpenGL ES إلى Vulkan. إذا كانت لعبتك تبدو مختلفة (مثلاً، بعض الألوان ليست تلك التي تتوقّعها) عند تشغيلها من خلال AGI، قد يكون هناك خطأ في AGI أو ANGLE. يمكنك مساعدتنا في التعرّف بشكل أفضل على السبب الجذري للمشكلة من خلال تجربة ما يلي.

ألعاب Vulkan: التتبّع باستخدام جميع إضافات Vulkan

يتحكّم خيار التتبُّع تضمين الإضافات غير المعروفة في ما إذا كان يجب أن تتضمّن أداة AGI إضافات Vulkan التي لا تتوافق معها. (يمكنك تصفّح قائمة بالإضافات المتوافقة.)

وإذا كان تطبيقك يستخدم إضافة لا تتوافق مع أداة AGI، قد تواجه سلوكًا غير مرغوب فيه، بما في ذلك أخطاء أو أعطال طفيفة عند إعادة تشغيل مسار التتبُّع.

جرِّب تفعيل هذا الخيار، ثم ابدأ عملية تتبُّع أخرى لمحلِّل الإطارات. وإذا ظهرت اللعبة على النحو المتوقّع مع تفعيل الخيار، قد تعتمد اللعبة على إضافة Vulkan غير متوافقة مع AGI.

ألعاب OpenGL ES: يمكن تشغيلها باستخدام محرِّك ANGLE فقط

يمكنك تشغيل لعبة OpenGL ES باستخدام محرِّك ANGLE ولكن بدون AGI لمعرفة ما إذا كان العرض الخاطئ ناتجًا عن مشكلة في ANGLE.

إذا سبق لك محاولة إنشاء تتبُّع لملف شخصي للإطار في لعبة OpenGL ES، يعني ذلك أنّ AGI ثبَّت محرِّك ANGLE على جهازك. تُسمّى حزمة ANGLE التي تستخدمها حزمة AGI org.chromium.angle.agi.

لفرض تشغيل لعبتك على محرِّك ANGLE، استخدِم الأوامر التالية:

# Make sure that the AGI capture layer will be ignored
adb shell settings delete global enable_gpu_debug_layers
# Force the package com.example.mygame to use ANGLE
adb shell settings put global angle_debug_package org.chromium.angle.agi
adb shell settings put global angle_gl_driver_selection_values angle
adb shell settings put global angle_gl_driver_selection_pkgs com.example.mygame

إذا كانت اللعبة تبدو مختلفة عند استخدام هذه الإعدادات، من المحتمل أن يكون هناك خطأ في ANGLE وليس في AGI. إذا كانت اللعبة تبدو صحيحة في ظل هذه الإعدادات، لكنّها تبدو مختلفة أثناء إنشاء تتبُّع AGI، من المحتمل أن يكون هناك خطأ في AGI.

يمكنك الإبلاغ عن أخطاء AGI من خلال إنشاء مشكلة في GitHub.