WIP zh-TW

Author: karnkaul

guide/build.cmake

@@ -24,4 +24,5 @@ endfunction()
 file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/theme" DESTINATION "${CMAKE_CURRENT_SOURCE_DIR}/translations")
 
 BuildBook("en" "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}/book")
+BuildBook("zh-TW" "${CMAKE_CURRENT_SOURCE_DIR}/translations/zh-TW" "${CMAKE_CURRENT_SOURCE_DIR}/book/zh-TW")
 BuildBook("ko-KR" "${CMAKE_CURRENT_SOURCE_DIR}/translations/ko-KR" "${CMAKE_CURRENT_SOURCE_DIR}/book/ko-KR")

guide/theme/index.hbs

@@ -143,6 +143,7 @@
                         </button>
                         <ul id="lang-list" class="theme-popup" aria-label="Languages" role="menu">
                           <li role="none"><button role="menuitem" class="theme" data-lang="en">English</button></li>
+                          <li role="none"><button role="menuitem" class="theme" data-lang="zh-TW">中文</button></li>
                           <li role="none"><button role="menuitem" class="theme" data-lang="ko-KR">한글</button></li>
                         </ul>
                         {{#if search_enabled}}

guide/translations/zh-TW/book.toml

@@ -0,0 +1,10 @@
+[book]
+authors = ["Karnage", "Mes"]
+language = "zh-TW"
+src = "src"
+title = "Learn Vulkan"
+
+[output.html]
+theme = "../theme"
+additional-js = ["../theme/lang_toggle.js"]
+additional-css = ["../theme/lang_toggle.css"]

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

@@ -0,0 +1,33 @@
+# (中文 WIP) Intro
+
+Vulkan is known for being explicit and verbose. But the _required_ verbosity has steadily reduced with each successive version, its new features, and previous extensions being absorbed into the core API. Similarly, RAII has been a pillar of C++ since its inception, yet most Vulkan guides do not utilize it, instead choosing to "extend" the explicitness by manually cleaning up resources.
+
+To fill that gap, this guide has the following goals:
+
+- Leverage modern C++, VulkanHPP, and Vulkan 1.3 features
+- Focus on keeping it simple and straightforward, _not_ on performance
+- Develop a basic but dynamic rendering foundation
+
+To reiterate, the focus is _not on performance_, it is on a quick introduction to the current standard multi-platform graphics API while utilizing the modern paradigms and tools (at the time of writing). Even disregarding potential performance gains, Vulkan has a better and modern design and ecosystem than OpenGL, eg: there is no global state machine, parameters are passed by filling structs with meaningful member variable names, multi-threading is largely trivial (yes, it is actually easier to do on Vulkan than OpenGL), there are a comprehensive set of validation layers to catch misuse which can be enabled without _any_ changes to application code, etc.
+
+## Target Audience
+
+The guide is for you if you:
+
+- Understand the principles of modern C++ and its usage
+- Have created C++ projects using third-party libraries
+- Are somewhat familiar with graphics
+    - Having done OpenGL tutorials would be ideal
+    - Experience with frameworks like SFML / SDL is great
+- Don't mind if all the information you need isn't monolithically in one place (ie, this guide)
+
+Some examples of what this guide _does not_ focus on:
+
+- GPU-driven rendering
+- Real-time graphics from ground-up
+- Considerations for tiled GPUs (eg mobile devices / Android)
+
+## Source
+
+The source code for the project (as well as this guide) is located in [this repository](https://github.com/cpp-gamedev/learn-vulkan). A `section/*` branch intends to reflect the state of the code at the end of a particular section of the guide. Bugfixes / changes are generally backported, but there may be some divergence from the current state of the code (ie, in `main`). The source of the guide itself is only up-to-date on `main`, changes are not backported.
+

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

@@ -0,0 +1,10 @@
+# (中文 WIP) Summary
+
+[(中文 WIP) Introduction](README.md)
+
+# (中文 WIP) Basics
+
+- [(中文 WIP) Getting Started](getting_started/README.md)
+  - [(中文 WIP) Project Layout](getting_started/project_layout.md)
+  - [(中文 WIP) Validation Layers](getting_started/validation_layers.md)
+  - [(中文 WIP) class App](getting_started/class_app.md)

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

@@ -0,0 +1,34 @@
+# (中文 WIP) Getting Started
+
+Vulkan is platform agnostic, which is one of the main reasons for its verbosity: it has to account for a wide range of implementations in its API. We shall be constraining our approach to Windows and Linux (x64 or aarch64), and focusing on discrete GPUs, enabing us to sidestep quite a bit of that verbosity. Vulkan 1.3 is widely supported by the target desktop platforms and reasonably recent graphics cards.
+
+> This doesn't mean that eg an integrated graphics chip will not be supported, it will just not be particularly designed/optimized for.
+
+## Technical Requirements
+
+1. Vulkan 1.3+ capable GPU and loader
+1. [Vulkan 1.3+ SDK](https://vulkan.lunarg.com/sdk/home)
+    1. This is required for validation layers, a critical component/tool to use when developing Vulkan applications. The project itself does not use the SDK.
+    1. Always using the latest SDK is recommended (1.4.x at the time of writing).
+1. Desktop operating system that natively supports Vulkan
+    1. Windows and/or Linux (distros that use repos with recent packages) is recommended.
+    1. MacOS does _not_ natively support Vulkan. It _can_ be used through MoltenVk, but at the time of writing MoltenVk does not fully support Vulkan 1.3, so if you decide to take this route, you may face some roadblocks.
+1. C++23 compiler and standard library
+    1. GCC14+, Clang18+, and/or latest MSVC are recommended. MinGW/MSYS is _not_ recommended.
+    1. Using C++20 with replacements for C++23 specific features is possible. Eg replace `std::print()` with `fmt::print()`, add `()` to lambdas, etc.
+1. CMake 3.24+
+
+## Overview
+
+While support for C++ modules is steadily growing, tooling is not yet ready on all platforms/IDEs we want to target, so we will unfortuntely still be using headers. This might change in the near future, followed by a refactor of this guide.
+
+The project uses a "Build the World" approach, enabling usage of sanitizers, reproducible builds on any supported platform, and requiring minimum pre-installed things on target machines. Feel free to use pre-built binaries instead, it doesn't change anything about how you would use Vulkan.
+
+## Dependencies
+
+1. [GLFW](https://github.com/glfw/glfw) for windowing, input, and Surface creation
+1. [VulkanHPP](https://github.com/KhronosGroup/Vulkan-Hpp) (via [Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers)) for interacting with Vulkan
+    1. While Vulkan is a C API, it offers an official C++ wrapper library with many quality-of-life features. This guide almost exclusively uses that, except at the boundaries of other C libraries that themselves use the C API (eg GLFW and VMA).
+1. [Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/) for dealing with Vulkan memory heaps
+1. [GLM](https://github.com/g-truc/glm) for GLSL-like linear algebra in C++
+1. [Dear ImGui](https://github.com/ocornut/imgui) for UI

guide/translations/zh-TW/src/getting_started/class_app.md

@@ -0,0 +1,39 @@
+# (中文 WIP) Application
+
+`class App` will serve as the owner and driver of the entire application. While there will only be one instance, using a class enables us to leverage RAII and destroy all its resources automatically and in the correct order, and avoids the need for globals.
+
+```cpp
+// app.hpp
+namespace lvk {
+class App {
+ public:
+  void run();
+};
+} // namespace lvk
+
+// app.cpp
+namespace lvk {
+void App::run() {
+  // TODO
+}
+} // namespace lvk
+```
+
+## Main
+
+`main.cpp` will not do much: it's mainly responsible for transferring control to the actual entry point, and catching fatal exceptions.
+
+```cpp
+// main.cpp
+auto main() -> int {
+  try {
+    lvk::App{}.run();
+  } catch (std::exception const& e) {
+    std::println(stderr, "PANIC: {}", e.what());
+    return EXIT_FAILURE;
+  } catch (...) {
+    std::println("PANIC!");
+    return EXIT_FAILURE;
+  }
+}
+```

guide/translations/zh-TW/src/getting_started/high_level_loader.png

@@ -0,0 +1,22 @@
+# (中文 WIP) Project Layout
+
+This page describes the layout used by the code in this guide. Everything here is just an opinionated option used by the guide, and is not related to Vulkan usage.
+
+External dependencies are stuffed into a zip file that's decompressed by CMake during the configure stage. Using FetchContent is a viable alternative.
+
+`Ninja Multi-Config` is the assumed generator used, regardless of OS/compiler. This is set up in a `CMakePresets.json` file in the project root. Additional custom presets can be added via `CMakeUserPresets.json`.
+
+> On Windows, Visual Studio CMake Mode uses this generator and automatically loads presets. With Visual Studio Code, the CMake Tools extension automatically uses presets. For other IDEs, refer to their documentation on using CMake presets.
+
+**Filesystem**
+
+```
+.
+|-- CMakeLists.txt         <== executable target
+|-- CMakePresets.json
+|-- [other project files]
+|-- ext/
+│   |-- CMakeLists.txt     <== external dependencies target
+|-- src/
+    |-- [sources and headers]
+```

guide/translations/zh-TW/src/getting_started/project_layout.md

@@ -0,0 +1,9 @@
+# (中文 WIP) Validation Layers
+
+The area of Vulkan that apps interact with: the loader, is very powerful and flexible. Read more about it [here](https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderInterfaceArchitecture.md). Its design enables it to chain API calls through configurable **layers**, eg for overlays, and most importantly for us: [Validation Layers](https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/README.md).
+
+![Vulkan Loader](high_level_loader.png)
+
+As [suggested](https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/khronos_validation_layer.md#vkconfig) by the Khronos Group, we recommend using [Vulkan Configurator (GUI)](https://github.com/LunarG/VulkanTools/tree/main/vkconfig_gui) for validation layers. This application is shipped with the Vulkan SDK, just keep it running while developing Vulkan applications, and ensure it is setup to inject validation layers into all detected applications, with Synchronization Validation enabled. This approach provides a lot of flexibility at runtime, including the ability to have VkConfig break the debugger on encountering an error, and also eliminates the need for validation layer specific code in the applications.
+
+> Note: modify your development (or desktop) environment's `PATH` (or use `LD_LIBRARY_PATH` on supported systems) to make sure the SDK's binaries are visible first.