From 98bdd36231b8dd7048783cb3b20d8492b44ad4b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Tue, 7 Feb 2017 20:56:48 +0100 Subject: [PATCH] Fix glfwVulkanSupported semantics --- docs/compat.dox | 7 ++++--- docs/vulkan.dox | 10 +++++----- include/GLFW/glfw3.h | 36 +++++++++++++++++++----------------- src/vulkan.c | 4 ++-- tests/glfwinfo.c | 2 +- 5 files changed, 31 insertions(+), 28 deletions(-) diff --git a/docs/compat.dox b/docs/compat.dox index c54bdd91..61eeb058 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -187,9 +187,10 @@ a non-default value will cause @ref glfwCreateWindow to fail and the By default, GLFW uses the standard system-wide Vulkan loader to access the Vulkan API on all platforms except macOS. This is installed by both graphics -drivers and Vulkan SDKs. If the loader is not found, @ref glfwVulkanSupported -will return `GLFW_FALSE` and all other Vulkan-related functions will fail with -an @ref GLFW_API_UNAVAILABLE error. +drivers and Vulkan SDKs. If either the loader or at least one minimally +functional ICD is missing, @ref glfwVulkanSupported will return `GLFW_FALSE` and +all other Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE +error. @section compat_wsi Vulkan WSI extensions diff --git a/docs/vulkan.dox b/docs/vulkan.dox index 4ecdafde..60d04941 100644 --- a/docs/vulkan.dox +++ b/docs/vulkan.dox @@ -81,7 +81,7 @@ section. The canonical desktop loader library exports all Vulkan core and Khronos extension functions, allowing them to be called directly. If you are loading the Vulkan loader dynamically instead of linking directly -against it, you can check for the availability of a loader with @ref +against it, you can check for the availability of a loader and ICD with @ref glfwVulkanSupported. @code @@ -91,11 +91,11 @@ if (glfwVulkanSupported()) } @endcode -This function returns `GLFW_TRUE` if the Vulkan loader was found. This check is -performed by @ref glfwInit. +This function returns `GLFW_TRUE` if the Vulkan loader and any minimally +functional ICD was found. -If no loader was found, calling any other Vulkan related GLFW function will -generate a @ref GLFW_API_UNAVAILABLE error. +If if one or both were not found, calling any other Vulkan related GLFW function +will generate a @ref GLFW_API_UNAVAILABLE error. @subsection vulkan_proc Querying Vulkan function pointers diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 1fcd476c..b0db24b7 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -4432,19 +4432,21 @@ GLFWAPI int glfwExtensionSupported(const char* extension); */ GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname); -/*! @brief Returns whether the Vulkan loader has been found. +/*! @brief Returns whether the Vulkan loader and an ICD have been found. * - * This function returns whether the Vulkan loader has been found. This check - * is performed by @ref glfwInit. + * This function returns whether the Vulkan loader and any minimally functional + * ICD have been found. * - * The availability of a Vulkan loader does not by itself guarantee that window - * surface creation or even device creation is possible. Call @ref - * glfwGetRequiredInstanceExtensions to check whether the extensions necessary - * for Vulkan surface creation are available and @ref - * glfwGetPhysicalDevicePresentationSupport to check whether a queue family of - * a physical device supports image presentation. + * The availability of a Vulkan loader and even an ICD does not by itself + * guarantee that surface creation or even instance creation is possible. + * For example, on Fermi systems Nvidia will install an ICD that provides no + * actual Vulkan support. Call @ref glfwGetRequiredInstanceExtensions to check + * whether the extensions necessary for Vulkan surface creation are available + * and @ref glfwGetPhysicalDevicePresentationSupport to check whether a queue + * family of a physical device supports image presentation. * - * @return `GLFW_TRUE` if Vulkan is available, or `GLFW_FALSE` otherwise. + * @return `GLFW_TRUE` if Vulkan is minimally available, or `GLFW_FALSE` + * otherwise. * * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. * @@ -4468,7 +4470,7 @@ GLFWAPI int glfwVulkanSupported(void); * * If Vulkan is not available on the machine, this function returns `NULL` and * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported - * to check whether Vulkan is available. + * 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 @@ -4521,7 +4523,7 @@ GLFWAPI const char** glfwGetRequiredInstanceExtensions(uint32_t* count); * * If Vulkan is not available on the machine, this function returns `NULL` and * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported - * to check whether Vulkan is available. + * 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. @@ -4557,7 +4559,7 @@ GLFWAPI GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char* p * 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 @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported - * to check whether Vulkan is available and @ref + * to check whether Vulkan is at least minimally available and @ref * glfwGetRequiredInstanceExtensions to check what instance extensions are * required. * @@ -4589,10 +4591,10 @@ GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhys * * 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 @ref GLFW_API_UNAVAILABLE - * error. Call @ref glfwVulkanSupported to check whether the Vulkan loader was - * found. + * If the Vulkan loader or at least one minimally functional ICD were not found, + * this function returns `VK_ERROR_INITIALIZATION_FAILED` and generates a @ref + * GLFW_API_UNAVAILABLE error. Call @ref 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 diff --git a/src/vulkan.c b/src/vulkan.c index 9bd10d43..91ea2671 100644 --- a/src/vulkan.c +++ b/src/vulkan.c @@ -102,7 +102,7 @@ GLFWbool _glfwInitVulkan(int mode) // NOTE: This happens on systems with a loader but without any Vulkan ICD if (mode == _GLFW_REQUIRE_LOADER) { - _glfwInputError(GLFW_PLATFORM_ERROR, + _glfwInputError(GLFW_API_UNAVAILABLE, "Vulkan: Failed to query instance extension count: %s", _glfwGetVulkanResultString(err)); } @@ -116,7 +116,7 @@ GLFWbool _glfwInitVulkan(int mode) err = vkEnumerateInstanceExtensionProperties(NULL, &count, ep); if (err) { - _glfwInputError(GLFW_PLATFORM_ERROR, + _glfwInputError(GLFW_API_UNAVAILABLE, "Vulkan: Failed to query instance extensions: %s", _glfwGetVulkanResultString(err)); diff --git a/tests/glfwinfo.c b/tests/glfwinfo.c index bb4f6a86..6e9335ee 100644 --- a/tests/glfwinfo.c +++ b/tests/glfwinfo.c @@ -800,7 +800,7 @@ int main(int argc, char** argv) if (list_extensions) list_context_extensions(client, major, minor); - printf("Vulkan loader: %s\n", + printf("Vulkan support: %s\n", glfwVulkanSupported() ? "available" : "missing"); if (glfwVulkanSupported())