diff --git a/REUSE.toml b/REUSE.toml index 00a75afe..e0e45c61 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -121,7 +121,7 @@ SPDX-License-Identifier = "CC-BY-4.0" path = [ "en/00_Introduction.adoc", "en/01_Overview.adoc", - "en/02_Development_environment.adoc", + "en/02_Build_and_development_environment.adoc", "en/03_Drawing_a_triangle/**", "en/04_Vertex_buffers/**", "en/05_Uniform_buffers/**", diff --git a/antora/modules/ROOT/nav.adoc b/antora/modules/ROOT/nav.adoc index ee0b4247..26d3ddd1 100644 --- a/antora/modules/ROOT/nav.adoc +++ b/antora/modules/ROOT/nav.adoc @@ -5,7 +5,7 @@ * xref:00_Introduction.adoc[Introduction] * xref:01_Overview.adoc[Overview] -* xref:02_Development_environment.adoc[Development environment] +* xref:02_Build_and_development_environment.adoc[Build and development environment] * xref:03_Drawing_a_triangle/00_Setup/00_Base_code.adoc[Drawing a triangle] ** xref:03_Drawing_a_triangle/00_Setup/00_Base_code.adoc[Setup] *** xref:03_Drawing_a_triangle/00_Setup/00_Base_code.adoc[Base Code] diff --git a/en/00_Introduction.adoc b/en/00_Introduction.adoc index ac4b3bf8..b89b8ef3 100644 --- a/en/00_Introduction.adoc +++ b/en/00_Introduction.adoc @@ -40,6 +40,11 @@ It also contains Vulkan usage clarifications, improved synchronization and new c This tutorial will teach you the basics of using the https://www.khronos.org/vulkan/[Vulkan] graphics and compute API. +You'll learn how to render a basic scene +while exploring the core features of a modern Vulkan application. + +image::/images/drawing_model.png[A textured model rendered with Vulkan] + Vulkan is an API by the https://www.khronos.org/[Khronos group] that provides a much better abstraction of modern graphics cards. This new interface allows you to better describe what your application diff --git a/en/01_Overview.adoc b/en/01_Overview.adoc index 20a5ce85..d5454cce 100644 --- a/en/01_Overview.adoc +++ b/en/01_Overview.adoc @@ -341,4 +341,4 @@ layers are so extensive, it can actually be a lot easier to find out why your screen is black compared to OpenGL and Direct3D! There's only one more step before we'll start writing code, and that's -xref:02_Development_environment.adoc[setting up the development environment]. +xref:02_Build_and_development_environment.adoc[setting up the development environment]. diff --git a/en/02_Development_environment.adoc b/en/02_Build_and_development_environment.adoc similarity index 82% rename from en/02_Development_environment.adoc rename to en/02_Build_and_development_environment.adoc index 4695857b..2e85817c 100644 --- a/en/02_Development_environment.adoc +++ b/en/02_Build_and_development_environment.adoc @@ -1,4 +1,5 @@ -= Development Environment += Build and Development Environment +:page-aliases: 02_Development_environment.adoc :pp: {plus}{plus} @@ -8,6 +9,66 @@ except for the compiler, are compatible with Windows, Linux and macOS, but the steps for installing them differ a bit, which is why they're described separately here. +== Quick start + +Follow these basic steps to build and test the repository on Windows and Linux. + +1. Obtain the source code for this project using git clone: ++ +[,shell] +---- +git clone https://github.com/KhronosGroup/Vulkan-Tutorial +cd Vulkan-Tutorial +---- +2. You'll need a C++20 compiler, CMake 3.29+, and Vulkan SDK 1.4.335+ + * The Vulkan SDK can be obtained from link:https://vulkan.lunarg.com/sdk/home[LunarG]. See <> for details. + * See the <<_cmake, CMake>>, <> and <> sections, for details about the build dependencies. +3. On Windows, install link:https://github.com/microsoft/vcpkg[vcpkg] following link:https://learn.microsoft.com/en-us/vcpkg/get_started/get-started[the official guide], and add the directory containing `vcpkg.exe` to your `PATH`. +4. From the repository folder, run the installation script for your platform: + * *Linux:* `bash scripts/install_dependencies_linux.sh` + * *Windows (PowerShell):* `.\scripts\install_dependencies_windows.bat` + * You can read <<_common_considerations,Common considerations>> for more details. +5. Manually configure the project: ++ +On Windows: ++ +[,shell] +---- +cd attachments +cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="[path/to/vcpkg]/scripts/buildsystems/vcpkg.cmake" +---- + * Replace `[path/to/vcpkg]` with your vcpkg installation directory. ++ +On Linux: ++ +[,shell] +---- +cd attachments +cmake -B build -S . +---- + * Read <> for more information. +6. You can compile the project manually: + * Go to the `attachments` folder + * Compile the project and generate binaries for all steps with: ++ +[,shell] +---- +cmake --build build --config Debug +---- +7. From `attachments`, run the model-loading example: + * *Windows, Visual Studio*: `cd build\28_model_loading\Debug`, then `.\28_model_loading.exe`. + * *Linux, Ninja or Unix Makefiles*: `cd build/28_model_loading`, then `./28_model_loading`. + * You should see a textured model like the one shown below. ++ +image::/images/drawing_model.png[A textured model rendered with Vulkan] +* See <<_running_the_examples,Running the examples>> for other examples and their expected output. + +The tutorial supports macOS. Read the <<_macos,macOS instructions>> if you want to run this on macOS. + +Alternatively, if you want to use an IDE: + * On Linux, install the dependencies, then you can use <> to configure, build and run the project. + * On Windows, install the dependencies including vcpkg, and configure the project `cd attachments; cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="[path/to/vcpkg]/scripts/buildsystems/vcpkg.cmake"`. Visual Studio should now be able to open `attachments\build\VulkanTutorial.sln` or `attachments\build\VulkanTutorial.slnx` depending on your version. + == Getting the code First we need to clone the code for the tutorial from the https://github.com/KhronosGroup/Vulkan-Tutorial[github repository]. @@ -50,6 +111,7 @@ If you prefer to install the dependencies manually, or if you're using macOS, fo == Common considerations +[#common_considerations_vulkan_sdk] === Vulkan SDK The most important part you'll need for developing Vulkan applications is the SDK. @@ -129,7 +191,7 @@ The Vulkan C{pp} headers also offer a C{pp} module. A large advantage of C{pp} m [NOTE] ==== Module support in the Vulkan C{pp} headers is still experimental and might not work with all compilers. Unless you want to experiment, it's recommended to **not** use them. -==== +==== To enable the Vulkan C{pp}20 module in the attachments template, configure CMake with: @@ -224,6 +286,7 @@ easy-to-support features available in a cross-platform library. However, for th tutorial, we're going to use tinyobjloader for its pure simplicity. We recommend tinyobjloader library only for small not complex projects. +[#common_considerations_windows] == Windows Development in Windows is easiest with Visual Studio. CLion works well with @@ -277,6 +340,7 @@ image::/images/library_directory.png[] Tinyobjloader can be installed with vcpkg like so: vcpkg install tinyobjloader +[#common_considerations_linux] == Linux These instructions will be aimed at Ubuntu, Fedora and Arch Linux users, but @@ -301,8 +365,8 @@ link to the latest on like so: [,shell] ---- pushd vulkansdk -tar -xf vulkansdk-linux-x86_64-1.4.304.1.tar.xz -ln -s 1.4.304.1 default +tar -xf vulkansdk-linux-x86_64-1.4.335.0.tar.xz +ln -s 1.4.335.0 default ---- Then add the following to your ~/.bashrc file so Vulkan's environment @@ -372,6 +436,7 @@ or sudo pacman -S glm ---- +[#setting-up-clion] === Setting up CLion (optional) You can get http://jetbrains.com[CLion] from there. We recommend installing @@ -500,6 +565,7 @@ You are now all set for xref:03_Drawing_a_triangle/00_Setup/00_Base_code.adoc[th Vulkan is a first-class API on Android and widely supported. But using it differs in several key areas from window management to build systems. So while the basic chapters focus on desktop platforms, the tutorial also has a xref:14_Android.adoc[dedicated chapter] that walks you through setting up your development environment and getting the tutorial code up-and-running on Android. +[#setting-up-a-cmake-project] == Setting up a CMake project Now that you have installed all the dependencies, we can set up a basic @@ -509,7 +575,7 @@ everything works. We will assume that you already have some basic experience with CMake, like how variables and rules work. If not, you can get up to speed very quickly with https://cmake.org/cmake/help/book/mastering-cmake/cmake/Help/guide/tutorial/[this tutorial]. -The `attachment\template` folder contains a CMake template that you can use to create a project file in the `build` folder for your IDE of choice. Use this as a starting point to work along the tutorial: +The `attachments/template` folder contains a CMake template that you can use to create a project file in the `build` folder for your IDE of choice. Use this as a starting point to work along the tutorial: ---- cd attachments\template @@ -524,3 +590,48 @@ cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path\to\vcpkg]\scripts\buildsystems\ ---- Congratulations, you're all set for xref:03_Drawing_a_triangle/00_Setup/00_Base_code.adoc[playing with Vulkan]! + +== Running the examples + +Each tutorial binary is a checkpoint in the tutorial, rather than a complete application. +The early examples, from `00_base_code` through `14_command_buffers`, +open an empty window that may appear black because they do not yet draw and present a triangle. +This alone does not mean your environment is broken. + +To check your setup, try the triangle and model-loading examples below. +Start from the `attachments` directory. +Each example must be run from its own folder so it can find its shaders and assets. + +=== Windows (Visual Studio, Debug build) + +[,shell] +---- +# Triangle +cd build\15_hello_triangle\Debug +.\15_hello_triangle.exe + +# Model loading +cd ..\..\28_model_loading\Debug +.\28_model_loading.exe +---- + +=== Linux (Ninja or Unix Makefiles) + +[,shell] +---- +# Triangle +cd build/15_hello_triangle +./15_hello_triangle + +# Model loading +cd ../28_model_loading +./28_model_loading +---- + +The triangle example should display: + +image::/images/triangle.png[A coloured triangle rendered with Vulkan] + +The model-loading example should display: + +image::/images/drawing_model.png[A textured model rendered with Vulkan] diff --git a/en/03_Drawing_a_triangle/00_Setup/00_Base_code.adoc b/en/03_Drawing_a_triangle/00_Setup/00_Base_code.adoc index 87176d09..e785c148 100644 --- a/en/03_Drawing_a_triangle/00_Setup/00_Base_code.adoc +++ b/en/03_Drawing_a_triangle/00_Setup/00_Base_code.adoc @@ -8,7 +8,7 @@ NOTE: We are going to use designated initializers introduced with C++ 20. By default, Vulkan-hpp uses a different way of initializing and we need to explicitly enable this by using the `VULKAN_HPP_NO_STRUCT_CONSTRUCTORS` define. This provides a better meaning towards what each option relates to in the structures that we're depending upon. -For this tutorial, said define is declared in the xref:../../02_Development_environment.adoc#cmake[CMake build setup]. +For this tutorial, said define is declared in the xref:../../02_Build_and_development_environment.adoc#_cmake[CMake build setup]. If you use a different build setup or want to write code from scratch, you need to manually define this before including the Vulkan-hpp headers like this: [,c++] diff --git a/en/08_Loading_models.adoc b/en/08_Loading_models.adoc index 31005b0f..093b86d1 100644 --- a/en/08_Loading_models.adoc +++ b/en/08_Loading_models.adoc @@ -15,7 +15,7 @@ We _will_ load mesh data from an OBJ model in this chapter, but we'll focus more We will use the https://github.com/syoyo/tinyobjloader[tinyobjloader] library to load vertices and faces from an OBJ file. It's fast and it's easy to integrate because it's a single file library like stb_image. -This was mentioned in the xref:02_Development_environment.adoc[Development Environment] chapter and should be part of the dependencies for this portion of the tutorial. +This was mentioned in the xref:02_Build_and_development_environment.adoc[Build and development environment] chapter and should be part of the dependencies for this portion of the tutorial. == Updating the fragment shader