Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion REUSE.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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/**",
Expand Down
2 changes: 1 addition & 1 deletion antora/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
5 changes: 5 additions & 0 deletions en/00_Introduction.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion en/01_Overview.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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].
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
= Development Environment
= Build and Development Environment
:page-aliases: 02_Development_environment.adoc

:pp: {plus}{plus}

Expand All @@ -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 <<common_considerations_vulkan_sdk,Vulkan SDK>> for details.
* See the <<_cmake, CMake>>, <<common_considerations_windows, Windows>> and <<common_considerations_linux, Linux>> 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 <<setting-up-a-cmake-project,Setting up a CMake project>> 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 <<setting-up-clion, CLion>> 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].
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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]
2 changes: 1 addition & 1 deletion en/03_Drawing_a_triangle/00_Setup/00_Base_code.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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++]
Expand Down
2 changes: 1 addition & 1 deletion en/08_Loading_models.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading