From 41b82903a80f689594da009e87cb9e835cf7f03b Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Wed, 17 Feb 2016 09:10:48 +0100 Subject: [PATCH] Documentation work --- docs/vulkan.dox | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/vulkan.dox b/docs/vulkan.dox index 7cd25abc..6b9b3b47 100644 --- a/docs/vulkan.dox +++ b/docs/vulkan.dox @@ -4,22 +4,24 @@ @tableofcontents -This guide is intended to fill the gaps between the Vulkan documentation and the -rest of the GLFW documentation and is not a replacement for either. +This guide is intended to fill the gaps between the [Vulkan +documentation](https://www.khronos.org/vulkan/) and the rest of the GLFW +documentation and is not a replacement for either. It assumes some familiarity +with Vulkan concepts like loaders, devices, queues and surfaces. To develop for Vulkan you should install an SDK for your platform, for example -the [LunarG Vulkan SDK](http://lunarg.com/vulkan-sdk/). Apart from the headers -and libraries, it also provides the validation layers necessary for development. +the [LunarG Vulkan SDK](https://vulkan.lunarg.com/). Apart from the headers and +libraries, it also provides the validation layers necessary for development. -GLFW itself does not need a Vulkan SDK to enable support for Vulkan. However, -any Vulkan-specific test and example programs are built only if the CMake files -find the LunarG SDK. +The GLFW library does not need the Vulkan SDK to enable support for Vulkan. +However, any Vulkan-specific test and example programs are built only if the +CMake files find a Vulkan SDK. @section vulkan_include Including the Vulkan and GLFW header files -To include the Vulkan header, define `GLFW_INCLUDE_VULKAN` before including the -GLFW header. +To include the Vulkan header, define [GLFW_INCLUDE_VULKAN](@ref build_macros) +before including the GLFW header. @code #define GLFW_INCLUDE_VULKAN @@ -30,15 +32,15 @@ If you want to include the Vulkan header from a custom location or use your own custom Vulkan header then you need to include them before the GLFW header. @code -#include +#include #include @endcode Unless a Vulkan header is included, either by the GLFW header or above it, any -GLFW functions that use Vulkan types will not be declared. +GLFW functions that take or return Vulkan types will not be declared. The `VK_USE_PLATFORM_*_KHR` macros do not need to be defined for the Vulkan part -of GLFW to work. +of GLFW to work. Define them only if you are using these extensions directly. @section vulkan_support Querying for Vulkan support @@ -110,8 +112,9 @@ be passed to @ref glfwGetPhysicalDevicePresentationSupport and @ref glfwCreateWindowSurface. The set of extensions will vary depending on platform and may also vary depending on graphics drivers and other factors. -If it fails it will return `NULL` and Vulkan window surface creation will not be -possible. You may still use Vulkan for off-screen rendering and compute work. +If it fails it will return `NULL` and GLFW will not be able to create Vulkan +window surfaces. You can still use Vulkan for off-screen rendering and compute +work. The returned array will always contain `VK_KHR_surface`, so if you don't require any additional extensions you can pass this list directly to the @@ -134,7 +137,7 @@ array, as it is an error to specify an extension more than once in the @section vulkan_present Querying for Vulkan presentation support -Not every Vulkan queue family of every device can present images to surfaces. +Not every queue family of every Vulkan device can present images to surfaces. To check whether a specific queue family of a physical device supports image presentation without first having to create a window and surface, call @ref glfwGetPhysicalDevicePresentationSupport. @@ -146,15 +149,15 @@ if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_fa } @endcode -The `VK_KHR_surface` extension also provides the +The `VK_KHR_surface` extension additionally provides the `vkGetPhysicalDeviceSurfaceSupportKHR` function, which performs the same test on an existing Vulkan surface. @section vulkan_window Creating the window -Unless you will be using OpenGL or OpenGL ES in addition to Vulkan, there is no -need to create a context for that window. You can disable context creation by +Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan, +there is no need to create a context. You can disable context creation by setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`. @code