Class VulkanLoader

java.lang.Object

club.doki7.vulkan.command.VulkanLoader

public final class VulkanLoader
extends Object

Utility class for loading Vulkan functions

Method Summary

Modifier and Type	Method	Description
static @NotNull VkDeviceCommands	loadDeviceCommands(@NotNull VkDevice device, @NotNull VkStaticCommands staticCommands)	Load Vulkan device commands.
static @NotNull VkEntryCommands	loadEntryCommands(@NotNull VkStaticCommands staticCommands)	Load Vulkan entry commands.
static @NotNull VkInstanceCommands	loadInstanceCommands(@NotNull VkInstance instance, @NotNull VkStaticCommands staticCommands)	Load Vulkan instance commands.
static @NotNull VkStaticCommands	loadStaticCommands()	Load Vulkan static commands.
static void	loadVulkanLibrary()	Try loading the Vulkan library.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

loadVulkanLibrary

public static void loadVulkanLibrary()

Try loading the Vulkan library.

This function is implemented in terms of System.loadLibrary(String). On Windows it will try "vulkan-1" (vulkan-1.dll), and on other platforms it will try "vulkan" (libvulkan.so or libvulkan.dylib).

Instead of using this function, you may also implement your own Vulkan library loading logic.

Notice for Linux users: On some Linux platforms, libvulkan.so may not be installed under /usr/lib, /usr/lib32 or /usr/lib64. For example, on my Debian 12 system, it is installed under /lib/cpu-os-libc-triplet. Such locations might not be included by Java java.library.path. In that case, you may need to set the LD_LIBRARY_PATH environment variable to include the directory where libvulkan.so is installed.

Notice for macOS users: According to my observation, as long as the libvulkan.dylib is contained in the java.library.path, it will be loaded correctly. Since java.library.path includes . (i.e. cwd), when developing on macOS, you may simply symlink the libvulkan.dylib (provided by MoltenVk) to the project root directory. But by this moment the project maintainer don't have any knowledge on macOS software packaging. You may need to implement your own loading logic when packaging and releasing software. Contributions are welcome.

Throws:

SecurityException - see System.loadLibrary(String)

UnsatisfiedLinkError - see System.loadLibrary(String)

loadStaticCommands

@NotNull
public static @NotNull VkStaticCommands loadStaticCommands()

Load Vulkan static commands.

This function is in effect implemented in terms of Loader.loadFunction(String, FunctionDescriptor) + Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED. If any of the static functions is not found, a RuntimeException will be thrown. If any of the functions cannot be linked due to any reason, the relevant exception will be thrown.

Instead of using this function, you may also implement your own commands loading logic.

Returns:

loaded static commands

Throws:

RuntimeException - if any static function is not found, see Loader.loadFunction(java.lang.String, java.lang.foreign.FunctionDescriptor)

IllegalArgumentException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED

IllegalCallerException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED

loadEntryCommands

@NotNull
public static @NotNull VkEntryCommands loadEntryCommands(@NotNull
 @NotNull VkStaticCommands staticCommands)

Load Vulkan entry commands.

This function is in effect implemented in terms of VkStaticCommands.getInstanceProcAddr(VkInstance, BytePtr) + Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED, while not providing actual pointer to the VkInstance. If any of the static functions is not found, a RuntimeException will be thrown. If any of the functions cannot be linked due to any reason, the relevant exception will be thrown.

Instead of using this function, you may also implement your own commands loading logic.

Parameters:

staticCommands - static commands, providing the vkGetInstanceProcAddr function

Returns:

loaded entry commands

Throws:

RuntimeException - if any entry function is not found

IllegalArgumentException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED

IllegalCallerException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED

loadInstanceCommands

@NotNull
public static @NotNull VkInstanceCommands loadInstanceCommands(@NotNull
 @NotNull VkInstance instance,
 @NotNull
 @NotNull VkStaticCommands staticCommands)

Load Vulkan instance commands.

This function is implemented in terms of VkStaticCommands.getInstanceProcAddr(VkInstance, BytePtr) + Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED. If any of the functions is not found, that "slot" will be filled with null. Calling a function not loaded will result in a NullPointerException. Not found functions are usually caused by unsupported or not requested Vulkan extensions or layers.

If the function address is found, but cannot be linked due to any reason, the relevant exception will be thrown.

Instead of using this function, you may also implement your own commands loading logic.

Parameters:

instance - Vulkan instance

staticCommands - static commands, providing the vkGetInstanceProcAddr function

Returns:

loaded instance commands

Throws:

IllegalArgumentException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED

IllegalCallerException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED

loadDeviceCommands

@NotNull
public static @NotNull VkDeviceCommands loadDeviceCommands(@NotNull
 @NotNull VkDevice device,
 @NotNull
 @NotNull VkStaticCommands staticCommands)

Load Vulkan device commands.

This function is implemented in terms of VkStaticCommands.getDeviceProcAddr(VkDevice, BytePtr) + Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED. If any of the functions is not found, that "slot" will be filled with null. Calling a function not loaded will result in a NullPointerException. Not found functions are usually caused by unsupported or not requested Vulkan extensions or layers.

If the function address is found, but cannot be linked due to any reason, the relevant exception will be thrown.

Instead of using this function, you may also implement your own commands loading logic.

Parameters:

device - Vulkan device

staticCommands - static commands, providing the loading functions

Returns:

loaded device commands

Throws:

IllegalArgumentException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED

IllegalCallerException - see Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)^RESTRICTED