198 lines
6.9 KiB
Plaintext
198 lines
6.9 KiB
Plaintext
////
|
|
- Copyright (c) 2019-2025, Arm Limited and Contributors
|
|
-
|
|
- SPDX-License-Identifier: Apache-2.0
|
|
-
|
|
- Licensed under the Apache License, Version 2.0 the "License";
|
|
- you may not use this file except in compliance with the License.
|
|
- You may obtain a copy of the License at
|
|
-
|
|
- http://www.apache.org/licenses/LICENSE-2.0
|
|
-
|
|
- Unless required by applicable law or agreed to in writing, software
|
|
- distributed under the License is distributed on an "AS IS" BASIS,
|
|
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
- See the License for the specific language governing permissions and
|
|
- limitations under the License.
|
|
-
|
|
////
|
|
= 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 git@github.com: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/<BuildType>/<Arch>/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
|