Repository files navigation

This repository hosts the contents ofvulkan-tutorial.com.The website itself is based ondaux.io,which supportsGitHub flavored Markdown.The actual site runs daux.io with a custom theme and a few modifications (https://github.com/Overv/daux.io) and this is built into aDocker image.

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

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

• EPUB (English,French)
• PDF (English,French)

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 (tested with version 1.0.2)
• pandoc: Building a PDF and EPUB from the Markdown code (tested with version 2.13)

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

It is sometimes necessary to change code that is reused across many chapters,for example a function likecreateBuffer. If you make such a change, then youshould 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 usingdiff -Naur base_code.cpp base_code_fixed.cpp > patch.txt.
• Apply the patch to the specified code file and all files in later chaptersusing theincremental_patch.sh script. Run it like this:./incremental_patch.sh base_code.cpp patch.txt.
• Clean up thebase_code_fixed.cpp andpatch.txt files.
• Commit.

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.

1. Make surePHP is installed (Daux is writtenin PHP)
   1. Both thephp_mbstring andphp_openssl extensions need to be enabled
   2. Thephar.readonly setting needs to be set toOff (to be able torebuild Daux)
2. Make sureComposer is installed, a php dependencymanager that Daux uses

1. Clonedaux
   • git clone https://github.com/dauxio/daux.io.git
2. Make a new branch at the older revision that the VulkanTutorial patch isagainst:
   • git checkout d45ccff -b vtpatch
   • Making a new branch isn't strictly necessary, as you could resetmaster,but this keeps master intact.
3. Copy over thedaux.patch file into the daux.io directory, make sure lineendings 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 dependenciesDaux needs in order to be built
   • composer install
5. Rebuild Daux
   • php bin/compile (this can take a while)
   • A newly madedaux.phar will now be in your base directory

Once you've completed the above, follow the instructions on the daux sitefor how torun daux using a web server.

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

1. In thedaux.io directory, editglobal.json so that thedocs_directoryoption points at your VulkanTutorial directory
   • "docs_directory": "../VulkanTutorial",
2. In thedaux.io directory, run
   • php -S localhost:8080 index.php
3. Typelocalhost:8080 in your web browser URL bar and hit enter. You shouldnow see the VulkanTutorial front page.

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

1. In theVulkanTutorial directory, editconfig.json and remove thegoogle_analytics line so daux doesn't try to load that.
2. In thedaux.io directory, editthemes/daux/config.json and remove thefont 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 themechanges.

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

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

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

Note: if you want to generate the docs again, delete theout directory firstor daux will make a newout directory within the existingout directory.

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

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