Package org.lwjgl.glfw

Class GLFWVulkan

java.lang.Object
org.lwjgl.glfw.GLFWVulkan
public class GLFWVulkan extends Object
Native bindings to the GLFW library's Vulkan functions.

  • Method Details

    • glfwInitVulkanLoader

      public static void glfwInitVulkanLoader(long loader)
      Sets the desired Vulkan vkGetInstanceProcAddr function.

      This function sets the vkGetInstanceProcAddr function that GLFW will use for all Vulkan related entry point queries.

      This feature is mostly useful on macOS, if your copy of the Vulkan loader is in a location where GLFW cannot find it through dynamic loading, or if you are still using the static library version of the loader.

      If set to NULL, GLFW will try to load the Vulkan loader dynamically by its standard name and get this function from there. This is the default behavior.

      The standard name of the loader is vulkan-1.dll on Windows, libvulkan.so.1 on Linux and other Unix-like systems and libvulkan.1.dylib on macOS. If your code is also loading it via these names then you probably don't need to use this function.

      The function address you set is never reset by GLFW, but it only takes effect during initialization. Once GLFW has been initialized, any updates will be ignored until the library is terminated and initialized again.

      This function may be called before Init.

      This function must only be called from the main thread.

      Parameters:
      loader - the address of the function to use, or NULL
      Since:
      version 3.4

    • glfwVulkanSupported

      public static boolean glfwVulkanSupported()
      Returns whether the Vulkan loader has been found. This check is performed by Init.

      The availability of a Vulkan loader and even an ICD does not by itself guarantee that surface creation or even instance creation is possible. Call GetRequiredInstanceExtensions to check whether the extensions necessary for Vulkan surface creation are available and GetPhysicalDevicePresentationSupport to check whether a queue family of a physical device supports image presentation.

      Possible errors include NOT_INITIALIZED.

      This function may be called from any thread.

      Returns:
      TRUE if Vulkan is available, or FALSE otherwise
      Since:
      version 3.2

    • nglfwGetRequiredInstanceExtensions

      public static long nglfwGetRequiredInstanceExtensions(long count)
      Unsafe version of: GetRequiredInstanceExtensions
      Parameters:
      count - where to store the number of extensions in the returned array. This is set to zero if an error occurred.

    • glfwGetRequiredInstanceExtensions

      @Nullable public static PointerBuffer glfwGetRequiredInstanceExtensions()
      Returns an array of names of Vulkan instance extensions required by GLFW for creating Vulkan surfaces for GLFW windows. If successful, the list will always contain VK_KHR_surface, so if you don't require any additional extensions you can pass this list directly to the VkInstanceCreateInfo struct.

      If Vulkan is not available on the machine, this function returns NULL and generates a API_UNAVAILABLE error. Call VulkanSupported to check whether Vulkan is available.

      If Vulkan is available but no set of extensions allowing window surface creation was found, this function returns NULL. You may still use Vulkan for off-screen rendering and compute work.

      Additional extensions may be required by future versions of GLFW. You should check if any extensions you wish to enable are already in the returned array, as it is an error to specify an extension more than once in the VkInstanceCreateInfo struct.

      The returned array is allocated and freed by GLFW. You should not free it yourself. It is guaranteed to be valid only until the library is terminated.

      This function may be called from any thread.

      Possible errors include NOT_INITIALIZED and API_UNAVAILABLE.

      Returns:
      an array of ASCII encoded extension names, or NULL if an error occurred
      Since:
      version 3.2

    • nglfwGetInstanceProcAddress

      public static long nglfwGetInstanceProcAddress(long instance, long procname)
      Unsafe version of: GetInstanceProcAddress

    • glfwGetInstanceProcAddress

      public static long glfwGetInstanceProcAddress(@Nullable VkInstance instance, ByteBuffer procname)
      Returns the address of the specified Vulkan core or extension function for the specified instance. If instance is set to NULL it can return any function exported from the Vulkan loader, including at least the following functions:

      If Vulkan is not available on the machine, this function returns NULL and generates a API_UNAVAILABLE error. Call VulkanSupported to check whether Vulkan is available.

      This function is equivalent to calling VK10.vkGetInstanceProcAddr(org.lwjgl.vulkan.VkInstance, java.nio.ByteBuffer) with a platform-specific query of the Vulkan loader as a fallback.

      Possible errors include NOT_INITIALIZED and API_UNAVAILABLE.

      The returned function pointer is valid until the library is terminated.

      This function may be called from any thread.

      Parameters:
      instance - the Vulkan instance to query, or NULL to retrieve functions related to instance creation
      procname - the ASCII encoded name of the function
      Returns:
      the address of the function, or NULL if an error occurred
      Since:
      version 3.2

    • glfwGetInstanceProcAddress

      public static long glfwGetInstanceProcAddress(@Nullable VkInstance instance, CharSequence procname)
      Returns the address of the specified Vulkan core or extension function for the specified instance. If instance is set to NULL it can return any function exported from the Vulkan loader, including at least the following functions:

      If Vulkan is not available on the machine, this function returns NULL and generates a API_UNAVAILABLE error. Call VulkanSupported to check whether Vulkan is available.

      This function is equivalent to calling VK10.vkGetInstanceProcAddr(org.lwjgl.vulkan.VkInstance, java.nio.ByteBuffer) with a platform-specific query of the Vulkan loader as a fallback.

      Possible errors include NOT_INITIALIZED and API_UNAVAILABLE.

      The returned function pointer is valid until the library is terminated.

      This function may be called from any thread.

      Parameters:
      instance - the Vulkan instance to query, or NULL to retrieve functions related to instance creation
      procname - the ASCII encoded name of the function
      Returns:
      the address of the function, or NULL if an error occurred
      Since:
      version 3.2

    • glfwGetPhysicalDevicePresentationSupport

      public static boolean glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, int queuefamily)
      Returns whether the specified queue family of the specified physical device supports presentation to the platform GLFW was built for.

      If Vulkan or the required window surface creation instance extensions are not available on the machine, or if the specified instance was not created with the required extensions, this function returns FALSE and generates a API_UNAVAILABLE error. Call VulkanSupported to check whether Vulkan is available and GetRequiredInstanceExtensions to check what instance extensions are required.

      Possible errors include NOT_INITIALIZED, API_UNAVAILABLE and PLATFORM_ERROR.

      macOS: This function currently always returns TRUE, as the VK_MVK_macos_surface and VK_EXT_metal_surface extensions do not provide a vkGetPhysicalDevice*PresentationSupport type function.

      This function may be called from any thread. For synchronization details of Vulkan objects, see the Vulkan specification.

      Parameters:
      instance - the instance that the physical device belongs to
      device - the physical device that the queue family belongs to
      queuefamily - the index of the queue family to query
      Returns:
      TRUE if the queue family supports presentation, or FALSE otherwise
      Since:
      version 3.2

    • nglfwCreateWindowSurface

      public static int nglfwCreateWindowSurface(long instance, long window, long allocator, long surface)
      Unsafe version of: CreateWindowSurface

    • glfwCreateWindowSurface

      public static int glfwCreateWindowSurface(VkInstance instance, long window, @Nullable VkAllocationCallbacks allocator, LongBuffer surface)
      Creates a Vulkan surface for the specified window.

      If the Vulkan loader was not found at initialization, this function returns VK10.VK_ERROR_INITIALIZATION_FAILED and generates a API_UNAVAILABLE error. Call VulkanSupported to check whether the Vulkan loader was found.

      If the required window surface creation instance extensions are not available or if the specified instance was not created with these extensions enabled, this function returns VK10.VK_ERROR_EXTENSION_NOT_PRESENT and generates a API_UNAVAILABLE error. Call GetRequiredInstanceExtensions to check what instance extensions are required.

      The window surface cannot be shared with another API so the window must have been created with the client api hint set to NO_API otherwise it generates a INVALID_VALUE error and returns KHRSurface.VK_ERROR_NATIVE_WINDOW_IN_USE_KHR.

      The window surface must be destroyed before the specified Vulkan instance. It is the responsibility of the caller to destroy the window surface. GLFW does not destroy it for you. Call KHRSurface.vkDestroySurfaceKHR(org.lwjgl.vulkan.VkInstance, long, org.lwjgl.vulkan.VkAllocationCallbacks) to destroy the surface.

      Possible errors include NOT_INITIALIZED, API_UNAVAILABLE, PLATFORM_ERROR and INVALID_VALUE.

      If an error occurs before the creation call is made, GLFW returns the Vulkan error code most appropriate for the error. Appropriate use of VulkanSupported and glfwGetRequiredInstanceExtensions should eliminate almost all occurrences of these errors.

      Notes:

      • This function may be called from any thread. For synchronization details of Vulkan objects, see the Vulkan specification.
      • macOS: GLFW prefers the VK_EXT_metal_surface extension, with the VK_MVK_macos_surface extension as a fallback. The name of the selected extension, if any, is included in the array returned by glfwGetRequiredInstanceExtensions.
      • macOS: This function creates and sets a CAMetalLayer instance for the window content view, which is required for MoltenVK to function.
      • x11: By default GLFW prefers the VK_KHR_xcb_surface extension, with the VK_KHR_xlib_surface extension as a fallback. You can make VK_KHR_xlib_surface the preferred extension by setting the X11_XCB_VULKAN_SURFACE init hint. The name of the selected extension, if any, is included in the array returned by glfwGetRequiredInstanceExtensions.
      Parameters:
      instance - the Vulkan instance to create the surface in
      window - the window to create the surface for
      allocator - the allocator to use, or NULL to use the default allocator.
      surface - where to store the handle of the surface. This is set to VK10.VK_NULL_HANDLE if an error occurred.
      Returns:
      VK10.VK_SUCCESS if successful, or a Vulkan error code if an error occurred
      Since:
      version 3.2

    • glfwCreateWindowSurface

      public static int glfwCreateWindowSurface(VkInstance instance, long window, @Nullable VkAllocationCallbacks allocator, long[] surface)
      Array version of: CreateWindowSurface

    • setPath

      public static void setPath(FunctionProvider sharedLibrary)
      Calls setPath(String) with the path of the specified SharedLibrary.

      Example usage: GLFWVulkan.setPath(VK.getFunctionProvider());

      Parameters:
      sharedLibrary - a FunctionProvider instance that will be cast to SharedLibrary

    • setPath

      public static void setPath(@Nullable String path)
      Overrides the Vulkan shared library that GLFW loads internally.

      This is useful when there's a mismatch between the shared libraries loaded by LWJGL and GLFW.

      This method must be called before GLFW initializes Vulkan. The override is available only in the default GLFW build bundled with LWJGL. Using the override with a custom GLFW build will produce a warning in DEBUG mode (but not an error).

      Parameters:
      path - the Vulkan shared library path, or null to remove the override.