Cleanup, wireframe

Author: karnkaul

guide/src/SUMMARY.md

@@ -28,3 +28,5 @@
   - [Locating Assets](pipeline/locating_assets.md)
   - [Shaders](pipeline/shaders.md)
   - [Pipeline Creation](pipeline/pipeline_creation.md)
+  - [Drawing a Triangle](pipeline/drawing_triangle.md)
+  - [Switching Pipelines](pipeline/switching_pipelines.md)

guide/src/pipeline/drawing_triangle.md

@@ -0,0 +1,138 @@
+# Drawing a Triangle
+
+We shall create two pipelines: one for standard draws, one for wireframe draws. Add new `App` members:
+
+```cpp
+void create_pipeline_builder();
+void create_pipelines();
+
+// ...
+std::optional<PipelineBuilder> m_pipeline_builder{};
+
+vk::UniquePipelineLayout m_pipeline_layout{};
+struct {
+  vk::UniquePipeline standard{};
+  vk::UniquePipeline wireframe{};
+} m_pipelines{};
+float m_line_width{1.0f};
+bool m_wireframe{};
+```
+
+Implement and call `create_pipeline_builder()`:
+
+```cpp
+void App::create_pipeline_builder() {
+  auto const pipeline_builder_ci = PipelineBuilder::CreateInfo{
+    .device = *m_device,
+    .samples = vk::SampleCountFlagBits::e1,
+    .color_format = m_swapchain->get_format(),
+  };
+  m_pipeline_builder.emplace(pipeline_builder_ci);
+}
+```
+
+Complete the implementation of `create_pipelines()`:
+
+```cpp
+// ...
+m_pipeline_layout = m_device->createPipelineLayoutUnique({});
+
+auto pipeline_state = PipelineState{
+  .vertex_shader = *vertex,
+  .fragment_shader = *fragment,
+};
+m_pipelines.standard =
+  m_pipeline_builder->build(*m_pipeline_layout, pipeline_state);
+pipeline_state.polygon_mode = vk::PolygonMode::eLine;
+m_pipelines.wireframe =
+  m_pipeline_builder->build(*m_pipeline_layout, pipeline_state);
+if (!m_pipelines.standard || !m_pipelines.wireframe) {
+  throw std::runtime_error{"Failed to create Graphics Pipelines"};
+}
+```
+
+Before `render()` grows to an unwieldy size, extract the higher level logic into two member functions:
+
+```cpp
+// ImGui code goes here.
+void inspect();
+// Issue draw calls here.
+void draw(vk::Rect2D const& render_area,
+      vk::CommandBuffer command_buffer) const;
+
+// ...
+void App::inspect() {
+  ImGui::ShowDemoWindow();
+  // TODO
+}
+
+// ...
+command_buffer.beginRendering(rendering_info);
+inspect();
+draw(render_area, command_buffer);
+command_buffer.endRendering();
+```
+
+We can now bind a pipeline and use it to draw the triangle in the shader. Making `draw()` `const` forces us to ensure no `App` state is changed:
+
+```cpp
+void App::draw(vk::Rect2D const& render_area,
+         vk::CommandBuffer const command_buffer) const {
+  command_buffer.bindPipeline(vk::PipelineBindPoint::eGraphics,
+              *m_pipelines.standard);
+  // 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 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))
+    .setWidth(static_cast<float>(m_render_target->extent.width))
+    .setHeight(-viewport.y);
+  command_buffer.setViewport(0, viewport);
+  command_buffer.setScissor(0, render_area);
+  // current shader has hard-coded logic for 3 vertices.
+  command_buffer.draw(3, 1, 0, 0);
+}
+```
+
+![White Triangle](./white_triangle.png)
+
+Updating our shaders to use interpolated RGB on each vertex:
+
+```glsl
+// shader.vert
+
+layout (location = 0) out vec3 out_color;
+
+// ...
+const vec3 colors[] = {
+  vec3(1.0, 0.0, 0.0),
+  vec3(0.0, 1.0, 0.0),
+  vec3(0.0, 0.0, 1.0),
+};
+
+// ...
+out_color = colors[gl_VertexIndex];
+
+// shader.frag
+
+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
+// ...
+.setClearValue(vk::ClearColorValue{0.0f, 0.0f, 0.0f, 1.0f});
+```
+
+Gives us the renowned Vulkan sRGB triangle:
+
+![sRGB Triangle](./srgb_triangle.png)
+

guide/src/pipeline/pipeline_creation.md

@@ -8,7 +8,7 @@ struct PipelineFlag {
   enum : std::uint8_t {
     None = 0,
     AlphaBlend = 1 << 0, // turn on alpha blending.
-    DepthTest = 1 << 1,	 // turn on depth write and test.
+    DepthTest = 1 << 1,  // turn on depth write and test.
   };
 };
 
@@ -20,7 +20,7 @@ struct PipelineState {
     return Flag::AlphaBlend | Flag::DepthTest;
   }
 
-  vk::ShaderModule vertex_shader;	  // required.
+  vk::ShaderModule vertex_shader;   // required.
   vk::ShaderModule fragment_shader; // required.
 
   std::span<vk::VertexInputAttributeDescription const> vertex_attributes{};
@@ -200,107 +200,3 @@ auto PipelineBuilder::build(vk::PipelineLayout const layout,
   return vk::UniquePipeline{ret, m_info.device};
 }
 ```
-
-Add new `App` members:
-
-```cpp
-void create_pipeline_builder();
-void create_pipeline();
-
-// ...
-std::optional<PipelineBuilder> m_pipeline_builder{};
-
-vk::UniquePipelineLayout m_pipeline_layout{};
-vk::UniquePipeline m_pipeline{};
-```
-
-Implement and call `create_pipeline_builder()`:
-
-```cpp
-void App::create_pipeline_builder() {
-  auto const pipeline_builder_ci = PipelineBuilder::CreateInfo{
-    .device = *m_device,
-    .samples = vk::SampleCountFlagBits::e1,
-    .color_format = m_swapchain->get_format(),
-  };
-  m_pipeline_builder.emplace(pipeline_builder_ci);
-}
-```
-
-Complete the implementation of `create_pipeline()`:
-
-```cpp
-// ...
-m_pipeline_layout = m_device->createPipelineLayoutUnique({});
-
-auto const pipeline_state = PipelineState{
-  .vertex_shader = *vertex,
-  .fragment_shader = *fragment,
-};
-m_pipeline = m_pipeline_builder->build(*m_pipeline_layout, pipeline_state);
-if (!m_pipeline) {
-  throw std::runtime_error{"Failed to create Graphics 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 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))
-  .setWidth(static_cast<float>(m_render_target->extent.width))
-  .setHeight(-viewport.y);
-command_buffer.setViewport(0, viewport);
-command_buffer.setScissor(0, render_area);
-// current shader has hard-coded logic for 3 vertices.
-command_buffer.draw(3, 1, 0, 0);
-```
-
-![White Triangle](./white_triangle.png)
-
-Updating our shaders to use interpolated RGB on each vertex:
-
-```glsl
-// shader.vert
-
-layout (location = 0) out vec3 out_color;
-
-// ...
-const vec3 colors[] = {
-  vec3(1.0, 0.0, 0.0),
-  vec3(0.0, 1.0, 0.0),
-  vec3(0.0, 0.0, 1.0),
-};
-
-// ...
-out_color = colors[gl_VertexIndex];
-
-// shader.frag
-
-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
-// ...
-.setClearValue(vk::ClearColorValue{0.0f, 0.0f, 0.0f, 1.0f});
-```
-
-Gives us the renowned Vulkan sRGB triangle:
-
-![sRGB Triangle](./srgb_triangle.png)

guide/src/pipeline/shaders.md

@@ -93,22 +93,18 @@ auto ShaderLoader::load(fs::path const& path) -> vk::UniqueShaderModule {
 Add new members to `App`:
 
 ```cpp
-void create_pipeline();
+void create_pipelines();
 
 [[nodiscard]] auto asset_path(std::string_view uri) const -> fs::path;
 ```
 
-Implement and call `create_pipeline()` before starting the main loop:
+Add code to load shaders in `create_pipelines()` and call it before starting the main loop:
 
 ```cpp
-auto App::asset_path(std::string_view const uri) const -> fs::path {
-  return m_assets_dir / uri;
-}
-
-void App::create_pipeline() {
+void App::create_pipelines() {
   auto shader_loader = ShaderLoader{*m_device};
-  // we only need shader modules to create the pipeline, thus no need to store
-  // them as members.
+  // we only need shader modules to create the pipelines, thus no need to
+  // store them as members.
   auto const vertex = shader_loader.load(asset_path("shader.vert"));
   auto const fragment = shader_loader.load(asset_path("shader.frag"));
   if (!vertex || !fragment) {
@@ -118,4 +114,8 @@ void App::create_pipeline() {
 
   // TODO
 }
+
+auto App::asset_path(std::string_view const uri) const -> fs::path {
+  return m_assets_dir / uri;
+}
 ```

guide/src/pipeline/srgb_triangle_wireframe.png

@@ -0,0 +1,39 @@
+# Switching Pipelines
+
+We can use an ImGui window to inspect / tweak some pipeline state:
+
+```cpp
+ImGui::ShowDemoWindow();
+
+ImGui::SetNextWindowSize({200.0f, 100.0f}, ImGuiCond_Once);
+if (ImGui::Begin("Inspect")) {
+  ImGui::Checkbox("wireframe", &m_wireframe);
+  if (m_wireframe) {
+    auto const& line_width_range =
+      m_gpu.properties.limits.lineWidthRange;
+    ImGui::SetNextItemWidth(100.0f);
+    ImGui::DragFloat("line width", &m_line_width, 0.25f,
+              line_width_range[0], line_width_range[1]);
+  }
+}
+ImGui::End();
+```
+
+Modify `draw()` to use the selected pipeline, and also set the line width:
+
+```cpp
+auto const pipeline =
+  m_wireframe ? *m_pipelines.wireframe : *m_pipelines.standard;
+command_buffer.bindPipeline(vk::PipelineBindPoint::eGraphics, pipeline);
+
+// ...
+// line width is also a dynamic state in our pipelines, but setting it is
+// not required (defaults to 1.0f or the minimum reported limit).
+command_buffer.setLineWidth(m_line_width);
+```
+
+And that's it.
+
+![sRGB Triangle (wireframe)](./srgb_triangle_wireframe.png)
+
+In a system with dynamic pipeline creation, the first frame where `m_wireframe == true` will trigger the complex pipeline building step. This can cause stutters, especially if many different shaders/pipelines are involved in a short period of "experience" time. This is why many modern games/engines have the dreaded "Building/Compiling Shaders" screen, where all the pipelines are being built and cached.