anulax
/
glfw
1
0
Fork 0
Code Issues Pull Requests Packages project_board Releases Wiki Activity

Remove CRLF line endings

Browse Source
master
Camilla Berglund ago%!(EXTRA string=9 years)
parent 2826f3d42f
commit 511183e76c
3 changed files with 330 additions and 330 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 44
      .appveyor.yml
  2. 212
      .github/CONTRIBUTING.md
  3. 404
      docs/vulkan.dox

44
.appveyor.yml
Unescape View File

@ -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

212
.github/CONTRIBUTING.md
Unescape View File

@ -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.

404
docs/vulkan.dox
Unescape View File

@ -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 <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 <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 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 <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 <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 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.
*/

Write Preview
Loading…
Cancel
Save