mirror of
https://github.com/glfw/glfw.git
synced 2026-09-22 08:50:15 +00:00
Add basic Vulkan support
Added GLFW_INCLUDE_VULKAN. Added glfwVulkanSupported, glfwGetRequiredInstanceExtensions, glfwGetInstanceProcAddress, glfwGetPhysicalDevicePresentationSupport and glfwCreateWindowSurface. Added port of LunarG SDK tri example.
This commit is contained in:
Camilla Berglund
+3
-1
@@ -674,6 +674,7 @@ INPUT = @GLFW_INTERNAL_DOCS@ \
|
||||
@GLFW_SOURCE_DIR@/docs/monitor.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/window.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/input.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/vulkan.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/rift.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/compat.dox
|
||||
|
||||
@@ -1590,7 +1591,8 @@ PREDEFINED = GLFWAPI= \
|
||||
GLFW_EXPOSE_NATIVE_GLX \
|
||||
GLFW_EXPOSE_NATIVE_COCOA \
|
||||
GLFW_EXPOSE_NATIVE_NSGL \
|
||||
GLFW_EXPOSE_NATIVE_EGL
|
||||
GLFW_EXPOSE_NATIVE_EGL \
|
||||
VK_VERSION_1_0
|
||||
|
||||
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
|
||||
# this tag can be used to specify a list of macro names that should be expanded.
|
||||
|
||||
@@ -80,6 +80,9 @@ header instead of the regular OpenGL header.
|
||||
`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
|
||||
header instead of the regular OpenGL header.
|
||||
|
||||
`GLFW_INCLUDE_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.h`
|
||||
header instead of the regular OpenGL header.
|
||||
|
||||
`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API
|
||||
header. This is useful in combination with an extension loading library.
|
||||
|
||||
|
||||
@@ -186,4 +186,43 @@ setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
|
||||
a non-default value will cause @ref glfwCreateWindow to fail and the
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
|
||||
|
||||
|
||||
@section compat_vulkan Vulkan loader and API
|
||||
|
||||
GLFW uses the standard system-wside Vulkan loader to access the Vulkan API.
|
||||
This should be installed by graphics drivers and Vulkan SDKs. If this is not
|
||||
available, @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
|
||||
|
||||
The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on
|
||||
all supported platforms.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and `VK_KHR_win32_surface` extensions to create
|
||||
surfaces on Microsoft Windows. If any of these extensions are not available,
|
||||
@ref glfwGetRequiredInstanceExtensions will return an empty list and window
|
||||
surface creation will fail.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and either the `VK_KHR_xlib_surface` or
|
||||
`VK_KHR_xcb_surface` extensions to create surfaces on X11. If `VK_KHR_surface`
|
||||
or both `VK_KHR_xlib_surface` and `VK_KHR_xcb_surface` are not available, @ref
|
||||
glfwGetRequiredInstanceExtensions will return an empty list and window surface
|
||||
creation will fail.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and `VK_KHR_wayland_surface` extensions to create
|
||||
surfaces on Wayland. If any of these extensions are not available, @ref
|
||||
glfwGetRequiredInstanceExtensions will return an empty list and window surface
|
||||
creation will fail.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and `VK_KHR_mir_surface` extensions to create
|
||||
surfaces on Mir. If any of these extensions are not available, @ref
|
||||
glfwGetRequiredInstanceExtensions will return an empty list and window surface
|
||||
creation will fail.
|
||||
|
||||
GLFW does not support any extensions for window surface creation on OS X,
|
||||
meaning@ref glfwGetRequiredInstanceExtensions will return an empty list and
|
||||
window surface creation will fail.
|
||||
|
||||
*/
|
||||
|
||||
@@ -26,6 +26,11 @@ as the context handle.
|
||||
To test the creation of various kinds of contexts and see their properties, run
|
||||
the `glfwinfo` test program.
|
||||
|
||||
@note Vulkan does not have a context and the Vulkan instance is created via the
|
||||
Vulkan API itself. If you will be using Vulkan to render to a window, disable
|
||||
context creation by setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to
|
||||
`GLFW_NO_API`. For more information, see the @ref vulkan.
|
||||
|
||||
|
||||
@subsection context_hints Context creation hints
|
||||
|
||||
|
||||
+5
-3
@@ -4,9 +4,9 @@
|
||||
|
||||
@section main_intro Introduction
|
||||
|
||||
__GLFW__ is a free, Open Source, multi-platform library for creating windows
|
||||
with OpenGL or OpenGL ES contexts and receiving many kinds of input. It is easy
|
||||
to integrate into existing applications and does not lay claim to the main loop.
|
||||
GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
|
||||
Vulkan application development. It provides a simple, platform-independent API
|
||||
for creating windows, contexts and surfaces, reading input, handling events, etc.
|
||||
|
||||
See @ref news_32 for release highlights or the
|
||||
[version history](http://www.glfw.org/changelog.html) for details.
|
||||
@@ -32,6 +32,8 @@ about specific functions.
|
||||
There is a section on @ref guarantees_limitations for pointer lifetimes,
|
||||
reentrancy, thread safety, event order and backward and forward compatibility.
|
||||
|
||||
The @ref vulkan guide fills in the gaps for how to use Vulkan with GLFW.
|
||||
|
||||
The @ref rift fills in the gaps for how to use LibOVR with GLFW.
|
||||
|
||||
The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
|
||||
|
||||
@@ -17,6 +17,15 @@ GLFW now supports querying the localized name of printable keys with @ref
|
||||
glfwGetKeyName, either by key token or by scancode.
|
||||
|
||||
|
||||
@subsection news_32_vulkan Support for Vulkan
|
||||
|
||||
GLFW now supports basic integration with Vulkan with @ref glfwVulkanSupported,
|
||||
@ref glfwGetRequiredInstanceExtensions, @ref glfwGetInstanceProcAddress, @ref
|
||||
glfwGetPhysicalDevicePresentationSupport and @ref glfwCreateWindowSurface.
|
||||
Vulkan header inclusion can be selected with
|
||||
[GLFW_INCLUDE_VULKAN](@ref build_macros).
|
||||
|
||||
|
||||
@section news_31 New features in 3.1
|
||||
|
||||
These are the release highlights. For a full list of changes see the
|
||||
|
||||
+185
@@ -0,0 +1,185 @@
|
||||
/*!
|
||||
|
||||
@page vulkan Vulkan guide
|
||||
|
||||
@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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@section vulkan_include Including the Vulkan and GLFW header files
|
||||
|
||||
To include the Vulkan header, define `GLFW_INCLUDE_VULKAN` before including the
|
||||
GLFW header.
|
||||
|
||||
@code
|
||||
#define GLFW_INCLUDE_VULKAN
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
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 <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.
|
||||
|
||||
The `VK_USE_PLATFORM_*_KHR` macros do not need to be defined for the Vulkan part
|
||||
of GLFW to work.
|
||||
|
||||
|
||||
@section vulkan_support Querying for Vulkan support
|
||||
|
||||
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
|
||||
glfwVulkanSupported.
|
||||
|
||||
@code
|
||||
if (glfwVulkanSupported())
|
||||
{
|
||||
// Vulkan is available, at least for compute
|
||||
}
|
||||
@endcode
|
||||
|
||||
This function returns `GLFW_TRUE` if the Vulkan loader was found. This check is
|
||||
performed by @ref glfwInit.
|
||||
|
||||
If no loader was found, calling any other Vulkan related GLFW function will
|
||||
generate a @ref GLFW_API_UNAVAILABLE error.
|
||||
|
||||
|
||||
@subsection vulkan_proc Querying Vulkan function pointers
|
||||
|
||||
To load any Vulkan core or extension function from the found loader, call @ref
|
||||
glfwGetInstanceProcAddress.
|
||||
|
||||
@code
|
||||
PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice)
|
||||
glfwGetInstanceProcAddress(instance, "vkCreateDevice");
|
||||
@endcode
|
||||
|
||||
This is equivalent to calling `vkGetInstanceProcAddr`. If that fails, the
|
||||
function falls back to a platform-specific query of the Vulkan loader (i.e.
|
||||
`dlsym` or `GetProcAddress`). If that also fails, the function returns `NULL`.
|
||||
For more information about `vkGetInstanceProcAddr`, see the Vulkan
|
||||
documentation.
|
||||
|
||||
Vulkan also provides `vkGetDeviceProcAddr` for loading device-specific versions
|
||||
of Vulkan function. This function can be retrieved from an instance with @ref
|
||||
glfwGetInstanceProcAddress.
|
||||
|
||||
@code
|
||||
PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr)
|
||||
glfwGetInstanceProcAddress(instance, "vkGetDeviceProcAddr");
|
||||
@endcode
|
||||
|
||||
Device-specific functions may execute a little bit faster, due to not having to
|
||||
dispatch internally based on the device passed to them. For more information
|
||||
about `vkGetDeviceProcAddr`, see the Vulkan documentation.
|
||||
|
||||
|
||||
@section vulkan_ext Querying required Vulkan extensions
|
||||
|
||||
To do anything useful with Vulkan you need to create an instance. If you want
|
||||
to use Vulkan to render to a window, you must enable the instance extensions
|
||||
GLFW requires to create Vulkan surfaces.
|
||||
|
||||
To query the instance extensions required, call @ref
|
||||
glfwGetRequiredInstanceExtensions.
|
||||
|
||||
@code
|
||||
int count;
|
||||
const char** extensions = glfwGetRequiredInstanceExtensions(&count);
|
||||
@endcode
|
||||
|
||||
These extensions must all be enabled when creating instances that are going to
|
||||
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.
|
||||
|
||||
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
|
||||
`VkInstanceCreateInfo` struct.
|
||||
|
||||
@code
|
||||
VkInstanceCreateInfo ici;
|
||||
|
||||
memset(&ici, 0, sizeof(ici));
|
||||
ici.enabledExtensionCount = count;
|
||||
ici.ppEnabledExtensionNames = extensions;
|
||||
...
|
||||
@endcode
|
||||
|
||||
Additional extensions may be required by future versions of GLFW. You should
|
||||
check whether 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.
|
||||
|
||||
|
||||
@section vulkan_present Querying for Vulkan presentation support
|
||||
|
||||
Not every Vulkan queue family of every 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.
|
||||
|
||||
@code
|
||||
if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index))
|
||||
{
|
||||
// Queue family supports image presentation
|
||||
}
|
||||
@endcode
|
||||
|
||||
The `VK_KHR_surface` extension also 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
|
||||
setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`.
|
||||
|
||||
@code
|
||||
glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "Window Title", NULL, NULL);
|
||||
@endcode
|
||||
|
||||
See @ref context_less for more information.
|
||||
|
||||
|
||||
@section vulkan_surface Creating a Vulkan window surface
|
||||
|
||||
You can create a Vulkan surface (as defined by the `VK_KHR_surface` extension)
|
||||
for a GLFW window with @ref glfwCreateWindowSurface.
|
||||
|
||||
@code
|
||||
VkSurfaceKHR surface;
|
||||
VkResult err = glfwCreateWindowSurface(instance, window, NULL, &surface);
|
||||
if (err)
|
||||
{
|
||||
// Window surface creation failed
|
||||
}
|
||||
@endcode
|
||||
|
||||
It is your responsibility to destroy the surface. GLFW does not destroy it for
|
||||
you. Call `vkDestroySurfaceKHR` function from the same extension to destroy it.
|
||||
|
||||
*/
|
||||
Reference in New Issue
Block a user