Volk

https://github.com/zeux/volk
Admin
Meta loader for Vulkan API
Tokens:3,749
Snippets:18
Trust Score:9.1
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### CMake: Enabling Volk Installation

Source: https://github.com/zeux/volk/blob/master/README.md

Demonstrates how to enable the installation of Volk and find it as a config-file package within a CMake project. This involves passing '-DVOLK_INSTALL=ON' during the CMake configuration step, and then using 'find_package' to locate the installed targets 'volk::volk' and 'volk::volk_headers'.

```cmake
# Pass -DVOLK_INSTALL=ON to CMake configuration
find_package(volk CONFIG REQUIRED)
target_link_library(my_application PRIVATE volk::volk)
```

--------------------------------

### CMake: Install Volk Library and Configuration Files

Source: https://github.com/zeux/volk/blob/master/CMakeLists.txt

Handles the installation of Volk's static library, interface library, header files, and CMake configuration files. It ensures that targets, headers, and configuration scripts are placed in the correct directories for package management.

```cmake
# -----------------------------------------------------
# Installation

if(VOLK_INSTALL)

  include(GNUInstallDirs)
  set(INSTALL_CONFIGDIR ${CMAKE_INSTALL_LIBDIR}/cmake/volk)

  # Install files
  install(FILES volk.h volk.c DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

  # Install library target and add it and any dependencies to export set.
  install(TARGETS volk volk_headers
    EXPORT volk-targets
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
  )

  # Actually write exported config w/ imported targets
  install(EXPORT volk-targets
    FILE volkTargets.cmake
    NAMESPACE volk::
    DESTINATION ${INSTALL_CONFIGDIR}
  )

  # Create a ConfigVersion.cmake file:
  include(CMakePackageConfigHelpers)
  write_basic_package_version_file(
    ${CMAKE_CURRENT_BINARY_DIR}/volkConfigVersion.cmake
    COMPATIBILITY AnyNewerVersion
  )

  # Configure config file
  configure_package_config_file(${CMAKE_CURRENT_LIST_DIR}/cmake/volkConfig.cmake.in
    ${CMAKE_CURRENT_BINARY_DIR}/volkConfig.cmake
    INSTALL_DESTINATION ${INSTALL_CONFIGDIR}
  )

  # Install the fully generated config and configVersion files
  install(FILES
    ${CMAKE_CURRENT_BINARY_DIR}/volkConfig.cmake
    ${CMAKE_CURRENT_BINARY_DIR}/volkConfigVersion.cmake
    DESTINATION ${INSTALL_CONFIGDIR}
  )

endif()
```

--------------------------------

### CMake Project Setup and Volk Compilation

Source: https://github.com/zeux/volk/blob/master/test/cmake_using_source_directly/CMakeLists.txt

This CMake script configures a project to compile Volk sources. It sets the minimum CMake version, project name, and language. It then adds the main C file and Volk's C source file to create an executable. Include directories and platform-specific compile definitions are set to ensure proper Vulkan integration.

```cmake
cmake_minimum_required(VERSION 3.5...3.30)
project(volk_test LANGUAGES C)

add_executable(volk_test main.c ../../volk.c)

# Set include path for volk.h
target_include_directories(volk_test PRIVATE ../..)

# Set suitable platform defines
if(CMAKE_SYSTEM_NAME STREQUAL Windows)
  target_compile_definitions(volk_test PRIVATE VK_USE_PLATFORM_WIN32_KHR)
elseif(CMAKE_SYSTEM_NAME STREQUAL Linux)
  target_compile_definitions(volk_test PRIVATE VK_USE_PLATFORM_XLIB_KHR)
elseif(CMAKE_SYSTEM_NAME STREQUAL Darwin)
  target_compile_definitions(volk_test PRIVATE VK_USE_PLATFORM_MACOS_MVK)
endif()

# Link requires libraries
if(NOT WIN32)
  target_link_libraries(volk_test PRIVATE dl)
endif()

# Get Vulkan dependency
find_package(Vulkan QUIET)
if(TARGET Vulkan::Vulkan)
  # Note: We don't use target_link_libraries for Vulkan::Vulkan to avoid a static dependency on libvulkan1
  target_include_directories(volk_test PRIVATE ${Vulkan_INCLUDE_DIRS})
elseif(DEFINED ENV{VULKAN_SDK})
  target_include_directories(volk_test PRIVATE "$ENV{VULKAN_SDK}/include")
endif()
```

--------------------------------

### Initialize Volk Vulkan Loader

Source: https://github.com/zeux/volk/blob/master/README.md

Initializes the volk meta-loader by attempting to load the Vulkan loader from the system. This function should be called first. If successful, it returns VK_SUCCESS, indicating that Vulkan loader is installed and ready to be used. Failure means the Vulkan loader is not present.

```c++
VkResult volkInitialize();
```

--------------------------------

### Volk Initialization and Loading

Source: https://github.com/zeux/volk/blob/master/README.md

This section covers the essential functions for initializing Volk and loading Vulkan entrypoints for instances and devices.

```APIDOC
## Volk Initialization and Loading

### Description
Functions to initialize Volk, load instance-level Vulkan entrypoints, and optionally load device-level entrypoints for optimization.

### `volkInitialize()`

#### Description
Attempts to load the Vulkan loader from the system. This function must be called before any other Volk functions or Vulkan instance creation.

#### Method
`VkResult volkInitialize();`

#### Return Value
- `VK_SUCCESS`: If the Vulkan loader is successfully loaded.
- Other `VkResult` codes: If the Vulkan loader cannot be loaded (e.g., not installed).

### `volkLoadInstance(VkInstance instance)`

#### Description
Loads all required Vulkan instance-level entrypoints, including those for all extensions. This should be called after creating a Vulkan instance.

#### Method
`void volkLoadInstance(VkInstance instance);
`

#### Parameters
- **instance** (`VkInstance`) - The Vulkan instance handle.

### `volkLoadInstanceOnly(VkInstance instance)`

#### Description
Similar to `volkLoadInstance`, but leaves device-specific functions as `NULL`. This can be useful for enforcing the use of function tables for devices.

#### Method
`void volkLoadInstanceOnly(VkInstance instance);
`

#### Parameters
- **instance** (`VkInstance`) - The Vulkan instance handle.

### `volkLoadDevice(VkDevice device)`

#### Description
Loads Vulkan device-related entrypoints directly from the driver for applications using a single `VkDevice`. This optimizes device call performance by bypassing loader dispatch.

#### Method
`void volkLoadDevice(VkDevice device);
`

#### Parameters
- **device** (`VkDevice`) - The Vulkan device handle.

### `volkLoadDeviceTable(struct VolkDeviceTable* table, VkDevice device)`

#### Description
Loads Vulkan device-related entrypoints into a provided table for applications using multiple `VkDevice` objects. Requires the application to use the `VolkDeviceTable` for device function calls.

#### Method
`void volkLoadDeviceTable(struct VolkDeviceTable* table, VkDevice device);
`

#### Parameters
- **table** (`struct VolkDeviceTable*`) - Pointer to the structure to store device function pointers.
- **device** (`VkDevice`) - The Vulkan device handle.

### `VolkDeviceTable` Structure

#### Description
A structure used to hold function pointers for device-specific Vulkan entrypoints when using the table-based loading mechanism.

#### Fields
(Specific fields depend on the Volk implementation, but would typically include function pointers for all Vulkan device commands.)

```

--------------------------------

### Load Volk Vulkan Instance Entrypoints

Source: https://github.com/zeux/volk/blob/master/README.md

Loads all required Vulkan entrypoints for the instance, including those for all extensions. This function should be called after successfully initializing volk and creating a Vulkan instance. Once called, Vulkan functions can be used as usual.

```c++
void volkLoadInstance(VkInstance instance);
```

--------------------------------

### Load Volk Vulkan Instance Only Entrypoints

Source: https://github.com/zeux/volk/blob/master/README.md

An alternative to `volkLoadInstance` that loads only instance-specific Vulkan entrypoints. When used with the table-based interface for devices, `volkLoadInstanceOnly` ensures that device-specific functions remain `NULL`, enforcing the use of function tables.

```c++
void volkLoadInstanceOnly();
```

--------------------------------

### CMake: Include Volk and Link Executable

Source: https://github.com/zeux/volk/blob/master/test/cmake_using_subdir_static/CMakeLists.txt

This CMake configuration includes the Volk library into the build and links the 'volk_test' executable against it. It assumes Volk is located in a parent directory and uses `add_subdirectory` for integration. The executable is built from `main.c`.

```cmake
# Include volk as part of the build tree to make the target known.
# The two-argument version of add_subdirectory allows adding non-subdirs.
add_subdirectory(../.. volk)

add_executable(volk_test main.c)
target_link_libraries(volk_test PRIVATE volk)
```

--------------------------------

### Load Volk Vulkan Device Entrypoints (Multiple Devices)

Source: https://github.com/zeux/volk/blob/master/README.md

Loads device-related Vulkan entrypoints into a provided table for applications managing multiple VkDevice objects. This requires the application to store a `VolkDeviceTable` per `VkDevice` and use functions from these tables. It's compatible with Vulkan layers and minimizes call overhead.

```c++
void volkLoadDeviceTable(struct VolkDeviceTable* table, VkDevice device);
```

--------------------------------

### CMake: Configure Volk Static and Interface Libraries

Source: https://github.com/zeux/volk/blob/master/CMakeLists.txt

Defines static and interface libraries for Volk. The static library is built from volk.c and volk.h, while the interface library provides header-only access. Both libraries manage include directories and dependencies.

```cmake
cmake_minimum_required(VERSION 3.5...3.30)

project(volk VERSION
# VOLK_GENERATE_VERSION
328
# VOLK_GENERATE_VERSION
  LANGUAGES C
)

if(NOT DEFINED VOLK_STATIC_DEFINES)
  set(VOLK_STATIC_DEFINES "" CACHE STRING "Additional defines for building the volk static library, e.g. Vulkan platform defines")
endif()
if(NOT DEFINED VOLK_PULL_IN_VULKAN)
  option(VOLK_PULL_IN_VULKAN "Vulkan as a transitive dependency" ON)
endif()
if(NOT DEFINED VOLK_INSTALL)
  option(VOLK_INSTALL "Create installation targets" OFF)
endif()
if(NOT DEFINED VOLK_NAMESPACE)
  option(VOLK_NAMESPACE "Use C++ namespace for vk* functions" OFF)
endif()
if(NOT DEFINED VOLK_HEADERS_ONLY)
  option(VOLK_HEADERS_ONLY "Add interface library only" OFF)
endif()
if(NOT DEFINED VULKAN_HEADERS_INSTALL_DIR)
  set(VULKAN_HEADERS_INSTALL_DIR "" CACHE PATH "Where to get the Vulkan headers")
endif()

# -----------------------------------------------------
# Static library

if(NOT VOLK_HEADERS_ONLY OR VOLK_INSTALL)
  add_library(volk STATIC volk.h volk.c)
  add_library(volk::volk ALIAS volk)
  target_include_directories(volk PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}>
    $<INSTALL_INTERFACE:include>
  )
  if(VOLK_NAMESPACE)
    target_compile_definitions(volk PUBLIC VOLK_NAMESPACE)
    set_source_files_properties(volk.c PROPERTIES LANGUAGE CXX)
  endif()
  if(VOLK_STATIC_DEFINES)
    target_compile_definitions(volk PUBLIC ${VOLK_STATIC_DEFINES})
  endif()
  if (NOT WIN32)
    target_link_libraries(volk PUBLIC ${CMAKE_DL_LIBS})
  endif()
endif()

# -----------------------------------------------------
# Interface library

add_library(volk_headers INTERFACE)
add_library(volk::volk_headers ALIAS volk_headers)
target_include_directories(volk_headers INTERFACE
  $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}>
  $<INSTALL_INTERFACE:include>
)
if (NOT WIN32)
  target_link_libraries(volk_headers INTERFACE ${CMAKE_DL_LIBS})
endif()
```

--------------------------------

### CMake: Integrate Vulkan Headers

Source: https://github.com/zeux/volk/blob/master/CMakeLists.txt

Manages the inclusion of Vulkan headers by prioritizing the VULKAN_HEADERS_INSTALL_DIR, then the FindVulkan module, and finally the VULKAN_SDK environment variable. Includes necessary headers for both static and interface libraries.

```cmake
# -----------------------------------------------------
# Vulkan transitive dependency

if(VOLK_PULL_IN_VULKAN)
  # Try an explicit CMake variable first, then any Vulkan paths
  # discovered by FindVulkan.cmake, then the $VULKAN_SDK environment
  # variable if nothing else works.
  if(VULKAN_HEADERS_INSTALL_DIR)
    message("volk: using VULKAN_HEADERS_INSTALL_DIR option")
    set(VOLK_INCLUDES "${VULKAN_HEADERS_INSTALL_DIR}/include")
  else()
    # If CMake has the FindVulkan module and it works, use it.
    find_package(Vulkan QUIET)
    if(Vulkan_INCLUDE_DIRS)
      message("volk: using Vulkan_INCLUDE_DIRS from FindVulkan module")
      set(VOLK_INCLUDES "${Vulkan_INCLUDE_DIRS}")
    elseif(DEFINED ENV{VULKAN_SDK})
      message("volk: using VULKAN_SDK environment variable")
      set(VOLK_INCLUDES "$ENV{VULKAN_SDK}/include")
    endif()
  endif()

  if(VOLK_INCLUDES)
    if(TARGET volk)
      target_include_directories(volk PUBLIC "${VOLK_INCLUDES}")
    endif()
    target_include_directories(volk_headers INTERFACE "${VOLK_INCLUDES}")
  endif()
endif()
```

--------------------------------

### CMake: Set Vulkan Platform Defines

Source: https://github.com/zeux/volk/blob/master/test/cmake_using_subdir_static/CMakeLists.txt

This code snippet defines Vulkan platform-specific macros based on the detected operating system. It ensures that the correct Vulkan KHR extension is used for windowing system integration on Windows, Linux, and macOS.

```cmake
cmake_minimum_required(VERSION 3.5...3.30)
project(volk_test LANGUAGES C)

# Set a suitable platform define to compile volk with.
if(CMAKE_SYSTEM_NAME STREQUAL Windows)
  set(VOLK_STATIC_DEFINES VK_USE_PLATFORM_WIN32_KHR)
elseif(CMAKE_SYSTEM_NAME STREQUAL Linux)
  set(VOLK_STATIC_DEFINES VK_USE_PLATFORM_XLIB_KHR)
elseif(CMAKE_SYSTEM_NAME STREQUAL Darwin)
  set(VOLK_STATIC_DEFINES VK_USE_PLATFORM_MACOS_MVK)
endif()
```

--------------------------------

### Load Volk Vulkan Device Entrypoints (Single Device)

Source: https://github.com/zeux/volk/blob/master/README.md

Loads device-related Vulkan entrypoints directly from the driver for applications using a single VkDevice. This method bypasses Vulkan loader dispatch for device calls, potentially increasing performance by reducing overhead. It should be used when only one VkDevice is managed.

```c++
void volkLoadDevice(VkDevice device);
```

--------------------------------

### C/C++: Enabling Volk Namespace

Source: https://github.com/zeux/volk/blob/master/README.md

Explains how to enable the 'VOLK_NAMESPACE' option to place all Volk symbols within the 'volk::' namespace. This is useful for preventing symbol conflicts when linking Volk with other libraries that might directly use Vulkan. This requires compiling Volk's C files in C++ mode.

```c
// Enable VOLK_NAMESPACE by defining it before including volk.h
#define VOLK_NAMESPACE
#include "volk.h"
```

--------------------------------

### CMake: Static Library Integration with Volk

Source: https://github.com/zeux/volk/blob/master/README.md

Integrates the Volk static library into a CMake project. It demonstrates setting platform-specific defines for compilation and linking the 'volk' target to the application. This method ensures all Volk symbols are available as global symbols.

```cmake
if (WIN32)
   set(VOLK_STATIC_DEFINES VK_USE_PLATFORM_WIN32_KHR)
elseif()
   ...
endif()
add_subdirectory(volk)
target_link_library(my_application PRIVATE volk)
```

--------------------------------

### CMake Platform Defines for Volk

Source: https://github.com/zeux/volk/blob/master/test/cmake_cpp_namespace/CMakeLists.txt

Sets platform-specific preprocessor defines required for Volk to function correctly with different operating systems. These defines ensure that the appropriate Vulkan platform extensions are enabled during compilation. This snippet is crucial for cross-platform Vulkan development.

```cmake
cmake_minimum_required(VERSION 3.5...3.30)
project(volk_test LANGUAGES CXX)

# Set a suitable platform define to compile volk with.
if(CMAKE_SYSTEM_NAME STREQUAL Windows)
  set(VOLK_STATIC_DEFINES VK_USE_PLATFORM_WIN32_KHR)
elseif(CMAKE_SYSTEM_NAME STREQUAL Linux)
  set(VOLK_STATIC_DEFINES VK_USE_PLATFORM_XLIB_KHR)
elseif(CMAKE_SYSTEM_NAME STREQUAL Darwin)
  set(VOLK_STATIC_DEFINES VK_USE_PLATFORM_MACOS_MVK)
endif()

# Enable volk C++ namespace feature; this only works when volk is compiled and used from C++
set(VOLK_NAMESPACE ON)

# Include volk as part of the build tree to make the target known.
# The two-argument version of add_subdirectory allows adding non-subdirs.
add_subdirectory(../.. volk)

add_executable(volk_test main.cpp)
target_link_libraries(volk_test PRIVATE volk)
```

--------------------------------

### CMake: Header-Only Library Integration with Volk

Source: https://github.com/zeux/volk/blob/master/README.md

Configures Volk for header-only usage within a CMake project. This involves linking the 'volk_headers' target and defining 'VOLK_IMPLEMENTATION' in the C/C++ source files before including 'volk.h'. This approach is suitable when copying Volk files directly into the project.

```cmake
add_subdirectory(volk)
target_link_library(my_application PRIVATE volk_headers)
```

```c
/* ...any logic setting VK_USE_PLATFORM_WIN32_KHR and friends... */
#define VOLK_IMPLEMENTATION
#include "volk.h"
```

--------------------------------

### C/C++: Hiding Device Level Function Prototypes

Source: https://github.com/zeux/volk/blob/master/README.md

Describes the 'VOLK_NO_DEVICE_PROTOTYPES' macro to hide device-level Vulkan function prototypes. This can help catch compilation errors related to incorrect usage of device-specific functions, especially when using functions like 'volkLoadInstanceOnly' and 'volkLoadDeviceTable'.

```c
// Define VOLK_NO_DEVICE_PROTOTYPES to hide device-level function prototypes
#define VOLK_NO_DEVICE_PROTOTYPES
#include "volk.h"
```
Tokens:
Raw