// Copyright 2019-2021 The Khronos Group, Inc.
// SPDX-License-Identifier: CC-BY-4.0

ifndef::chapters[:chapters:]

[[loader]]
= Loader

The loader is responsible for mapping an application to Vulkan layers and Vulkan installable client drivers (ICD).

image::images/loader_overview.png[loader_overview.png]

Anyone can create their own Vulkan Loader, as long as they follow the link:https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md[Loader Interface]. One can build the link:https://github.com/KhronosGroup/Vulkan-Loader/blob/master/BUILD.md[reference loader] as well or grab a built version from the link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK] for selected platforms.

== Linking Against the Loader

The link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan headers] only provide the Vulkan function prototypes. When building a Vulkan application you have to link it to the loader or you will get errors about undefined references to the Vulkan functions. There are two ways of linking the loader, link:https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md#directly-linking-to-the-loader[directly] and link:https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md#indirectly-linking-to-the-loader[indirectly], which should not be confused with "`static and dynamic linking`".

  * link:https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md#directly-linking-to-the-loader[Directly linking] at compile time
  ** This requires having a built Vulkan Loader (either as a static or dynamic library) that your build system can find.
  ** Build systems (Visual Studio, CMake, etc) have documentation on how to link to the library. Try searching "`(InsertBuildSystem) link to external library`" online.
  * link:https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md#indirectly-linking-to-the-loader[Indirectly linking] at runtime
  ** Using dynamic symbol lookup (via system calls such as `dlsym` and `dlopen`) an application can initialize its own dispatch table. This allows an application to fail gracefully if the loader cannot be found. It also provides the fastest mechanism for the application to call Vulkan functions.
  ** link:https://github.com/zeux/volk/[Volk] is an open source implementation of a meta-loader to help simplify this process.

== Platform Variations

Each platform can set its own rules on how to enforce the Vulkan Loader.

=== Android

Android devices supporting Vulkan provide a link:https://source.android.com/devices/graphics/implement-vulkan#vulkan_loader[Vulkan loader] already built into the OS.

A link:https://developer.android.com/ndk/guides/graphics/getting-started#using[vulkan_wrapper.c/h] file is provided in the Android NDK for indirectly linking. This is needed, in part, because the Vulkan Loader can be different across different vendors and OEM devices.

=== Linux

The link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK] provides a pre-built loader for Linux.

The link:https://vulkan.lunarg.com/doc/sdk/latest/linux/getting_started.html[Getting Started] page in the Vulkan SDK explains how the loader is found on Linux.

=== MacOS

The link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK] provides a pre-built loader for MacOS

The link:https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html[Getting Started] page in the Vulkan SDK explains how the loader is found on MacOS.

=== Windows

The link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK] provides a pre-built loader for Windows.

The link:https://vulkan.lunarg.com/doc/sdk/latest/windows/getting_started.html[Getting Started] page in the Vulkan SDK explains how the loader is found on Windows.