Copyright © 2015-2020 LunarG, Inc.

# Vulkan Samples

The Vulkan SDK includes a set of C++ Vulkan sample programs. These samples illustrate specific Vulkan entry points and their use in implementing graphical features.

The source code of the sample Vulkan programs is available in the `samples` directory of the Vulkan SDK.

## Build and Run Samples

Note that you will need a recent CMake and Python 3 to build the samples. Recommended CMake versions:

- Windows: CMake 3.10.2
- Linux: CMake 3.10.2
- MacOS: CMake 3.10.2

To build and run the sample programs:

1. Configure the sample program build system for a release build and build the samples. Start with your current directory in the root of the SDK directory (where the `setup-env.sh` script can be found).

   ### Linux:

   Prepare the SDK environment.

       $ source ./setup-env.sh

   A shell script is provided to build the samples and their dependencies. Use the following command to run this script.

       $ ./vulkansdk samples

   Alternatively you can manually build the samples using the following commands.

       $ pushd samples
       $ mkdir build
       $ cd build
       $ cmake ..
       $ make
       $ popd

   #### WSI Selection

   When building the samples on Linux, the Xcb windowing system is used by default.

   The environment variable `SAMPLES_WSI_SELECTION` can be set to build for a different windowing system. The supported options are `XCB` and `WAYLAND`.

   Example:

       $ mkdir build
       $ cd build
       $ cmake -DSAMPLES_WSI_SELECTION=WAYLAND ..

   This can be done by either modifying the `vulkansdk` script or by building manually.

   ### Windows:

   Make sure CMake, python and MSBuild are in your PATH. The MSBuild path is included automatically when opening `Developer Command Prompt for VS201x`, or alternatively can be loaded in a command window by executing '`vsvars32.bat`' found in `\Program Files (x86)\Microsoft Visual Studio xx.0\Common7\Tools\`.

   A Windows batch file `build_windows_samples.bat` is provided to locate the installed build tools and build the samples and their dependencies. Note: This batch file builds only 64-bit versions of the tools and samples.

   If desired to build the samples manually, do so by running the following commands:

       > cd samples
       > mkdir build
       > cd build
       > cmake -G "Visual Studio 14 2015 Win64" ..
       > msbuild ALL_BUILD.vcxproj /p:Platform=x64 /p:Configuration=Debug /verbosity:quiet
       > msbuild ALL_BUILD.vcxproj /p:Platform=x64 /p:Configuration=Release /verbosity:quiet
       > cd ..

   Alternatively you may skip the msbuild steps above, and build within the Visual Studio IDE by opening the `VULKAN_SAMPLES.sln` file generated by the cmake command.

   - The Debug versions of the loader and layers were built with VS 2015.
   - If you want to run the samples with the debug version of the loader and layers, you should build the samples with VS 2015.
   - Note that VS 2017 is supported. Attempting to use VS2017 with the debug loader and layers will fail on loading `MSVCR140.dll`.

   #### 32-bit support

   32-bit support is currently available, but should only be considered at an Alpha level of stability. 32-bit applications and layers have only been validated to a minimal extent.

2. Verify the build artifacts.

   ### Linux:

       $ cd samples/build/API-Samples
       $ ls

   ### Windows:

       cd src\Release
       dir

   Notice the listed set of Vulkan sample programs. The program name identifies the Vulkan entry point or graphical feature implemented in the sample.

3. Generate the list of samples currently available (Linux).

       $ ./get-short-descripts.sh

   This script displays each sample filename and a short description of the sample.

4. Run the textured cube sample program.

   ### Linux:

       $ ./draw_textured_cube

   ### Windows:

       drawtexturedcube.exe

   This program uses the appropriate Vulkan entry points to open a window and draw a textured cube.

5. If desired, run all the sample programs. This script works with both Python 2 and Python 3:

   ### Linux:

       $ python run_all_samples.py

Note: The focus of some sample programs may be to enumerate individual features of specific Vulkan entry points and may not render to the screen at all.

## Examine Sample Code

The Vulkan Samples compile or assemble their shaders at build time using `glslang` and `spirv-tools` utilities shipped with the SDK.

A typical sample Vulkan program will, using one or more Vulkan API entry points, perform the following activities:

- Retrieve the list of instance and device layers available on the system and their extensions
- Identify specific extensions supported by the application
- Initialize the application and Vulkan instances
- Enumerate and select GPU device on the system
- Identify and set up the presentation window (OS-specific)
- Initialize command/depth/uniform buffers, descriptors, shaders, and pipelines
- Bind the buffers, pipelines, and descriptors and submit the command buffer
- Present the image in the window
- Destroy the objects used

To find code for a specific entry point, search for that entry point name in all or specific samples.