Repository navigation
Rework the README to explain what the repository contains #541
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -10,93 +10,51 @@ The tutorial uses the Antora site generator, documentation links might not work | |
| ==== | ||
| endif::[] | ||
|
|
||
| == Attribution | ||
|
|
||
| The Khronos Vulkan^®^ Tutorial is based on the "link:https://vulkan-tutorial.com/[Vulkan Tutorial]" by Alexander Overvoorde licensed under link:https://creativecommons.org/licenses/by-sa/4.0/[CC BY-SA 4.0]. | ||
|
|
||
| The following tutorials were written by Holochip Corporation and released under the link:https://www.apache.org/licenses/LICENSE-2.0[Apache-2.0]: | ||
|
|
||
| * xref:ML_Inference/introduction.adoc[Machine learning inference] | ||
| * xref:OpenXR_Vulkan_Spatial_Computing/introduction.adoc[Vulkan for XR] | ||
| * xref:AI_Assisted_Vulkan/introduction.adoc[LLM-Assistant Vulkan Development] | ||
| * xref:Advanced_glTF/introduction.adoc[Advanced glTF] | ||
| * xref:Advanced_Vulkan_Compute/introduction.adoc[Advanced Vulkan Compute] | ||
| * xref:Building_a_Simple_Engine/introduction.adoc[Building a Simple Game Engine] | ||
| * xref:Synchronization/introduction.adoc[Synchronization] | ||
| * xref:Building_a_Simple_Engine/Courses/Opacity_Micromaps/00_introduction.adoc[Opacity Micromaps mini course] | ||
|
|
||
| The following courses were written by Arm Limited. | ||
|
|
||
| * xref:courses/18_Ray_tracing/00_Overview.adoc[SIGGRAPH 2025: Hands-on Vulkan Ray Tracing with Dynamic Rendering] | ||
| * xref:courses/siggraph2026_vk_tutorial/00_Overview.adoc[SIGGRAPH 2026: How to write a Vulkan application in 2026] | ||
|
|
||
| == About | ||
|
|
||
| This repository hosts the contents of the link:https://docs.vulkan.org/tutorial/latest[Khronos Vulkan Tutorial]. The tutorial is part of the link:https://github.com/KhronosGroup/Vulkan-Site[Vulkan Documentation Project]. | ||
|
|
||
| == Differences | ||
| This repository hosts the contents of the link:https://docs.vulkan.org/tutorial/latest[Khronos Vulkan Tutorial]. | ||
| The tutorial is part of the link:https://github.com/KhronosGroup/Vulkan-Site[Vulkan Documentation Project]. | ||
| Start with the online tutorial if you want to learn Vulkan. | ||
|
|
||
| Compared to the original tutorial, this version of the tutorial is teaching up-to-date concepts: | ||
| The repository hosts several tutorials: | ||
|
|
||
| * Vulkan 1.4 as a baseline | ||
| * Dynamic rendering instead of render passes | ||
| * Timeline semaphores | ||
| * link:https://shader-slang.org/[Slang] as the primary shading language | ||
| * Modern C++ (20) | ||
| * link:https://github.com/KhronosGroup/Vulkan-Hpp[Vulkan-Hpp] with link:https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization[RAII] | ||
|
|
||
| It also contains Vulkan usage clarifications, improved synchronization and new content. | ||
| * The primary **Khronos Vulkan Tutorial** updates the traditional link:https://vulkan-tutorial.com/[Vulkan Tutorial by Alexander Overvoorde] to use modern Vulkan features and practices. | ||
| See link:en/00_Introduction.adoc[the introduction] for a quick start. | ||
| * A set of tutorials on advanced Vulkan topics, which you can follow once you have completed the primary tutorial. | ||
| They are listed in the link:en/00_Introduction.adoc#_advanced_topics[advanced topics section] of the introduction. | ||
|
|
||
| == Project Structure | ||
|
|
||
| The repository is organized into several important directories: | ||
|
|
||
| * `en/` - Contains the tutorial content in English, organized by chapters | ||
| ** The main tutorial covers fundamental Vulkan concepts (chapters 00-17) | ||
| ** The "Building a Simple Engine" section builds upon these fundamentals to create a structured rendering engine | ||
| * `attachments/` - Contains code examples, shader files, and resources used in the tutorial | ||
| * `images/` - Contains illustrations, diagrams, and screenshots used in the tutorial | ||
| * `scripts/` - Contains utility scripts, including dependency installation scripts | ||
| * `antora/` - Contains configuration files for the Antora documentation system | ||
|
|
||
| == Installation Dependencies | ||
|
|
||
| The project provides scripts to help you install the necessary dependencies: | ||
|
|
||
| === Linux | ||
| Run the following command to install dependencies on Linux: | ||
| [source,bash] | ||
| ---- | ||
| ./scripts/install_dependencies_linux.sh | ||
| ---- | ||
|
|
||
| This script detects your package manager (apt, dnf, pacman) and installs the required dependencies, including: | ||
| * Build essentials (gcc, cmake, ninja-build) | ||
| * GLFW, GLM, tinyobjloader, stb | ||
| * X Window System dependencies | ||
| * `en/` - the tutorial content in English. | ||
| ** `en/00_Introduction.adoc` to `en/17_Multithreading.adoc`, together with the numbered subdirectories, make up the primary Khronos Vulkan Tutorial. | ||
| ** `en/Building_a_Simple_Engine/`, `en/Advanced_glTF/`, `en/Advanced_Vulkan_Compute/`, `en/Synchronization/`, `en/ML_Inference/`, `en/OpenXR_Vulkan_Spatial_Computing/` and `en/AI_Assisted_Vulkan/` contain the tutorials on advanced topics. | ||
| ** `en/courses/` contains the SIGGRAPH courses. | ||
| * `attachments/` - code examples, shaders, and resources used by the tutorials. | ||
| * `images/` - illustrations, diagrams, and screenshots. | ||
| * `scripts/` - utility scripts, including dependency installation scripts. | ||
| * `antora/` - the configuration for the link:https://antora.org/[Antora] documentation system the site is built with. | ||
|
|
||
| It also provides instructions for installing the Vulkan SDK. | ||
| == Building the Code Examples | ||
|
|
||
| === Windows | ||
| Run the following command to install dependencies on Windows: | ||
| [source,batch] | ||
| ---- | ||
| scripts\install_dependencies_windows.bat | ||
| ---- | ||
| The code for the primary tutorial lives in `attachments/`. | ||
| The tutorial's link:en/02_Development_environment.adoc[development environment chapter] explains how to set up the dependencies, and `scripts/` contains scripts that install them on Linux and Windows. | ||
| Some of the advanced tutorials have additional requirements, which are described in their own chapters. | ||
|
|
||
| This script uses vcpkg to install the required dependencies, including: | ||
| * GLFW, GLM, tinyobjloader, stb | ||
| == Previewing Changes to the Tutorial | ||
|
|
||
| You will also need to install the Vulkan SDK separately from https://vulkan.lunarg.com/. | ||
| The tutorial is written in AsciiDoc and rendered with Antora, so some things that look broken in GitHub's preview, such as missing images or cross-references, are expected. | ||
| See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for how to preview AsciiDoc in your editor. | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should be an xref |
||
|
|
||
| == License | ||
| To build the documentation the same way CI does, follow the steps in link:.github/workflows/build-antora-doc.yml[`build-antora-doc.yml`]: | ||
| build the Khronos Antora UI bundle from link:https://github.com/KhronosGroup/antora-ui-khronos[antora-ui-khronos], copy `ui-bundle.zip` to the repository root, run `make` in `antora/`, and then run `npx antora antora-ci-playbook.yml` from the repository root. | ||
|
|
||
| The contents of this repository are licensed as https://creativecommons.org/licenses/by-sa/4.0/[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. | ||
| == License and Attribution | ||
|
|
||
| The code listings in the `attachments` directory are licensed as | ||
| https://creativecommons.org/publicdomain/zero/1.0/[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. | ||
| The primary Khronos Vulkan Tutorial is based on the "link:https://vulkan-tutorial.com/[Vulkan Tutorial]" by Alexander Overvoorde and is licensed under link:https://creativecommons.org/licenses/by-sa/4.0/[CC BY-SA 4.0]. | ||
| Different parts of the repository are under different licenses: | ||
| the Arm tutorials are also CC BY-SA 4.0, the Holochip tutorials are link:https://www.apache.org/licenses/LICENSE-2.0[Apache-2.0], and code listings are link:https://creativecommons.org/publicdomain/zero/1.0/[CC0 1.0 Universal] where applicable. | ||
| The link:en/00_Introduction.adoc#_attribution[attribution section] of the introduction lists which tutorials are covered by which license, the full license texts are in the `LICENSES` directory, and `REUSE.toml` records which license covers which files. | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should be an xref |
||
| See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for how contributions are licensed. | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should be an xref |
||
|
|
||
| == Contributing | ||
|
|
||
|
|
@@ -114,5 +72,5 @@ AI was used for: | |
|
|
||
| Humans have reviewed all content of all tutorials and we welcome feedback. | ||
|
|
||
| xref:AI_Assisted_Vulkan/introduction.adoc[LLM-Assistant Vulkan Development] tutorial used for all LLM use in these tutorials and sample code. | ||
| The link:en/AI_Assisted_Vulkan/introduction.adoc[LLM-Assistant Vulkan Development] tutorial used for all LLM use in these tutorials and sample code. | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should be an xref. |
||
| ==== | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should be an xref.