mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-22 04:54:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove CRLF line endings

Browse Source
This commit is contained in:
Camilla Berglund 2016-02-17 22:03:12 +01:00
parent 2826f3d42f
commit 511183e76c
3 changed files with 330 additions and 330 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
.appveyor.yml
View File

@ -1,22 +1,22 @@
branches: branches:
only: only:
- ci - ci
- master - master
skip_tags: true skip_tags: true
environment: environment:
matrix: matrix:
- BUILD_SHARED_LIBS: ON - BUILD_SHARED_LIBS: ON
- BUILD_SHARED_LIBS: OFF - BUILD_SHARED_LIBS: OFF
matrix: matrix:
fast_finish: true fast_finish: true
build_script: build_script:
- mkdir build - mkdir build
- cd build - cd build
- cmake -DBUILD_SHARED_LIBS=%BUILD_SHARED_LIBS% .. - cmake -DBUILD_SHARED_LIBS=%BUILD_SHARED_LIBS% ..
- cmake --build . - cmake --build .
notifications: notifications:
- provider: Email - provider: Email
to: to:
- ci@glfw.org - ci@glfw.org
- on_build_failure: true - on_build_failure: true
- on_build_success: false - on_build_success: false

212
.github/CONTRIBUTING.md vendored
View File

@ -1,106 +1,106 @@
# Contribution Guide # Contribution Guide
This file is a work in progress and you can report errors or submit patches for This file is a work in progress and you can report errors or submit patches for
it the same as any other file. it the same as any other file.
## Reporting a bug ## Reporting a bug
If GLFW is behaving unexpectedly, make sure you have set an error callback. 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. 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 If GLFW is crashing or triggering asserts, make sure that all your object
handles and other pointers are valid. handles and other pointers are valid.
Always include the __operating system name and version__ (i.e. `Windows 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, 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 include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the
__GLFW commit ID__ (i.e. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. __GLFW commit ID__ (i.e. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
If possible, please also include the __GLFW version string__ (`3.2.0 X11 EGL If possible, please also include the __GLFW version string__ (`3.2.0 X11 EGL
clock_gettime /dev/js XI Xf86vm`), as described clock_gettime /dev/js XI Xf86vm`), as described
[here](http://www.glfw.org/docs/latest/intro.html#intro_version_string). [here](http://www.glfw.org/docs/latest/intro.html#intro_version_string).
### Reporting a compile or link bug ### Reporting a compile or link bug
__Note:__ GLFW needs many system APIs to do its job. See the [Building __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 applications](http://www.glfw.org/docs/latest/build.html) guide for more
information. information.
In addition to the information above, always include the complete build log from 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 your compiler and linker. Issue posts are editable so it can always be
shortened later. shortened later.
### Reporting a context creation bug ### Reporting a context creation bug
__Note:__ Windows ships with graphics drivers that do not support OpenGL. If __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. GLFW says that your machine lacks support for OpenGL, it very likely does.
Install drivers from the computer manufacturer or graphics card manufacturer Install drivers from the computer manufacturer or graphics card manufacturer
([Nvidia](http://www.geforce.com/drivers), ([Nvidia](http://www.geforce.com/drivers),
[AMD](http://support.amd.com/en-us/download), [AMD](http://support.amd.com/en-us/download),
[Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to [Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to
fix this. fix this.
__Note:__ AMD only supports OpenGL ES on Windows via EGL. EGL support is not __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 enabled in GLFW by default. You need to [enable EGL when
compiling](http://www.glfw.org/docs/latest/compile.html) GLFW to use this. 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` 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 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. 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 If context creation fails in your application, please verify that it also fails
with this tool before reporting it as a bug. with this tool before reporting it as a bug.
In addition to the information above (OS and GLFW version), always include the 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 __GPU model and driver version__ (i.e. `GeForce GTX660 with 352.79`) when
reporting this kind of bug. reporting this kind of bug.
### Reporting a monitor or video mode bug ### Reporting a monitor or video mode bug
__Note:__ On headless systems on some platforms, no monitors are reported. This __Note:__ On headless systems on some platforms, no monitors are reported. This
causes glfwGetPrimaryMonitor to return `NULL`, which not all applications are causes glfwGetPrimaryMonitor to return `NULL`, which not all applications are
prepared for. prepared for.
__Note:__ Some third-party tools report more video modes than those approved of __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 by the OS. For safety and compatbility, GLFW only reports video modes the OS
wants programs to use. This is not a bug. wants programs to use. This is not a bug.
The `monitors` tool is included in the GLFW source tree as `tests/monitors.c` 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 and is built along with the library. lists all information about connected
monitors made available by GLFW. monitors made available by GLFW.
In addition to the information above (OS and GLFW version), please also include 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 the output of the `monitors` tool when reporting this kind of bug. If it
doesn't work at all, please mention this. doesn't work at all, please mention this.
### Reporting a window event bug ### Reporting a window event bug
__Note:__ While GLFW tries to provide the exact same behavior between platforms, __Note:__ While GLFW tries to provide the exact same behavior between platforms,
the exact ordering of related window events will sometimes differ. 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 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 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 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 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. command-line options for creating multiple windows and full screen windows.
### Reporting a documentation bug ### Reporting a documentation bug
If you found the error in the generated documentation then it's fine to just 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 link to that webpage. You don't need to figure out which documentation source
file the text comes from. file the text comes from.
## Contributing a bug fix ## Contributing a bug fix
There should be text here, but there isn't. There should be text here, but there isn't.
## Contributing a feature ## Contributing a feature
This is not (yet) the text you are looking for. This is not (yet) the text you are looking for.

404
docs/vulkan.dox
View File

@ -1,202 +1,202 @@
/*! /*!
@page vulkan Vulkan guide @page vulkan Vulkan guide
@tableofcontents @tableofcontents
This guide is intended to fill the gaps between the [Vulkan This guide is intended to fill the gaps between the [Vulkan
documentation](https://www.khronos.org/vulkan/) and the rest of the GLFW documentation](https://www.khronos.org/vulkan/) and the rest of the GLFW
documentation and is not a replacement for either. It assumes some familiarity 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 with Vulkan concepts like loaders, devices, queues and surfaces and leaves it to
the Vulkan documentation to explain the details of Vulkan functions. the Vulkan documentation to explain the details of Vulkan functions.
To develop for Vulkan you should install an SDK for your platform, for example 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 the [LunarG Vulkan SDK](https://vulkan.lunarg.com/). Apart from the headers and
libraries, it also provides the validation layers necessary for development. libraries, it also provides the validation layers necessary for development.
The GLFW library does not need the Vulkan SDK to enable support for Vulkan. 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 However, any Vulkan-specific test and example programs are built only if the
CMake files find a Vulkan SDK. CMake files find a Vulkan SDK.
@section vulkan_include Including the Vulkan and GLFW header files @section vulkan_include Including the Vulkan and GLFW header files
To include the Vulkan header, define [GLFW_INCLUDE_VULKAN](@ref build_macros) To include the Vulkan header, define [GLFW_INCLUDE_VULKAN](@ref build_macros)
before including the GLFW header. before including the GLFW header.
@code @code
#define GLFW_INCLUDE_VULKAN #define GLFW_INCLUDE_VULKAN
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode @endcode
If you want to include the Vulkan header from a custom location or use your own 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. custom Vulkan header then you need to include them before the GLFW header.
@code @code
#include <path/to/vulkan.h> #include <path/to/vulkan.h>
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode @endcode
Unless a Vulkan header is included, either by the GLFW header or above it, any 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. 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 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. of GLFW to work. Define them only if you are using these extensions directly.
@section vulkan_support Querying for Vulkan support @section vulkan_support Querying for Vulkan support
If you are linking directly against the Vulkan loader then you can skip this 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 section. The canonical desktop loader library exports all Vulkan core and
Khronos extension functions, allowing them to be called directly. Khronos extension functions, allowing them to be called directly.
If you are loading the Vulkan loader dynamically instead of linking 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 with @ref
glfwVulkanSupported. glfwVulkanSupported.
@code @code
if (glfwVulkanSupported()) if (glfwVulkanSupported())
{ {
// Vulkan is available, at least for compute // Vulkan is available, at least for compute
} }
@endcode @endcode
This function returns `GLFW_TRUE` if the Vulkan loader was found. This check is This function returns `GLFW_TRUE` if the Vulkan loader was found. This check is
performed by @ref glfwInit. performed by @ref glfwInit.
If no loader was found, calling any other Vulkan related GLFW function will If no loader was found, calling any other Vulkan related GLFW function will
generate a @ref GLFW_API_UNAVAILABLE error. generate a @ref GLFW_API_UNAVAILABLE error.
@subsection vulkan_proc Querying Vulkan function pointers @subsection vulkan_proc Querying Vulkan function pointers
To load any Vulkan core or extension function from the found loader, call @ref To load any Vulkan core or extension function from the found loader, call @ref
glfwGetInstanceProcAddress. To load functions needed for instance creation, glfwGetInstanceProcAddress. To load functions needed for instance creation,
pass `NULL` as the instance. pass `NULL` as the instance.
@code @code
PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance) PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance)
glfwGetInstanceProcAddress(NULL, "vkCreateInstance"); glfwGetInstanceProcAddress(NULL, "vkCreateInstance");
@endcode @endcode
Once you have created an instance, you can load from it all other Vulkan core Once you have created an instance, you can load from it all other Vulkan core
functions and functions from any instance extensions you enabled. functions and functions from any instance extensions you enabled.
@code @code
PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice) PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice)
glfwGetInstanceProcAddress(instance, "vkCreateDevice"); glfwGetInstanceProcAddress(instance, "vkCreateDevice");
@endcode @endcode
This function in turn calls `vkGetInstanceProcAddr`. If that fails, the This function in turn calls `vkGetInstanceProcAddr`. If that fails, the
function falls back to a platform-specific query of the Vulkan loader (i.e. 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`. `dlsym` or `GetProcAddress`). If that also fails, the function returns `NULL`.
For more information about `vkGetInstanceProcAddr`, see the Vulkan For more information about `vkGetInstanceProcAddr`, see the Vulkan
documentation. documentation.
Vulkan also provides `vkGetDeviceProcAddr` for loading device-specific versions Vulkan also provides `vkGetDeviceProcAddr` for loading device-specific versions
of Vulkan function. This function can be retrieved from an instance with @ref of Vulkan function. This function can be retrieved from an instance with @ref
glfwGetInstanceProcAddress. glfwGetInstanceProcAddress.
@code @code
PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr) PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr)
glfwGetInstanceProcAddress(instance, "vkGetDeviceProcAddr"); glfwGetInstanceProcAddress(instance, "vkGetDeviceProcAddr");
@endcode @endcode
Device-specific functions may execute a little bit faster, due to not having to 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 dispatch internally based on the device passed to them. For more information
about `vkGetDeviceProcAddr`, see the Vulkan documentation. about `vkGetDeviceProcAddr`, see the Vulkan documentation.
@section vulkan_ext Querying required Vulkan extensions @section vulkan_ext Querying required Vulkan extensions
To do anything useful with Vulkan you need to create an instance. If you want 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 to use Vulkan to render to a window, you must enable the instance extensions
GLFW requires to create Vulkan surfaces. GLFW requires to create Vulkan surfaces.
To query the instance extensions required, call @ref To query the instance extensions required, call @ref
glfwGetRequiredInstanceExtensions. glfwGetRequiredInstanceExtensions.
@code @code
int count; int count;
const char** extensions = glfwGetRequiredInstanceExtensions(&count); const char** extensions = glfwGetRequiredInstanceExtensions(&count);
@endcode @endcode
These extensions must all be enabled when creating instances that are going to These extensions must all be enabled when creating instances that are going to
be passed to @ref glfwGetPhysicalDevicePresentationSupport and @ref be passed to @ref glfwGetPhysicalDevicePresentationSupport and @ref
glfwCreateWindowSurface. The set of extensions will vary depending on platform glfwCreateWindowSurface. The set of extensions will vary depending on platform
and may also vary depending on graphics drivers and other factors. 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 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 window surfaces. You can still use Vulkan for off-screen rendering and compute
work. work.
The returned array will always contain `VK_KHR_surface`, so if you don't 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 require any additional extensions you can pass this list directly to the
`VkInstanceCreateInfo` struct. `VkInstanceCreateInfo` struct.
@code @code
VkInstanceCreateInfo ici; VkInstanceCreateInfo ici;
memset(&ici, 0, sizeof(ici)); memset(&ici, 0, sizeof(ici));
ici.enabledExtensionCount = count; ici.enabledExtensionCount = count;
ici.ppEnabledExtensionNames = extensions; ici.ppEnabledExtensionNames = extensions;
... ...
@endcode @endcode
Additional extensions may be required by future versions of GLFW. You should 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 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 array, as it is an error to specify an extension more than once in the
`VkInstanceCreateInfo` struct. `VkInstanceCreateInfo` struct.
@section vulkan_present Querying for Vulkan presentation support @section vulkan_present Querying for Vulkan presentation support
Not every queue family of every Vulkan 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 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 presentation without first having to create a window and surface, call @ref
glfwGetPhysicalDevicePresentationSupport. glfwGetPhysicalDevicePresentationSupport.
@code @code
if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index)) if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index))
{ {
// Queue family supports image presentation // Queue family supports image presentation
} }
@endcode @endcode
The `VK_KHR_surface` extension additionally provides the The `VK_KHR_surface` extension additionally provides the
`vkGetPhysicalDeviceSurfaceSupportKHR` function, which performs the same test on `vkGetPhysicalDeviceSurfaceSupportKHR` function, which performs the same test on
an existing Vulkan surface. an existing Vulkan surface.
@section vulkan_window Creating the window @section vulkan_window Creating the window
Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan, 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 there is no need to create a context. You can disable context creation with the
[GLFW_CLIENT_API](@ref window_hints_ctx) hint. [GLFW_CLIENT_API](@ref window_hints_ctx) hint.
@code @code
glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API); glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
GLFWwindow* window = glfwCreateWindow(640, 480, "Window Title", NULL, NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "Window Title", NULL, NULL);
@endcode @endcode
See @ref context_less for more information. See @ref context_less for more information.
@section vulkan_surface Creating a Vulkan window surface @section vulkan_surface Creating a Vulkan window surface
You can create a Vulkan surface (as defined by the `VK_KHR_surface` extension) You can create a Vulkan surface (as defined by the `VK_KHR_surface` extension)
for a GLFW window with @ref glfwCreateWindowSurface. for a GLFW window with @ref glfwCreateWindowSurface.
@code @code
VkSurfaceKHR surface; VkSurfaceKHR surface;
VkResult err = glfwCreateWindowSurface(instance, window, NULL, &surface); VkResult err = glfwCreateWindowSurface(instance, window, NULL, &surface);
if (err) if (err)
{ {
// Window surface creation failed // Window surface creation failed
} }
@endcode @endcode
It is your responsibility to destroy the surface. GLFW does not destroy it for 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. you. Call `vkDestroySurfaceKHR` function from the same extension to destroy it.
*/ */