////
////
= Vulkan Samples
// omit in toc
:pp: {plus}{plus}
ifndef::site-gen-antora[]
:toc:
endif::[]
image::banner.jpg[Vulkan Samples banner]
ifndef::site-gen-antora[]
== Vulkan Documentation Site
Documentation for the samples is best viewed at the new link:https://docs.vulkan.org/samples/latest/README.html[Vulkan Documentation Site]. The documentation uses AsciiDoc which isn't fully supported by github.
endif::[]
== Introduction
The Vulkan Samples is collection of resources to help you develop optimized Vulkan applications.
If you are new to Vulkan the xref:samples/api/README.adoc[API samples] are the right place to start.
Additionally you may find the following links useful:
ifdef::site-gen-antora[]
- xref:guide:ROOT:index.adoc[Vulkan Guide]
- xref:tutorial:ROOT:00_Introduction.adoc[Get Started in Vulkan]
endif::[]
ifndef::site-gen-antora[]
- https://docs.vulkan.org/guide/latest/index.html[Vulkan Guide]
- https://docs.vulkan.org/tutorial/latest/index.html[Get Started in Vulkan]
endif::[]
xref:samples/performance/README.adoc[Performance samples] show the recommended best practice together with real-time profiling information.
They are more advanced but also contain a detailed tutorial with more in-detail explanations.
=== Requirements
The samples are written in C{pp} and require a compiler that supports at least C{pp}20. To run the samples, a device that supports at least Vulkan 1.1 or newer is required. Some samples might require a higher Vulkan version and/or support for certain extensions.
=== Goals
- Create a collection of resources that demonstrate best-practice recommendations in Vulkan
- Create tutorials that explain the implementation of best-practices and include performance analysis guides
== Samples
- xref:./samples/README.adoc[Listing of all samples available in this repository]
== General information
- Project Basics
** xref:./docs/misc.adoc#controls[Controls]
** xref:./docs/misc.adoc#debug-window[Debug window]
** xref:./scripts/README.adoc[Create a Sample]
- Vulkan Essentials
** xref:./samples/vulkan_basics.adoc[How does Vulkan compare to OpenGL ES?
What should you expect when targeting Vulkan?]
- Misc
** xref:./docs/misc.adoc#driver-version[Driver version]
** xref:./docs/memory_limits.adoc[Memory limits]
== Setup
Prerequisites: https://git-scm.com/downloads[git] with https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage[git large file storage (git-lfs)].
Clone the repo with submodules using the following command:
git clone --recurse-submodules https://github.com/KhronosGroup/Vulkan-Samples.git
cd Vulkan-Samples
Follow build instructions for your platform below.
[NOTE]
The full repository is very large, and some ISPs appear to have trouble
providing a robust connection to github while the clone is being made.
If you notice problems such as submodules downloading at reported rates in
the tens of kB/s, or fatal timeout errors occurring, these may be due to
network routing issues to github within your ISP's internal network, rather
than anything wrong in your own networking setup.
It can be very difficult to get ISPs to acknowledge such problems exist, much
less to fix them.
One workaround is to switch the repository to use ssh protocol prior to the
submodule download, which can be done via e.g.
[source,sh]
git clone [email protected]:KhronosGroup/Vulkan-Samples.git
cd Vulkan-Samples
perl -i -p -e 's|https://(.*?)/|git@\1:|g' .gitmodules
git submodule sync
git submodule update
While this can be a good alternative if you are running into this connection
issue, you must have GitHub ssh key authentication setup to use ssh
protocol - see
link:https://docs.github.com/en/authentication/connecting-to-github-with-ssh[Connecting
to GitHub with SSH] for details.
So it is a not a solution we can implement as the repository default.
Another option which may help is to run github through a VPN service.
== Build
=== Supported Platforms
- Windows - xref:./docs/build.adoc#windows[Build Guide]
- Linux - xref:./docs/build.adoc#linux[Build Guide]
- Android - xref:./docs/build.adoc#android[Build Guide]
- macOS - xref:./docs/build.adoc#macos[Build Guide]
- iOS - xref:./docs/build.adoc#ios[Build Guide]
== Usage
The following shows some example command line usage on how to configure and run the Vulkan Samples.
Make sure that you are running the samples from the root directory of the repository.
Otherwise the samples will not be able to find the assets.
./build/app/bin///vulkan_samples
For the entire usage use
vulkan_samples --help
For subcommand usage use
vulkan_samples <sub_command> --help
Run Swapchain Images sample
vulkan_samples sample swapchain_images
Run AFBC sample in benchmark mode for 5000 frames
vulkan_samples sample afbc --benchmark --stop-after-frame 5000
Run compute nbody using headless-surface and take a screenshot of frame 5
Note: headless-surface uses VK_EXT_headless_surface.
This will create a surface and a Swapchain, but present will be a no op.
The extension is supported by Swiftshader(https://github.com/google/swiftshader).
It allows to quickly test content in environments without a GPU.
vulkan_samples sample compute_nbody --headless-surface --screenshot 5
Run all the performance samples for 10 seconds in each configuration
vulkan_samples batch --category performance --duration 10
Run Swapchain Images sample on an Android device
adb shell am start-activity -n com.khronos.vulkan_samples/com.khronos.vulkan_samples.SampleLauncherActivity -e sample swapchain_images
== License
See link:LICENSE[LICENSE].
This project has several xref:./third_party/README.adoc[third-party dependencies]
This project uses assets from https://github.com/KhronosGroup/Vulkan-Samples-Assets[vulkan-samples-assets].
Each one has its own license.
=== Trademarks
Vulkan is a registered trademark of the Khronos Group Inc.
== Contributions
Donated to Khronos by Arm, with further contributions by Sascha Willems and Adam Sawicki.
See xref:CONTRIBUTORS.adoc[CONTRIBUTORS] for the full contributor list.
Also see xref:CONTRIBUTING.adoc[CONTRIBUTING] for contribution guidelines.
== Related resources
- https://developer.arm.com/documentation/101897/latest/[Mali GPU Best Practices]: A document with recommendations for efficient API usage
