C++ Other
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
03_Drawing_a_triangle Update tutorial to use VK_EXT_debug_utils (fixes #102) Aug 6, 2018
04_Vertex_buffers Update remaining references to synchronization May 21, 2018
05_Uniform_buffers Fix typo Jul 17, 2018
06_Texture_mapping Add mention that VK_PIPELINE_STAGE_TRANSFER_BIT is a pseudo-stage Jul 3, 2018
code Update the multisampling chapter to only create one color and depth b… Aug 13, 2018
ebook Update ebook Aug 13, 2018
images Update tutorial to use VK_EXT_debug_utils (fixes #102) Aug 6, 2018
resources Publish website contents Jul 17, 2016
.gitignore Update website description Dec 11, 2016
00_Introduction.md Mention notification of tutorial updates in introduction Jul 3, 2018
01_Overview.md Fix typo in overview Jul 19, 2016
02_Development_environment.md Update Vulkan SDK installation instructions for Linux Aug 19, 2018
07_Depth_buffering.md Revert "Fix all frames in flight using a single depth buffer" Aug 13, 2018
08_Loading_models.md Add chapter on mipmapping Mar 25, 2018
09_Generating_Mipmaps.md Remove conclusion Aug 14, 2018
10_Multisampling.md Update the multisampling chapter to only create one color and depth b… Aug 13, 2018
99_FAQ.md Update the tutorial for Visual Studio 2017 Jul 29, 2018
README.md Location for daux.io on github has changed Jul 20, 2018
build_ebook.py Update ebooks and fix code overflowing in PDF (fixes #96) Jul 9, 2018
config.json Add more workarounds for Steam overlay crash to FAQ Jul 26, 2018
daux.patch Fix non-unique ids on Development Environment page Jul 20, 2018

README.md

Vulkan tutorial

This repository hosts the contents of vulkan-tutorial.com. The website itself is based on daux.io, which supports GitHub flavored Markdown. A few changes were made to daux.io and its themes, which are included in daux.patch and are licensed as MIT. The patch is based on commit d45ccff.

Use issues and pull requests to provide feedback related to the website. If you have a problem with your code, then use the comments section in the related chapter to ask a question. Please provide your operating system, graphics card, driver version, source code, expected behaviour and actual behaviour.

E-book

This guide is now available in e-book formats as well:

The e-book can be built from the existing content by running:

 python3 build_ebook.py

This script depends on the following utilities being available on the path:

  • inkscape: SVG to PNG conversion
  • pandoc: Building a PDF and EPUB from the Markdown code

You also need to install a LaTeX distribution for PDF generation.

Changing code across chapters

It is sometimes necessary to change code that is reused across many chapters, for example a function like createBuffer. If you make such a change, then you should update the code files using the following steps:

  • Update any chapters that reference the modified code.
  • Make a copy of the first file that uses it and modify the code there, e.g. base_code_fixed.cpp.
  • Create a patch using diff -Naur base_code.cpp base_code_fixed.cpp > patch.txt.
  • Apply the patch to the specified code file and all files in later chapters using the incremental_patch.sh script. Run it like this: ./incremental_patch.sh base_code.cpp patch.txt.
  • Clean up the base_code_fixed.cpp and patch.txt files.
  • Commit.

Rendering the tutorial

To render the tutorial (i.e. convert the markdown to html), you have two options:

  1. Serve rendered files on the fly using a web server that has php installed
  2. Generate static html files that you can view locally or put on a server

For either of these options, you'll need php and a patch'ed daux.

PHP

  1. Make sure PHP is installed (Daux is written in PHP)
    1. Both the php_mbstring and php_openssl extensions need to be enabled
    2. The phar.readonly setting needs to be set to Off (to be able to rebuild Daux)
  2. Make sure Composer is installed, a php dependency manager that Daux uses

Clone, patch, and rebuild daux

  1. Clone daux
    • git clone https://github.com/dauxio/daux.io.git
  2. Make a new branch at the older revision that the VulkanTutorial patch is against:
    • git checkout d45ccff -b vtpatch
    • Making a new branch isn't strictly necessary, as you could reset master, but this keeps master intact.
  3. Copy over the daux.patch file into the daux.io directory, make sure line endings are UNIX style (in case you're using Windows), and apply the patch. It should apply cleanly.
    • git am daux.patch
  4. Run composer in the daux.io directory so that it downloads the dependencies Daux needs in order to be built
    • composer install
  5. Rebuild Daux
    • php bin/compile (this can take a while)
    • A newly made daux.phar will now be in your base directory

Using Daux to serve rendered files on the fly

Once you've completed the above, follow the instructions on the daux site for how to run daux using a web server.

As a simple option considering you have php installed, you can also use php's built in development web server if you just need to locally see what things look like:

  1. In the daux.io directory, edit global.json so that the docs_directory option points at your VulkanTutorial directory
    • "docs_directory": "../VulkanTutorial",
  2. In the daux.io directory, run
    • php -S localhost:8080 index.php
  3. Type localhost:8080 in your web browser URL bar and hit enter. You should now see the VulkanTutorial front page.

Using Daux to statically generate html files

Before we generate the static files, we need to tweak daux and the tutorial setup to prevent it from trying to load a few outside resources (which will stall your browser when trying to load the otherwise static page)

  1. In the VulkanTutorial directory, edit config.json and remove the google_analytics line so daux doesn't try to load that.
  2. In the daux.io directory, edit themes/daux/config.json and remove the font line so that daux doesn't try to load an external font.
  3. Rebuild daux according to the earlier instructions so it picks up the theme changes.

We're working on improvements so in the future the above steps won't be necessary.

Now with the above done, we can generate the static files. Asuming the daux.io and VulkanTutorial directories are next to each other, go into the daux.io directory and run a command similar to: php generate -s ../VulkanTutorial -d ../VulkanTutorial\out.

-s tells it where to find the documentation, while -d tells it where to put the generated files.

Note: if you want to generate the docs again, delete the out directory first or daux will make a new out directory within the existing out directory.

License

The contents of this repository are licensed as CC BY-SA 4.0, unless stated otherwise. By contributing to this repository, you agree to license your contributions to the public under that same license.

The code listings in the code directory are licensed as CC0 1.0 Universal. By contributing to that directory, you agree to license your contributions to the public under that same public domain-like license.