diff --git a/.appveyor.yml b/.appveyor.yml index 74a2f0aa..ae658cc3 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -1,22 +1,22 @@ -branches: - only: - - ci - - master -skip_tags: true -environment: - matrix: - - BUILD_SHARED_LIBS: ON - - BUILD_SHARED_LIBS: OFF -matrix: - fast_finish: true -build_script: - - mkdir build - - cd build - - cmake -DBUILD_SHARED_LIBS=%BUILD_SHARED_LIBS% .. - - cmake --build . -notifications: - - provider: Email - to: - - ci@glfw.org - - on_build_failure: true - - on_build_success: false +branches: + only: + - ci + - master +skip_tags: true +environment: + matrix: + - BUILD_SHARED_LIBS: ON + - BUILD_SHARED_LIBS: OFF +matrix: + fast_finish: true +build_script: + - mkdir build + - cd build + - cmake -DBUILD_SHARED_LIBS=%BUILD_SHARED_LIBS% .. + - cmake --build . +notifications: + - provider: Email + to: + - ci@glfw.org + - on_build_failure: true + - on_build_success: false diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fbe09669..53c3a6c3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,106 +1,106 @@ -# Contribution Guide - -This file is a work in progress and you can report errors or submit patches for -it the same as any other file. - - -## Reporting a bug - -If GLFW is behaving unexpectedly, make sure you have set an error callback. -GLFW will often tell you the cause of an issue via this callback. - -If GLFW is crashing or triggering asserts, make sure that all your object -handles and other pointers are valid. - -Always include the __operating system name and version__ (i.e. `Windows -7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, -include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the -__GLFW commit ID__ (i.e. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. -If possible, please also include the __GLFW version string__ (`3.2.0 X11 EGL -clock_gettime /dev/js XI Xf86vm`), as described -[here](http://www.glfw.org/docs/latest/intro.html#intro_version_string). - - -### Reporting a compile or link bug - -__Note:__ GLFW needs many system APIs to do its job. See the [Building -applications](http://www.glfw.org/docs/latest/build.html) guide for more -information. - -In addition to the information above, always include the complete build log from -your compiler and linker. Issue posts are editable so it can always be -shortened later. - - -### Reporting a context creation bug - -__Note:__ Windows ships with graphics drivers that do not support OpenGL. If -GLFW says that your machine lacks support for OpenGL, it very likely does. -Install drivers from the computer manufacturer or graphics card manufacturer -([Nvidia](http://www.geforce.com/drivers), - [AMD](http://support.amd.com/en-us/download), - [Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to -fix this. - -__Note:__ AMD only supports OpenGL ES on Windows via EGL. EGL support is not -enabled in GLFW by default. You need to [enable EGL when -compiling](http://www.glfw.org/docs/latest/compile.html) GLFW to use this. - -The `glfwinfo` tool is included in the GLFW source tree as `tests/glfwinfo.c` -and is built along with the library. It lets you request any kind of context -and framebuffer format supported by the GLFW API without having to recompile. -If context creation fails in your application, please verify that it also fails -with this tool before reporting it as a bug. - -In addition to the information above (OS and GLFW version), always include the -__GPU model and driver version__ (i.e. `GeForce GTX660 with 352.79`) when -reporting this kind of bug. - - -### Reporting a monitor or video mode bug - -__Note:__ On headless systems on some platforms, no monitors are reported. This -causes glfwGetPrimaryMonitor to return `NULL`, which not all applications are -prepared for. - -__Note:__ Some third-party tools report more video modes than those approved of -by the OS. For safety and compatbility, GLFW only reports video modes the OS -wants programs to use. This is not a bug. - -The `monitors` tool is included in the GLFW source tree as `tests/monitors.c` -and is built along with the library. lists all information about connected -monitors made available by GLFW. - -In addition to the information above (OS and GLFW version), please also include -the output of the `monitors` tool when reporting this kind of bug. If it -doesn't work at all, please mention this. - - -### Reporting a window event bug - -__Note:__ While GLFW tries to provide the exact same behavior between platforms, -the exact ordering of related window events will sometimes differ. - -The `events` tool is included in the GLFW source tree as `tests/events.c` and is -built along with the library. It prints all information provided to every -callback supported by GLFW as events occur. Each event is listed with the time -and a unique number to make discussions about event logs easier. The tool has -command-line options for creating multiple windows and full screen windows. - - -### Reporting a documentation bug - -If you found the error in the generated documentation then it's fine to just -link to that webpage. You don't need to figure out which documentation source -file the text comes from. - - -## Contributing a bug fix - -There should be text here, but there isn't. - - -## Contributing a feature - -This is not (yet) the text you are looking for. - +# Contribution Guide + +This file is a work in progress and you can report errors or submit patches for +it the same as any other file. + + +## Reporting a bug + +If GLFW is behaving unexpectedly, make sure you have set an error callback. +GLFW will often tell you the cause of an issue via this callback. + +If GLFW is crashing or triggering asserts, make sure that all your object +handles and other pointers are valid. + +Always include the __operating system name and version__ (i.e. `Windows +7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, +include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the +__GLFW commit ID__ (i.e. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. +If possible, please also include the __GLFW version string__ (`3.2.0 X11 EGL +clock_gettime /dev/js XI Xf86vm`), as described +[here](http://www.glfw.org/docs/latest/intro.html#intro_version_string). + + +### Reporting a compile or link bug + +__Note:__ GLFW needs many system APIs to do its job. See the [Building +applications](http://www.glfw.org/docs/latest/build.html) guide for more +information. + +In addition to the information above, always include the complete build log from +your compiler and linker. Issue posts are editable so it can always be +shortened later. + + +### Reporting a context creation bug + +__Note:__ Windows ships with graphics drivers that do not support OpenGL. If +GLFW says that your machine lacks support for OpenGL, it very likely does. +Install drivers from the computer manufacturer or graphics card manufacturer +([Nvidia](http://www.geforce.com/drivers), + [AMD](http://support.amd.com/en-us/download), + [Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to +fix this. + +__Note:__ AMD only supports OpenGL ES on Windows via EGL. EGL support is not +enabled in GLFW by default. You need to [enable EGL when +compiling](http://www.glfw.org/docs/latest/compile.html) GLFW to use this. + +The `glfwinfo` tool is included in the GLFW source tree as `tests/glfwinfo.c` +and is built along with the library. It lets you request any kind of context +and framebuffer format supported by the GLFW API without having to recompile. +If context creation fails in your application, please verify that it also fails +with this tool before reporting it as a bug. + +In addition to the information above (OS and GLFW version), always include the +__GPU model and driver version__ (i.e. `GeForce GTX660 with 352.79`) when +reporting this kind of bug. + + +### Reporting a monitor or video mode bug + +__Note:__ On headless systems on some platforms, no monitors are reported. This +causes glfwGetPrimaryMonitor to return `NULL`, which not all applications are +prepared for. + +__Note:__ Some third-party tools report more video modes than those approved of +by the OS. For safety and compatbility, GLFW only reports video modes the OS +wants programs to use. This is not a bug. + +The `monitors` tool is included in the GLFW source tree as `tests/monitors.c` +and is built along with the library. lists all information about connected +monitors made available by GLFW. + +In addition to the information above (OS and GLFW version), please also include +the output of the `monitors` tool when reporting this kind of bug. If it +doesn't work at all, please mention this. + + +### Reporting a window event bug + +__Note:__ While GLFW tries to provide the exact same behavior between platforms, +the exact ordering of related window events will sometimes differ. + +The `events` tool is included in the GLFW source tree as `tests/events.c` and is +built along with the library. It prints all information provided to every +callback supported by GLFW as events occur. Each event is listed with the time +and a unique number to make discussions about event logs easier. The tool has +command-line options for creating multiple windows and full screen windows. + + +### Reporting a documentation bug + +If you found the error in the generated documentation then it's fine to just +link to that webpage. You don't need to figure out which documentation source +file the text comes from. + + +## Contributing a bug fix + +There should be text here, but there isn't. + + +## Contributing a feature + +This is not (yet) the text you are looking for. + diff --git a/docs/vulkan.dox b/docs/vulkan.dox index 098507e5..af9ffce0 100644 --- a/docs/vulkan.dox +++ b/docs/vulkan.dox @@ -1,202 +1,202 @@ -/*! - -@page vulkan Vulkan guide - -@tableofcontents - -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 and leaves it to -the Vulkan documentation to explain the details of Vulkan functions. - -To develop for Vulkan you should install an SDK for your platform, for example -the [LunarG Vulkan SDK](https://vulkan.lunarg.com/). Apart from the headers and -libraries, it also provides the validation layers necessary for development. - -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](@ref build_macros) -before including the GLFW header. - -@code -#define GLFW_INCLUDE_VULKAN -#include -@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 -#include -@endcode - -Unless a Vulkan header is included, either by the GLFW header or above it, any -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. Define them only if you are using these extensions directly. - - -@section vulkan_support Querying for Vulkan support - -If you are linking directly against the Vulkan loader then you can skip this -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 -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. To load functions needed for instance creation, -pass `NULL` as the instance. - -@code -PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance) - glfwGetInstanceProcAddress(NULL, "vkCreateInstance"); -@endcode - -Once you have created an instance, you can load from it all other Vulkan core -functions and functions from any instance extensions you enabled. - -@code -PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice) - glfwGetInstanceProcAddress(instance, "vkCreateDevice"); -@endcode - -This function in turn calls `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 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 -`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 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. - -@code -if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index)) -{ - // Queue family supports image presentation -} -@endcode - -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 with the same window as Vulkan, -there is no need to create a context. You can disable context creation with the -[GLFW_CLIENT_API](@ref window_hints_ctx) hint. - -@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. - -*/ +/*! + +@page vulkan Vulkan guide + +@tableofcontents + +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 and leaves it to +the Vulkan documentation to explain the details of Vulkan functions. + +To develop for Vulkan you should install an SDK for your platform, for example +the [LunarG Vulkan SDK](https://vulkan.lunarg.com/). Apart from the headers and +libraries, it also provides the validation layers necessary for development. + +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](@ref build_macros) +before including the GLFW header. + +@code +#define GLFW_INCLUDE_VULKAN +#include +@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 +#include +@endcode + +Unless a Vulkan header is included, either by the GLFW header or above it, any +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. Define them only if you are using these extensions directly. + + +@section vulkan_support Querying for Vulkan support + +If you are linking directly against the Vulkan loader then you can skip this +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 +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. To load functions needed for instance creation, +pass `NULL` as the instance. + +@code +PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance) + glfwGetInstanceProcAddress(NULL, "vkCreateInstance"); +@endcode + +Once you have created an instance, you can load from it all other Vulkan core +functions and functions from any instance extensions you enabled. + +@code +PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice) + glfwGetInstanceProcAddress(instance, "vkCreateDevice"); +@endcode + +This function in turn calls `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 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 +`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 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. + +@code +if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index)) +{ + // Queue family supports image presentation +} +@endcode + +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 with the same window as Vulkan, +there is no need to create a context. You can disable context creation with the +[GLFW_CLIENT_API](@ref window_hints_ctx) hint. + +@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. + +*/