Add Specialization Constants

Author: Mysvac

docs/codes/04/11_specialization/GraphicsPipeline.cppm

@@ -0,0 +1,181 @@
+module;
+
+#include <memory>
+#include <vector>
+
+export module GraphicsPipeline;
+
+import vulkan_hpp;
+
+import DataLoader;
+import Utility;
+import Device;
+import RenderPass;
+
+export namespace vht {
+
+    /**
+     * @brief 图形管线相关
+     * @details
+     * - 依赖：
+     *  - m_device: 逻辑设备与队列
+     *  - m_render_pass: 渲染通道
+     * - 工作：
+     *  - 创建描述符集布局
+     *  - 创建图形管线布局和图形管线
+     * - 可访问成员：
+     *  - descriptor_set_layout(): 描述符集布局
+     *  - pipeline_layout(): 管线布局
+     *  - pipeline(): 图形管线
+     */
+    class GraphicsPipeline {
+        std::shared_ptr<vht::Device> m_device;
+        std::shared_ptr<vht::RenderPass> m_render_pass;
+        vk::raii::DescriptorSetLayout m_descriptor_set_layout{ nullptr };
+        vk::raii::PipelineLayout m_pipeline_layout{ nullptr };
+        vk::raii::Pipeline m_pipeline{ nullptr };
+    public:
+        explicit GraphicsPipeline(std::shared_ptr<vht::Device> device, std::shared_ptr<vht::RenderPass> render_pass)
+        :   m_device(std::move(device)),
+            m_render_pass(std::move(render_pass)) {
+            init();
+        }
+
+        [[nodiscard]]
+        const vk::raii::DescriptorSetLayout& descriptor_set_layout() const { return m_descriptor_set_layout; }
+        [[nodiscard]]
+        const vk::raii::PipelineLayout& pipeline_layout() const { return m_pipeline_layout; }
+        [[nodiscard]]
+        const vk::raii::Pipeline& pipeline() const { return m_pipeline; }
+
+    private:
+        void init() {
+            create_descriptor_set_layout();
+            create_graphics_pipeline();
+        }
+        // 创建描述符集布局
+        void create_descriptor_set_layout() {
+            vk::DescriptorSetLayoutBinding ubo_layout_binging;
+            ubo_layout_binging.binding = 0;
+            ubo_layout_binging.descriptorType = vk::DescriptorType::eUniformBuffer;
+            ubo_layout_binging.descriptorCount = 1;
+            ubo_layout_binging.stageFlags = vk::ShaderStageFlagBits::eVertex;
+
+            vk::DescriptorSetLayoutBinding sampler_layout_binding;
+            sampler_layout_binding.binding = 1;
+            sampler_layout_binding.descriptorType = vk::DescriptorType::eCombinedImageSampler;
+            sampler_layout_binding.descriptorCount = 1;
+            sampler_layout_binding.stageFlags = vk::ShaderStageFlagBits::eFragment;
+
+            auto bindings = { ubo_layout_binging, sampler_layout_binding };
+            vk::DescriptorSetLayoutCreateInfo layoutInfo;
+            layoutInfo.setBindings( bindings );
+
+            m_descriptor_set_layout = m_device->device().createDescriptorSetLayout( layoutInfo );
+        }
+        // 创建图形管线
+        void create_graphics_pipeline() {
+            const auto vertex_shader_code = vht::read_shader("shaders/vert.spv");
+            const auto fragment_shader_code = vht::read_shader("shaders/frag.spv");
+            const auto vertex_shader_module = vht::create_shader_module(m_device->device(), vertex_shader_code);
+            const auto fragment_shader_module = vht::create_shader_module(m_device->device(), fragment_shader_code);
+            vk::PipelineShaderStageCreateInfo vertex_shader_create_info;
+            vertex_shader_create_info.stage = vk::ShaderStageFlagBits::eVertex;
+            vertex_shader_create_info.module = vertex_shader_module;
+            vertex_shader_create_info.pName = "main";
+
+            // 1. 数据源
+            float my_color = 0.4f;
+            // 2. 特化映射条目
+            vk::SpecializationMapEntry mapEntry;
+            mapEntry.constantID = 0; // 对应 GLSL 中的 constant_id 和 SPIR-V 中的 SpecId
+            mapEntry.offset     = 0; // 源数据的起始偏移量
+            mapEntry.size       = sizeof(float);
+            // 3. 特化信息
+            vk::SpecializationInfo specializationInfo;
+            specializationInfo.setMapEntries(mapEntry);
+            specializationInfo.setData<float>(my_color);
+            // 此模板设置了 指针 和 数据大小 ，不能放右值
+
+            vk::PipelineShaderStageCreateInfo fragment_shader_create_info; // 片段着色器
+            fragment_shader_create_info.stage = vk::ShaderStageFlagBits::eFragment;
+            fragment_shader_create_info.module = fragment_shader_module;
+            fragment_shader_create_info.pName = "main";
+            fragment_shader_create_info.pSpecializationInfo = &specializationInfo; // 特化信息
+
+            const auto shader_stages = { vertex_shader_create_info, fragment_shader_create_info };
+
+            const auto dynamic_states = { vk::DynamicState::eViewport, vk::DynamicState::eScissor };
+            vk::PipelineDynamicStateCreateInfo dynamic_state;
+            dynamic_state.setDynamicStates(dynamic_states);
+
+            auto binding_description = vht::Vertex::get_binding_description();
+            auto attribute_description = vht::Vertex::get_attribute_description();
+            vk::PipelineVertexInputStateCreateInfo vertex_input;
+            vertex_input.setVertexBindingDescriptions(binding_description);
+            vertex_input.setVertexAttributeDescriptions(attribute_description);
+
+            vk::PipelineInputAssemblyStateCreateInfo input_assembly;
+            input_assembly.topology = vk::PrimitiveTopology::eTriangleList;
+
+            vk::PipelineViewportStateCreateInfo viewport_state;
+            viewport_state.viewportCount = 1;
+            viewport_state.scissorCount = 1;
+
+            vk::PipelineDepthStencilStateCreateInfo depth_stencil;
+            depth_stencil.depthTestEnable = true;
+            depth_stencil.depthWriteEnable = true;
+            depth_stencil.depthCompareOp = vk::CompareOp::eLess;
+            depth_stencil.depthBoundsTestEnable = false; // Optional
+            depth_stencil.stencilTestEnable = false; // Optional
+
+            vk::PipelineRasterizationStateCreateInfo rasterizer;
+            rasterizer.depthClampEnable = false;
+            rasterizer.rasterizerDiscardEnable = false;
+            rasterizer.polygonMode = vk::PolygonMode::eFill;
+            rasterizer.lineWidth = 1.0f;
+            rasterizer.cullMode = vk::CullModeFlagBits::eBack;
+            rasterizer.frontFace = vk::FrontFace::eCounterClockwise;
+            rasterizer.depthBiasEnable = false;
+
+            vk::PipelineMultisampleStateCreateInfo multisampling;
+            multisampling.rasterizationSamples =  vk::SampleCountFlagBits::e1;
+            multisampling.sampleShadingEnable = false;  // default
+
+            vk::PipelineColorBlendAttachmentState color_blend_attachment;
+            color_blend_attachment.blendEnable = false; // default
+            color_blend_attachment.colorWriteMask = vk::FlagTraits<vk::ColorComponentFlagBits>::allFlags;
+
+            vk::PipelineColorBlendStateCreateInfo color_blend;
+            color_blend.logicOpEnable = false;
+            color_blend.logicOp = vk::LogicOp::eCopy;
+            color_blend.setAttachments( color_blend_attachment );
+
+            vk::PipelineLayoutCreateInfo layout_create_info;
+            layout_create_info.setSetLayouts( *m_descriptor_set_layout );
+            m_pipeline_layout = m_device->device().createPipelineLayout( layout_create_info );
+
+            vk::GraphicsPipelineCreateInfo create_info;
+            create_info.setStages( shader_stages );
+
+            create_info.layout = m_pipeline_layout;
+
+
+            create_info.pVertexInputState =  &vertex_input;
+            create_info.pInputAssemblyState = &input_assembly;
+            create_info.pDynamicState = &dynamic_state;
+            create_info.pViewportState = &viewport_state;
+            create_info.pDepthStencilState = &depth_stencil;
+            create_info.pRasterizationState = &rasterizer;
+            create_info.pMultisampleState = &multisampling;
+            create_info.pColorBlendState = &color_blend;
+
+            create_info.renderPass = m_render_pass->render_pass();
+            create_info.subpass = 0;
+
+            m_pipeline = m_device->device().createGraphicsPipeline( nullptr, create_info );
+        }
+    };
+}
+
+

docs/codes/04/11_specialization/GraphicsPipeline.diff

@@ -0,0 +1,13 @@
+#version 450
+// 提供默认值 0.0
+layout (constant_id = 0) const float myColor = 0.0;
+
+layout(binding = 1) uniform sampler2D texSampler;
+
+layout(location = 0) in vec2 fragTexCoord;
+
+layout(location = 0) out vec4 outColor;
+
+void main() {
+    outColor = vec4(texture(texSampler, fragTexCoord).xy, myColor, 1.0);
+}

docs/codes/04/11_specialization/shader.frag

@@ -6,16 +6,17 @@ comments: true
 
 ## **教程简介**
 
-本文档是 Vulkan 的入门教程，将系统讲解 Vulkan 图形与计算 API 的基础知识与实际应用。
+本文档是 Vulkan 的入门教程，将介绍 Vulkan 图形与计算 API 的基础知识与实际应用。
 
-教程将使用 C++ 编写代码，借助 Vulkan-Hpp 封装，充分利用 RAII 等现代 C++ 特性，减少手动资源管理。
+文档以代码演示为主，你可以在 **[Vulkan Guide](https://docs.vulkan.org/guide/latest/index.html)** 等网站找到更详细的 Vulkan 规范和概念介绍。
+
+教程将使用 C++ 编写代码， C++20 标准，使用 Vulkan-SDK 内含的 Vulkan-Hpp 封装，充分利用 RAII 等现代 C++ 特性。
 
-> 注：Vulkan-Hpp 是 Vulkan SDK 的官方组成部分，非第三方库。  
 > 如果你发现了文档的错误，请点击右上角前往Github仓库，提交 Issue 或 PR 。
 
 ## **代码说明**
 
-教程将采用 C++20 标准，主要使用以下工具链：
+教程不限操作系统、代码编辑器与 C++ 编译器，主要使用以下工具链：
 
 - [Vulkan SDK](https://lunarg.com/vulkan-sdk/)
 - [GLM](http://glm.g-truc.net/) 线性代数库
@@ -29,24 +30,34 @@ comments: true
 
 `Vcpkg` 用于管理第三方库，主要用于安装 `glfw3` 和 `glm` 等依赖，这非常简单。
 
+> 教程预期在 C++23 标准完全支持后，使用 23 标准重构内容。
+
 ## **其他说明**
 
 Vulkan SDK 本身由 C 编写，因此具有更好的跨语言兼容性，可通过 C 接口供其他语言调用。
 
 如果你更喜欢 C 风格的底层接口，或希望使用 Rust：
 
-- 基于底层C接口的C++教程：[Vulkan-tutorial](https://vulkan-tutorial.com/)
+- 基于底层C接口的C++教程： [Vulkan-tutorial](https://vulkan-tutorial.com/)
 
-- 基于Vulkano封装的Rust教程 [Vulkan-tutorial-rs](https://github.com/bwasty/vulkan-tutorial-rs)
+- 基于Vulkano封装的Rust教程： [Vulkan-tutorial-rs](https://github.com/bwasty/vulkan-tutorial-rs)
 
 ## **致谢**
 
-项目文档与知识点参考以下内容：
+本文档内容参考了许多公开的资料以及课程，在此感谢：
+
+- [Vulkan-Hpp](https://github.com/KhronosGroup/Vulkan-Hpp) 
 
-- [vulkan-hpp](https://github.com/KhronosGroup/Vulkan-Hpp) 
+- [Vulkan-Guide](https://docs.vulkan.org/guide/latest/index.html)
 
 - [Vulkan-Tutorial](https://github.com/Overv/VulkanTutorial) 
 
 - [EasyVulkan](https://easyvulkan.github.io/index.html) 
 
+- [GAMES101-现代计算机图形学入门\(闫令琪\)](https://www.bilibili.com/video/BV1X7411F744)
+
+- [GAMES202-高质量实时渲染\(闫令琪\)](https://www.bilibili.com/video/BV1YK4y1T7yY)
+
+- [GAMES104-现代游戏引擎：从入门到实践\(王希\)](https://games104.boomingtech.com/sc/)
+
 ---

docs/images/0411/blue_room.png

@@ -32,7 +32,7 @@ comments: true
 ## **学习前提**
 
 ### 硬件要求
-- 支持 Vulkan 的显卡（NVIDIA/AMD/Intel/Apple Silicon）
+- 支持 Vulkan 的设备（大部分现代显卡都支持）
 - 较新的显卡驱动
 
 ### 软件技能

docs/images/0411/yellow_room.png

@@ -148,6 +148,9 @@ void cleanup() {
 
 ---
 
+需要说明的是，基础部分的代码重点用于功能演示，因此可能忽略**可选**的 const 与 static 等 C++ 标识符细节。
+但进阶部分会提供尽量优雅的基础代码框架。
+
 这个基础框架为后续开发奠定了良好基础，接下来可以开始初始化 Vulkan 实例和设备。
 
 ---

docs/index.md

@@ -26,8 +26,7 @@ private:
 
 现在直接构建与运行程序，请保证程序不出错。
 
-> RAII机制参考“接口介绍”章节。
-
+> 更加详细的 Loader 介绍可以参考 [Vulkan-Guide \[Loader\]](https://docs.vulkan.org/guide/latest/loader.html) 文档。
 
 ## **创建实例**
 
@@ -150,9 +149,9 @@ createInfo.ppEnabledExtensionNames = requiredExtensions.data();
 ### 2. 特殊setter函数说明
 
 由于数组类型传参时会隐式退化成指针，底层C风格接口都使用“开始指针+元素数量”的方式引用数组。
-vulkan-hpp 需要调用底层C接口，所以这些配置信息采用相同的方式记录。
+Vulkan-Hpp 需要调用底层C接口，所以这些配置信息采用相同的方式记录。
 
-但 vulkan-hpp 提供了一些特殊的 `setter` 成员函数，它们通过 `vk::ArrayProxyNoTemporaries` 模板参数简化了数组参数的设置，
+但 Vulkan-Hpp 提供了一些特殊的 `setter` 成员函数，它们通过 `vk::ArrayProxyNoTemporaries` 模板参数简化了数组参数的设置，
 这些函数能够自动处理数组参数：
 
    - 接收任意连续容器（`std::vector`、`std::array`、原生数组）或初始化列表。

docs/md/00/00_intro.md

@@ -13,14 +13,6 @@ Vulkan API 的设计理念: **尽量减少驱动程序开销**
 
 Vulkan 引入了一个优雅的系统来实现程序检查，称为 **验证层\(Validation Layer\)**。
 
-它是 Vulkan 的核心调试工具，通过拦截API调用来实现：
-
-- **参数验证**：检查参数合法性和规范符合性
-- **资源追踪**：监控资源生命周期和泄漏
-- **线程安全**：验证多线程调用合规性
-- **性能分析**：记录调用耗时和频率
-- **调试输出**：提供详细的运行时信息
-
 以下是诊断验证层中函数实现的一个简化示例
 
 ```cpp
@@ -50,12 +42,7 @@ VkResult vkCreateInstance_WithValidation(
 
 你可以**在调试时启用验证层**，在**发布时完全禁用它**，两全其美！！
 
-> Vulkan 本身不附带任何内置的验证层，但 LunarG Vulkan SDK 提供了一组很好的验证层，用于检查常见错误。
-> 它们是完全开源的，你可以查看它们能够检查哪些的错误或做出贡献。
-> 
-> Vulkan 以前有两种不同类型的验证层：实例特定和设备特定。  
-> 设备特定层现在已被弃用，这意味着实例验证层适用于所有 Vulkan 调用。  
-> 你依然可以启用设备级验证层，但它会被最新的 API 忽略。
+> Vulkan 本身不附带任何内置的验证层，但 LunarG Vulkan SDK 提供了一组开源的验证层，用于检查常见错误。
 
 ## **使用验证层**
 
@@ -133,11 +120,13 @@ void createInstance() {
 
 ```cpp
 if (enableValidationLayers) {
+    // 使用 setter 同时设置指针和数量两个成员变量
     createInfo.setPEnabledLayerNames( validationLayers );
 }
 ```
 
-> 我们用了上一节提到的 `setter` ，它实际设置了指针和数量这两个成员变量。
+> Vulkan 以前有两种不同类型的“层\(layer\)”：实例特定和设备特定。  
+> 设备特定层现在已被弃用，这意味着实例验证层适用于所有 Vulkan 调用。
 
 ## **设置调试回调**
 
@@ -195,7 +184,7 @@ static VKAPI_ATTR VkBool32 VKAPI_CALL debugMessageFunc(
 }
 ```
 
-此函数只做了一件事，把验证层反馈数据中的信息输出到标准错误流。
+此函数只做了一件事，把验证层反馈数据中的信息输出到标准错误流，你可以自行添加内容。
 
 ### 3. 函数参数说明
 

docs/md/01/00_base.md

@@ -4,9 +4,11 @@ comments: true
 ---
 # **物理设备与队列族**
 
-在创建实例之后，我们需要查找并选择系统中合适的物理设备\(通常指 GPU \)。
+在创建实例之后，我们需要查找并选择系统中合适的物理设备\(常指显卡\)。
 实际上，我们可以选择任意数量的显卡并同时使用它们，但在本教程中，我们只使用第一张满足我们需求的显卡。
 
+> 相关概念：[Vulkan-Guide \[Querying Properties, Extensions, Features ...\]](https://docs.vulkan.org/guide/latest/querying_extensions_features.html)
+
 ## **选择物理设备**
 
 ### 1. 成员变量与辅助函数
@@ -143,12 +145,15 @@ bool isDeviceSuitable(const vk::raii::PhysicalDevice& physicalDevice) {
 
 Vulkan 中的几乎每个操作，从绘制到上传纹理，都需要将命令提交到队列。
 
-### 1. 队列查找函数
 
 队列有不同的类型，这些类型源自不同的队列族，并且每个队列族仅允许一些特定的命令。
 例如，可能有一个队列族仅允许处理计算命令，或者一个队列族仅允许与内存传输相关的命令。
 
-为此，我们将添加一个新函数 `findQueueFamilies` ，用于查找我们需要的所有队列族。
+> 更详细的概念：[Vulkan-Guide \[Queues\]](https://docs.vulkan.org/guide/latest/queues.html)
+
+### 1. 队列查找函数
+
+我们需要添加一个新函数 `findQueueFamilies` ，用于查找我们需要的所有队列族。
 
 现在我们只打算查找支持图形命令的队列族，因此该函数可能如下所示：