Chapter 0 Comments

[utterances-bot]

Chapter 0 - Vulkan Guide

Brand new guide to vulkan graphics programming

https://www.vkguide.dev/docs/chapter_0

[arydevy]

whats this?

[LapysDev]

There a way to begin setting up Vulkan in as minimal and bare-bones a way as possible? That is, if one wanted to maybe use only a CLI and the Vulkan SDK and that's it?

[Nyran]

@LapysDev : Actually, the setup as described works like a charm also on the command line. Naturally, for what vblanco is trying to teach here, you'll need some API that is able to provide you with a window/surface , and vk-bootstrap really makes the tutorial easy to follow.

I was very happy to realize that the tutorial works without any problem under Ubuntu 20.4 using the little code skeleton that is provided and, in my case, GLFW3 to create the surface. The dependencies that the project has are really minimal and it helps a lot to concentrate on the concepts - so the tutorial is basically 'bare-bones' :)

Although you could work using the command line only, it makes sense to at least setup some build system to handle for instance the integration of vk-bootstrap. CMake usually works very well.

thumbs up for vkguide

[pr0g]

I'm just starting out on macOS and got things building with a couple of tweaks to the CMakeLists.txt file. I had to explicitly enable a higher C++ standard using target_compile_features(vulkan_guide PRIVATE cxx_std_14) and target_compile_features(vkbootstrap PRIVATE cxx_std_14) (C++14 seems to be the minimum required but you could set cxx_std_17 if you wanted) and I also simplified the SDL2 CMake logic by just installing it locally and using find_package(SDL2 REQUIRED CONFIG). Looks like an awesome tutorial! :+1: 🙂

[AdlanSADOU]

Just dropped the source and third party stuff into my existing vulkan build system that ran with SDL2 (just a vscode task.json) compiled and linked like a charm and got the window 👍

[megalithic3]

Got stuck on this step. "Once CMake is installed, use CMake-gui to open the project root CMakeLists" The only "CMakelists" I found was C:\VulkanSDK\1.2.189.1\Third-Party\Include\glm, and that gives errors. There is no CMakelists.txt in C:\Vulkan\vulkan-guide

[Kaminate]

@megalithic3 you need to download the "Starting Point" link on this page

[Kaminate]

( if you want to clone it from github, its not the master branch https://github.com/vblanco20-1/vulkan-guide/tree/starting-point )

[Ribosome2]

if you are using Clion ,you just need to change set(sdl2_DIR "SDL_PATH" CACHE PATH "Path to SDL2") to set(sdl2_DIR $ENV{SDL_PATH}) and then run

[iaomw]

One macOS, it's always ld: library not found for -lSDL2

[pr0g]

I fixed this in my fork @iaomw, check out https://github.com/pr0g/vulkan-guide/commit/bc64b45093c465a8805a31ddbadd5214219143c0 and https://github.com/pr0g/vulkan-guide/commit/25d574591a076e711a5c9dafce6b5ab4fccfc502 to see if that might help. To install SDL2 as a third-party dependency this repo might also be useful https://github.com/pr0g/sdl-bgfx-imgui-starter (see the instructions in the README and third-party folder).

[ghost]

I downloaded SDL2 and it only has DLL file, which is causing imgui to have a breakdown because it can't find "SLD.h". Did I download the wrong thing? (I downloaded the x64 zip)

[pr0g]

I'd try checking out the links I mentioned above @unnamed-platformer, it'll show how to download SDL2 as a dependency and use it with CMake

One way is also to use it with FetchContent like so...

# CMakeLists.txt
cmake_minimum_required(VERSION 3.22)

project(example LANGUAGES CXX)
cmake_policy(SET CMP0135 NEW) # deals with new behavior with
                              # DOWNLOAD_EXTRACT_TIMESTAMP

include(FetchContent)

FetchContent_Declare(
  SDL2
  URL https://www.libsdl.org/release/SDL2-2.0.20.tar.gz
  URL_HASH MD5=a53acc02e1cca98c4123229069b67c9e)

FetchContent_MakeAvailable(SDL2)

add_executable(${PROJECT_NAME})
target_sources(${PROJECT_NAME} PRIVATE main.cpp)
target_link_libraries(${PROJECT_NAME} PRIVATE SDL2::SDL2 SDL2::SDL2main)

if(WIN32)
  # copy the SDL2.dll to the same folder as the executable
  add_custom_command(
    TARGET ${PROJECT_NAME}
    POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different $<TARGET_FILE:SDL2::SDL2>
            $<TARGET_FILE_DIR:${PROJECT_NAME}>
    VERBATIM)
endif()

// main.cpp

#include <SDL.h>

int main() {
  // do SDL stuff...
  return 0;
}

[ghost]

A problem I have with this is that I don’t know how to use CMAke. I’ve been using regular Visual Studio without backing up my files or anything. Would you recommend any resources to learn it?

[pr0g]

I didn't know much about CMake a few years ago too but it is definitely worth learning. I put together this repo with a bunch of example projects which you might find useful - https://github.com/pr0g/cmake-examples

[whiitehead]

I think you need to revisit the SDL2 stuff something must have changed since you wrote this.

[pr0g]

I rechecked this and have updated my fork (https://github.com/pr0g/vulkan-guide/tree/all-chapters).

If you don't have SDL2 installed on your system, go to the new SDL2 folder I've added in third_party. Run cmake -B build (ideally with -G Ninja to speed things up) and then run cmake --build build. This will download, build and install SDL2 to the third_party/SDL2/build folder.

Once you've done that, go back to the root (all_chapters branch) and run cmake -B build -G Ninja -DCMAKE_PREFIX_PATH=$(pwd)/third_party/SDL2/build and things should build correctly. Note you'll need to have Vulkan installed on the system for this to work (see this page for more info https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html). It really boils down to these steps for getting Vulkan set up.

VULKAN_SDK="<path/to>/vulkan-sdk/macOS"
export VULKAN_SDK
PATH=$PATH:$VULKAN_SDK/bin
export PATH
DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$VULKAN_SDK/lib
export DYLD_LIBRARY_PATH
VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d
export VK_LAYER_PATH
VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json
export VK_ICD_FILENAMES

For completeness, the steps for building this repo after setting up Vulkan would be

cd <vkguide-root> # (all-chapters branch)
cd third_party/SDL2/build
cmake -B build -G Ninja
cmake --build build
cd ../..
cmake -B build -G Ninja -DCMAKE_PREFIX_PATH=$(pwd)/third_party/SDL2/build
cmake --build build
./build/bin/chapter-2

[zhulinspace]

when I build on macos 13.0, it gives errors like below:

[build] /Users/linlinzhu/CPlusProjects/vulkan-guide-all-chapters/third_party/imgui/imgui_impl_vulkan.cpp:76:33: error: cannot initialize a variable of type 'VkRenderPass' (aka 'VkRenderPass_T *') with an rvalue of type 'void *'
[build] static VkRenderPass             g_RenderPass = VK_NULL_HANDLE;

I don't know how to fix this , I tried on windows ,it builded sucess.

[zhulinspace]

I added set(CMAKE_CXX_STANDARD 11) in the cmakeLists.txt , the error rvalue of type void * disappered. it gives other errors:

[build] In file included from /Users/linlinzhu/CPlusProjects/vulkan-guide-all-chapters/third_party/vkbootstrap/VkBootstrap.cpp:17:
[build] /Users/linlinzhu/CPlusProjects/vulkan-guide-all-chapters/third_party/vkbootstrap/VkBootstrap.h:44:4: error: no matching constructor for initialization of 'vkb::detail::Error'
[build]         : m_error{ error_code, result }, m_init{ false } {}
[build]           ^      ~~~~~~~~~~~~~~~~~~~~~~
[build] /Users/linlinzhu/CPlusProjects/vulkan-guide-all-chapters/third_party/vkbootstrap/VkBootstrap.h:31:8: note: candidate constructor (the implicit copy constructor) not viable: requires 1 argument, but 2 were provided
[build] struct Error {
[build]        ^
[build] /Users/linlinzhu/CPlusProjects/vulkan-guide-all-chapters/third_party/vkbootstrap/VkBootstrap.h:31:8: note: candidate constructor (the implicit move constructor) not viable: requires 1 argument, but 2 were provided

it should Specify the c++ version？which version?

[pr0g]

I think you need to use at least C++ 14.

I have target_compile_features(vkbootstrap PRIVATE cxx_std_14) added to third_party/CMakeLists.txt and target_compile_features(vulkan_guide PRIVATE cxx_std_14) added to src/CMakeLists.txt.

Also for things to work on macOS you might need to check out the fork I mentioned above (see https://github.com/pr0g/vulkan-guide/tree/all-chapters)

[zhulinspace]

Thanks for the reply, I checked out the fork :https://github.com/pr0g/vulkan-guide/tree/all-chapters,then it builded sucess.

[rafaelbeckel]

If anyone is running on MacOS with CLion, this is what worked for me: I installed SDL2 with Homebrew brew install sdl2 and edited the third_party/CMakeLists.txt file to set sdl2_DIR variable to: set(sdl2_DIR "/opt/homebrew/Cellar/sdl2/2.26.4").

[liulikui1984]

vk_init.h looks like this should be: vk_initializers.h looks like this ?

[adlambert]

Don't really need all of this extra stuff when I just want to get into the Vulkan. I've avoided all the CMake stuff and created new projects directly in Visual Studio. It just didn't work, didn't match with the guide (for example SDL2 has moved to github) and became very frustrating.

[pr0g]

@adlambert I know the CMake stuff can be a bit of a pain at times but I can assure you getting a build up and running using it will be easier than trying to do everything yourself from scratch inside Visual Studio.

I have just updated my fork on Windows that should make it easier to get things working (and it will generate a Visual Studio solution you can then use).

Please try following these steps:

1. Ensure you have the latest Vulkan SDK installed.
2. Open a new terminal/command prompt session (this will make sure all environment variables are refreshed).
   1. Mine are VK_SDK_PATH=C:\VulkanSDK\1.3.250.0 and VULKAN_SDK=C:\VulkanSDK\1.3.250.0 (you can check this in the Windows Environment Variables dialog).
3. Create a new folder with this fork of vkguide.
   1. mkdir vkguide && cd vkguide
   2. git clone https://github.com/pr0g/vulkan-guide.git .
4. Run git fetch origin to make sure you have all the branches.
5. Run git switch all-chapters to switch to the all-chapters branch.
6. Go to the SDL2 directory.
   4. cd third-party/SDL2
7. Run cmake -B build
   6. This should most likely pick Visual Studio as the default generator on Windows (if not, delete the build folder and run cmake -B build -G "Visual Studio 17 2022" (or whatever is the latest version you have).
8. Next build and install SDL2.
   8. cmake --build build --config Release
      9. (note: SDL2 will not be installed globally but in the build folder you just created).
9. Go back up to the root folder (vkguide directory).
   11. cd ../..
10. Run cmake -B build -DCMAKE_PREFIX_PATH=%cd%/third_party/SDL2/build.
    13. This will generate the project (Visual Studio solution) for all the examples.
    14. (CMAKE_PREFIX_PATH is used to tell CMake where to find the SDL2 library we just built).
11. At this stage you can open the .sln file in the build folder, or...
12. Run cmake --build build
    17. You can specify what config type to build by using --config (e.g. cmake --build build --config Release, not passing this will default to Debug).
13. This will build all the examples, you can then run them by entering.
    19. build\bin\chapter-2.exe

I hope that helps, I know it seems like a lot of steps but once this is done you can then just build happily from inside Visual Studio (from there you can pick to have a Debug or Release build too instead of passing --config when invoking CMake).

About 4-5 years ago I also didn't much care for CMake but then spent a bunch of time researching it and now I do find it insanely useful. I wrote up all my findings here that you might find helpful cmake-examples.

[adlambert]

@pr0g, I got a bit frustrated but I should stop and thank you for giving your time and energy to make this tutorial and share your knowledge, and for taking the time to provide the updated information. I really do appreciate it.

I will roll everything back and follow your advice, thanks again.

[pr0g]

No worries at all @adlambert, I know the feeling all too well 😅 My pleasure, I hope that helps. If you get stuck at some point let me know and I'll see if I can unblock you. It would be cool if I could get the fork changes merged back to the main branch too, I'll see if I can follow up on that next weekend. Let me know how you get on 👍

[adlambert]

@pr0g, those instructions appear to work nicely , they get me to the point of having the solution in Visual Studio. Chapter zero starts a black full screen in the foreground. Chapter 1 starts a full screen window that cycles through blue shades. Running chapter 2 fails to compile shaders and then outputs a screenful of validation errors, I'm hoping this is because I haven't completed the chapter 2 tutorial.

I will have time to start working through the chapters tomorrow to see if I can fix it. Thanks again for you generous help.

[pr0g]

@adlambert That's great to hear! 🥳 Thanks for letting me know.

Hmm I think chapter 2 should work correctly (when I tested you get a large triangle filling the screen). You might need to build all targets (projects in Visual Studio) in case one is needed to build the shaders potentially. I'd try the cmake --build build command on the folder that got generated with the Visual Studio solution inside it. Next time I'm at my machine I'll try and test only building in VS to see what has to be built.

Not at all! Really glad it was helpful, have fun learning Vulkan! 🙂

[adlambert]

@pr0g It's in init_pipelines() calling load_shader_module() it's returning the error and cout << the error message. The the validation layers: If module is not VK_NULL_HANDLE, module must be a valid VkShaderModule handle.

The path passed to load_shader_module() is shaders/triangle.vert.spv etc, but the actual shaders folder is not in the chapter2 folder, it's in the vkguide folder at the same level as the chapters folders.

I have done all the builds as suggested. This is fine apart from a few uint32_t / size_t warnings. I've also seen the shaders get built during the cmake -B build -DCMAKE_PREFIX_PATH=%cd%/third_party/SDL2/build .

[pr0g]

Aah this will be down to the Visual Studio working directory... I'll look at a proper fix later (I need to find the right place to add this line).

set_target_properties(
  ${PROJECT_NAME}
  # required for project when using visual studio generator
  PROPERTIES VS_DEBUGGER_WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})

In the meantime if you set the working directory directly inside of Visual Studio it'll get things working. Right click a project in Visual Studio and click Properties, then go to Debugging, and change the Working Directory setting to the root folder of vkguide. Something like the below...

The alternative is to not run from inside Visual Studio and just ensure you launch the executable from the vkguide root folder (such as ....\projects\vk-guide>build\bin\chapter-2.exe).

[adlambert]

@pr0g, that worked, I have the triangle. Thanks again. It runs OK if I start launch the debug release from the run > triangles in VS, with or without debugging.

Thanks so much for your help again. I'm excited now, I have the afternoon free to work through the tutorial.

I've done plenty of OpenGL with GLFW, but this is like being on another planet.

[pr0g]

Awesome! 😄 That's great to hear @adlambert. I'll get my fork updated later this week hopefully to make this automatic but good to hear you're unblocked in the meantime.

My pleasure, I'm very pleased to hear! I hope the rest of the tutorial goes well 🙂

[pr0g]

Quick FYI I added another commit to my fork that should have things work correctly in Visual Studio without making any manual edits (see https://github.com/pr0g/vulkan-guide/commit/815ff65695b03a2f844b8c57b5abd9c6d8b62e2e). I also got rid of the bin subfolder as that was causing more issues than it was worth. The change unfortunately has some of my autoformatter updates too, probably shouldn't have run that but it's not too bad looking at the diff.

[adlambert]

Thanks @pr0g, having a easier project startup will lower the barrier to entry to the tutorial for some. Still important to understand the tools like CMake and GIT, especially for anyone interested in training for a career in development.

[XiaochaoYan]

This tutorial seems to assuming readers having piror knowledge with SDL2 libraby.

For SDL2 related problems. 1.You need to download BOTH SDL2-2.28.1-win32-x64.zip AND SDL2-devel-2.28.1-VC.zip SDL2-2.28.1-win32-x64.zip -> copy the SDL2.dll file to your VisualStdio project folder (e.g. "vulkan-guide-all-chapters\bin\Debug") SDL2-devel-2.28.1-VC.zip -> Just put it anywhere convenientfor you, then config its path in CMAKE and use CMAKE to open the ViusalStudio project.

Sovled my SDL2 related problem on Win11 / VisualStudio 2022 Aug 2nd 2023. Best of luck to you all.

[XiaochaoYan]

@ghost you will need to download BOTH SDL2-2.28.1-win32-x64.zip AND SDL2-devel-2.28.1-VC.zip for SLD2 library. Please see my comment above.

[JElledgeCG]

@XiaochaoYan Lifesaving comment, this helped a lot!