初始化

在使用 Vulkan 之前,应用程序必须通过加载 Vulkan 命令并创建一个 VkInstance 对象来初始化它。

命令函数指针

Vulkan 命令不一定通过平台上的静态链接公开。下面描述了查询 Vulkan 命令的函数指针的命令。

当扩展 提升 或以其他方式合并到另一个扩展或 Vulkan 核心版本中时,可能会包含命令 别名。虽然每个命令别名的行为是相同的,但检索每个别名的函数指针的行为却不是。只有在支持并启用引入该别名的扩展或版本的情况下,才能检索给定别名的函数指针,而不管是否有任何其他别名可用。

所有 Vulkan 命令的函数指针可以通过调用获取

// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetInstanceProcAddr(
    VkInstance                                  instance,
    const char*                                 pName);
  • instance 是函数指针将与之兼容的实例,或者对于不依赖于任何实例的命令,则为 NULL

  • pName 是要获取的命令的名称。

vkGetInstanceProcAddr 本身以平台和加载程序特定的方式获取。通常,加载程序库会将此命令作为函数符号导出,因此应用程序可以链接到加载程序库,或者动态加载它并使用特定于平台的 API 查找符号。

下表定义了 vkGetInstanceProcAddr 的各种用例以及每种情况的预期返回值(“fp”是“函数指针”)。有效的返回函数指针(“fp”)不得NULL

返回的函数指针的类型为 PFN_vkVoidFunction,并且在使用之前必须将其强制转换为正在查询的命令的类型。

表 1. vkGetInstanceProcAddr 的行为
instance pName 返回值

*1

NULL

未定义

无效的非 NULL 实例

*1

未定义

NULL

全局命令2

fp

NULL

vkGetInstanceProcAddr

fp5

instance

vkGetInstanceProcAddr

fp

instance

核心 可分发命令

fp3

instance

instance 启用的实例扩展可分发命令

fp3

instance

instance 提供的设备扩展4可分发命令

fp3

任何其他未涵盖的情况

NULL

1

“*”表示参数的任何可表示值(包括有效值、无效值和 NULL)。

2

全局命令为:vkEnumerateInstanceVersionvkEnumerateInstanceExtensionPropertiesvkEnumerateInstanceLayerPropertiesvkCreateInstance。可分发命令是所有其他非全局的命令。

3

返回的函数指针必须仅使用可分发对象(第一个参数)进行调用,该对象是 instanceinstance 的子对象,例如 VkInstanceVkPhysicalDeviceVkDeviceVkQueueVkCommandBuffer

4

“提供的设备扩展”是 instance 枚举的任何物理设备都支持的设备扩展。

5

从 Vulkan 1.2 开始,vkGetInstanceProcAddr 可以使用 NULL 实例指针解析自身。

有效用法(隐式)
  • VUID-vkGetInstanceProcAddr-instance-parameter
    如果 instance 不是 NULL,则 instance 必须是有效的 VkInstance 句柄

  • VUID-vkGetInstanceProcAddr-pName-parameter
    pName 必须是以 null 结尾的 UTF-8 字符串

为了支持具有多个 Vulkan 实现的系统,由 vkGetInstanceProcAddr 返回的函数指针可以指向为不同的 VkDevice 对象或其子对象调用不同实际实现的调度代码。通过获取任何使用设备或设备子对象作为其可分发对象的命令的设备特定函数指针,可以避免 VkDevice 对象的内部调度的开销。此类函数指针可以通过调用获取

// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetDeviceProcAddr(
    VkDevice                                    device,
    const char*                                 pName);

下表定义了 vkGetDeviceProcAddr 的各种用例以及每种情况的预期返回值(“fp”是“函数指针”)。有效的返回函数指针(“fp”)不得NULL

返回的函数指针的类型为 PFN_vkVoidFunction,并且在使用之前必须将其强制转换为正在查询的命令的类型。该函数指针必须仅使用可分发对象(第一个参数)进行调用,该对象是 devicedevice 的子对象。

表 2. vkGetDeviceProcAddr 的行为
device pName 返回值

NULL

*1

未定义

无效设备

*1

未定义

device

NULL

未定义

device

请求的核心版本2 设备级别可分发命令3

fp4

device

启用的扩展设备级别可分发命令3

fp4

任何其他未涵盖的情况

NULL

1

“*”表示参数的任何可表示值(包括有效值、无效值和 NULL)。

2

当创建实例时,由 VkApplicationInfo::apiVersion 指定的核心版本中的设备级命令将始终返回有效的函数指针。如果启用了 maintenance5 功能,则超出该版本的核心命令(如果实现支持)将返回 NULL,否则实现可能返回 NULL 或函数指针。如果返回函数指针,则必须不调用它。

3

在此函数中,设备级排除所有物理设备级命令。

4

返回的函数指针必须仅使用可调度对象(第一个参数)调用,该对象是 devicedevice 的子对象,例如 VkDeviceVkQueueVkCommandBuffer

有效用法(隐式)
  • VUID-vkGetDeviceProcAddr-device-parameter
    device 必须是有效的 VkDevice 句柄

  • VUID-vkGetDeviceProcAddr-pName-parameter
    pName 必须是以 null 结尾的 UTF-8 字符串

PFN_vkVoidFunction 的定义是

// Provided by VK_VERSION_1_0
typedef void (VKAPI_PTR *PFN_vkVoidFunction)(void);

此类型从命令函数指针查询返回,并且在使用前必须强制转换为实际的命令函数指针。

扩展物理设备核心功能

VkPhysicalDeviceProperties::apiVersionVkApplicationInfo::apiVersion 都大于或等于添加新功能的 Vulkan 版本时,可以使用新的核心物理设备级功能。物理设备支持的 Vulkan 版本可以通过调用 vkGetPhysicalDeviceProperties 来获得。

从设备扩展扩展物理设备

当启用 VK_KHR_get_physical_device_properties2 扩展时,或者当实例和物理设备版本都至少为 1.1 时,如果相应的扩展被该物理设备的 vkEnumerateDeviceExtensionProperties 枚举,则可以将设备扩展的物理设备级功能与物理设备一起使用,即使在创建逻辑设备之前也是如此。

要从设备扩展获取物理设备级命令的函数指针,应用程序可以使用 vkGetInstanceProcAddr。此函数指针可能指向调度代码,该代码为不同的 VkPhysicalDevice 对象调用不同的真实实现。应用程序必须不在任何由扩展或核心版本添加的且该物理设备不支持的命令中使用 VkPhysicalDevice

设备扩展可能定义可以添加到物理设备级命令的 pNext 链的结构。

实例

Vulkan 中没有全局状态,所有每个应用程序的状态都存储在 VkInstance 对象中。创建 VkInstance 对象会初始化 Vulkan 库,并允许应用程序将有关自身的信息传递给实现。

实例由 VkInstance 句柄表示

// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkInstance)

要查询实现支持的实例级功能的版本,请调用

// Provided by VK_VERSION_1_1
VkResult vkEnumerateInstanceVersion(
    uint32_t*                                   pApiVersion);
  • pApiVersion 是指向 uint32_t 的指针,它是实例级功能支持的 Vulkan 版本,编码方式如 版本号 中所述。

vkEnumerateInstanceVersion 的预期行为是,实现应该不需要执行内存分配,并且应该无条件返回 VK_SUCCESS。在内存分配失败的情况下,加载器和任何启用的层可能返回 VK_ERROR_OUT_OF_HOST_MEMORY

有效用法(隐式)
  • VUID-vkEnumerateInstanceVersion-pApiVersion-parameter
    pApiVersion 必须是指向 uint32_t 值的有效指针

返回代码
成功
  • VK_SUCCESS

失败
  • VK_ERROR_OUT_OF_HOST_MEMORY

要创建实例对象,请调用

// Provided by VK_VERSION_1_0
VkResult vkCreateInstance(
    const VkInstanceCreateInfo*                 pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkInstance*                                 pInstance);
  • pCreateInfo 是指向控制实例创建的 VkInstanceCreateInfo 结构的指针。

  • pAllocator 控制主机内存分配,如 内存分配 章节所述。

  • pInstance 指向 VkInstance 句柄,其中返回结果实例。

vkCreateInstance 验证请求的层是否存在。如果不存在,vkCreateInstance 将返回 VK_ERROR_LAYER_NOT_PRESENT。接下来,vkCreateInstance 验证是否支持请求的扩展(例如,在实现中或在任何启用的实例层中),如果不支持任何请求的扩展,vkCreateInstance 必须返回 VK_ERROR_EXTENSION_NOT_PRESENT。在验证并启用实例层和扩展之后,将创建 VkInstance 对象并返回给应用程序。如果请求的扩展仅由层支持,则需要在 vkCreateInstance 时同时指定层和扩展才能使创建成功。

有效用法
  • VUID-vkCreateInstance-ppEnabledExtensionNames-01388
    VkInstanceCreateInfo::ppEnabledExtensionNames 列表中每个扩展的 必需扩展必须在该列表中存在

有效用法(隐式)
  • VUID-vkCreateInstance-pCreateInfo-parameter
    pCreateInfo 必须是指向有效 VkInstanceCreateInfo 结构的有效指针

  • VUID-vkCreateInstance-pAllocator-parameter
    如果 pAllocator 不为 NULL,则 pAllocator 必须是指向有效 VkAllocationCallbacks 结构的有效指针

  • VUID-vkCreateInstance-pInstance-parameter
    pInstance 必须是指向 VkInstance 句柄的有效指针

返回代码
成功
  • VK_SUCCESS

失败
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_LAYER_NOT_PRESENT

  • VK_ERROR_EXTENSION_NOT_PRESENT

  • VK_ERROR_INCOMPATIBLE_DRIVER

VkInstanceCreateInfo 结构定义为

// Provided by VK_VERSION_1_0
typedef struct VkInstanceCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkInstanceCreateFlags       flags;
    const VkApplicationInfo*    pApplicationInfo;
    uint32_t                    enabledLayerCount;
    const char* const*          ppEnabledLayerNames;
    uint32_t                    enabledExtensionCount;
    const char* const*          ppEnabledExtensionNames;
} VkInstanceCreateInfo;
  • sType 是一个 VkStructureType 值,用于标识此结构。

  • pNextNULL 或指向扩展此结构的结构的指针。

  • flags 是一个 VkInstanceCreateFlagBits 的位掩码,指示实例的行为。

  • pApplicationInfoNULL 或指向 VkApplicationInfo 结构的指针。如果不是 NULL,此信息有助于实现识别应用程序类固有的行为。VkApplicationInfo 在下面详细定义。

  • enabledLayerCount 是要启用的全局层的数量。

  • ppEnabledLayerNames 是指向 enabledLayerCount 个以 null 结尾的 UTF-8 字符串数组的指针,其中包含要为创建的实例启用的层的名称。这些层按此数组中列出的顺序加载,第一个数组元素最接近应用程序,最后一个数组元素最接近驱动程序。有关更多详细信息,请参阅 部分。

  • enabledExtensionCount 是要启用的全局扩展的数量。

  • ppEnabledExtensionNames 是指向 enabledExtensionCount 个以 null 结尾的 UTF-8 字符串数组的指针,其中包含要启用的扩展的名称。

为了捕获创建或销毁实例时发生的事件,应用程序可以VkDebugReportCallbackCreateInfoEXT 结构体或 VkDebugUtilsMessengerCreateInfoEXT 结构体链接到传递给 vkCreateInstanceVkInstanceCreateInfo 结构体的 pNext 成员。此回调仅在 vkCreateInstancevkDestroyInstance 调用的持续时间内有效。使用 vkCreateDebugReportCallbackEXTvkCreateDebugUtilsMessengerEXT 来创建持久的回调对象。

应用程序可以通过将 VkDirectDriverLoadingListLUNARG 结构体添加到传递给 vkCreateInstanceVkInstanceCreateInfo 结构体的 pNext 成员来添加额外的驱动程序。

VkDirectDriverLoadingListLUNARG 允许应用程序随自身一起发布驱动程序。应仅使用设计为与它一起工作的驱动程序,例如在软件中实现 Vulkan 或通过将其转换为不同的 API 来实现 Vulkan 的驱动程序。不应使用任何需要安装的驱动程序,例如硬件驱动程序。

有效用法
有效用法(隐式)
// Provided by VK_VERSION_1_0
typedef enum VkInstanceCreateFlagBits {
  // Provided by VK_KHR_portability_enumeration
    VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR = 0x00000001,
} VkInstanceCreateFlagBits;
  • VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR 指定实例将枚举可用的符合 Vulkan 可移植性标准的物理设备和组,以及默认枚举的 Vulkan 物理设备和组。

// Provided by VK_VERSION_1_0
typedef VkFlags VkInstanceCreateFlags;

VkInstanceCreateFlags 是一个位掩码类型,用于设置零个或多个 VkInstanceCreateFlagBits 的掩码。

当创建一个你希望禁用验证检查的 Vulkan 实例时,将一个 VkValidationFlagsEXT 结构添加到 VkInstanceCreateInfo 结构的 pNext 链中,指定要禁用的检查。

// Provided by VK_EXT_validation_flags
typedef struct VkValidationFlagsEXT {
    VkStructureType                sType;
    const void*                    pNext;
    uint32_t                       disabledValidationCheckCount;
    const VkValidationCheckEXT*    pDisabledValidationChecks;
} VkValidationFlagsEXT;
  • sType 是一个 VkStructureType 值,用于标识此结构。

  • pNextNULL 或指向扩展此结构的结构的指针。

  • disabledValidationCheckCount 是要禁用的检查的数量。

  • pDisabledValidationChecks 是指向一个 VkValidationCheckEXT 值数组的指针,指定要禁用的验证检查。

有效用法(隐式)
  • VUID-VkValidationFlagsEXT-sType-sType
    sType 必须VK_STRUCTURE_TYPE_VALIDATION_FLAGS_EXT

  • VUID-VkValidationFlagsEXT-pDisabledValidationChecks-parameter
    pDisabledValidationChecks 必须 是一个有效的指针,指向一个包含 disabledValidationCheckCount 个有效 VkValidationCheckEXT 值的数组。

  • VUID-VkValidationFlagsEXT-disabledValidationCheckCount-arraylength
    disabledValidationCheckCount 必须 大于 0

VkValidationFlagsEXT::pDisabledValidationChecks 数组的元素可能的值,指定要禁用的验证检查,如下所示:

// Provided by VK_EXT_validation_flags
typedef enum VkValidationCheckEXT {
    VK_VALIDATION_CHECK_ALL_EXT = 0,
    VK_VALIDATION_CHECK_SHADERS_EXT = 1,
} VkValidationCheckEXT;
  • VK_VALIDATION_CHECK_ALL_EXT 指定禁用所有验证检查。

  • VK_VALIDATION_CHECK_SHADERS_EXT 指定禁用着色器验证。

当创建一个你希望启用或禁用特定验证功能的 Vulkan 实例时,将一个 VkValidationFeaturesEXT 结构添加到 VkInstanceCreateInfo 结构的 pNext 链中,指定要启用或禁用的功能。

// Provided by VK_EXT_validation_features
typedef struct VkValidationFeaturesEXT {
    VkStructureType                         sType;
    const void*                             pNext;
    uint32_t                                enabledValidationFeatureCount;
    const VkValidationFeatureEnableEXT*     pEnabledValidationFeatures;
    uint32_t                                disabledValidationFeatureCount;
    const VkValidationFeatureDisableEXT*    pDisabledValidationFeatures;
} VkValidationFeaturesEXT;
  • sType 是一个 VkStructureType 值,用于标识此结构。

  • pNextNULL 或指向扩展此结构的结构的指针。

  • enabledValidationFeatureCount 是要启用的功能的数量。

  • pEnabledValidationFeatures 是指向一个 VkValidationFeatureEnableEXT 值数组的指针,指定要启用的验证功能。

  • disabledValidationFeatureCount 是要禁用的功能的数量。

  • pDisabledValidationFeatures 是指向一个 VkValidationFeatureDisableEXT 值数组的指针,指定要禁用的验证功能。

有效用法
  • VUID-VkValidationFeaturesEXT-pEnabledValidationFeatures-02967
    如果 pEnabledValidationFeatures 数组包含 VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT,那么它必须也包含 VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXTVK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT

有效用法(隐式)
  • VUID-VkValidationFeaturesEXT-sType-sType
    sType 必须VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT

  • VUID-VkValidationFeaturesEXT-pEnabledValidationFeatures-parameter
    如果 enabledValidationFeatureCount 不为 0pEnabledValidationFeatures 必须 是一个有效的指针,指向一个包含 enabledValidationFeatureCount 个有效 VkValidationFeatureEnableEXT 值的数组。

  • VUID-VkValidationFeaturesEXT-pDisabledValidationFeatures-parameter
    如果 disabledValidationFeatureCount 不为 0pDisabledValidationFeatures 必须 是一个有效的指针,指向一个包含 disabledValidationFeatureCount 个有效 VkValidationFeatureDisableEXT 值的数组。

VkValidationFeaturesEXT::pEnabledValidationFeatures 数组的元素可能的值,指定要启用的验证功能,如下所示:

// Provided by VK_EXT_validation_features
typedef enum VkValidationFeatureEnableEXT {
    VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT = 0,
    VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT = 1,
    VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT = 2,
    VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT = 3,
    VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT = 4,
} VkValidationFeatureEnableEXT;
  • VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT 指定启用 GPU 辅助验证。 激活此功能会检测着色器程序以生成额外的诊断数据。 默认情况下,此功能处于禁用状态。

  • VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT 指定验证层为其自身使用保留一个描述符集绑定槽。 该层报告一个 VkPhysicalDeviceLimits::maxBoundDescriptorSets 的值,该值比设备报告的值小 1。如果设备仅支持绑定一个描述符集,则验证层不执行 GPU 辅助验证。 默认情况下,此功能处于禁用状态。

  • VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT 指定启用 Vulkan 最佳实践验证。 激活此功能会启用与 API 的常见误用相关的警告输出,但这些误用并非规范明确禁止的。默认情况下,此功能处于禁用状态。

  • VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT 指定层将处理着色器中的 debugPrintfEXT 操作,并将结果输出发送到调试回调。 默认情况下,此功能处于禁用状态。

  • VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT 指定启用 Vulkan 同步验证。 此功能报告由于读取或写入相同内存区域的操作(绘制、复制、调度、区块传输)之间缺少或不正确的同步操作而导致的资源访问冲突。 默认情况下,此功能处于禁用状态。

VkValidationFeaturesEXT::pDisabledValidationFeatures 数组的元素可能的值,指定要禁用的验证功能,如下所示:

// Provided by VK_EXT_validation_features
typedef enum VkValidationFeatureDisableEXT {
    VK_VALIDATION_FEATURE_DISABLE_ALL_EXT = 0,
    VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT = 1,
    VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT = 2,
    VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT = 3,
    VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT = 4,
    VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT = 5,
    VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT = 6,
    VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXT = 7,
} VkValidationFeatureDisableEXT;
  • VK_VALIDATION_FEATURE_DISABLE_ALL_EXT 指定禁用所有验证检查。

  • VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT 指定禁用运行时和独立的着色器验证。 此验证发生在 VkShaderCreateInfoEXTVkShaderModuleCreateInfo 中。 默认情况下,此功能处于启用状态。

  • VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT 指定禁用线程安全验证。 默认情况下,此功能处于启用状态。

  • VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT 指定禁用无状态参数验证。 默认情况下,此功能处于启用状态。

  • VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT 指定禁用对象生命周期验证。 默认情况下,此功能处于启用状态。

  • VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT 指定禁用核心验证检查。 默认情况下,此功能处于启用状态。 如果禁用此功能,则表示 VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT 也被禁用。

  • VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT 指定禁用对重复的非分派对象句柄的保护。 默认情况下,此功能处于启用状态。

  • VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXT 指定将不会缓存着色器验证结果,并且每次应用程序执行时都会验证每个着色器。 默认情况下,启用着色器验证缓存。

禁用参数验证和对象生命周期验证等检查会阻止报告可能导致其他验证检查行为不正确或崩溃的错误情况。 一些验证检查假设它们的输入已经有效,并且不总是重新验证它们。

VK_EXT_validation_features 扩展取代了 VK_EXT_validation_flags 扩展中提供的所有功能。

要创建一个具有特定图层设置配置的 Vulkan 实例,将 VkLayerSettingsCreateInfoEXT 结构添加到 VkInstanceCreateInfo 结构的 pNext 链中,指定要配置的设置。

// Provided by VK_EXT_layer_settings
typedef struct VkLayerSettingsCreateInfoEXT {
    VkStructureType             sType;
    const void*                 pNext;
    uint32_t                    settingCount;
    const VkLayerSettingEXT*    pSettings;
} VkLayerSettingsCreateInfoEXT;
  • sType 是一个 VkStructureType 值,用于标识此结构。

  • pNextNULL 或指向扩展此结构的结构的指针。

  • settingCount 是要配置的设置的数量。

  • pSettings 是指向 settingCountVkLayerSettingEXT 值的数组的指针,用于指定要配置的设置。

有效用法(隐式)
  • VUID-VkLayerSettingsCreateInfoEXT-sType-sType
    sType 必须VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT

  • VUID-VkLayerSettingsCreateInfoEXT-pSettings-parameter
    如果 settingCount 不为 0,则 pSettings 必须 是指向 settingCount 个有效 VkLayerSettingEXT 结构体的有效指针

VkLayerSettingsCreateInfoEXT::pSettings 数组的元素值,用于指定要配置的图层设置,如下:

// Provided by VK_EXT_layer_settings
typedef struct VkLayerSettingEXT {
    const char*              pLayerName;
    const char*              pSettingName;
    VkLayerSettingTypeEXT    type;
    uint32_t                 valueCount;
    const void*              pValues;
} VkLayerSettingEXT;
  • pLayerName 是指向以 null 结尾的 UTF-8 字符串的指针,该字符串命名要从中配置设置的图层。

  • pSettingName 是指向以 null 结尾的 UTF-8 字符串的指针,该字符串命名要配置的设置。图层未知的 pSettingName 值将被忽略。

  • type 是一个 VkLayerSettingTypeEXT 值,用于指定 pValues 值的类型。

  • valueCount 是用于配置图层设置的值的数量。

  • pValues 是指向 valueCount 个由 type 指示类型的值的数组的指针,用于配置图层设置。

当多个 VkLayerSettingsCreateInfoEXT 结构体被链接,并且相同的 pSettingName 被引用到相同的 pLayerName 时,将使用第一个引用的图层设置的值。

有效用法
  • VUID-VkLayerSettingEXT-valueCount-10070
    如果 valueCount 不为 0,则 pValues 必须 是指向 valueCount 个由 type 指示类型的值的数组的有效指针

有效用法(隐式)
  • VUID-VkLayerSettingEXT-pLayerName-parameter
    pLayerName 必须 是一个以 null 结尾的 UTF-8 字符串

  • VUID-VkLayerSettingEXT-pSettingName-parameter
    pSettingName 必须 是一个以 null 结尾的 UTF-8 字符串

  • VUID-VkLayerSettingEXT-type-parameter
    type 必须 是一个有效的 VkLayerSettingTypeEXT

VkLayerSettingEXT::type 的可能值,指定 VkLayerSettingEXT::pValues 中返回的数据类型,如下:

// Provided by VK_EXT_layer_settings
typedef enum VkLayerSettingTypeEXT {
    VK_LAYER_SETTING_TYPE_BOOL32_EXT = 0,
    VK_LAYER_SETTING_TYPE_INT32_EXT = 1,
    VK_LAYER_SETTING_TYPE_INT64_EXT = 2,
    VK_LAYER_SETTING_TYPE_UINT32_EXT = 3,
    VK_LAYER_SETTING_TYPE_UINT64_EXT = 4,
    VK_LAYER_SETTING_TYPE_FLOAT32_EXT = 5,
    VK_LAYER_SETTING_TYPE_FLOAT64_EXT = 6,
    VK_LAYER_SETTING_TYPE_STRING_EXT = 7,
} VkLayerSettingTypeEXT;
  • VK_LAYER_SETTING_TYPE_BOOL32_EXT 指定图层设置的类型为 VkBool32

  • VK_LAYER_SETTING_TYPE_INT32_EXT 指定图层设置的类型为有符号 32 位整数。

  • VK_LAYER_SETTING_TYPE_INT64_EXT 指定图层设置的类型为有符号 64 位整数。

  • VK_LAYER_SETTING_TYPE_UINT32_EXT 指定图层设置的类型为无符号 32 位整数。

  • VK_LAYER_SETTING_TYPE_UINT64_EXT 指定图层设置的类型为无符号 64 位整数。

  • VK_LAYER_SETTING_TYPE_FLOAT32_EXT 指定图层设置的类型为 32 位浮点数。

  • VK_LAYER_SETTING_TYPE_FLOAT64_EXT 指定图层设置的类型为 64 位浮点数。

  • VK_LAYER_SETTING_TYPE_STRING_EXT 指定图层设置的类型是指向以 null 结尾的 UTF-8 字符串的指针。

VkDirectDriverLoadingListLUNARG 结构体定义如下:

// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingListLUNARG {
    VkStructureType                           sType;
    const void*                               pNext;
    VkDirectDriverLoadingModeLUNARG           mode;
    uint32_t                                  driverCount;
    const VkDirectDriverLoadingInfoLUNARG*    pDrivers;
} VkDirectDriverLoadingListLUNARG;
  • sType 是一个 VkStructureType 值,用于标识此结构。

  • pNextNULL 或指向扩展此结构的结构的指针。

  • mode 控制加载所提供的驱动程序的模式。

  • driverCount 是驱动程序清单路径的数量。

  • pDrivers 是指向 driverCountVkDirectDriverLoadingInfoLUNARG 结构体数组的指针。

当创建一个要包含其他驱动程序的 Vulkan 实例时,将 VkDirectDriverLoadingListLUNARG 结构体添加到 VkInstanceCreateInfo 结构的 pNext 链中,并包含 VkDirectDriverLoadingInfoLUNARG 结构体的列表,其中包含加载其他驱动程序所需的信息。

有效用法(隐式)
  • VUID-VkDirectDriverLoadingListLUNARG-sType-sType
    sType 必须VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_LIST_LUNARG

  • VUID-VkDirectDriverLoadingListLUNARG-mode-parameter
    mode 必须 是一个有效的 VkDirectDriverLoadingModeLUNARG

  • VUID-VkDirectDriverLoadingListLUNARG-pDrivers-parameter
    pDrivers 必须 是指向 driverCount 个有效 VkDirectDriverLoadingInfoLUNARG 结构体的有效指针

  • VUID-VkDirectDriverLoadingListLUNARG-driverCount-arraylength
    driverCount 必须 大于 0

VkDirectDriverLoadingInfoLUNARG 结构体定义如下:

// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingInfoLUNARG {
    VkStructureType                     sType;
    void*                               pNext;
    VkDirectDriverLoadingFlagsLUNARG    flags;
    PFN_vkGetInstanceProcAddrLUNARG     pfnGetInstanceProcAddr;
} VkDirectDriverLoadingInfoLUNARG;
有效用法(隐式)
  • VUID-VkDirectDriverLoadingInfoLUNARG-sType-sType
    sType 必须VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_INFO_LUNARG

  • VUID-VkDirectDriverLoadingInfoLUNARG-flags-zerobitmask
    flags 必须0

VkDirectDriverLoadingListLUNARG::mode 的可能值,指定驱动程序的使用模式,如下:

// Provided by VK_LUNARG_direct_driver_loading
typedef enum VkDirectDriverLoadingModeLUNARG {
    VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG = 0,
    VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG = 1,
} VkDirectDriverLoadingModeLUNARG;
  • VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG 指定使用提供的驱动程序而不是系统加载的驱动程序。

  • VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG 指定除了系统加载的驱动程序外,还使用提供的驱动程序。

// Provided by VK_LUNARG_direct_driver_loading
typedef VkFlags VkDirectDriverLoadingFlagsLUNARG;

VkDirectDriverLoadingFlagsLUNARG 是用于设置掩码的位掩码类型,但目前保留供将来使用。

// Provided by VK_LUNARG_direct_driver_loading
typedef PFN_vkVoidFunction (VKAPI_PTR *PFN_vkGetInstanceProcAddrLUNARG)(
    VkInstance instance, const char* pName);
  • instance 是一个 VkInstance 句柄。

  • pName 是 Vulkan 命令的名称。

此类型与指向 vkGetInstanceProcAddr 命令的指针类型兼容,但仅用于指定 VkDirectDriverLoadingInfoLUNARG::pfnGetInstanceProcAddr 中的设备驱动程序地址。

此类型存在的原因仅仅是因为 XML 架构和处理脚本的限制,并且其名称将来可能会更改。理想情况下,我们将使用在 vulkan_core.h 头文件中生成的 PFN_vkGetInstanceProcAddr 类型。

VkApplicationInfo 结构体定义如下:

// Provided by VK_VERSION_1_0
typedef struct VkApplicationInfo {
    VkStructureType    sType;
    const void*        pNext;
    const char*        pApplicationName;
    uint32_t           applicationVersion;
    const char*        pEngineName;
    uint32_t           engineVersion;
    uint32_t           apiVersion;
} VkApplicationInfo;
  • sType 是一个 VkStructureType 值,用于标识此结构。

  • pNextNULL 或指向扩展此结构的结构的指针。

  • pApplicationNameNULL 或指向包含应用程序名称的以 null 结尾的 UTF-8 字符串的指针。

  • applicationVersion 是一个无符号整数变量,包含开发人员提供的应用程序版本号。

  • pEngineNameNULL 或指向包含用于创建应用程序的引擎名称(如果有)的以 null 结尾的 UTF-8 字符串的指针。

  • engineVersion 是一个无符号整数变量,包含开发人员提供的用于创建应用程序的引擎版本号。

  • apiVersion 必须 是应用程序设计使用的最高 Vulkan 版本,其编码方式如 版本号 中所述。创建实例对象时,apiVersion 中指定的补丁版本号将被忽略。实例的变体版本必须apiVersion 中请求的版本匹配。

如果 apiVersion 大于 1.0,Vulkan 1.0 实现必须返回 VK_ERROR_INCOMPATIBLE_DRIVER。支持 Vulkan 1.1 或更高版本的实现必须对于任何 apiVersion 的值都不返回 VK_ERROR_INCOMPATIBLE_DRIVER

由于 Vulkan 1.0 实现可能会失败并返回 VK_ERROR_INCOMPATIBLE_DRIVER,应用程序在调用 vkCreateInstance 之前应该确定可用的 Vulkan 版本。如果 vkGetInstanceProcAddr 对于 vkEnumerateInstanceVersion 返回 NULL,则表明这是一个 Vulkan 1.0 实现。否则,应用程序可以调用 vkEnumerateInstanceVersion 来确定 Vulkan 的版本。

只要实例支持至少 Vulkan 1.1,应用程序可以在实例中使用与设备或物理设备不同的 Vulkan 版本。

Khronos 验证层会将 apiVersion 视为应用程序的目标最高 API 版本,并将根据该版本和实现版本(取决于上下文,可能是实例或设备)中的最小值来验证 API 使用情况。如果应用程序尝试使用高于此版本的特性,则会触发验证错误。

例如,如果实例支持 Vulkan 1.1,并且三个物理设备分别支持 Vulkan 1.0、Vulkan 1.1 和 Vulkan 1.2,并且如果应用程序将 apiVersion 设置为 1.2,则应用程序可以使用以下 Vulkan 版本:

  • Vulkan 1.0 可以用于实例和所有物理设备。

  • Vulkan 1.1 可以用于实例以及支持 Vulkan 1.1 和 Vulkan 1.2 的物理设备。

  • Vulkan 1.2 可以用于支持 Vulkan 1.2 的物理设备。

如果我们修改上述示例,使应用程序将 apiVersion 设置为 1.1,那么应用程序必须不在支持 Vulkan 1.2 的物理设备上使用 Vulkan 1.2 的功能。

提供 NULL VkInstanceCreateInfo::pApplicationInfo 或提供 apiVersion 为 0 等同于提供 apiVersionVK_MAKE_API_VERSION(0,1,0,0)

有效用法
  • VUID-VkApplicationInfo-apiVersion-04010
    如果 apiVersion 不为 0,则它必须大于或等于 VK_API_VERSION_1_0

有效用法(隐式)
  • VUID-VkApplicationInfo-sType-sType
    sType 必须VK_STRUCTURE_TYPE_APPLICATION_INFO

  • VUID-VkApplicationInfo-pNext-pNext
    pNext 必须NULL

  • VUID-VkApplicationInfo-pApplicationName-parameter
    如果 pApplicationName 不为 NULL,则 pApplicationName 必须是以 null 结尾的 UTF-8 字符串

  • VUID-VkApplicationInfo-pEngineName-parameter
    如果 pEngineName 不为 NULL,则 pEngineName 必须是以 null 结尾的 UTF-8 字符串

要销毁实例,请调用

// Provided by VK_VERSION_1_0
void vkDestroyInstance(
    VkInstance                                  instance,
    const VkAllocationCallbacks*                pAllocator);
  • instance 是要销毁的实例的句柄。

  • pAllocator 控制主机内存分配,如 内存分配 章节所述。

有效用法
  • VUID-vkDestroyInstance-instance-00629
    使用 instance 创建的所有子对象必须在销毁 instance 之前销毁

  • VUID-vkDestroyInstance-instance-00630
    如果在创建 instance 时提供了 VkAllocationCallbacks,则此处必须提供一组兼容的回调

  • VUID-vkDestroyInstance-instance-00631
    如果在创建 instance 时未提供 VkAllocationCallbacks,则 pAllocator 必须NULL

有效用法(隐式)
  • VUID-vkDestroyInstance-instance-parameter
    如果 instance 不是 NULL,则 instance 必须是有效的 VkInstance 句柄

  • VUID-vkDestroyInstance-pAllocator-parameter
    如果 pAllocator 不为 NULL,则 pAllocator 必须是指向有效 VkAllocationCallbacks 结构的有效指针

主机同步
  • instance 的主机访问必须在外部同步

  • 对从 instance 枚举的所有 VkPhysicalDevice 对象的主机访问必须在外部同步