Create Window and Instance

Author: karnkaul

CMakeLists.txt

@@ -11,11 +11,21 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 set(CMAKE_DEBUG_POSTFIX "-d")
 set(BUILD_SHARED_LIBS OFF)
 
+# add learn-vk::ext target
+add_subdirectory(ext)
+
 # declare executable target
 add_executable(${PROJECT_NAME})
 
+# link to ext target
+target_link_libraries(${PROJECT_NAME} PRIVATE
+  learn-vk::ext
+)
+
 # setup precompiled header
 target_precompile_headers(${PROJECT_NAME} PRIVATE
+  <glm/glm.hpp>
+  <vulkan/vulkan.hpp>
 )
 
 # enable including headers in 'src/'

ext/.gitignore

@@ -0,0 +1 @@
+src/

ext/CMakeLists.txt

@@ -0,0 +1,50 @@
+project(learn-vk-ext)
+
+# extract src.zip
+file(ARCHIVE_EXTRACT INPUT "${CMAKE_CURRENT_SOURCE_DIR}/src.zip" DESTINATION "${CMAKE_CURRENT_SOURCE_DIR}")
+
+# add GLFW to build tree
+set(GLFW_INSTALL OFF)
+set(GLFW_BUILD_DOCS OFF)
+message(STATUS "[glfw]")
+add_subdirectory(src/glfw)
+add_library(glfw::glfw ALIAS glfw)
+
+# add GLM to build tree
+set(GLM_ENABLE_CXX_20 ON)
+message(STATUS "[glm]")
+add_subdirectory(src/glm)
+target_compile_definitions(glm PUBLIC
+  GLM_FORCE_XYZW_ONLY
+  GLM_FORCE_RADIANS
+  GLM_FORCE_DEPTH_ZERO_TO_ONE
+  GLM_FORCE_SILENT_WARNINGS
+  GLM_ENABLE_EXPERIMENTAL
+  GLM_EXT_INCLUDED
+)
+
+# add Vulkan-Headers to build tree
+message(STATUS "[Vulkan-Headers]")
+add_subdirectory(src/Vulkan-Headers)
+
+# declare ext library target
+add_library(${PROJECT_NAME} INTERFACE)
+add_library(learn-vk::ext ALIAS ${PROJECT_NAME})
+
+# link to all dependencies
+target_link_libraries(${PROJECT_NAME} INTERFACE
+  glfw::glfw
+  glm::glm
+  Vulkan::Headers
+)
+
+# setup preprocessor defines
+target_compile_definitions(${PROJECT_NAME} INTERFACE
+  GLFW_INCLUDE_VULKAN # enable GLFW's Vulkan API
+  VK_NO_PROTOTYPES # Dynamically load Vulkan at runtime
+)
+
+if(CMAKE_SYSTEM_NAME STREQUAL Linux)
+  # link to dynamic loader
+  target_link_libraries(${PROJECT_NAME} INTERFACE dl)
+endif()

ext/src.zip

@@ -8,4 +8,7 @@
   - [Project Layout](getting_started/project_layout.md)
   - [Validation Layers](getting_started/validation_layers.md)
   - [class App](getting_started/class_app.md)
+- [Initialization](initialization/README.md)
+  - [GLFW Window](initialization/glfw_window.md)
+  - [Vulkan Instance](initialization/instance.md)
 

guide/src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Initialization
+
+This section deals with initialization of all the systems needed, including:
+
+- Initializing GLFW and creating a Window
+- Creating a Vulkan Instance
+- Creating a Vulkan Surface
+- Selecting a Vulkan Physical Device
+- Creating a Vulkan logical Device
+
+If any step here fails, it is a fatal error as we can't do anything meaningful beyond that point.

guide/src/initialization/README.md

@@ -0,0 +1,87 @@
+# GLFW Window
+
+We will use GLFW (3.4) for windowing and related events. The library - like all external dependencies - is configured and added to the build tree in `ext/CMakeLists.txt`. `GLFW_INCLUDE_VULKAN` is defined for all consumers, to enable GLFW's Vulkan related functions (known as **Window System Integration (WSI)**). GLFW 3.4 supports Wayland on Linux, and by default it builds backends for both X11 and Wayland. For this reason it will need the development headers for both platforms (and some other Wayland/CMake dependencies) to configure/build successfully. A particular backend can be requested at runtime if desired via `GLFW_PLATFORM`.
+
+Although it is quite feasible to have multiple windows in a Vulkan-GLFW application, that is out of scope of this guide. So for our purposes GLFW (the library) and a single window are a monolithic unit - initialized and destroyed together. This can be encapsulated in a `std::unique_ptr` with a custom deleter, especially since GLFW returns an opaque pointer (`GLFWwindow*`).
+
+```cpp
+// window.hpp
+namespace lvk::glfw {
+struct Deleter {
+	void operator()(GLFWwindow* window) const noexcept;
+};
+
+using Window = std::unique_ptr<GLFWwindow, Deleter>;
+
+// Returns a valid Window if successful, else throws.
+[[nodiscard]] auto create_window(glm::ivec2 size, char const* title) -> Window;
+} // namespace lvk::glfw
+
+// window.cpp
+void Deleter::operator()(GLFWwindow* window) const noexcept {
+	glfwDestroyWindow(window);
+	glfwTerminate();
+}
+```
+
+GLFW can create fullscreen and borderless windows, but we will stick to a standard window with decorations. Since we cannot do anything useful if we are unable to create a window, all other branches throw a fatal exception (caught in main).
+
+```cpp
+auto glfw::create_window(glm::ivec2 const size, char const* title) -> Window {
+	static auto const on_error = [](int const code, char const* description) {
+		std::println(stderr, "[GLFW] Error {}: {}", code, description);
+	};
+	glfwSetErrorCallback(on_error);
+	if (glfwInit() != GLFW_TRUE) {
+		throw std::runtime_error{"Failed to initialize GLFW"};
+	}
+	// check for Vulkan support.
+	if (glfwVulkanSupported() != GLFW_TRUE) {
+		throw std::runtime_error{"Vulkan not supported"};
+	}
+	auto ret = Window{};
+	ret.reset(glfwCreateWindow(size.x, size.y, title, nullptr, nullptr));
+	if (!ret) { throw std::runtime_error{"Failed to create GLFW Window"}; }
+	return ret;
+}
+```
+
+`App` can now store a `glfw::Window` and keep polling it in `run()` until it gets closed by the user. We will not be able to draw anything to the window for a while, but this is the first step in that journey.
+
+Declare it as a private member:
+
+```cpp
+ private:
+	glfw::Window m_window{};
+```
+
+Add some private member functions to encapsulate each operation:
+
+```cpp
+	void create_window();
+
+	void main_loop();
+```
+
+Implement them and call them in `run()`:
+
+```cpp
+void App::run() {
+	create_window();
+
+	main_loop();
+}
+
+void App::create_window() {
+	m_window = glfw::create_window({1280, 720}, "Learn Vulkan");
+}
+
+void App::main_loop() {
+	while (glfwWindowShouldClose(m_window.get()) == GLFW_FALSE) {
+		glfwPollEvents();
+	}
+}
+```
+
+> On Wayland you will not even see a window yet: it is only shown _after_ the application presents a framebuffer to it.
+

guide/src/initialization/glfw_window.md

@@ -0,0 +1,74 @@
+# Vulkan Instance
+
+Instead of linking to Vulkan (via the SDK) at build-time, we will load Vulkan at runtime. This requires a few adjustments:
+
+1. In the CMake script `VK_NO_PROTOTYPES` is defined, which turns API function declarations into function pointers
+1. In `app.cpp` this line is added to the global scope: `VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE`
+1. Before and during initialization `VULKAN_HPP_DEFAULT_DISPATCHER.init()` is called
+
+The first thing to do in Vulkan is to create a `vk::Instance`, which will enable enumeration of physical devices (GPUs) and creation of a logical device.
+
+Since we require Vulkan 1.3, store that in a constant to be easily referenced:
+
+```cpp
+namespace {
+constexpr auto vk_version_v = VK_MAKE_VERSION(1, 3, 0);
+} // namespace
+```
+
+In `App`, create  a new member function `create_instance()` and call it after `create_window()` in `run()`. After initializing the dispatcher, check that the loader meets the version requirement:
+
+```cpp
+void App::create_instance() {
+	VULKAN_HPP_DEFAULT_DISPATCHER.init();
+	auto const loader_version = vk::enumerateInstanceVersion();
+	if (loader_version < vk_version_v) {
+		throw std::runtime_error{"Loader does not support Vulkan 1.3"};
+	}
+}
+```
+
+We will need the WSI instance extensions, which GLFW conveniently provides for us. Add a helper function in `window.hpp`:
+
+```cpp
+auto glfw::instance_extensions() -> std::span<char const* const> {
+	auto count = std::uint32_t{};
+	auto const* extensions = glfwGetRequiredInstanceExtensions(&count);
+	return {extensions, static_cast<std::size_t>(count)};
+}
+```
+
+Continuing with instance creation, create a `vk::ApplicationInfo` object and fill it up:
+
+```cpp
+	auto app_info = vk::ApplicationInfo{};
+	app_info.setPApplicationName("Learn Vulkan").setApiVersion(vk_version_v);
+```
+
+Create a `vk::InstanceCreateInfo` object and fill it up:
+
+```cpp
+	auto instance_ci = vk::InstanceCreateInfo{};
+	auto const extensions = glfw::instance_extensions();
+	instance_ci.setPApplicationInfo(&app_info).setPEnabledExtensionNames(
+		extensions);
+```
+
+Add a `vk::UniqueInstance` member, create it, and initialize the dispatcher against it:
+
+```cpp
+	m_instance = vk::createInstanceUnique(instance_ci);
+	VULKAN_HPP_DEFAULT_DISPATCHER.init(*m_instance);
+```
+
+Make sure VkConfig is running with validation layers enabled, and debug/run the app. If "Information" level loader messages are enabled, you should see quite a bit of console output at this point: information about layers being loaded, physical devices and their ICDs being enumerated, etc.
+
+If this line or equivalent is not visible in the logs, re-check your Vulkan Configurator setup and `PATH`:
+
+```
+INFO | LAYER:      Insert instance layer "VK_LAYER_KHRONOS_validation"
+```
+
+Congratulations, you have successfully initialized a Vulkan Instance!
+
+> Wayland users: seeing the window is still a long way off, these VkConfig/validation logs are your only feedback for now.

guide/src/initialization/instance.md

@@ -1,5 +1,46 @@
 #include <app.hpp>
+#include <print>
+
+VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE
 
 namespace lvk {
-void App::run() {}
+namespace {
+constexpr auto vk_version_v = VK_MAKE_VERSION(1, 3, 0);
+} // namespace
+
+void App::run() {
+	create_window();
+	create_instance();
+
+	main_loop();
+}
+
+void App::create_window() {
+	m_window = glfw::create_window({1280, 720}, "Learn Vulkan");
+}
+
+void App::create_instance() {
+	VULKAN_HPP_DEFAULT_DISPATCHER.init();
+	auto const loader_version = vk::enumerateInstanceVersion();
+	if (loader_version < vk_version_v) {
+		throw std::runtime_error{"Loader does not support Vulkan 1.3"};
+	}
+
+	auto app_info = vk::ApplicationInfo{};
+	app_info.setPApplicationName("Learn Vulkan").setApiVersion(vk_version_v);
+
+	auto instance_ci = vk::InstanceCreateInfo{};
+	auto const extensions = glfw::instance_extensions();
+	instance_ci.setPApplicationInfo(&app_info).setPEnabledExtensionNames(
+		extensions);
+
+	m_instance = vk::createInstanceUnique(instance_ci);
+	VULKAN_HPP_DEFAULT_DISPATCHER.init(*m_instance);
+}
+
+void App::main_loop() {
+	while (glfwWindowShouldClose(m_window.get()) == GLFW_FALSE) {
+		glfwPollEvents();
+	}
+}
 } // namespace lvk

src/app.cpp

@@ -1,8 +1,19 @@
 #pragma once
+#include <vulkan/vulkan.hpp>
+#include <window.hpp>
 
 namespace lvk {
 class App {
   public:
 	void run();
+
+  private:
+	void create_window();
+	void create_instance();
+
+	void main_loop();
+
+	glfw::Window m_window{};
+	vk::UniqueInstance m_instance{};
 };
 } // namespace lvk

src/app.hpp

@@ -0,0 +1,37 @@
+#include <window.hpp>
+#include <cstdint>
+#include <print>
+#include <stdexcept>
+
+namespace lvk {
+namespace glfw {
+void Deleter::operator()(GLFWwindow* window) const noexcept {
+	glfwDestroyWindow(window);
+	glfwTerminate();
+}
+} // namespace glfw
+
+auto glfw::create_window(glm::ivec2 const size, char const* title) -> Window {
+	static auto const on_error = [](int const code, char const* description) {
+		std::println(stderr, "[GLFW] Error {}: {}", code, description);
+	};
+	glfwSetErrorCallback(on_error);
+	if (glfwInit() != GLFW_TRUE) {
+		throw std::runtime_error{"Failed to initialize GLFW"};
+	}
+	// check for Vulkan support.
+	if (glfwVulkanSupported() != GLFW_TRUE) {
+		throw std::runtime_error{"Vulkan not supported"};
+	}
+	auto ret = Window{};
+	ret.reset(glfwCreateWindow(size.x, size.y, title, nullptr, nullptr));
+	if (!ret) { throw std::runtime_error{"Failed to create GLFW Window"}; }
+	return ret;
+}
+
+auto glfw::instance_extensions() -> std::span<char const* const> {
+	auto count = std::uint32_t{};
+	auto const* extensions = glfwGetRequiredInstanceExtensions(&count);
+	return {extensions, static_cast<std::size_t>(count)};
+}
+} // namespace lvk

src/window.cpp

@@ -0,0 +1,18 @@
+#pragma once
+#include <GLFW/glfw3.h>
+#include <glm/vec2.hpp>
+#include <memory>
+#include <span>
+
+namespace lvk::glfw {
+struct Deleter {
+	void operator()(GLFWwindow* window) const noexcept;
+};
+
+using Window = std::unique_ptr<GLFWwindow, Deleter>;
+
+// Returns a valid Window if successful, else throws.
+[[nodiscard]] auto create_window(glm::ivec2 size, char const* title) -> Window;
+
+[[nodiscard]] auto instance_extensions() -> std::span<char const* const>;
+} // namespace lvk::glfw