Translate chapter 2 into Traditional Chinese (zh-TW) (#30)

* CI: add `workflow_dispatch`

* Port present semaphore sync fix to main (#26)

* 🐛 Fix present semaphore sync  (#25)

* Refactor build scripts and presets (#24)

- Move compile flags to presets
- Update CI script

* 🐛 Fix present semaphore sync

Discovered on SDK 1.4.313

* Fixup guide

* Fixup guide

* ko-translation revised (#27)

* Fix typo and remove redundant blank space (#29)

* Fix typo and remove redundant blank space

* Fix typo

* Translate chapter 2 into Traditional Chinese

---------

Co-authored-by: Karn Kaul <[email protected]>
Co-authored-by: MyungKun Chang <[email protected]>

Author: 3 people

guide/src/descriptor_sets/descriptor_buffer.md

@@ -1,6 +1,6 @@
 # Descriptor Buffer
 
-Uniform and Storage buffers need to be N-buffered unless they are "GPU const", ie contents do not change after creation.  Encapsulate a `vma::Buffer` per virtual frame in a `DescriptorBuffer`:
+Uniform and Storage buffers need to be N-buffered unless they are "GPU const", ie contents do not change after creation. Encapsulate a `vma::Buffer` per virtual frame in a `DescriptorBuffer`:
 
 ```cpp
 class DescriptorBuffer {

guide/src/initialization/device.md

@@ -2,7 +2,7 @@
 
 A [Vulkan Device](https://docs.vulkan.org/spec/latest/chapters/devsandqueues.html#devsandqueues-devices) is a logical instance of a Physical Device, and will the primary interface for everything Vulkan now onwards. [Vulkan Queues](https://docs.vulkan.org/spec/latest/chapters/devsandqueues.html#devsandqueues-queues) are owned by the Device, we will need one from the queue family stored in the `Gpu` to submit recorded command buffers. We also need to explicitly declare all features we want to use, eg [Dynamic Rendering](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_dynamic_rendering.html) and [Synchronization2](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_synchronization2.html).
 
-Setup a `vk::QueueCreateInfo` object:
+Setup a `vk::DeviceQueueCreateInfo` object:
 
 ```cpp
 auto queue_ci = vk::DeviceQueueCreateInfo{};

guide/src/initialization/instance.md

@@ -16,7 +16,7 @@ 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:
+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() {

guide/src/initialization/scoped_waiter.md

@@ -2,7 +2,7 @@
 
 A useful abstraction to have is an object that in its destructor waits/blocks until the Device is idle. It is incorrect usage to destroy Vulkan objects while they are in use by the GPU, such an object helps with making sure the device is idle before some dependent resource gets destroyed.
 
-Being able to do arbitary things on scope exit will be useful in other spots too, so we encapsulate that in a basic class template `Scoped`. It's somewhat like a `unique_ptr<Type, Deleter>` that stores the value (`Type`) instead of a pointer (`Type*`), with some constraints:
+Being able to do arbitrary things on scope exit will be useful in other spots too, so we encapsulate that in a basic class template `Scoped`. It's somewhat like a `unique_ptr<Type, Deleter>` that stores the value (`Type`) instead of a pointer (`Type*`), with some constraints:
 
 1. `Type` must be default constructible
 1. Assumes a default constructed `Type` is equivalent to null (does not call `Deleter`)

guide/translations/ko-KR/src/initialization/device.md

@@ -2,7 +2,7 @@
 
 [디바이스](https://docs.vulkan.org/spec/latest/chapters/devsandqueues.html#devsandqueues-devices)는 Physical Device의 논리적 인스턴스이며, 이후의 모든 Vulkan 작업에서 주요 인터페이스 역할을 하게 됩니다. [큐](https://docs.vulkan.org/spec/latest/chapters/devsandqueues.html#devsandqueues-queues)는 디바이스가 소유하는 것으로, `Gpu` 구조체에 저장된 큐 패밀리에서 하나를 가져와 기록된 커맨드 버퍼를 제출하는 데 사용할 것입니다. 또한 사용하기를 원하는 [Dynamic Rendering](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_dynamic_rendering.html) 과 [Synchronization2](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_synchronization2.html)같은 기능들을 명시적으로 선언해야 합니다.
 
-`vk::QueueCreateInfo`객체를 설정합시다.
+`vk::DeviceQueueCreateInfo`객체를 설정합시다.
 
 ```cpp
 auto queue_ci = vk::DeviceQueueCreateInfo{};

guide/translations/zh-TW/src/SUMMARY.md

@@ -8,3 +8,11 @@
   - [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)
+  - [Vulkan Surface](initialization/surface.md)
+  - [Vulkan Physical Device](initialization/gpu.md)
+  - [Vulkan Device](initialization/device.md)
+  - [Scoped Waiter](initialization/scoped_waiter.md)
+  - [Swapchain](initialization/swapchain.md)

guide/translations/zh-TW/src/initialization/README.md

@@ -0,0 +1,12 @@
+# Initialization
+
+本節將處理所有必要系統的初始化工作，包括：
+
+- 初始化 GLFW 並建立視窗
+- 建立 Vulkan Instance
+- 建立 Vulkan Surface
+- 選擇 Vulkan Physical Device
+- 建立 Vulkan logical Device
+- 建立 Vulkan Swapchain
+
+如果其中任何一步失敗，都會是致命錯誤，之後的操作都會變得沒有意義

guide/translations/zh-TW/src/initialization/device.md

@@ -0,0 +1,66 @@
+# Vulkan Device
+
+[Vulkan Device](https://docs.vulkan.org/spec/latest/chapters/devsandqueues.html#devsandqueues-devices) 是實體裝置（Physical Device）的邏輯實例，它是我們之後操作 Vulkan 的主要介面。 [Vulkan Queues](https://docs.vulkan.org/spec/latest/chapters/devsandqueues.html#devsandqueues-queues) 由 Device 所擁有，我們需要從儲存在 `Gpu` 中的佇列家族（queue family）中取得一個 Device，來提交已記錄的指令緩衝區（command buffer）。 我們還需要顯式地宣告所有想要使用的功能，例如 [Dynamic Rendering](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_dynamic_rendering.html) 與 [Synchronization2](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_synchronization2.html)
+
+接下來讓我們來設定各項功能。 首先要設定 `vk::DeviceQueueCreateInfo` 物件：
+
+```cpp
+auto queue_ci = vk::DeviceQueueCreateInfo{};
+// since we use only one queue, it has the entire priority range, ie, 1.0
+static constexpr auto queue_priorities_v = std::array{1.0f};
+queue_ci.setQueueFamilyIndex(m_gpu.queue_family)
+  .setQueueCount(1)
+  .setQueuePriorities(queue_priorities_v);
+```
+
+接著設定核心功能：
+
+```cpp
+// nice-to-have optional core features, enable if GPU supports them.
+auto enabled_features = vk::PhysicalDeviceFeatures{};
+enabled_features.fillModeNonSolid = m_gpu.features.fillModeNonSolid;
+enabled_features.wideLines = m_gpu.features.wideLines;
+enabled_features.samplerAnisotropy = m_gpu.features.samplerAnisotropy;
+enabled_features.sampleRateShading = m_gpu.features.sampleRateShading;
+```
+
+設定額外功能，並用 `setPNext()` 把它們串接起來：
+
+```cpp
+// extra features that need to be explicitly enabled.
+auto sync_feature = vk::PhysicalDeviceSynchronization2Features{vk::True};
+auto dynamic_rendering_feature =
+  vk::PhysicalDeviceDynamicRenderingFeatures{vk::True};
+// sync_feature.pNext => dynamic_rendering_feature,
+// and later device_ci.pNext => sync_feature.
+// this is 'pNext chaining'.
+sync_feature.setPNext(&dynamic_rendering_feature);
+```
+
+建立並設定一個 `vk::DeviceCreateInfo` 物件：
+
+```cpp
+auto device_ci = vk::DeviceCreateInfo{};
+// we only need one device extension: Swapchain.
+static constexpr auto extensions_v =
+  std::array{VK_KHR_SWAPCHAIN_EXTENSION_NAME};
+device_ci.setPEnabledExtensionNames(extensions_v)
+  .setQueueCreateInfos(queue_ci)
+  .setPEnabledFeatures(&enabled_features)
+  .setPNext(&sync_feature);
+```
+
+在 `m_gpu` 之後宣告一個 `vk::UniqueDevice` 成員，建立它，並針對它初始化 dispatcher：
+
+```cpp
+m_device = m_gpu.device.createDeviceUnique(device_ci);
+// initialize the dispatcher against the created Device.
+VULKAN_HPP_DEFAULT_DISPATCHER.init(*m_device);
+```
+
+宣告一個 `vk::Queue` 成員（順序無所謂，因為它只是個 handle，實際的 Queue 由 Device 擁有），並完成初始化：
+
+```cpp
+static constexpr std::uint32_t queue_index_v{0};
+m_queue = m_device->getQueue(m_gpu.queue_family, queue_index_v);
+```

guide/translations/zh-TW/src/initialization/glfw_window.md

@@ -0,0 +1,90 @@
+# GLFW Window
+
+本教學使用 GLFW（3.4）來處理視窗與相關事件。 這個函式庫和其他外部相依套件一樣，會在 `ext/CMakeLists.txt` 中設定並加入建置樹（build tree）。 對使用者而言，我們會定義 `GLFW_INCLUDE_VULKAN`，以啟用 GLFW 的 Vulkan 相關功能，這些功能被稱為「視窗系統整合（Window System Integration, WSI）」
+
+GLFW 3.4 在 Linux 上支援 Wayland，並且預設會同時建置 X11 與 Wayland 兩種後端。 因此，你必須同時安裝[兩個平台的開發套件](https://www.glfw.org/docs/latest/compile_guide.html#compile_deps_wayland)（以及一些其他 Wayland/CMake 相依套件），才能順利完成設定與建置。 如果需要，你也可以在執行階段透過 `GLFW_PLATFORM` 來指定要使用的特定後端
+
+雖然 Vulkan-GLFW 的應用程式可以同時擁有多個視窗，但這不在本書探討範圍內。 對我們而言，GLFW（函式庫）與單一視窗被視為一個整體單元，它們會一起初始化並一起銷毀。 由於 GLFW 會回傳一個不透明指標（opaque pointer） `GLFWwindow*`，因此你可以將它封裝在帶有自訂刪除器的 `std::unique_ptr` 中來管理
+
+```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 可以建立全螢幕或無邊框的視窗，本教學會使用帶有邊框與標題列的標準視窗。 由於如果無法建立視窗，就無法再進行任何有意義的操作，因此其他所有分支都會丟出致命例外（會在 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{};
+  // tell GLFW that we don't want an OpenGL context.
+  glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
+  ret.reset(glfwCreateWindow(size.x, size.y, title, nullptr, nullptr));
+  if (!ret) { throw std::runtime_error{"Failed to create GLFW Window"}; }
+  return ret;
+}
+```
+
+接著 `App` 會儲存一個 `glfw::Window`，並在 `run()` 中持續輪詢它，直到使用者關閉視窗為止。 雖然暫時還無法在視窗上繪製任何內容，但這是邁向該目標的第一步
+
+首先將它宣告為私有成員：
+
+```cpp
+private:
+  glfw::Window m_window{};
+```
+
+接著加上一些私有的成員函式來將相關的操作封裝起來：
+
+```cpp
+void create_window();
+
+void main_loop();
+```
+
+最後補上函式定義，並在 `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();
+  }
+}
+```
+
+> 如果是在 Wayland 上，此時還看不到視窗。 Wayland 需要應用程式將 framebuffer 給它後，視窗才會顯示出來

guide/translations/zh-TW/src/initialization/gpu.md

@@ -0,0 +1,94 @@
+# Vulkan Physical Device
+
+[Physical Device](https://docs.vulkan.org/spec/latest/chapters/devsandqueues.html#devsandqueues-physical-device-enumeration) 代表一個完整的 Vulkan 實作； 就我們的用途而言，可以把它視為一張 GPU（它也可能是像 Mesa/lavapipe 這樣的軟體算繪器）。 有些機器上可能同時存在多個 Physical Device，例如配備雙顯卡的筆電。 我們需要在下列限制條件下，挑選要使用的是哪一個：
+
+1. 必須支援 Vulkan 1.3
+2. 必須支援 Vulkan Swapchain
+3. 必須有支援 Graphics 與 Transfer 作業的 Vulkan Queue
+4. 必須能呈現（present）先前建立的 Vulkan Surface
+5. （Optional）優先選擇獨立顯示卡（discrete GPU）
+
+我們會把實際的 Physical Device 以及其他幾個實用物件包裝成 `struct Gpu`。 由於它會搭配一個相當龐大的工具函式，我們會把它放到獨立的 hpp/cpp 檔案中，並把 `vk_version_v` 這個常數移到新的標頭檔裡：
+
+```cpp
+constexpr auto vk_version_v = VK_MAKE_VERSION(1, 3, 0);
+
+struct Gpu {
+  vk::PhysicalDevice device{};
+  vk::PhysicalDeviceProperties properties{};
+  vk::PhysicalDeviceFeatures features{};
+  std::uint32_t queue_family{};
+};
+
+[[nodiscard]] auto get_suitable_gpu(vk::Instance instance,
+                                    vk::SurfaceKHR surface) -> Gpu;
+```
+
+函式定義：
+
+```cpp
+auto lvk::get_suitable_gpu(vk::Instance const instance,
+               vk::SurfaceKHR const surface) -> Gpu {
+  auto const supports_swapchain = [](Gpu const& gpu) {
+    static constexpr std::string_view name_v =
+      VK_KHR_SWAPCHAIN_EXTENSION_NAME;
+    static constexpr auto is_swapchain =
+      [](vk::ExtensionProperties const& properties) {
+        return properties.extensionName.data() == name_v;
+      };
+    auto const properties = gpu.device.enumerateDeviceExtensionProperties();
+    auto const it = std::ranges::find_if(properties, is_swapchain);
+    return it != properties.end();
+  };
+
+  auto const set_queue_family = [](Gpu& out_gpu) {
+    static constexpr auto queue_flags_v =
+      vk::QueueFlagBits::eGraphics | vk::QueueFlagBits::eTransfer;
+    for (auto const [index, family] :
+       std::views::enumerate(out_gpu.device.getQueueFamilyProperties())) {
+      if ((family.queueFlags & queue_flags_v) == queue_flags_v) {
+        out_gpu.queue_family = static_cast<std::uint32_t>(index);
+        return true;
+      }
+    }
+    return false;
+  };
+
+  auto const can_present = [surface](Gpu const& gpu) {
+    return gpu.device.getSurfaceSupportKHR(gpu.queue_family, surface) ==
+         vk::True;
+  };
+
+  auto fallback = Gpu{};
+  for (auto const& device : instance.enumeratePhysicalDevices()) {
+    auto gpu = Gpu{.device = device, .properties = device.getProperties()};
+    if (gpu.properties.apiVersion < vk_version_v) { continue; }
+    if (!supports_swapchain(gpu)) { continue; }
+    if (!set_queue_family(gpu)) { continue; }
+    if (!can_present(gpu)) { continue; }
+    gpu.features = gpu.device.getFeatures();
+    if (gpu.properties.deviceType == vk::PhysicalDeviceType::eDiscreteGpu) {
+      return gpu;
+    }
+    // keep iterating in case we find a Discrete Gpu later.
+    fallback = gpu;
+  }
+  if (fallback.device) { return fallback; }
+
+  throw std::runtime_error{"No suitable Vulkan Physical Devices"};
+}
+```
+
+最後，在 `App` 中加入 `Gpu` 成員，並在 `create_surface()` 之後初始化它：
+
+```cpp
+create_surface();
+select_gpu();
+
+// ...
+void App::select_gpu() {
+  m_gpu = get_suitable_gpu(*m_instance, *m_surface);
+  std::println("Using GPU: {}",
+               std::string_view{m_gpu.properties.deviceName});
+}
+```