GLFW: Vulkan reference

GLFW

- Documentation
- Download
- Media
- Community

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Typedefs | Functions
Vulkan reference

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

## Functions
int | glfwVulkanSupported (void)
| Returns whether the Vulkan loader has 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...

## Detailed Description

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

## Typedef Documentation

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

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 was not found at initialization, this function returns `VK_ERROR_INITIALIZATION_FAILED` and generates a GLFW_API_UNAVAILABLE error. Call glfwVulkanSupported 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 `VK_ERROR_EXTENSION_NOT_PRESENT` and generates a GLFW_API_UNAVAILABLE error. Call glfwGetRequiredInstanceExtensions to check what instance extensions are required.

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 and GLFW_PLATFORM_ERROR.

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.

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.

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 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.

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 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.

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.

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 contains `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 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.

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.

int glfwVulkanSupported | ( | void |  | ) |

This function returns whether the Vulkan loader has been found. This check is performed by glfwInit.

The availability of a Vulkan loader does not by itself guarantee that window surface creation or even device 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 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.