dev merge to main

.github/workflows/release.yml

@@ -25,6 +25,8 @@ jobs:
           pip install sphinx_last_updated_by_git
           pip install sphinx_design
           pip install sphinx-comments
+          pip install setuptools
+          pip install sphinxcontrib-images
       - name: Build
         run: |
           make html

source/Changelog.md

@@ -4,6 +4,21 @@
 此更新日志为纵览更新，对于具体文章的更新位于每个文章的开头的 `更新记录` 中。
 ```
 
+## 2024/4/14
+
+>* 更新`资源`文档
+>* 增加`相关链接`文档
+>* 更新`欢迎来到 Vulkan 入门精要`文档
+
+## 2024/4/13
+
+>* 更新`内存`文档
+>* 更新`资源`文档
+
+## 2024/4/10
+
+>* 更新`资源`文档
+
 ## 2024/4/9
 
 >* 更新`资源`文档

source/InformalEssay/SomeLinks.rst

@@ -0,0 +1,8 @@
+相关链接
+================
+
+.. dropdown:: 更新记录
+   :color: muted
+   :icon: history
+
+   * 2023/4/14 增加该文章

source/Memory.rst

@@ -58,7 +58,9 @@
    * 2024/3/24 增加 ``设备内存同步到虚拟内存`` 章节。
    * 2024/3/24 ``设备内存同步到虚拟内存`` 章节，增加 ``示例`` 章节。
    * 2024/3/26 更新 ``内存映射`` 章节。
-   * 2024/3/26 增加 ``vkUnmapMemory`` 章节标题。
+   * 2024/3/26 增加 ``vkUnmapMemory`` 章节。
+   * 2024/4/13 增加 ``惰性内存`` 章节。
+   * 2024/4/13 增加 ``vkGetDeviceMemoryCommitment`` 章节。
 
 ``Vulkan`` 中有两种分配内存的途径：
 
@@ -925,14 +927,43 @@ VkMemoryPropertyFlagBits
 
    具体如何进行内存同步将会在之后的章节进行讲解。
 
-.. admonition:: 惰性内存
-   :class: important
+惰性内存
+^^^^^^^^^^^^^^^^^^^^
 
-   当使用 ``VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`` 类型分配内存时，表示底层分配 ``惰性内存`` 。所谓惰性内存是表示在该内存分配时其大小可以为 ``0`` 也可以为申请的内存大小。当该内存被需要时，其内存大小会随着需求单调增加。
-
-   *该类型内存平时用的不多*。
+当使用 ``VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`` 类型分配内存时，表示底层分配为 ``惰性内存`` 。所谓惰性内存表示：在该内存分配时，其底层内存占用大小可以为 ``0`` 也可以为申请的内存大小。当该内存被需要时，其内存大小会随着需求单调增加。
+
+.. note::
+
+   某些设备 :bdg-danger:`没有` 提供支持 ``VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`` 类型的内存。所以该类型内存平时用的不多。
+
+且惰性内存有如下限制：
+
+* :bdg-danger:`只有` ``Device`` 端能够访问该内存
+* 分配的 ``VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`` 惰性内存类型中不能包含 ``VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT`` （ ``VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`` 与 ``VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT`` 为互斥关系，不能同时存在）。
+* 只能用于 ``VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT`` 的图片进行绑定（这意味着 ``缓存`` 资源不存在使用惰性内存的情况）。（具体可参阅 `资源 <./Resource.html>`_ 文档）。
+
+查询一个惰性内存挡墙占有的内存大小，可通过 ``vkGetDeviceMemoryCommitment(...)`` 函数获取到，其定义如下：
+
+vkGetDeviceMemoryCommitment
+""""""""""""""""""""""""""""""""""""
+
+.. code:: c++
+
+   // 由 VK_VERSION_1_0 提供
+   void vkGetDeviceMemoryCommitment(
+       VkDevice                                    device,
+       VkDeviceMemory                              memory,
+       VkDeviceSize*                               pCommittedMemoryInBytes);
+
+* :bdg-secondary:`device` 对应的逻辑设备。
+* :bdg-secondary:`memory` 对应的设备内存。其 :bdg-danger:`必须` 以 ``VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`` 内存类型进行分配的惰性内存。
+* :bdg-secondary:`pCommittedMemoryInBytes` 指定的 ``memory`` 当前的大小将会写入其中。单位为 ``字节`` 。
+
+.. note::
+
+   驱动会随时更新占用的大小，所以该函数返回的惰性内存大小值将会在不久失效。
 
-如下，为一种可能的设备内存类型获取结果：
+如下，为一种可能的 ``设备内存类型`` 获取结果：
 
 .. _memory_heap_and_type:
 

source/Resource.rst

@@ -32,6 +32,15 @@
    * 2024/4/6 增加 ``图片资源逻辑模型`` 章节。
    * 2024/4/6 增加 ``VkImageTiling`` 章节。
    * 2024/4/9 更新 ``图片资源逻辑模型`` 章节。
+   * 2024/4/10 增加 ``VkImageUsageFlagBits`` 章节。
+   * 2024/4/13 增加 ``多级渐远`` 章节。
+   * 2024/4/14 更新 ``多级渐远`` 章节。
+   * 2024/4/14 更新 ``VkExtent3D`` 章节。
+   * 2024/4/14 更新 ``VkImageCreateInfo`` 章节。
+   * 2024/4/14 更新 ``VkImageUsageFlagBits`` 章节。
+   * 2024/4/14 增加 ``格式属性`` 章节。
+   * 2024/4/14 更新 ``VkImageTiling`` 章节。
+   * 2024/4/14 增加 ``vkGetPhysicalDeviceFormatProperties`` 章节。
 
 在 ``Vulkan`` 中只有 ``2`` 种资源 :
 
@@ -392,8 +401,8 @@ VkImageCreateInfo
 * :bdg-secondary:`imageType` 图片资源的类型。
 * :bdg-secondary:`format` 该图片资源的纹素格式。
 * :bdg-secondary:`extent` 该图片资源（各维度上的）大小。
-* :bdg-secondary:`mipLevels` 多级渐远纹理级别。
-* :bdg-secondary:`arrayLayers` 层级数量。
+* :bdg-secondary:`mipLevels` 多级渐远纹理级别。 :bdg-danger:`必须` 大于 ``0`` 。
+* :bdg-secondary:`arrayLayers` 层级数量。 :bdg-danger:`必须` 大于 ``0`` 。
 * :bdg-secondary:`samples` 采样点数量。
 * :bdg-secondary:`tiling` 瓦片排布。
 * :bdg-secondary:`usage` 该图片资源的用途。
@@ -486,9 +495,9 @@ VkExtent3D
        uint32_t    depth;
    } VkExtent3D;
 
-* :bdg-secondary:`width` 宽。
-* :bdg-secondary:`height` 高。
-* :bdg-secondary:`depth` 深度。
+* :bdg-secondary:`width` 宽。 :bdg-danger:`必须` 大于 ``0`` 。
+* :bdg-secondary:`height` 高。 :bdg-danger:`必须` 大于 ``0`` 。
+* :bdg-secondary:`depth` 深度。 :bdg-danger:`必须` 大于 ``0`` 。
 
 当 ``VkImageCreateInfo::imageType`` 为 ``VkImageType::VK_IMAGE_TYPE_1D`` 时，其大小规则如下：
 
@@ -743,6 +752,50 @@ VkSampleCountFlagBits
 
    ``arrayLayers`` :bdg-danger:`不可以` 随意指定数量，有一些限制。将会在之后的章节说明。
 
+多级渐远
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+在 ``VkImageCreateInfo`` 中有一个 ``mipLevels`` 参数。该参数用于设置该图片的 ``多级渐远纹理级别`` 。
+
+当使用透视投影（近大远小）相机加看向场景进行渲染时：
+
+* 离相机近的物体会比较大，占用更多的像素。此时由于离相机近，使用分辨率较高的纹理将会获得更佳清晰的渲染结果。
+* 离相机远的物体会比较小，占用更少的像素。此时由于离相机较远，使用分辨率较高的纹理在如此小范围的像素范围内采样将会导致效果锐化。为了减少这种锐化，最简单的方式就是使用一个相对较低分辨率的图片进行采样。
+
+随着距离采样不同分辨率图片的技术叫做 ``多级渐远`` ，支持这种技术的图片叫做 ``多级渐远纹理（图片）`` 。
+
+如下为 :bdg-danger:`不使用` 和 :bdg-danger:`使用` 多级渐远纹理的结果示意图：
+
+.. list-table::
+
+    * - .. figure:: ./_static/mip_mapping_off.jpg
+
+           无多级渐远效果示意
+
+      - .. figure:: ./_static/mip_mapping_anisotropic.jpg
+
+           多级渐远效果示意
+
+为了生成一系列低分辨率的图片，需要通过 ``VkImageCreateInfo::mipLevels`` 指定要为低分辨率图片分配的级别，每一个级别都对应一张新图片，下一级别图片的分辨率是上一级别图片分辨率的一半。
+
+.. note::
+
+   当 ``VkImageCreateInfo::mipLevels`` 为 ``1`` 时表示图片自身即为 ``一级渐远纹理`` 。
+
+如下为一张二维图片的 ``多级渐远级别`` 为 ``4`` 的多级渐远纹理结构示意图：
+
+* :bdg-secondary:`W` 为一级渐远纹理（图片其本身）宽度。
+* :bdg-secondary:`H` 为一级渐远纹理（图片其本身）高度。
+
+.. figure:: ./_static/image_level.png
+
+   二维图片多级渐远纹理结构示意图
+
+.. admonition:: 多级渐远纹理内部数据
+   :class: note
+
+   如上示意图中各级的渐远纹理中每个像素都是有确切图像值的，这些只是帮助您从逻辑上理解多级渐远，但是在实际通过 ``vkCreateImage(...)`` 创建带有多级渐远纹理中，图片数据全都是初始值（可能为 ``0`` ）。每一级别的多级渐远图片中每个像素具体为何值，需要通过执行 ``GPU指令`` 手动运算赋值。这将会在之后的章节进行讲解。
+
 VkImageTiling
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -759,9 +812,9 @@ VkImageTiling
 
 在 :ref:`Buffer` 章节我们已经知道缓存资源在 ``Host端`` 和 ``Device端`` 其为了更高的效率，内部的结构是不同的，图片资源也是如此。
 
-当使用 ``VkImageTiling::VK_IMAGE_TILING_OPTIMAL`` 时，用于指示该图片资源将会使用 ``Device端`` 内部偏爱的结构（驱动内部结构）进行创建。
+当使用 ``VkImageTiling::VK_IMAGE_TILING_OPTIMAL`` 时，用于指示该图片资源将会使用 ``Device端`` 内部偏爱的结构（驱动内部结构）进行创建。这一般在 ``GPU`` 上高速并行读写计算时使用。
 
-当使用 ``VkImageTiling::VK_IMAGE_TILING_LINEAR`` 时，用于指示该图片资源将会使用 ``Host端`` 偏爱的线性结构进行创建。这一般用于 ``CPU`` 读写图片资源数据时使用。
+当使用 ``VkImageTiling::VK_IMAGE_TILING_LINEAR`` 时，用于指示该图片资源将会使用 ``Host端`` 偏爱的线性结构进行创建。这一般在 ``CPU`` 读写图片资源数据时使用。
 
 ..
    VK_IMAGE_TILING_LINEAR限制
@@ -770,4 +823,94 @@ VkImageTiling
    mipLevels is 1
    arrayLayers is 1
    samples is VK_SAMPLE_COUNT_1_BIT
-   usage only includes VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or VK_IMAGE_USAGE_TRANSFER_DST_BIT
+   usage only includes VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or VK_IMAGE_USAGE_TRANSFER_DST_BIT
+
+其中 ``VkImageCreateInfo::usage`` 标志位的有效值定义在 ``VkImageUsageFlagBits`` 枚举中，其定义如下：
+
+VkImageUsageFlagBits
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: c++
+
+   // 由 VK_VERSION_1_0 提供
+   typedef enum VkImageUsageFlagBits {
+       VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
+       VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
+       VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
+       VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
+       VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
+       VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
+       VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
+       VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
+   } VkImageUsageFlagBits;
+
+* :bdg-secondary:`VK_IMAGE_USAGE_TRANSFER_SRC_BIT` 该图片用于数据传输的数据源。
+* :bdg-secondary:`VK_IMAGE_USAGE_TRANSFER_DST_BIT` 该图片用于数据传输的目的数据。
+* :bdg-secondary:`VK_IMAGE_USAGE_SAMPLED_BIT` 该图片用于（纹素）采样（读取）。
+* :bdg-secondary:`VK_IMAGE_USAGE_STORAGE_BIT` 该图片用于（纹素）数据存储（也可以读）。
+* :bdg-secondary:`VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT` 该图片用于颜色附件。
+* :bdg-secondary:`VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT` 该图片用于深度-模板附件。
+* :bdg-secondary:`VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT` 该图片用于临时附件。该附件支持与 ``VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`` 属性的（惰性）内存进行交互。
+* :bdg-secondary:`VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT` 该图片用于输入附件。既可以用于采样（读取），也可以用于存储。与 ``VK_IMAGE_USAGE_STORAGE_BIT`` 不同的是可以用于附件。
+
+.. admonition:: 采样
+   :class: note
+
+   图片采样就是获取图片中某一坐标位置像素的值。
+
+.. admonition:: 附件
+   :class: note
+
+   所有的 ``附件`` 都是用于存储 ``GPU`` 的输出数据。在 ``Vulkan`` 中有 ``4`` 种附件：
+
+   * :bdg-secondary:`VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT` 颜色附件。用于存储 ``GPU`` 在渲染图形后的输出数据。主要以颜色的形式（ ``rgba`` 等）进行存储。
+   * :bdg-secondary:`VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT` 深度-模板附件。用于存储 ``GPU`` 在渲染图形后输出的深度-模板数据。主要以深度-模板的形式（浮点数-整数）进行存储。
+   * :bdg-secondary:`VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT` 临时附件。主要用于与 ``惰性内存`` 进行交互。当图片资源确定只在 ``GPU`` 端进行读写时，可以使用该类型。
+   * :bdg-secondary:`VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT` 输入附件。既可以用于采样（读取），也可以用于存储。与 ``VK_IMAGE_USAGE_STORAGE_BIT`` 不同的是可以用于附件。与其他附件类型不同的是，该附件类型原生支持 ``读`` 操作。
+
+   更多 ``附件`` 说明将会在之后的 ``管线`` 和 ``帧缓冲（存）`` 中进行展开。
+
+.. admonition:: 图片读写
+   :class: note
+
+   ``VkImageUsageFlagBits`` 中有些枚举值对应的图片用途或都支持读，或都支持写，但不同类型的图片用途在读写途径上不尽相同。这将会在之后的章节展开。
+
+现在基本上将 ``VkImageCreateInfo`` 中相关的核心概念过了一遍，但目前还有一个问题需要解决：
+
+.. admonition:: 问题
+   :class: hint
+
+   ``VkImageCreateInfo::format`` 具体应该如何选取正确的格式进行设置？
+
+格式属性
+-----------------------
+
+在 ``VkFormat`` 中有各种各样的格式，每种格式都代表着不同的数据布局和数据类型。相应 ``VkImageCreateInfo::format`` 的选择也会跟着 ``VkImageCreateInfo::usage`` 中指定的图片用途的不同而不同。
+
+为此我们需要知道哪些格式在何种情况下会被使用。这就需要我们知道各种格式的属性。如果我们能够获取某一格式的属性，我们就能知道该格式支持何种使用方式。
+
+在 ``Vulkan`` 中为我们提供了 ``vkGetPhysicalDeviceFormatProperties(...)`` 函数，用于获取某一格式的属性数据。其定义如下：
+
+vkGetPhysicalDeviceFormatProperties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: c++
+
+   // 由 VK_VERSION_1_0 提供
+   void vkGetPhysicalDeviceFormatProperties(
+       VkPhysicalDevice                            physicalDevice,
+       VkFormat                                    format,
+       VkFormatProperties*                         pFormatProperties);
+
+.. note:: 未完待续
+
+.. 
+   获取支持的格式
+      vkGetPhysicalDeviceFormatProperties
+
+   图片创建示例
+   哪些格式支持颜色
+   哪些格式支持深度
+
+   imageview 和 bufferview 在单独的章节展开（在资源与内存之后）
+

source/conf.py

@@ -16,6 +16,7 @@
 
 extensions = [
     'sphinxcontrib.mermaid', 
+    'sphinxcontrib.images',
     'myst_parser', 
     'sphinx_copybutton',
     'sphinx_inline_tabs',

source/index.rst

@@ -23,6 +23,7 @@
    * 2024/1/2 增加 ``内存`` 文档链接
    * 2024/1/2 增加 ``资源`` 文档链接
    * 2024/1/2 增加 ``资源与内存`` 文档链接
+   * 2024/4/14 增加 ``相关链接`` 文章链接
 
 .. image:: https://img.shields.io/badge/QQ%20Group-128656761-deepgreen?logo=tencentqq
    :target: https://jq.qq.com/?_wv=1027&k=rZGd2LHr
@@ -98,6 +99,7 @@
    ./InformalEssay/index.rst
    ./InformalEssay/VulkanForAndroid.rst
    ./InformalEssay/VSCode.rst
+   ./InformalEssay/SomeLinks.rst
 
 .. toctree::
    :caption: 工程应用

source/test.rst

@@ -514,4 +514,9 @@ Lorem ipsum [Ref]_ dolor sit amet.
    try2_stmt: "try" ":" `suite`
             : "finally" ":" `suite`
 
-It refers to the section itself, see :ref:`my-reference-label`.
+It refers to the section itself, see :ref:`my-reference-label`.
+
+.. thumbnail:: ./_static/memory_heap_and_type.png
+   :align: center
+
+    设备内存类型示意图