Android 上的 Vulkan 驗證層

大多數煽情露骨圖形 API 都不會執行錯誤檢查，因為這可能導致效能降低。Vulkan 具有「驗證層」，可在開發期間執行錯誤檢查，避免應用程式的發布子版本效能下降。驗證層採用一般用途分層機制，可攔截 API 進入點。

單一 Khronos 驗證層

Vulkan 先前提供多個驗證層，且需依照特定順序啟用。從 1.1.106.0 Vulkan SDK 版開始，應用程式只需啟用單一驗證層 VK_LAYER_KHRONOS_validation，就能使用舊版驗證層的所有功能。

注意：非行動裝置也支援統一的 VK_LAYER_KHRONOS_validation 層，因此您可以在所有平台上共享相同的驗證碼。

使用封裝在 APK 中的驗證層

在 APK 中封裝驗證層可確保發揮最佳相容效果。 驗證層可做為預先建構的二進位檔，也可以使用原始碼建構。

注意：Android 9 (API 級別 28) 以上版本允許 Vulkan 載入與應用程式 APK 位置不同的層。詳情請參閱「使用外部驗證層」。

使用預先建構的二進位檔

從 GitHub 發布頁面下載最新的 Android Vulkan 驗證層二進位檔。

如要在 APK 中新增層，最簡單的方法就是將預先建構的層二進位檔擷取至模組的 src/main/jniLibs/ 目錄，並讓 ABI 目錄 (例如 arm64-v8a 或 x86-64) 保持不變，具體如下所示：

src/main/jniLibs/
  arm64-v8a/
    libVkLayer_khronos_validation.so
  armeabi-v7a/
    libVkLayer_khronos_validation.so
  x86/
    libVkLayer_khronos_validation.so
  x86-64/
    libVkLayer_khronos_validation.so

使用原始碼建構驗證層

如要對驗證層原始碼進行偵錯，請從 Khronos Group GitHub 存放區中提取最新的原始碼，然後按照其中的建構說明進行操作。

確認驗證層已正確封裝

無論您在建構時是使用 Khronos 預先建構的層，或是使用以原始碼建構的層，建構程序都會在 APK 中產生最終的檔案結構，如下所示：

lib/
  arm64-v8a/
    libVkLayer_khronos_validation.so
  armeabi-v7a/
    libVkLayer_khronos_validation.so
  x86/
    libVkLayer_khronos_validation.so
  x86-64/
    libVkLayer_khronos_validation.so

下列指令顯示如何驗證 APK 是否含有預期的驗證層：

$ jar -tf project.apk | grep libVkLayer
lib/x86_64/libVkLayer_khronos_validation.so
lib/armeabi-v7a/libVkLayer_khronos_validation.so
lib/arm64-v8a/libVkLayer_khronos_validation.so
lib/x86/libVkLayer_khronos_validation.so

在建立執行個體時啟用驗證層

Vulkan API 可讓應用程式在建立執行個體時啟用層。層攔截的進入點必須將下列其中一個物件做為第一個參數：

• VkInstance
• VkPhysicalDevice
• VkDevice
• VkCommandBuffer
• VkQueue

呼叫 vkEnumerateInstanceLayerProperties() 列出可用層及其屬性。Vulkan 會在 vkCreateInstance() 執行時啟用層。

下列程式碼片段顯示應用程式如何使用 Vulkan API 以程式輔助方式查詢和啟用層：

// Enable just the Khronos validation layer.
static const char *layers[] = {"VK_LAYER_KHRONOS_validation"};

// Get the layer count using a null pointer as the last parameter.
uint32_t instance_layer_present_count = 0;
vkEnumerateInstanceLayerProperties(&instance_layer_present_count, nullptr);

// Enumerate layers with a valid pointer in the last parameter.
VkLayerProperties layer_props[instance_layer_present_count];
vkEnumerateInstanceLayerProperties(&instance_layer_present_count, layer_props);

// Make sure selected validation layers are available.
VkLayerProperties *layer_props_end = layer_props + instance_layer_present_count;
for (const char* layer:layers) {
  assert(layer_props_end !=
  std::find_if(layer_props, layer_props_end, [layer](VkLayerProperties layerProperties) {
    return strcmp(layerProperties.layerName, layer) == 0;
  }));
}

// Create a Vulkan instance, requesting all enabled layers or extensions
// available on the system
VkInstanceCreateInfo instanceCreateInfo{
  .sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO,
  .pNext = nullptr,
  .pApplicationInfo = &appInfo,
  .enabledLayerCount = sizeof(layers) / sizeof(layers[0]),
  .ppEnabledLayerNames = layers,

預設 logcat 輸出

驗證層會在標有 VALIDATION 標記的 logcat 中發出警告和錯誤訊息。驗證層訊息如下所示 (當中加入分行符號以方便捲動)：

Validation -- Validation Error:
  [ VUID-VkDeviceQueueCreateInfo-pQueuePriorities-parameter ]
Object 0: VK_NULL_HANDLE, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0xd6d720c6 |
vkCreateDevice: required parameter
  pCreateInfo->pQueueCreateInfos[0].pQueuePriorities specified as NULL.
The Vulkan spec states: pQueuePriorities must be a valid pointer to an array of
  queueCount float values
  (https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html
  #VUID-VkDeviceQueueCreateInfo-pQueuePriorities-parameter)

啟用偵錯回呼

偵錯公用程式擴充功能 VK_EXT_debug_utils 可讓應用程式建立偵錯訊息傳遞工具，將驗證層訊息傳遞至應用程式提供的回呼。您的裝置可能並未實作這個擴充功能，不過最新的驗證層中已可實作。另一個已淘汰的擴充功能 VK_EXT_debug_report 會在 VK_EXT_debug_utils 無法使用時提供類似功能。

使用偵錯公用程式擴充功能之前，請先確認您的裝置或載入的驗證層支援這項功能。下列範例說明如何檢查是否支援偵錯公用程式擴充功能，以及在裝置或驗證層支援這項功能時應如何註冊回呼。

// Get the instance extension count.
uint32_t inst_ext_count = 0;
vkEnumerateInstanceExtensionProperties(nullptr, &inst_ext_count, nullptr);

// Enumerate the instance extensions.
VkExtensionProperties inst_exts[inst_ext_count];
vkEnumerateInstanceExtensionProperties(nullptr, &inst_ext_count, inst_exts);

// Check for debug utils extension within the system driver or loader.
// Check if the debug utils extension is available (in the driver).
VkExtensionProperties *inst_exts_end = inst_exts + inst_ext_count;
bool debugUtilsExtAvailable = inst_exts_end !=
  std::find_if(inst_exts, inst_exts_end, [](VkExtensionProperties
    extensionProperties) {
    return strcmp(extensionProperties.extensionName,
      VK_EXT_DEBUG_UTILS_EXTENSION_NAME) == 0;
  });

if ( !debugUtilsExtAvailable ) {
  // Also check the layers for the debug utils extension.
  for (auto layer: layer_props) {
    uint32_t layer_ext_count;
    vkEnumerateInstanceExtensionProperties(layer.layerName, &layer_ext_count,
      nullptr);
    if (layer_ext_count == 0) continue;
    VkExtensionProperties layer_exts[layer_ext_count];
    vkEnumerateInstanceExtensionProperties(layer.layerName, &layer_ext_count,
    layer_exts);

    VkExtensionProperties * layer_exts_end = layer_exts + layer_ext_count;
    debugUtilsExtAvailable = layer_exts != std::find_if(
      layer_exts, layer_exts_end,[](VkExtensionProperties extensionProperties) {
        return strcmp(extensionProperties.extensionName,
        VK_EXT_DEBUG_UTILS_EXTENSION_NAME) == 0;
      });
    if (debugUtilsExtAvailable) {
        // Add the including layer into the layer request list if necessary.
        break;
    }
  }
}

if (!debugUtilsExtAvailable) return; // since this snippet depends on debugUtils

const char * enabled_inst_exts[] = { ..., VK_EXT_DEBUG_UTILS_EXTENSION_NAME };
uint32_t enabled_extension_count =
  sizeof(enabled_inst_exts)/sizeof(enabled_inst_exts[0]);

// Pass the instance extensions into vkCreateInstance.
VkInstanceCreateInfo instance_info = {};
instance_info.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
instance_info.enabledExtensionCount = enabled_extension_count;
instance_info.ppEnabledExtensionNames = enabled_inst_exts;

// NOTE: Can still return VK_ERROR_EXTENSION_NOT_PRESENT if validation layer
// isn't loaded.
vkCreateInstance(&instance_info, nullptr, &instance);

auto pfnCreateDebugUtilsMessengerEXT =
  (PFN_vkCreateDebugUtilsMessengerEXT)vkGetInstanceProcAddr(
    tutorialInstance, "vkCreateDebugUtilsMessengerEXT");
auto pfnDestroyDebugUtilsMessengerEXT =
  (PFN_vkDestroyDebugUtilsMessengerEXT)vkGetInstanceProcAddr(
    tutorialInstance, "vkDestroyDebugUtilsMessengerEXT");

// Create the debug messenger callback with your the settings you want.
VkDebugUtilsMessengerEXT debugUtilsMessenger;
if (pfnCreateDebugUtilsMessengerEXT) {
  VkDebugUtilsMessengerCreateInfoEXT messengerInfo;
  constexpr VkDebugUtilsMessageSeverityFlagsEXT kSeveritiesToLog =
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT |
    VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT;

constexpr VkDebugUtilsMessageTypeFlagsEXT kMessagesToLog =
  VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
  VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT |
  VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT;

  messengerInfo.sType           = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT;
  messengerInfo.pNext           = nullptr;
  messengerInfo.flags           = 0;
  messengerInfo.messageSeverity = kSeveritiesToLog;
  messengerInfo.messageType     = kMessagesToLog;

  // The DebugUtilsMessenger callback is explained in the following section.
  messengerInfo.pfnUserCallback = &DebugUtilsMessenger;
  messengerInfo.pUserData       = nullptr; // Custom user data passed to callback

  pfnCreateDebugUtilsMessengerEXT(instance, &messengerInfo, nullptr,
    &debugUtilsMessenger);
}

// Later, when shutting down Vulkan, call the following:
if (pfnDestroyDebugUtilsMessengerEXT) {
    pfnDestroyDebugUtilsMessengerEXT(instance, debugUtilsMessenger, nullptr);
}

應用程式註冊並啟用回呼後，系統便會將偵錯訊息轉送至對應的回呼。

#include <android/log.h>

VKAPI_ATTR VkBool32 VKAPI_CALL DebugUtilsMessenger(
                        VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity,
                        VkDebugUtilsMessageTypeFlagsEXT messageTypes,
                        const VkDebugUtilsMessengerCallbackDataEXT *callbackData,
                        void *userData)
{
  const char validation[]  = "Validation";
  const char performance[] = "Performance";
  const char error[]       = "ERROR";
  const char warning[]     = "WARNING";
  const char unknownType[] = "UNKNOWN_TYPE";
  const char unknownSeverity[] = "UNKNOWN_SEVERITY";
  const char* typeString      = unknownType;
  const char* severityString  = unknownSeverity;
  const char* messageIdName   = callbackData->pMessageIdName;
  int32_t messageIdNumber     = callbackData->messageIdNumber;
  const char* message         = callbackData->pMessage;
  android_LogPriority priority = ANDROID_LOG_UNKNOWN;

  if (messageSeverity & VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT) {
    severityString = error;
    priority = ANDROID_LOG_ERROR;
  }
  else if (messageSeverity & VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) {
    severityString = warning;
    priority = ANDROID_LOG_WARN;
  }
  if (messageTypes & VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT) {
     typeString = validation;
  }
  else if (messageTypes & VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT) {
     typeString = performance;
  }

  __android_log_print(priority,
                     "AppName",
                     "%s %s: [%s] Code %i : %s",
                     typeString,
                     severityString,
                     messageIdName,
                     messageIdNumber,
                     message);

  // Returning false tells the layer not to stop when the event occurs, so
  // they see the same behavior with and without validation layers enabled.
  return VK_FALSE;
}

使用外部驗證層

您不必在 APK 中封裝驗證層；搭載 Android 9 (API 級別 28) 以上版本的裝置可以使用二進位檔之外的驗證層，並動態關閉及開啟這些驗證層。請按照本節中的步驟將驗證層推送至測試裝置：

讓應用程式可以使用外部驗證層

Android 的安全性模型和政策與其他平台有很大差異。如要載入外部驗證層，必須符合下列其中一項條件：

• 目標應用程式可進行偵錯。這個選項會產生更多偵錯資訊，但可能會降低應用程式的效能。

• 目標應用程式在授予 Root 存取權的作業系統使用者偵錯版本上執行。

• 指定目標版本僅限 Android 11 (API 級別 30) 以上版本的應用程式：您的目標 Android 資訊清單檔案包含下列 meta-data 元素：

  <meta-data android:name="com.android.graphics.injectLayers.enable"
    android:value="true"/>
  

載入外部驗證層

搭載 Android 9 (API 級別 28) 以上版本的裝置允許 Vulkan 從應用程式的本機儲存空間載入驗證層。從 Android 10 (API 級別 29) 開始，Vulkan 也可以從單獨的 APK 載入驗證層。只要 Android 版本支援，您就能自由選擇任何一種方法。

從裝置本機儲存空間載入驗證層二進位檔

由於 Vulkan 會在裝置的暫存資料目錄中尋找二進位檔，因此您必須先使用 Android Debug Bridge (ADB) 將二進位檔推送至該目錄，如下所示：

1. 使用 adb push 指令將層二進位檔載入應用程式在裝置上的資料儲存空間：

   $ adb push libVkLayer_khronos_validation.so /data/local/tmp
   

2. 使用 adb shell 和 run-as 指令，透過應用程式程序載入層。也就是說，二進位檔具有應用程式所擁有的裝置存取權，無須要求 Root 存取權。

   $ adb shell run-as com.example.myapp cp
     /data/local/tmp/libVkLayer_khronos_validation.so .
   $ adb shell run-as com.example.myapp ls libVkLayer_khronos_validation.so
   

3. 啟用層。

從其他 APK 載入驗證層二進位檔

您可以使用 adb 安裝含有層的 APK，然後啟用層。

adb install --abi abi path_to_apk

在應用程式外啟用層

您可以為個別應用程式啟用 Vulkan 層，也可以全域啟用。在每次重新啟動時，個別應用程式設定會維持不變，而全域屬性則會在重新啟動時被清除。

針對個別應用程式啟用層

下列步驟說明如何針對個別應用程式啟用層：

1. 使用 ADB 殼層設定啟用層：

   $ adb shell settings put global enable_gpu_debug_layers 1
   

2. 指定要啟用層的目標應用程式：

   $ adb shell settings put global gpu_debug_app <package_name>
   

3. 指定要啟用的層的清單 (由上至下)，並以半形冒號分隔每個層：

   $ adb shell settings put global gpu_debug_layers <layer1:layer2:layerN>
   

   由於我們採用單一 Khronos 驗證層，因此這個指令可能會如下所示：

   $ adb shell settings put global gpu_debug_layers VK_LAYER_KHRONOS_validation
   

4. 指定一或多個要在其中搜尋層的套件：

   $ adb shell settings put global
     gpu_debug_layer_app <package1:package2:packageN>
   

注意：您也可以透過裝置端的開發人員選項啟用 enable_gpu_debug_layers 設定。啟用開發人員選項後，請在測試裝置上開啟設定應用程式，然後依序前往「開發人員選項」>「偵錯」，然後確定已開啟「啟用 GPU 偵錯圖層」選項。

您可以使用下列指令來檢查設定是否已啟用：

$ adb shell settings list global | grep gpu
enable_gpu_debug_layers=1
gpu_debug_app=com.example.myapp
gpu_debug_layers=VK_LAYER_KHRONOS_validation

由於套用的設定不會因為裝置重新啟動而重設，因此您可能需要在載入層後清除設定：

$ 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

全域啟用層

您可以在裝置下次重新啟動之前，全域啟用一或多個層。 這樣一來，系統會嘗試針對所有應用程式 (包括原生執行檔) 載入層。

$ adb shell setprop debug.vulkan.layers <layer1:layer2:layerN>