Translate chapter 2 into Traditional Chinese

Mes0903 · Mes0903 · commit 5ea8db8c5fb2 · 2025-08-10T19:29:35.000+08:00
diff --git a/guide/translations/zh-TW/src/SUMMARY.md b/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)
diff --git a/guide/translations/zh-TW/src/initialization/README.md b/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
+
+如果其中任何一步失敗，都會是致命錯誤，之後的操作都會變得沒有意義
diff --git a/guide/translations/zh-TW/src/initialization/device.md b/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);
+```
diff --git a/guide/translations/zh-TW/src/initialization/glfw_window.md b/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 給它後，視窗才會顯示出來
diff --git a/guide/translations/zh-TW/src/initialization/gpu.md b/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});
+}
+```
diff --git a/guide/translations/zh-TW/src/initialization/instance.md b/guide/translations/zh-TW/src/initialization/instance.md
@@ -0,0 +1,87 @@
+# Vulkan Instance
+
+本教學不會在建置階段透過 SDK 連結 Vulkan，而是在執行期載入 Vulkan，這需要做一些調整：
+
+1. 在 CMake ext target 中定義 `VK_NO_PROTOTYPES`，讓 API 的函式宣告變成函示指標
+2. 在 `app.cpp` 的全域範圍新增這行：`VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE`
+3. 在初始化前與初始化過程中呼叫 `VULKAN_HPP_DEFAULT_DISPATCHER.init()`
+
+在 Vulkan 中，第一步是建立一個 [Instance](https://docs.vulkan.org/spec/latest/chapters/initialization.html#initialization-instances)，這讓我們能列舉可用的實體裝置（GPU），並建立邏輯裝置
+
+由於我們需要 Vulkan 1.3，因此會將這個需求存為常數，以方便後續引用：
+
+```cpp
+namespace {
+constexpr auto vk_version_v = VK_MAKE_VERSION(1, 3, 0);
+} // namespace
+```
+
+現在讓我們於 `App` 中建立一個新的成員函式 `create_instance()`，並在 `run()` 中於 `create_window()` 之後呼叫它。 這會在初始化 dispatcher 後，檢查載入器是否符合版本需求：
+
+```cpp
+void App::create_instance() {
+  // initialize the dispatcher without any arguments.
+  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"};
+  }
+}
+```
+
+我們之後會需要 WSI 的 instance 擴充功能，對此 GLFW 為我們提供了方便的介面。 讓我們在 `window.hpp/cpp` 中加入一個輔助函式：
+
+```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)};
+}
+```
+
+接著繼續建立 Instance，先建立一個 `vk::ApplicationInfo` 物件並填入其內容：
+
+```cpp
+auto app_info = vk::ApplicationInfo{};
+app_info.setPApplicationName("Learn Vulkan").setApiVersion(vk_version_v);
+```
+
+並建立一個 `vk::InstanceCreateInfo` 並填入其內容：
+
+```cpp
+auto instance_ci = vk::InstanceCreateInfo{};
+// need WSI instance extensions here (platform-specific Swapchains).
+auto const extensions = glfw::instance_extensions();
+instance_ci.setPApplicationInfo(&app_info).setPEnabledExtensionNames(
+  extensions);
+```
+
+在 `m_window`「之後」新增一個 `vk::UniqueInstance` 成員，因為它必須在 GLFW 結束前銷毀。 建立它並針對它初始化 dispatcher：
+
+```cpp
+glfw::Window m_window{};
+vk::UniqueInstance m_instance{};
+
+// ...
+// initialize the dispatcher against the created Instance.
+m_instance = vk::createInstanceUnique(instance_ci);
+VULKAN_HPP_DEFAULT_DISPATCHER.init(*m_instance);
+```
+
+請確保 VkConfig 是在啟用了 validation layer 的情況下執行的，接著再去偵錯/執行你的應用程式。 若啟用了「Information」等級的載入器訊息，此時你應該會在主控台上看到不少的輸出，像是已載入的 validation layer 的資訊、實體裝置（physical device）及其 ICD 的列舉結果等
+
+如果在日誌中看不到以下這行或類似的內容，請重新檢查你 Vulkan Configurator 的設定與 `PATH`：
+
+```
+INFO | LAYER:      Insert instance layer "VK_LAYER_KHRONOS_validation"
+```
+
+另外例如，如果應用程式或載入器無法找到 `libVkLayer_khronos_validation.so` / `VkLayer_khronos_validation.dll`，你會看到類似以下的訊息：
+
+```
+INFO | LAYER:   Requested layer "VK_LAYER_KHRONOS_validation" failed to load.
+```
+
+至此，你已經成功初始化了 Vulkan Instance，恭喜你！
+
+> Wayland 使用者注意：要看到視窗還有很長一段路要走，目前 VkConfig 與驗證層的日誌就是你唯一的回饋來源
diff --git a/guide/translations/zh-TW/src/initialization/scoped_waiter.md b/guide/translations/zh-TW/src/initialization/scoped_waiter.md
diff --git a/guide/translations/zh-TW/src/initialization/surface.md b/guide/translations/zh-TW/src/initialization/surface.md
diff --git a/guide/translations/zh-TW/src/initialization/swapchain.md b/guide/translations/zh-TW/src/initialization/swapchain.md
