From 7c997f74e4726ae6170fc8fdbb3d0937f855e9a8 Mon Sep 17 00:00:00 2001 From: FuXiii Date: Fri, 26 Jan 2024 00:01:22 +0800 Subject: [PATCH] Update source\Instance.rst --- source/Changelog.md | 4 ++ source/Instance.rst | 127 +++++++++++++++++++++++++++++++++++++++++++- source/Overview.rst | 2 +- 3 files changed, 131 insertions(+), 2 deletions(-) diff --git a/source/Changelog.md b/source/Changelog.md index 8de4aa5..3b0bb01 100644 --- a/source/Changelog.md +++ b/source/Changelog.md @@ -4,6 +4,10 @@ 此更新日志为纵览更新，对于具体文章的更新位于每个文章的开头的 `更新记录` 中。 ``` +## 2024/1/25 + +>* 更新`最初之物 VkInstance`文档 + ## 2024/1/20 >* 更新`纵览`文档 diff --git a/source/Instance.rst b/source/Instance.rst index ad24b65..efdf4f8 100644 --- a/source/Instance.rst +++ b/source/Instance.rst @@ -5,4 +5,129 @@ :color: muted :icon: history - * 2024/1/2 增加该文档 \ No newline at end of file + * 2024/1/2 增加该文档。 + * 2024/1/25 更新该文档。 + * 2024/1/25 增加 ``创建 VkInstance`` 章节。 + * 2024/1/25 增加 ``vkCreateInstance`` 章节。 + * 2024/1/25 增加 ``VkInstanceCreateInfo`` 章节。 + * 2024/1/25 增加 ``VkApplicationInfo`` 章节。 + * 2024/1/25 增加 ``vkEnumerateInstanceVersion`` 章节。 + +开发 ``Vulkan`` 第一步就是创建 ``VkInstance`` ，也就是 ``Vulkan`` 的 ``实例`` 。一个实例代表一整 ``Vulkan`` 环境（或上下文）。不同的 ``Vulkan`` 环境能够获取到不同的 ``Vulkan`` 功能特性。其中最重要的就是配置 ``Vulkan`` 要使用的 ``版本`` 。 + +创建 VkInstance +###################### + +通过 ``vkCreateInstance(...)`` 函数创建 ``VkInstance`` ： + +vkCreateInstance +************************* + +.. code:: c++ + + // 由 VK_VERSION_1_0 提供 + VkResult vkCreateInstance( + const VkInstanceCreateInfo* pCreateInfo, + const VkAllocationCallbacks* pAllocator, + VkInstance* pInstance); + +* :bdg-secondary:`pCreateInfo` 指向 ``VkInstanceCreateInfo`` 数据结构对象，用于配置 ``VkInstance`` 的创建信息。 +* :bdg-secondary:`pAllocator` 内存分配器。为 ``nullptr`` 表示使用内部默认分配器，否则为自定义分配器。 +* :bdg-secondary:`pInstance` 返回创建的目标 ``VkInstance`` 结果。 + +其中 ``VkInstanceCreateInfo`` 结构体定义如下： + +VkInstanceCreateInfo +************************* + +.. code:: c++ + + // 由 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; + +* :bdg-secondary:`sType` 是该结构体的类型枚举值， :bdg-danger:`必须` 是 ``VkStructureType::VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO`` 。 +* :bdg-secondary:`pNext` 要么是 ``NULL`` 要么指向其他结构体来扩展该结构体。 +* :bdg-secondary:`flags` 是 ``VkInstanceCreateFlagBits`` 所表示的位域值，用于设置 ``VkInstance`` 的行为。 +* :bdg-secondary:`pApplicationInfo` 要么是 ``NULL`` 要么指向应用信息结构体，用于应用细节设置。 +* :bdg-secondary:`enabledLayerCount` 激活的 ``layer`` 数量。 +* :bdg-secondary:`ppEnabledLayerNames` 指向数量为 ``enabledLayerCount`` 的 ``layer`` 字符串数组，用于设置要激活的 ``layer``。 +* :bdg-secondary:`enabledExtensionCount` 激活 ``instance`` 扩展的数量。 +* :bdg-secondary:`enabledExtensionCount` 指向数量为 ``enabledExtensionCount`` 的扩展字符串数组，用于设置要激活的 ``instance`` 扩展。 + +其中 ``VkApplicationInfo`` 结构体定义如下： + +VkApplicationInfo +************************* + +.. code:: c++ + + // 由 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; + +* :bdg-secondary:`sType` 是该结构体的类型枚举值， :bdg-danger:`必须` 是 ``VkStructureType::VK_STRUCTURE_TYPE_APPLICATION_INFO`` 。 +* :bdg-secondary:`pNext` 要么是 ``NULL`` 要么指向其他结构体来扩展该结构体。 +* :bdg-secondary:`pApplicationName` 要么是 ``NULL`` 要么指向一个以空字符为结尾的 ``UTF-8`` 字符串，用于表示用户自定义应用名称。 +* :bdg-secondary:`applicationVersion` 一个无符号整型，用于用户自定义应用版本。 +* :bdg-secondary:`pEngineName` 要么是 ``NULL`` 要么指向一个以空字符为结尾的 ``UTF-8`` 字符串，用于表示用户自定义引擎名称。 +* :bdg-secondary:`engineVersion` 一个无符号整型，用于用户自定义引擎版本。 +* :bdg-secondary:`apiVersion` 应用打算使用的 ``Vulkan`` 的最高 :bdg-danger:`核心` 版本，并且忽略 ``apiVersion`` 的 ``patch`` 版本。 + +其中 ``pApplicationName`` 、 ``applicationVersion`` 、 ``pEngineName`` 和 ``engineVersion`` 这几个值随便设置，甚至可以不设置，赋为 ``空`` 都可以，这些参数不影响实例的创建。 + +而 ``apiVersion`` 参数是 :bdg-danger:`最为重要的核心参数` ，当创建实例时，该参数用于指定此实例环境中 ``Vulkan`` 的 :bdg-danger:`核心` ``版本`` 。目前 ``Vulkan`` 有 ``3`` 个版本： + +* ``Vulkan 1.0`` 主要提供光栅化图形和并行计算的功能。对应 ``VK_API_VERSION_1_0`` 。 +* ``Vulkan 1.1`` 主要为 ``Vulkan 1.0`` 不完善的地方进行补全。对应 ``VK_API_VERSION_1_1`` 。 +* ``Vulkan 1.2`` 主要提供硬件光追的功能。对应 ``VK_API_VERSION_1_2`` 。 +* ``Vulkan 1.3`` 主要提供动态光栅化图形的功能。对应 ``VK_API_VERSION_1_3`` 。 + +每个 ``Vulkan`` 新版本的发布不单单提供基本功能，还会提供一系列扩展功能，并且会将之前版本中的一些扩展功能提升囊括至核心版本中。 ``VkApplicationInfo::apiVersion`` 将会在调用 ``vkCreateInstance`` 时告诉驱动将使用的 ``Vulkan`` 版本，驱动会为您做好必要的初始化。 + +如果想要使用的功能为高版本中的功能，而创建实例时 ``VkApplicationInfo::apiVersion`` 指定的是低版本，此时如果获取高版本的功能函数大概率会返回 ``空`` 。所以 ``VkApplicationInfo::apiVersion`` 尽可能的设置为自己需要的高版本。比如： + + 如果 ``VkApplicationInfo::apiVersion`` 设置为 ``VK_API_VERSION_1_0`` 则表示可以使用该实例在 ``Vulkan Loader`` 中加载 ``Vulkan 1.0`` 版本发布的函数，而不能加载 ``Vulkan 1.1`` 及高版本的接口函数。如下： + + .. code:: c++ + + // 由 VK_VERSION_1_0 提供 + vkCmdCopyImageToBuffer(...) // 该函数为 Vulkan 1.0 版本中的函数，可以加载（可有效加载）。 + + // 由 VK_VERSION_1_3 提供 + vkCmdCopyImageToBuffer2(...) // 该函数为 Vulkan 1.3 版本中的函数，不可以加载（加载将返回空）。 + +在 `纵览 <./Overview.html>`_ 中我们知道由于历史原因， ``Vulkan`` 在 ``Vulkan 1.1`` 版本时推出了 ``vkEnumerateInstanceVersion(...)`` 函数，用于获取驱动支持加载 ``Instance 域函数`` 的 ``Vulkan`` 版本。该函数定义如下： + +vkEnumerateInstanceVersion +****************************** + +.. code:: c++ + + // 由 VK_VERSION_1_0 提供 + VkResult vkEnumerateInstanceVersion( + uint32_t* pApiVersion); + +* :bdg-secondary:`pApiVersion` 返回支持的 ``Instance 域函数`` 对应的 ``Vulkan`` 版本。 + +.. admonition:: vkEnumerateInstanceVersion + :class: note + + * 该函数为全局函数。 + * 该函数返回的版本为可获取的 ``Instance 域函数`` 所对应的版本。 + * 与物理设备（ ``GPU`` ）支持的 ``Vulkan`` 版本可能会不同。 \ No newline at end of file diff --git a/source/Overview.rst b/source/Overview.rst index ae1523e..f8f0e1a 100644 --- a/source/Overview.rst +++ b/source/Overview.rst @@ -700,7 +700,7 @@ VkApplicationInfo uint32_t apiVersion; } VkApplicationInfo; -* :bdg-secondary:`sType` 是该结构体的类型枚举值， :bdg-danger:`必须`是 ``VkStructureType::VK_STRUCTURE_TYPE_APPLICATION_INFO`` 。 +* :bdg-secondary:`sType` 是该结构体的类型枚举值， :bdg-danger:`必须` 是 ``VkStructureType::VK_STRUCTURE_TYPE_APPLICATION_INFO`` 。 * :bdg-secondary:`pNext` 要么是 ``NULL`` 要么指向其他结构体来扩展该结构体。 * :bdg-secondary:`pApplicationName` 要么是 ``NULL`` 要么指向一个以空字符为结尾的 ``UTF-8`` 字符串，用于表示用户自定义应用名称。 * :bdg-secondary:`applicationVersion` 一个无符号整型，用于用户自定义应用版本。