Skip to content

Commit 33f5364

Browse files
Mes0903karnkaulCDDing
authored
Translate chapter 1 into Traditional Chinese (zh-TW) (#28)
* 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) * Translate chapter 1 into Traditional Chinese Includes: - Introduction - Getting Started - Project Layout - Validation Layers - class App --------- Co-authored-by: Karn Kaul <[email protected]> Co-authored-by: MyungKun Chang <[email protected]>
1 parent 12ba16a commit 33f5364

23 files changed

+347
-115
lines changed

‎.github/workflows/ci.yml

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ on:
44
branches-ignore:
55
- staging
66
- production
7+
workflow_dispatch:
78
jobs:
89
format-check:
910
runs-on: ubuntu-latest
@@ -26,11 +27,11 @@ jobs:
2627
- name: init
2728
run: uname -m; sudo apt update -yqq && sudo apt install -yqq ninja-build mesa-common-dev libwayland-dev libxkbcommon-dev wayland-protocols extra-cmake-modules
2829
- name: configure
29-
run: export CXX=g++-14; cmake -S . --preset=default -B build -DGLFW_BUILD_X11=OFF
30+
run: cmake -S . --preset=ninja-gcc -B build -DGLFW_BUILD_X11=OFF -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14
3031
- name: build debug
31-
run: cmake --build build --config=Debug
32+
run: cmake --build build --config=Debug -- -v
3233
- name: build release
33-
run: cmake --build build --config=Release
34+
run: cmake --build build --config=Release -- -v
3435
- name: test debug
3536
run: cd build && ctest -V -C Debug
3637
- name: test release
@@ -44,9 +45,9 @@ jobs:
4445
- name: configure
4546
run: cmake -S . --preset=ninja-clang -B build -DGLFW_BUILD_X11=OFF
4647
- name: build debug
47-
run: cmake --build build --config=Debug
48+
run: cmake --build build --config=Debug -- -v
4849
- name: build release
49-
run: cmake --build build --config=Release
50+
run: cmake --build build --config=Release -- -v
5051
- name: test debug
5152
run: cd build && ctest -V -C Debug
5253
- name: test release
@@ -58,11 +59,11 @@ jobs:
5859
- name: init
5960
run: uname -m; sudo apt update -yqq && sudo apt install -yqq ninja-build mesa-common-dev libwayland-dev libxkbcommon-dev wayland-protocols extra-cmake-modules
6061
- name: configure
61-
run: export CXX=g++-14; cmake -S . --preset=default -B build -DGLFW_BUILD_X11=OFF
62+
run: cmake -S . --preset=ninja-gcc -B build -DGLFW_BUILD_X11=OFF -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14
6263
- name: build debug
63-
run: cmake --build build --config=Debug
64+
run: cmake --build build --config=Debug -- -v
6465
- name: build release
65-
run: cmake --build build --config=Release
66+
run: cmake --build build --config=Release -- -v
6667
- name: test debug
6768
run: cd build && ctest -V -C Debug
6869
- name: test release
@@ -76,9 +77,9 @@ jobs:
7677
- name: configure
7778
run: cmake -S . --preset=ninja-clang -B build -DGLFW_BUILD_X11=OFF
7879
- name: build debug
79-
run: cmake --build build --config=Debug
80+
run: cmake --build build --config=Debug -- -v
8081
- name: build release
81-
run: cmake --build build --config=Release
82+
run: cmake --build build --config=Release -- -v
8283
- name: test debug
8384
run: cd build && ctest -V -C Debug
8485
- name: test release
@@ -106,9 +107,9 @@ jobs:
106107
- name: configure
107108
run: cmake -S . --preset=ninja-clang -B clang
108109
- name: build debug
109-
run: cmake --build clang --config=Debug
110+
run: cmake --build clang --config=Debug -- -v
110111
- name: build release
111-
run: cmake --build clang --config=Release
112+
run: cmake --build clang --config=Release -- -v
112113
- name: test debug
113114
run: cd clang && ctest -V -C Debug
114115
- name: test release

‎.github/workflows/deploy.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ on:
44
branches:
55
- production
66
- staging
7+
workflow_dispatch:
78
jobs:
89
deploy:
910
runs-on: ubuntu-latest

‎.github/workflows/guide.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ on:
33
pull_request:
44
branches-ignore:
55
- staging
6+
workflow_dispatch:
67
jobs:
78
build-book:
89
runs-on: ubuntu-latest

‎CMakePresets.json

Lines changed: 144 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,131 @@
11
{
2-
"version": 2,
2+
"version": 5,
33
"cmakeMinimumRequired": {
44
"major": 3,
5-
"minor": 20,
5+
"minor": 24,
66
"patch": 0
77
},
88
"configurePresets": [
99
{
1010
"name": "default",
11-
"description": "Build configuration using Ninja Multi-config",
11+
"displayName": "Default Config",
12+
"description": "Base configuration using Ninja Multi-config",
1213
"generator": "Ninja Multi-Config",
1314
"binaryDir": "${sourceDir}/out/default",
1415
"cacheVariables": {
1516
"CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
1617
}
1718
},
1819
{
19-
"name": "ninja-clang",
20-
"description": "Build configuration using Ninja Multi-config / clang",
20+
"name": "base-gcc",
21+
"hidden": true,
22+
"inherits": "default",
23+
"cacheVariables": {
24+
"CMAKE_C_COMPILER": "gcc",
25+
"CMAKE_CXX_COMPILER": "g++"
26+
}
27+
},
28+
{
29+
"name": "base-clang",
30+
"hidden": true,
2131
"inherits": "default",
22-
"binaryDir": "${sourceDir}/out/clang",
2332
"cacheVariables": {
2433
"CMAKE_C_COMPILER": "clang",
2534
"CMAKE_CXX_COMPILER": "clang++"
2635
}
2736
},
37+
{
38+
"name": "base-msvc",
39+
"hidden": true,
40+
"inherits": "default",
41+
"cacheVariables": {
42+
"CMAKE_C_COMPILER": "cl",
43+
"CMAKE_CXX_COMPILER": "cl"
44+
}
45+
},
46+
{
47+
"name": "ninja-gcc",
48+
"displayName": "Ninja GCC",
49+
"description": "Build configuration using Ninja Multi-config / GCC",
50+
"inherits": "base-gcc",
51+
"binaryDir": "${sourceDir}/out/gcc",
52+
"cacheVariables": {
53+
"CMAKE_CXX_FLAGS_DEBUG_INIT": "-Wall -Wextra -Wpedantic -Werror=return-type",
54+
"CMAKE_CXX_FLAGS_INIT": "-Wall -Wextra -Wpedantic -Werror"
55+
}
56+
},
57+
{
58+
"name": "ninja-clang",
59+
"displayName": "Ninja Clang",
60+
"description": "Build configuration using Ninja Multi-config / Clang",
61+
"inherits": "base-clang",
62+
"binaryDir": "${sourceDir}/out/clang",
63+
"cacheVariables": {
64+
"CMAKE_CXX_FLAGS_DEBUG_INIT": "-Wall -Wextra -Wpedantic -Werror=return-type",
65+
"CMAKE_CXX_FLAGS_INIT": "-Wall -Wextra -Wpedantic -Werror"
66+
}
67+
},
68+
{
69+
"name": "ninja-msvc",
70+
"displayName": "Ninja MSVC",
71+
"description": "Build configuration using Ninja Multi-config / MSVC",
72+
"inherits": "base-msvc",
73+
"binaryDir": "${sourceDir}/out/msvc",
74+
"cacheVariables": {
75+
"CMAKE_CXX_FLAGS_INIT": "/WX"
76+
}
77+
},
2878
{
2979
"name": "ninja-ubsan",
80+
"displayName": "Ninja UBSan",
3081
"description": "UBSan build configuration using Ninja Multi-config",
3182
"inherits": "default",
3283
"binaryDir": "${sourceDir}/out/ubsan",
3384
"cacheVariables": {
34-
"CMAKE_C_FLAGS": "-fsanitize=undefined",
35-
"CMAKE_CXX_FLAGS": "-fsanitize=undefined"
85+
"CMAKE_CXX_FLAGS_DEBUG_INIT": "-fsanitize=undefined -Wall -Wextra -Wpedantic -Werror=return-type",
86+
"CMAKE_CXX_FLAGS_INIT": "-fsanitize=undefined -Wall -Wextra -Wpedantic -Werror"
3687
}
3788
},
3889
{
3990
"name": "ninja-asan",
91+
"displayName": "Ninja ASan",
4092
"description": "ASan build configuration using Ninja Multi-config",
4193
"inherits": "default",
4294
"binaryDir": "${sourceDir}/out/asan",
4395
"cacheVariables": {
44-
"CMAKE_C_FLAGS": "-fsanitize=address",
45-
"CMAKE_CXX_FLAGS": "-fsanitize=address"
96+
"CMAKE_CXX_FLAGS_DEBUG_INIT": "-fsanitize=address -Wall -Wextra -Wpedantic -Werror=return-type",
97+
"CMAKE_CXX_FLAGS_INIT": "-fsanitize=address -Wall -Wextra -Wpedantic -Werror"
98+
}
99+
},
100+
{
101+
"name": "ninja-msvc-asan",
102+
"displayName": "Ninja MSVC ASan",
103+
"description": "ASan build configuration using Ninja Multi-config",
104+
"inherits": "base-msvc",
105+
"binaryDir": "${sourceDir}/out/asan",
106+
"cacheVariables": {
107+
"CMAKE_CXX_FLAGS_INIT": "-fsanitize=address"
46108
}
47109
},
48110
{
49111
"name": "ninja-tsan",
112+
"displayName": "Ninja TSan",
50113
"description": "TSan build configuration using Ninja Multi-config",
51114
"inherits": "default",
52115
"binaryDir": "${sourceDir}/out/tsan",
53116
"cacheVariables": {
54-
"CMAKE_C_FLAGS": "-fsanitize=thread",
55-
"CMAKE_CXX_FLAGS": "-fsanitize=thread"
117+
"CMAKE_CXX_FLAGS_INIT": "-fsanitize=thread -Wall -Wextra -Wpedantic -Werror=return-type"
56118
}
57119
},
58120
{
59121
"name": "vs22",
122+
"displayName": "Visual Studio 2022",
60123
"description": "Build configuration using Visual Studio 17 (2022)",
61124
"generator": "Visual Studio 17 2022",
62125
"binaryDir": "${sourceDir}/out/vs",
126+
"cacheVariables": {
127+
"CMAKE_CXX_FLAGS_INIT": "/WX"
128+
},
63129
"architecture": {
64130
"value": "x64",
65131
"strategy": "external"
@@ -82,6 +148,36 @@
82148
"configurePreset": "default",
83149
"configuration": "RelWithDebInfo"
84150
},
151+
{
152+
"name": "GCC Debug",
153+
"configurePreset": "ninja-gcc",
154+
"configuration": "Debug"
155+
},
156+
{
157+
"name": "GCC RelWithDebInfo",
158+
"configurePreset": "ninja-gcc",
159+
"configuration": "RelWithDebInfo"
160+
},
161+
{
162+
"name": "Clang Debug",
163+
"configurePreset": "ninja-clang",
164+
"configuration": "Debug"
165+
},
166+
{
167+
"name": "Clang RelWithDebInfo",
168+
"configurePreset": "ninja-clang",
169+
"configuration": "RelWithDebInfo"
170+
},
171+
{
172+
"name": "MSVC Debug",
173+
"configurePreset": "ninja-msvc",
174+
"configuration": "Debug"
175+
},
176+
{
177+
"name": "MSVC Release",
178+
"configurePreset": "ninja-msvc",
179+
"configuration": "Release"
180+
},
85181
{
86182
"name": "UBSan Debug",
87183
"configurePreset": "ninja-ubsan",
@@ -107,6 +203,42 @@
107203
"configuration": "RelWithDebInfo",
108204
"inheritConfigureEnvironment": true
109205
},
206+
{
207+
"name": "GCC Debug",
208+
"configurePreset": "ninja-gcc",
209+
"configuration": "Debug",
210+
"inheritConfigureEnvironment": true
211+
},
212+
{
213+
"name": "GCC RelWithDebInfo",
214+
"configurePreset": "ninja-gcc",
215+
"configuration": "RelWithDebInfo",
216+
"inheritConfigureEnvironment": true
217+
},
218+
{
219+
"name": "Clang Debug",
220+
"configurePreset": "ninja-clang",
221+
"configuration": "Debug",
222+
"inheritConfigureEnvironment": true
223+
},
224+
{
225+
"name": "Clang RelWithDebInfo",
226+
"configurePreset": "ninja-clang",
227+
"configuration": "RelWithDebInfo",
228+
"inheritConfigureEnvironment": true
229+
},
230+
{
231+
"name": "MSVC Debug",
232+
"configurePreset": "ninja-msvc",
233+
"configuration": "Debug",
234+
"inheritConfigureEnvironment": true
235+
},
236+
{
237+
"name": "MSVC Release",
238+
"configurePreset": "ninja-msvc",
239+
"configuration": "Release",
240+
"inheritConfigureEnvironment": true
241+
},
110242
{
111243
"name": "UBSan Debug",
112244
"configurePreset": "ninja-ubsan",

‎guide/src/rendering/dynamic_rendering.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ void App::submit_and_present() {
161161
wait_semaphore_info.setSemaphore(*render_sync.draw)
162162
.setStageMask(vk::PipelineStageFlagBits2::eColorAttachmentOutput);
163163
auto signal_semaphore_info = vk::SemaphoreSubmitInfo{};
164-
signal_semaphore_info.setSemaphore(*render_sync.present)
164+
signal_semaphore_info.setSemaphore(m_swapchain->get_present_semaphore())
165165
.setStageMask(vk::PipelineStageFlagBits2::eColorAttachmentOutput);
166166
submit_info.setCommandBufferInfos(command_buffer_info)
167167
.setWaitSemaphoreInfos(wait_semaphore_info)
@@ -175,8 +175,7 @@ void App::submit_and_present() {
175175
// framebuffer size does not match the Swapchain image size, check it
176176
// explicitly.
177177
auto const fb_size_changed = m_framebuffer_size != m_swapchain->get_size();
178-
auto const out_of_date =
179-
!m_swapchain->present(m_queue, *render_sync.present);
178+
auto const out_of_date = !m_swapchain->present(m_queue);
180179
if (fb_size_changed || out_of_date) {
181180
m_swapchain->recreate(m_framebuffer_size);
182181
}

‎guide/src/rendering/render_sync.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,6 @@ Add a private `struct RenderSync` to `App`:
1717
struct RenderSync {
1818
// signaled when Swapchain image has been acquired.
1919
vk::UniqueSemaphore draw{};
20-
// signaled when image is ready to be presented.
21-
vk::UniqueSemaphore present{};
2220
// signaled with present Semaphore, waited on before next render.
2321
vk::UniqueFence drawn{};
2422
// used to record rendering commands.
@@ -68,7 +66,6 @@ void App::create_render_sync() {
6866
std::views::zip(m_render_sync, command_buffers)) {
6967
sync.command_buffer = command_buffer;
7068
sync.draw = m_device->createSemaphoreUnique({});
71-
sync.present = m_device->createSemaphoreUnique({});
7269
sync.drawn = m_device->createFenceUnique(fence_create_info_v);
7370
}
7471
}

‎guide/src/rendering/swapchain_loop.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ Additionally, the number of swapchain images can vary, whereas the engine should
1919

2020
## Virtual Frames
2121

22-
All the dynamic resources used during the rendering of a frame comprise a virtual frame. The application has a fixed number of virtual frames which it cycles through on each render pass. For synchronization, each frame will be associated with a [`vk::Fence`](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#synchronization-fences) which will be waited on before rendering to it again. It will also have a pair of [`vk::Semaphore`](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#synchronization-semaphores)s to synchronize the acquire, render, and present calls on the GPU (we don't need to wait for them on the CPU side / in C++). For recording commands, there will be a [`vk::CommandBuffer`](https://docs.vulkan.org/spec/latest/chapters/cmdbuffers.html) per virtual frame, where all rendering commands for that frame (including layout transitions) will be recorded.
22+
All the dynamic resources used during the rendering of a frame comprise a virtual frame. The application has a fixed number of virtual frames which it cycles through on each render pass. For synchronization, each frame will be associated with a [`vk::Fence`](https://registry.khronos.org/vulkan/specs/latest/man/html/VkFence.html) which will be waited on before rendering to it again. It will also have a [`vk::Semaphore`](https://registry.khronos.org/vulkan/specs/latest/man/html/VkSemaphore.html) to synchronize the acquire and render calls on the GPU (we don't need to wait for them in the code). For recording commands, there will be a [`vk::CommandBuffer`](https://docs.vulkan.org/spec/latest/chapters/cmdbuffers.html) per virtual frame, where all rendering commands for that frame (including layout transitions) will be recorded.
23+
24+
Presentation will require a semaphore for synchronization too, but since the swapchain loop waits on the _drawn_ fence, which will be pre-signaled for each virtual frame on first use, present semaphores cannot be part of the virtual frame. It is possible to acquire another image and submit commands with a present semaphore that has not been signaled yet - this is invalid. Thus, these semaphores will be tied to the swapchain images (associated with their indices), and recreated with it.
2325

2426
## Image Layouts
2527

0 commit comments

Comments
 (0)