排解 AGI 問題

本主題說明如何修正使用 Android GPU Inspector (AGI) 時的常見問題。

正在重設 AGI 設定

AGI 會將其設定儲存在 ~/.agic 檔案中。如果移除這個檔案，所有 AGI 設定也會一併刪除，包括最近開啟的追蹤記錄和裝置驗證結果清單。

部分裝置上的 AGI 無法正常運作

請確定您的設定符合所有需求。

下列做法也有助於解決問題：

  • 停止透過 ADB 與裝置互動的任何程式，例如 Android Studio。

  • 在 Android 的開發人員選項下方啟用 Stay awake 選項，避免裝置螢幕因睡眠模式而關閉時出現的問題。

系統分析器不會回報 OpenGL ES 遊戲的 GPU 活動

目前追蹤 OpenGL ES 應用程式時僅支援 GPU 計數器。OpenGL ES 應用程式的 GPU 活動資訊仍在開發中。

部分 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 後有任何問題，您可以使用下列 AGI 指令清除這些設定：

# 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 會攔截遊戲發出的圖形 API 呼叫，這可能會影響遊戲算繪。

AGI 會擷取 Vulkan 呼叫。針對 OpenGL ES 遊戲，AGI 需仰賴 ANGLE 將 OpenGL ES 轉譯為 Vulkan。如果您的遊戲在透過 AGI 啟動時看起來不一樣 (例如某些顏色不如預期)，則可能是 AGI 或 ANGLE 中的錯誤。您可以嘗試下列做法，協助我們進一步瞭解問題的根本原因。

Vulkan 遊戲：支援所有 Vulkan 擴充功能進行追蹤

「Include Unknown Extensions」(納入不明擴充功能) 追蹤選項可控管 AGI 是否應納入不支援的 Vulkan 擴充功能。(瀏覽支援的擴充功能清單)。

如果您的應用程式使用 AGI 不支援的擴充功能，您可能會在重播追蹤記錄時遇到不理想的行為，包括細微錯誤或當機情形。

請嘗試啟用這個選項，然後啟動另一個影格分析器追蹤記錄。如果遊戲正常顯示啟用選項時，遊戲可能會依賴 AGI 不支援的 Vulkan 擴充功能。

OpenGL ES 遊戲：僅透過 ANGLE 執行

您可以在不使用 AGI 的情況下執行 OpenGL ES 遊戲，藉此查看轉譯錯誤的是否為 ANGLE 中的問題。

如果您已嘗試為 OpenGL ES 遊戲建立影格設定檔追蹤記錄，表示 AGI 已在裝置上安裝 ANGLE。AGI 使用的 ANGLE 套件名稱為 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 中的錯誤。

您可以建立 GitHub 問題來回報 AGI 錯誤。