Load shaders

Author: karnkaul

assets/shader.frag

@@ -24,3 +24,6 @@
 - [Dear ImGui](dear_imgui/README.md)
   - [class DearImGui](dear_imgui/dear_imgui.md)
   - [ImGui Integration](dear_imgui/imgui_integration.md)
+- [Graphics Pipeline](pipeline/README.md)
+  - [Locating Assets](pipeline/locating_assets.md)
+  - [Shaders](pipeline/shaders.md)

assets/shader.vert

@@ -0,0 +1,14 @@
+# Graphics Pipeline
+
+A [Vulkan Graphics Pipeline](https://docs.vulkan.org/spec/latest/chapters/pipelines.html) is a large object that encompasses the entire graphics pipeline. It consists of many stages - all this happens during a single `draw()` call. We again constrain ourselves to caring about a small subset:
+
+1. Input Assembly: vertex buffers are read here
+1. Vertex Shader: shader is run for each vertex in the primitive
+1. Early Fragment Tests (EFT): pre-shading tests
+1. Fragment Shader: shader is run for each fragment
+1. Late Fragment Tests (LFT): depth buffer is written here
+1. Color Blending: transparency
+
+A Graphics Pipeline's specification broadly includes configuration of the vertex attributes and fixed state (baked into the pipeline), dynamic states (must be set at draw-time), shader code (SPIR-V), and its layout (Descriptor Sets and Push Constants). Creation of a pipeline is verbose _and_ expensive, most engines use some sort of "hash and cache" approach to optimize reuse of existing pipelines. The Descriptor Set Layouts of a shader program need to be explicitly specified, engines can either dictate a static layout or use runtime reflection via [SPIR-V Cross](https://github.com/KhronosGroup/SPIRV-Cross).
+
+We shall use a single Pipeline Layout that evolves over chapters.

guide/src/SUMMARY.md

@@ -0,0 +1,83 @@
+# Locating Assets
+
+Before we can use shaders (and thus graphics pipelines), we need to load them as asset/data files. To do that correctly, first the asset directory needs to be located. There are a few ways to go about this, we will use the approach of looking for a particular subdirectory, starting from the working directory and walking up the parent directory tree. This enables `app` in any project/build subdirectory to locate `assets/` in the various examples below:
+
+```
+.
+|-- assets/
+|-- app
+|-- build/
+    |-- app
+|-- out/
+    |-- default/Release/
+        |-- app
+    |-- ubsan/Debug/
+        |-- app
+```
+
+In a release package you would want to use the path to the executable instead (and probably not perform an "upfind" walk), the working directory could be anywhere whereas assets shipped with the package will be in the vicinity of the executable.
+
+## Assets Directory
+
+Add a member to `App` to store this path to `assets/`:
+
+```cpp
+namespace fs = std::filesystem;
+
+// ...
+fs::path m_assets_dir{};
+```
+
+Add a helper function to locate the assets dir, and assign `m_assets_dir` to its return value at the top of `run()`:
+
+```cpp
+[[nodiscard]] auto locate_assets_dir() -> fs::path {
+  // look for '<path>/assets/', starting from the working
+  // directory and walking up the parent directory tree.
+  static constexpr std::string_view dir_name_v{"assets"};
+  for (auto path = fs::current_path();
+     !path.empty() && path.has_parent_path(); path = path.parent_path()) {
+    auto ret = path / dir_name_v;
+    if (fs::is_directory(ret)) { return ret; }
+  }
+  std::println("[lvk] Warning: could not locate 'assets' directory");
+  return fs::current_path();
+}
+
+// ...
+m_assets_dir = locate_assets_dir();
+```
+
+We can also support a command line argument to override this algorithm:
+
+```cpp
+// app.hpp
+void run(std::string_view assets_dir);
+
+// app.cpp
+[[nodiscard]] auto locate_assets_dir(std::string_view const in) -> fs::path {
+  if (!in.empty()) {
+    std::println("[lvk] Using custom assets directory: '{}'", in);
+    return in;
+  }
+  // ...
+}
+
+// ...
+void App::run(std::string_view const assets_dir) {
+  m_assets_dir = locate_assets_dir(assets_dir);
+  // ...
+}
+
+// main.cpp
+auto assets_dir = std::string_view{};
+
+// ...
+if (arg == "-x" || arg == "--force-x11") {
+  glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_X11);
+}
+if (arg == "-a" || arg == "--assets") { assets_dir = arg; }
+
+// ...
+lvk::App{}.run(assets_dir);
+```

guide/src/pipeline/README.md

@@ -0,0 +1,119 @@
+# Shaders
+
+Shaders work in NDC space: -1 to +1 for X and Y. We set up a triangle's coordinates and output that in the vertex shader save it to `src/glsl/shader.vert`:
+
+```glsl
+#version 450 core
+
+void main() {
+  const vec2 positions[] = {
+    vec2(-0.5, -0.5),
+    vec2(0.5, -0.5),
+    vec2(0.0, 0.5),
+  };
+
+  const vec2 position = positions[gl_VertexIndex];
+
+  gl_Position = vec4(position, 0.0, 1.0);
+}
+```
+
+The fragment shader just outputs white for now, in `src/glsl/shader.frag`:
+
+```glsl
+#version 450 core
+
+layout (location = 0) out vec4 out_color;
+
+void main() {
+  out_color = vec4(1.0);
+}
+```
+
+Compile both shaders into `assets/`:
+
+```
+glslc src/glsl/shader.vert -o assets/shader.vert
+glslc src/glsl/shader.frag -o assets/shader.frag
+```
+
+## 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).
+
+Add a new `class ShaderLoader`:
+
+```cpp
+class ShaderLoader {
+ public:
+  explicit ShaderLoader(vk::Device const device) : m_device(device) {}
+
+  [[nodiscard]] auto load(fs::path const& path) -> vk::UniqueShaderModule;
+
+ private:
+  vk::Device m_device{};
+  std::vector<std::uint32_t> m_code{};
+};
+```
+
+Implement `load()`:
+
+```cpp
+auto ShaderLoader::load(fs::path const& path) -> vk::UniqueShaderModule {
+  // open the file at the end, to get the total size.
+  auto file = std::ifstream{path, std::ios::binary | std::ios::ate};
+  if (!file.is_open()) {
+    std::println(stderr, "Failed to open file: '{}'",
+                 path.generic_string());
+    return {};
+  }
+
+  auto const size = file.tellg();
+  auto const usize = static_cast<std::uint64_t>(size);
+  // file data must be uint32 aligned.
+  if (usize % sizeof(std::uint32_t) != 0) {
+    std::println(stderr, "Invalid SPIR-V size: {}", usize);
+    return {};
+  }
+
+  // seek to the beginning before reading.
+  file.seekg({}, std::ios::beg);
+  m_code.resize(usize / sizeof(std::uint32_t));
+  void* data = m_code.data();
+  file.read(static_cast<char*>(data), size);
+
+  auto shader_module_ci = vk::ShaderModuleCreateInfo{};
+  shader_module_ci.setCode(m_code);
+  return m_device.createShaderModuleUnique(shader_module_ci);
+}
+```
+
+Add new members to `App`:
+
+```cpp
+void create_pipeline();
+
+[[nodiscard]] auto asset_path(std::string_view uri) const -> fs::path;
+```
+
+Implement and call `create_pipeline()` 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() {
+  auto shader_loader = ShaderLoader{*m_device};
+  // we only need shader modules to create the pipeline, 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) {
+    throw std::runtime_error{"Failed to load Shaders"};
+  }
+  std::println("[lvk] Shaders loaded");
+
+  // TODO
+}
+```

guide/src/pipeline/locating_assets.md

@@ -1,4 +1,5 @@
 #include <app.hpp>
+#include <shader_loader.hpp>
 #include <cassert>
 #include <chrono>
 #include <print>
@@ -9,7 +10,28 @@ VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE
 namespace lvk {
 using namespace std::chrono_literals;
 
-void App::run() {
+namespace {
+[[nodiscard]] auto locate_assets_dir(std::string_view const in) -> fs::path {
+	if (!in.empty()) {
+		std::println("[lvk] Using custom assets directory: '{}'", in);
+		return in;
+	}
+	// look for '<path>/assets/', starting from the working
+	// directory and walking up the parent directory tree.
+	static constexpr std::string_view dir_name_v{"assets"};
+	for (auto path = fs::current_path();
+		 !path.empty() && path.has_parent_path(); path = path.parent_path()) {
+		auto ret = path / dir_name_v;
+		if (fs::is_directory(ret)) { return ret; }
+	}
+	std::println("[lvk] Warning: could not locate 'assets' directory");
+	return fs::current_path();
+}
+} // namespace
+
+void App::run(std::string_view const assets_dir) {
+	m_assets_dir = locate_assets_dir(assets_dir);
+
 	create_window();
 	create_instance();
 	create_surface();
@@ -19,6 +41,8 @@ void App::run() {
 	create_render_sync();
 	create_imgui();
 
+	create_pipeline();
+
 	main_loop();
 }
 
@@ -153,6 +177,24 @@ void App::create_imgui() {
 	m_imgui.emplace(imgui_ci);
 }
 
+auto App::asset_path(std::string_view const uri) const -> fs::path {
+	return m_assets_dir / uri;
+}
+
+void App::create_pipeline() {
+	auto shader_loader = ShaderLoader{*m_device};
+	// we only need shader modules to create the pipeline, 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) {
+		throw std::runtime_error{"Failed to load Shaders"};
+	}
+	std::println("[lvk] Shaders loaded");
+
+	// TODO
+}
+
 void App::main_loop() {
 	while (glfwWindowShouldClose(m_window.get()) == GLFW_FALSE) {
 		glfwPollEvents();

guide/src/pipeline/shaders.md

@@ -6,11 +6,14 @@
 #include <swapchain.hpp>
 #include <vulkan/vulkan.hpp>
 #include <window.hpp>
+#include <filesystem>
 
 namespace lvk {
+namespace fs = std::filesystem;
+
 class App {
   public:
-	void run();
+	void run(std::string_view assets_dir);
 
   private:
 	struct RenderSync {
@@ -32,6 +35,9 @@ class App {
 	void create_swapchain();
 	void create_render_sync();
 	void create_imgui();
+	void create_pipeline();
+
+	[[nodiscard]] auto asset_path(std::string_view uri) const -> fs::path;
 
 	void main_loop();
 
@@ -42,6 +48,8 @@ class App {
 	void transition_for_present(vk::CommandBuffer command_buffer) const;
 	void submit_and_present();
 
+	fs::path m_assets_dir{};
+
 	// the order of these RAII members is crucially important.
 	glfw::Window m_window{};
 	vk::UniqueInstance m_instance{};

src/app.cpp

@@ -0,0 +1,7 @@
+#version 450 core
+
+layout (location = 0) out vec4 out_color;
+
+void main() {
+	out_color = vec4(1.0);
+}

src/app.hpp

@@ -0,0 +1,13 @@
+#version 450 core
+
+void main() {
+	const vec2 positions[] = {
+		vec2(-0.5, -0.5),
+		vec2(0.5, -0.5),
+		vec2(0.0, 0.5),
+	};
+
+	const vec2 position = positions[gl_VertexIndex];
+
+	gl_Position = vec4(position, 0.0, 1.0);
+}