Split up pipeline creation, update docs

karnkaul · karnkaul · commit 21d4adceb133 · 2025-03-25T22:21:25.000-07:00
diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
@@ -27,4 +27,4 @@
 - [Graphics Pipeline](pipeline/README.md)
   - [Locating Assets](pipeline/locating_assets.md)
   - [Shaders](pipeline/shaders.md)
-  - [Pipeline Creation](pipeline/creation.md)
+  - [Pipeline Creation](pipeline/pipeline_creation.md)
diff --git a/guide/src/pipeline/pipeline_creation.md b/guide/src/pipeline/pipeline_creation.md
@@ -59,92 +59,140 @@ class PipelineBuilder {
 };
 ```
 
-Implement `build()`:
+Before implementing `build()`, add some helper functions/constants, starting with the viewport and dynamic states:
 
 ```cpp
-auto PipelineBuilder::build(vk::PipelineLayout const layout,
-              PipelineState const& state) const
-  -> vk::UniquePipeline {
+// single viewport and scissor.
+constexpr auto viewport_state_v =
+  vk::PipelineViewportStateCreateInfo({}, 1, {}, 1);
+
+// these dynamic states are guaranteed to be available.
+constexpr auto dynamic_states_v = std::array{
+  vk::DynamicState::eViewport,
+  vk::DynamicState::eScissor,
+  vk::DynamicState::eLineWidth,
+};
+```
+
+The shader stages:
+
+```cpp
+[[nodiscard]] constexpr auto
+create_shader_stages(vk::ShaderModule const vertex,
+           vk::ShaderModule const fragment) {
   // set vertex (0) and fragment (1) shader stages.
-  auto shader_stages = std::array<vk::PipelineShaderStageCreateInfo, 2>{};
-  shader_stages[0]
+  auto ret = std::array<vk::PipelineShaderStageCreateInfo, 2>{};
+  ret[0]
     .setStage(vk::ShaderStageFlagBits::eVertex)
     .setPName("main")
-    .setModule(state.vertex_shader);
-  shader_stages[1]
+    .setModule(vertex);
+  ret[1]
     .setStage(vk::ShaderStageFlagBits::eFragment)
     .setPName("main")
-    .setModule(state.fragment_shader);
-
-  auto pvisci = vk::PipelineVertexInputStateCreateInfo{};
-  pvisci.setVertexAttributeDescriptions(state.vertex_attributes)
-      .setVertexBindingDescriptions(state.vertex_bindings);
+    .setModule(fragment);
+  return ret;
+}
+```
 
-  auto prsci = vk::PipelineRasterizationStateCreateInfo{};
-  prsci.setPolygonMode(state.polygon_mode).setCullMode(state.cull_mode);
+The depth/stencil state:
 
-  auto pdssci = vk::PipelineDepthStencilStateCreateInfo{};
+```cpp
+[[nodiscard]] constexpr auto
+create_depth_stencil_state(std::uint8_t flags,
+               vk::CompareOp const depth_compare) {
+  auto ret = vk::PipelineDepthStencilStateCreateInfo{};
   auto const depth_test =
-    (state.flags & PipelineFlag::DepthTest) == PipelineFlag::DepthTest;
-  pdssci.setDepthTestEnable(depth_test ? vk::True : vk::False)
-    .setDepthCompareOp(state.depth_compare);
+    (flags & PipelineFlag::DepthTest) == PipelineFlag::DepthTest;
+  ret.setDepthTestEnable(depth_test ? vk::True : vk::False)
+    .setDepthCompareOp(depth_compare);
+  return ret;
+}
+```
 
-  auto const piasci =
-    vk::PipelineInputAssemblyStateCreateInfo{{}, state.topology};
+And a color blend attachment:
 
-  auto pcbas = vk::PipelineColorBlendAttachmentState{};
+```cpp
+[[nodiscard]] constexpr auto
+create_color_blend_attachment(std::uint8_t const flags) {
+  auto ret = vk::PipelineColorBlendAttachmentState{};
   auto const alpha_blend =
-    (state.flags & PipelineFlag::AlphaBlend) == PipelineFlag::AlphaBlend;
+    (flags & PipelineFlag::AlphaBlend) == PipelineFlag::AlphaBlend;
   using CCF = vk::ColorComponentFlagBits;
-  pcbas.setColorWriteMask(CCF::eR | CCF::eG | CCF::eB | CCF::eA)
+  ret.setColorWriteMask(CCF::eR | CCF::eG | CCF::eB | CCF::eA)
     .setBlendEnable(alpha_blend ? vk::True : vk::False)
+    // standard alpha blending:
+    // (alpha * src) + (1 - alpha) * dst
     .setSrcColorBlendFactor(vk::BlendFactor::eSrcAlpha)
     .setDstColorBlendFactor(vk::BlendFactor::eOneMinusSrcAlpha)
     .setColorBlendOp(vk::BlendOp::eAdd)
     .setSrcAlphaBlendFactor(vk::BlendFactor::eOne)
     .setDstAlphaBlendFactor(vk::BlendFactor::eZero)
     .setAlphaBlendOp(vk::BlendOp::eAdd);
-  auto pcbsci = vk::PipelineColorBlendStateCreateInfo{};
-  pcbsci.setAttachments(pcbas);
-
-  // these dynamic states are guaranteed to be available.
-  auto const pdscis = std::array{
-    vk::DynamicState::eViewport,
-    vk::DynamicState::eScissor,
-    vk::DynamicState::eLineWidth,
-  };
-  auto pdsci = vk::PipelineDynamicStateCreateInfo{};
-  pdsci.setDynamicStates(pdscis);
+  return ret;
+}
+```
+
+Now we can implement `build()`:
+
+```cpp
+auto PipelineBuilder::build(vk::PipelineLayout const layout,
+              PipelineState const& state) const
+  -> vk::UniquePipeline {
+  auto const shader_stage_ci =
+    create_shader_stages(state.vertex_shader, state.fragment_shader);
 
-  // single viewport and scissor.
-  auto const pvsci = vk::PipelineViewportStateCreateInfo({}, 1, {}, 1);
+  auto vertex_input_ci = vk::PipelineVertexInputStateCreateInfo{};
+  vertex_input_ci.setVertexAttributeDescriptions(state.vertex_attributes)
+    .setVertexBindingDescriptions(state.vertex_bindings);
 
-  auto pmsci = vk::PipelineMultisampleStateCreateInfo{};
-  pmsci.setRasterizationSamples(m_info.samples)
+  auto multisample_state_ci = vk::PipelineMultisampleStateCreateInfo{};
+  multisample_state_ci.setRasterizationSamples(m_info.samples)
     .setSampleShadingEnable(vk::False);
 
-  auto prci = vk::PipelineRenderingCreateInfo{};
-  // could be a depth-only pass.
+  auto const input_assembly_ci =
+    vk::PipelineInputAssemblyStateCreateInfo{{}, state.topology};
+
+  auto rasterization_state_ci = vk::PipelineRasterizationStateCreateInfo{};
+  rasterization_state_ci.setPolygonMode(state.polygon_mode)
+    .setCullMode(state.cull_mode);
+
+  auto const depth_stencil_state_ci =
+    create_depth_stencil_state(state.flags, state.depth_compare);
+
+  auto const color_blend_attachment =
+    create_color_blend_attachment(state.flags);
+  auto color_blend_state_ci = vk::PipelineColorBlendStateCreateInfo{};
+  color_blend_state_ci.setAttachments(color_blend_attachment);
+
+  auto dynamic_state_ci = vk::PipelineDynamicStateCreateInfo{};
+  dynamic_state_ci.setDynamicStates(dynamic_states_v);
+
+  // Dynamic Rendering requires passing this in the pNext chain.
+  auto rendering_ci = vk::PipelineRenderingCreateInfo{};
+  // could be a depth-only pass, argument is span-like (notice the plural
+  // `Formats()`), only set if not Undefined.
   if (m_info.color_format != vk::Format::eUndefined) {
-    prci.setColorAttachmentFormats(m_info.color_format);
+    rendering_ci.setColorAttachmentFormats(m_info.color_format);
   }
-  prci.setDepthAttachmentFormat(m_info.depth_format);
-
-  auto gpci = vk::GraphicsPipelineCreateInfo{};
-  gpci.setStages(shader_stages)
-    .setPRasterizationState(&prsci)
-    .setPDepthStencilState(&pdssci)
-    .setPInputAssemblyState(&piasci)
-    .setPColorBlendState(&pcbsci)
-    .setPDynamicState(&pdsci)
-    .setPViewportState(&pvsci)
-    .setPMultisampleState(&pmsci)
-    .setLayout(layout)
-    .setPNext(&prci);
+  // single depth attachment format, ok to set to Undefined.
+  rendering_ci.setDepthAttachmentFormat(m_info.depth_format);
+
+  auto pipeline_ci = vk::GraphicsPipelineCreateInfo{};
+  pipeline_ci.setLayout(layout)
+    .setStages(shader_stage_ci)
+    .setPVertexInputState(&vertex_input_ci)
+    .setPViewportState(&viewport_state_v)
+    .setPMultisampleState(&multisample_state_ci)
+    .setPInputAssemblyState(&input_assembly_ci)
+    .setPRasterizationState(&rasterization_state_ci)
+    .setPDepthStencilState(&depth_stencil_state_ci)
+    .setPColorBlendState(&color_blend_state_ci)
+    .setPDynamicState(&dynamic_state_ci)
+    .setPNext(&rendering_ci);
 
   auto ret = vk::Pipeline{};
   // use non-throwing API.
-  if (m_info.device.createGraphicsPipelines({}, 1, &gpci, {}, &ret) !=
+  if (m_info.device.createGraphicsPipelines({}, 1, &pipeline_ci, {}, &ret) !=
     vk::Result::eSuccess) {
     return {};
   }
@@ -195,15 +243,17 @@ if (!m_pipeline) {
 }
 ```
 
-We can now bind it and use it to draw the triangle in the shader. Since we used dynamic viewport and scissor during pipeline creation, we need to set those after binding the pipeline.
+We can now bind it and use it to draw the triangle in the shader:
 
 ```cpp
 command_buffer.beginRendering(rendering_info);
 ImGui::ShowDemoWindow();
 
 command_buffer.bindPipeline(vk::PipelineBindPoint::eGraphics, *m_pipeline);
+// we are creating pipelines with dynamic viewport and scissor states.
+// they must be set here after binding (before drawing).
 auto viewport = vk::Viewport{};
-// flip the viewport across the X-axis (negative height):
+// flip the viewport about the X-axis (negative height):
 // https://www.saschawillems.de/blog/2019/03/29/flipping-the-vulkan-viewport/
 viewport.setX(0.0f)
   .setY(static_cast<float>(m_render_target->extent.height))
@@ -242,6 +292,8 @@ layout (location = 0) in vec3 in_color;
 out_color = vec4(in_color, 1.0);
 ```
 
+> Make sure to recompile both the SPIR-V shaders in assets/.
+
 And a black clear color:
 
 ```cpp
diff --git a/guide/src/pipeline/shaders.md b/guide/src/pipeline/shaders.md
@@ -37,6 +37,8 @@ glslc src/glsl/shader.vert -o assets/shader.vert
 glslc src/glsl/shader.frag -o assets/shader.frag
 ```
 
+> glslc is part of the Vulkan SDK.
+
 ## Shader Modules
 
 SPIR-V modules are binary files with a stride/alignment of 4 bytes. The Vulkan API accepts a span of `std::uint32_t`s, so we need to load it into such a buffer (and _not_ `std::vector<std::byte>` or other 1-byte equivalents).
diff --git a/src/app.cpp b/src/app.cpp
@@ -303,8 +303,10 @@ void App::render(vk::CommandBuffer const command_buffer) {
 	ImGui::ShowDemoWindow();
 
 	command_buffer.bindPipeline(vk::PipelineBindPoint::eGraphics, *m_pipeline);
+	// we are creating pipelines with dynamic viewport and scissor states.
+	// they must be set here after binding (before drawing).
 	auto viewport = vk::Viewport{};
-	// flip the viewport across the X-axis (negative height):
+	// flip the viewport about the X-axis (negative height):
 	// https://www.saschawillems.de/blog/2019/03/29/flipping-the-vulkan-viewport/
 	viewport.setX(0.0f)
 		.setY(static_cast<float>(m_render_target->extent.height))
diff --git a/src/pipeline_builder.cpp b/src/pipeline_builder.cpp
