Documentation work

This commit is contained in:
Camilla Berglund 2016-02-17 09:10:48 +01:00
parent b955936ee1
commit 41b82903a8

View File

@ -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 <custom/path/vulkan.h>
#include <path/to/vulkan.h>
#include <GLFW/glfw3.h>
@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