# Vulkan Samples

The LunarG Vulkan SDK includes a set of C++ Vulkan sample programs. These samples illustrate specific Vulkan entrypoints 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 CMake and Python 3 to build the samples To build and run the sample programs:

1. Configure the sample program build system for a release build and build the samples.

   ### Linux:

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

       $ ./build_samples.sh

   Alternatively you can manually build the samples as described next. The Vulkan sample programs have a dependency on certain glslang components. These libraries and header files are included in the Vulkan SDK. Specifically, the Linux samples build will pull the libraries from `$VULKAN_SDK/x64_64/lib/glslang` and the headers from `$VULKAN_SDK/source/glslang`. Use the following commands to build the glslang components.

       $ pushd source/glslang
       $ cmake -H. -Bbuild
       $ make -C build
       $ cp build/SPIRV/libSPIRV.a ../../x86_64/lib/glslang
       $ cp build/glslang/libglslang.a ../../x86_64/lib/glslang
       $ cp build/glslang/OSDependent/Unix/libOSDependent.a ../../x86_64/lib/glslang
       $ cp build/OGLCompilersDLL/libOGLCompiler.a ../../x86_64/lib/glslang
       $ cp build/hlsl/libHLSL.a ../../x86_64/lib/glslang
       $ popd

   Use the following commands to build the samples.

       $ pushd samples
       $ cmake -H. -Bbuild
       $ make -C build
       $ popd

   ### 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 that 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:

       > mkdir build
       > cd build
       > cmake -G "Visual Studio 12 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 ..

   within the following directories, in order:

   C:\VulkanSDK<sdk version>\glslang
   C:\VulkanSDK<sdk version>\spirv-tools
   C:\VulkanSDK<sdk version>\Samples

   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.

   #### Using Visual Studio 2015

   - The build_windows_samples.bat batch file detects the installed version of Visual Studio automatically. When building manually with Visual Studio 15, substitute the cmake string "Visual Studio 14" in place of "Visual Studio 12" shown above, e.g.

       > cmake -G "Visual Studio 14 Win64" ..'

   - You will not be able to use the Debug versions of the loader and layers which were built with VS 2013. If you attempt to run with the Debug versions, execution will fail on loading MSVCR120.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 build/src
       $ ls

   ### Windows:

       cd src\Release
       ls

   Notice the listed set of Vulkan sample programs. The program name identifies the Vulkan entrypoint 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:

       $ ./drawtexturedcube

   ### Windows:

       drawtexturedcube.exe

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

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

## Examine Sample Code

The Vulkan Samples currently include samples that are both self-contained and those that use external utilities. In future releases, all samples will be self-contained, i.e. all code will be located within the sample source file itself.

A typical sample Vulkan program will, using one or more Vulkan API entrypoints, 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 entrypoint, search for that entrypoint name in all or specific samples.

More detailed information on programming with specific Vulkan API entrypoints will be provided in future SDK releases.

## Provide input, feedback, or contribute a New Sample

- Issues and pull requests can be submitted through the Samples source code repository at https://github.com/LunarG/VulkanSamples