Description

This is the reference documentation for Vulkan related functions and types. For more task-oriented information, see the Vulkan guide.

Typedefs
typedef void(*	GLFWvkproc) (void)
	Vulkan API function pointer type. More...

Functions
int	glfwVulkanSupported (void)
	Returns whether the Vulkan loader and an ICD have been found. More...

const char **	glfwGetRequiredInstanceExtensions (uint32_t *count)
	Returns the Vulkan instance extensions required by GLFW. More...

GLFWvkproc	glfwGetInstanceProcAddress (VkInstance instance, const char *procname)
	Returns the address of the specified Vulkan instance function. More...

int	glfwGetPhysicalDevicePresentationSupport (VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily)
	Returns whether the specified queue family can present images. More...

VkResult	glfwCreateWindowSurface (VkInstance instance, GLFWwindow window, const VkAllocationCallbacks allocator, VkSurfaceKHR *surface)
	Creates a Vulkan surface for the specified window. More...

Typedef Documentation

◆ GLFWvkproc

typedef void(* GLFWvkproc) (void)

Generic function pointer used for returning Vulkan API function pointers without forcing a cast from a regular pointer.

See also: Querying Vulkan function pointers; glfwGetInstanceProcAddress

Since: Added in version 3.2.

Function Documentation

◆ glfwVulkanSupported()

int glfwVulkanSupported ( void )

This function returns whether the Vulkan loader and any minimally functional ICD have been found.

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 glfwGetRequiredInstanceExtensions to check whether the extensions necessary for Vulkan surface creation are available and glfwGetPhysicalDevicePresentationSupport to check whether a queue family of a physical device supports image presentation.

Returns: GLFW_TRUE if Vulkan is minimally available, or GLFW_FALSE otherwise.

Errors: Possible errors include GLFW_NOT_INITIALIZED.

Thread safety: This function may be called from any thread.

See also: Querying for Vulkan support

Since: Added in version 3.2.

◆ glfwGetRequiredInstanceExtensions()

const char ** glfwGetRequiredInstanceExtensions ( uint32_t * count )

This function 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 GLFW_API_UNAVAILABLE error. Call glfwVulkanSupported to check whether Vulkan is at least minimally 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.

Parameters

[out] count Where to store the number of extensions in the returned array. This is set to zero if an error occurred.

Returns: An array of ASCII encoded extension names, or NULL if an error occurred.

Errors: Possible errors include GLFW_NOT_INITIALIZED and GLFW_API_UNAVAILABLE.

Remarks: 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.; macOS: GLFW currently supports both the VK_MVK_macos_surface and the newer VK_EXT_metal_surface extensions.

Pointer lifetime: 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.

Thread safety: This function may be called from any thread.

See also: Querying required Vulkan extensions; glfwCreateWindowSurface

Since: Added in version 3.2.

◆ glfwGetInstanceProcAddress()

GLFWvkproc glfwGetInstanceProcAddress	(	VkInstance	instance,
		const char *	procname
	)

This function 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:

vkEnumerateInstanceExtensionProperties
vkEnumerateInstanceLayerProperties
vkCreateInstance
vkGetInstanceProcAddr

If Vulkan is not available on the machine, this function returns NULL and generates a GLFW_API_UNAVAILABLE error. Call glfwVulkanSupported to check whether Vulkan is at least minimally available.

This function is equivalent to calling vkGetInstanceProcAddr with a platform-specific query of the Vulkan loader as a fallback.

Parameters

[in]	instance	The Vulkan instance to query, or `NULL` to retrieve functions related to instance creation.
[in]	procname	The ASCII encoded name of the function.

Returns: The address of the function, or NULL if an error occurred.

Errors: Possible errors include GLFW_NOT_INITIALIZED and GLFW_API_UNAVAILABLE.

Pointer lifetime: The returned function pointer is valid until the library is terminated.

Thread safety: This function may be called from any thread.

See also: Querying Vulkan function pointers

Since: Added in version 3.2.

◆ glfwGetPhysicalDevicePresentationSupport()

int glfwGetPhysicalDevicePresentationSupport	(	VkInstance	instance,
		VkPhysicalDevice	device,
		uint32_t	queuefamily
	)

This function 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 GLFW_FALSE and generates a GLFW_API_UNAVAILABLE error. Call glfwVulkanSupported to check whether Vulkan is at least minimally available and glfwGetRequiredInstanceExtensions to check what instance extensions are required.

Parameters

[in]	instance	The instance that the physical device belongs to.
[in]	device	The physical device that the queue family belongs to.
[in]	queuefamily	The index of the queue family to query.

Returns: GLFW_TRUE if the queue family supports presentation, or GLFW_FALSE otherwise.

Errors: Possible errors include GLFW_NOT_INITIALIZED, GLFW_API_UNAVAILABLE and GLFW_PLATFORM_ERROR.

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

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

See also: Querying for Vulkan presentation support

Since: Added in version 3.2.

◆ glfwCreateWindowSurface()

VkResult glfwCreateWindowSurface	(	VkInstance	instance,
		GLFWwindow *	window,
		const VkAllocationCallbacks *	allocator,
		VkSurfaceKHR *	surface
	)

This function creates a Vulkan surface for the specified window.

If the Vulkan loader or at least one minimally functional ICD were not found, this function returns VK_ERROR_INITIALIZATION_FAILED and generates a GLFW_API_UNAVAILABLE error. Call glfwVulkanSupported to check whether Vulkan is at least minimally available.

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 VK_ERROR_EXTENSION_NOT_PRESENT and generates a GLFW_API_UNAVAILABLE error. Call glfwGetRequiredInstanceExtensions 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 GLFW_NO_API otherwise it generates a GLFW_INVALID_VALUE error and returns 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 vkDestroySurfaceKHR to destroy the surface.

Parameters

[in]	instance	The Vulkan instance to create the surface in.
[in]	window	The window to create the surface for.
[in]	allocator	The allocator to use, or `NULL` to use the default allocator.
[out]	surface	Where to store the handle of the surface. This is set to `VK_NULL_HANDLE` if an error occurred.

Returns: VK_SUCCESS if successful, or a Vulkan error code if an error occurred.

Errors: Possible errors include GLFW_NOT_INITIALIZED, GLFW_API_UNAVAILABLE, GLFW_PLATFORM_ERROR and GLFW_INVALID_VALUE

Remarks: If an error occurs before the creation call is made, GLFW returns the Vulkan error code most appropriate for the error. Appropriate use of glfwVulkanSupported and glfwGetRequiredInstanceExtensions should eliminate almost all occurrences of these errors.; macOS: This function currently only supports the VK_MVK_macos_surface extension from MoltenVK.; macOS: This function creates and sets a CAMetalLayer instance for the window content view, which is required for MoltenVK to function.

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

See also: Creating a Vulkan window surface; glfwGetRequiredInstanceExtensions

Since: Added in version 3.2.

Description

Typedefs

Functions

Typedef Documentation

◆ GLFWvkproc

Function Documentation

◆ glfwVulkanSupported()

◆ glfwGetRequiredInstanceExtensions()

◆ glfwGetInstanceProcAddress()

◆ glfwGetPhysicalDevicePresentationSupport()

◆ glfwCreateWindowSurface()