Fix glfwVulkanSupported semantics

This commit is contained in:
Camilla Löwy 2017-02-07 20:56:48 +01:00
parent 8e870d4cc0
commit 98bdd36231
5 changed files with 31 additions and 28 deletions

View File

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

View File

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

View File

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

View File

@ -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));

View File

@ -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())