medfall

A super great game engine
Log | Files | Refs

README.md (15386B)


      1 # GLFW
      2 
      3 [![Build status](https://travis-ci.org/glfw/glfw.svg?branch=master)](https://travis-ci.org/glfw/glfw)
      4 [![Build status](https://ci.appveyor.com/api/projects/status/0kf0ct9831i5l6sp/branch/master?svg=true)](https://ci.appveyor.com/project/elmindreda/glfw)
      5 [![Coverity Scan](https://scan.coverity.com/projects/4884/badge.svg)](https://scan.coverity.com/projects/glfw-glfw)
      6 
      7 ## Introduction
      8 
      9 GLFW is an Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan
     10 application development.  It provides a simple, platform-independent API for
     11 creating windows, contexts and surfaces, reading input, handling events, etc.
     12 
     13 GLFW natively supports Windows, macOS and Linux and other Unix-like systems.
     14 Experimental implementations for the Wayland protocol and the Mir display server
     15 are available but not yet officially supported.                             
     16 
     17 GLFW is licensed under the [zlib/libpng
     18 license](http://www.glfw.org/license.html).
     19 
     20 The latest stable release is version 3.2.1.
     21 
     22 See the [downloads](http://www.glfw.org/download.html) page for details and
     23 files, or fetch the `latest` branch, which always points to the latest stable
     24 release.  Each release starting with 3.0 also has a corresponding [annotated
     25 tag](https://github.com/glfw/glfw/releases) with source and binary archives.
     26 The [version history](http://www.glfw.org/changelog.html) lists all user-visible
     27 changes for every release.
     28 
     29 This is a development branch for version 3.3, which is _not yet described_.
     30 Pre-release documentation is available [here](http://www.glfw.org/docs/3.3/).
     31 
     32 The `master` branch is the stable integration branch and _should_ always compile
     33 and run on all supported platforms, although details of newly added features may
     34 change until they have been included in a release.  New features and many bug
     35 fixes live in [other branches](https://github.com/glfw/glfw/branches/all) until
     36 they are stable enough to merge.
     37 
     38 If you are new to GLFW, you may find the
     39 [tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW 3 useful.  If
     40 you have used GLFW 2 in the past, there is a [transition
     41 guide](http://www.glfw.org/docs/latest/moving.html) for moving to the GLFW
     42 3 API.
     43 
     44 
     45 ## Compiling GLFW
     46 
     47 GLFW itself requires only the headers and libraries for your window system.  It
     48 does not need the headers for any context creation API (WGL, GLX, EGL, NSGL) or
     49 rendering API (OpenGL, OpenGL ES, Vulkan) to enable support for them.
     50 
     51 GLFW supports compilation on Windows with Visual C++ 2010 and later, MinGW and
     52 MinGW-w64, on macOS with Clang and on Linux and other Unix-like systems with GCC
     53 and Clang.  It will likely compile in other environments as well, but this is
     54 not regularly tested.
     55 
     56 There are [pre-compiled Windows binaries](http://www.glfw.org/download.html)
     57 available for all supported compilers.
     58 
     59 See the [compilation guide](http://www.glfw.org/docs/latest/compile.html) for
     60 more information about how to compile GLFW yourself.
     61 
     62 
     63 ## Using GLFW
     64 
     65 See the [documentation](http://www.glfw.org/docs/latest/) for tutorials, guides
     66 and the API reference.
     67 
     68 
     69 ## Contributing to GLFW
     70 
     71 See the [contribution
     72 guide](https://github.com/glfw/glfw/blob/master/.github/CONTRIBUTING.md) for
     73 more information.
     74 
     75 
     76 ## System requirements
     77 
     78 GLFW supports Windows XP and later and macOS 10.7 and later.  Linux and other
     79 Unix-like systems running the X Window System are supported even without
     80 a desktop environment or modern extensions, although some features require
     81 a running window or clipboard manager.  The OSMesa backend requires Mesa 6.3.
     82 
     83 See the [compatibility guide](http://www.glfw.org/docs/latest/compat.html)
     84 in the documentation for more information.
     85 
     86 
     87 ## Dependencies
     88 
     89 GLFW itself depends only on the headers and libraries for your window system.
     90 
     91 The (experimental) Wayland backend also depends on the `extra-cmake-modules`
     92 package, which is used to generated Wayland protocol headers.
     93 
     94 The examples and test programs depend on a number of tiny libraries.  These are
     95 located in the `deps/` directory.
     96 
     97  - [getopt\_port](https://github.com/kimgr/getopt_port/) for examples
     98    with command-line options
     99  - [TinyCThread](https://github.com/tinycthread/tinycthread) for threaded
    100    examples
    101  - An OpenGL 3.2 core loader generated by
    102    [glad](https://github.com/Dav1dde/glad) for examples using modern OpenGL
    103  - [linmath.h](https://github.com/datenwolf/linmath.h) for linear algebra in
    104    examples
    105  - [Nuklear](https://github.com/vurtun/nuklear) for test and example UI
    106  - [stb\_image\_write](https://github.com/nothings/stb) for writing images to disk
    107  - [Vulkan headers](https://www.khronos.org/registry/vulkan/) for Vulkan tests
    108 
    109 The Vulkan example additionally requires the Vulkan SDK to be installed, or it
    110 will not be included in the build.  On macOS you need to provide the path to the
    111 MoltenVK SDK manually as it has no standard installation location.
    112 
    113 The documentation is generated with [Doxygen](http://doxygen.org/) if CMake can
    114 find that tool.
    115 
    116 
    117 ## Reporting bugs
    118 
    119 Bugs are reported to our [issue tracker](https://github.com/glfw/glfw/issues).
    120 Please check the [contribution
    121 guide](https://github.com/glfw/glfw/blob/master/.github/CONTRIBUTING.md) for
    122 information on what to include when reporting a bug.
    123 
    124 
    125 ## Changelog
    126 
    127 - Added `glfwGetError` function for querying the last error code and its
    128   description (#970)
    129 - Added `glfwUpdateGamepadMappings` function for importing gamepad mappings in
    130   SDL\_GameControllerDB format (#900)
    131 - Added `glfwJoystickIsGamepad` function for querying whether a joystick has
    132   a gamepad mapping (#900)
    133 - Added `glfwGetJoystickGUID` function for querying the SDL compatible GUID of
    134   a joystick (#900)
    135 - Added `glfwGetGamepadName` function for querying the name provided by the
    136   gamepad mapping (#900)
    137 - Added `glfwGetGamepadState` function, `GLFW_GAMEPAD_*` and `GLFWgamepadstate`
    138   for retrieving gamepad input state (#900)
    139 - Added `glfwRequestWindowAttention` function for requesting attention from the
    140   user (#732,#988)
    141 - Added `glfwGetKeyScancode` function that allows retrieving platform dependent
    142   scancodes for keys (#830)
    143 - Added `glfwSetWindowMaximizeCallback` and `GLFWwindowmaximizefun` for
    144   receiving window maximization events (#778)
    145 - Added `glfwSetWindowAttrib` function for changing window attributes (#537)
    146 - Added `glfwGetJoystickHats` function for querying joystick hats
    147   (#889,#906,#934)
    148 - Added `glfwInitHint` and `glfwInitHintString` for setting initialization hints
    149 - Added `glfwGetX11SelectionString` and `glfwSetX11SelectionString`
    150   functions for accessing X11 primary selection (#894,#1056)
    151 - Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#850)
    152 - Added definition of `GLAPIENTRY` to public header
    153 - Added `GLFW_CENTER_CURSOR` window hint for controlling cursor centering
    154   (#749,#842)
    155 - Added `GLFW_JOYSTICK_HAT_BUTTONS` init hint (#889)
    156 - Added macOS specific `GLFW_COCOA_RETINA_FRAMEBUFFER` window hint
    157 - Added macOS specific `GLFW_COCOA_FRAME_AUTOSAVE` window hint (#195)
    158 - Added macOS specific `GLFW_COCOA_GRAPHICS_SWITCHING` window hint (#377,#935)
    159 - Added macOS specific `GLFW_COCOA_CHDIR_RESOURCES` init hint
    160 - Added macOS specific `GLFW_COCOA_MENUBAR` init hint
    161 - Added X11 specific `GLFW_X11_WM_CLASS_NAME` and `GLFW_X11_WM_CLASS_CLASS` init
    162   hints (#893)
    163 - Added `GLFW_INCLUDE_ES32` for including the OpenGL ES 3.2 header
    164 - Added `GLFW_OSMESA_CONTEXT_API` for creating OpenGL contexts with
    165   [OSMesa](https://www.mesa3d.org/osmesa.html) (#281)
    166 - Removed `GLFW_USE_RETINA` compile-time option
    167 - Removed `GLFW_USE_CHDIR` compile-time option
    168 - Removed `GLFW_USE_MENUBAR` compile-time option
    169 - Bugfix: Calling `glfwMaximizeWindow` on a full screen window was not ignored
    170 - Bugfix: `GLFW_INCLUDE_VULKAN` could not be combined with the corresponding
    171           OpenGL and OpenGL ES header macros
    172 - Bugfix: `glfwGetInstanceProcAddress` returned `NULL` for
    173           `vkGetInstanceProcAddr` when `_GLFW_VULKAN_STATIC` was enabled
    174 - Bugfix: Invalid library paths were used in test and example CMake files (#930)
    175 - Bugfix: The scancode for synthetic key release events was always zero
    176 - [Win32] Added system error strings to relevant GLFW error descriptions (#733)
    177 - [Win32] Moved to `WM_INPUT` for disabled cursor mode motion input (#125)
    178 - [Win32] Removed XInput circular deadzone from joystick axis data (#1045)
    179 - [Win32] Bugfix: Undecorated windows could not be iconified by the user (#861)
    180 - [Win32] Bugfix: Deadzone logic could underflow with some controllers (#910)
    181 - [Win32] Bugfix: Bitness test in `FindVulkan.cmake` was VS specific (#928)
    182 - [Win32] Bugfix: `glfwVulkanSupported` emitted an error on systems with
    183                   a loader but no ICD (#916)
    184 - [Win32] Bugfix: Non-iconified full sreeen windows did not prevent screen
    185                   blanking or password enabled screensavers (#851)
    186 - [Win32] Bugfix: Mouse capture logic lost secondary release messages (#954)
    187 - [Win32] Bugfix: The 32-bit Vulkan loader library static was not searched for
    188 - [Win32] Bugfix: Vulkan libraries have a new path as of SDK 1.0.42.0 (#956)
    189 - [Win32] Bugfix: Monitors with no display devices were not enumerated (#960)
    190 - [Win32] Bugfix: Monitor events were not emitted (#784)
    191 - [Win32] Bugfix: The Cygwin DLL was installed to the wrong directory (#1035)
    192 - [Win32] Bugfix: Normalization of axis data via XInput was incorrect (#1045)
    193 - [X11] Moved to XI2 `XI_RawMotion` for disable cursor mode motion input (#125)
    194 - [X11] Replaced `_GLFW_HAS_XF86VM` compile-time option with dynamic loading
    195 - [X11] Bugfix: `glfwGetVideoMode` would segfault on Cygwin/X
    196 - [X11] Bugfix: Dynamic X11 library loading did not use full sonames (#941)
    197 - [X11] Bugfix: Window creation on 64-bit would read past top of stack (#951)
    198 - [X11] Bugfix: XDND support had multiple non-conformance issues (#968)
    199 - [X11] Bugfix: The RandR monitor path was disabled despite working RandR (#972)
    200 - [X11] Bugfix: IM-duplicated key events would leak at low polling rates (#747)
    201 - [X11] Bugfix: Gamma ramp setting via RandR did not validate ramp size
    202 - [X11] Bugfix: Key name string encoding depended on current locale (#981,#983)
    203 - [Linux] Moved to evdev for joystick input (#906,#1005)
    204 - [Linux] Bugfix: Event processing did not detect joystick disconnection (#932)
    205 - [Linux] Bugfix: The joystick device path could be truncated (#1025)
    206 - [Linux] Bugfix: `glfwInit` would fail if inotify creation failed (#833)
    207 - [Linux] Bugfix: `strdup` was used without any required feature macro (#1055)
    208 - [Cocoa] Added support for Vulkan window surface creation via
    209           [MoltenVK](https://moltengl.com/moltenvk/) (#870)
    210 - [Cocoa] Added support for loading a `MainMenu.nib` when available
    211 - [Cocoa] Bugfix: Disabling window aspect ratio would assert (#852)
    212 - [Cocoa] Bugfix: Window creation failed to set first responder (#876,#883)
    213 - [Cocoa] Bugfix: Removed use of deprecated `CGDisplayIOServicePort` function
    214                   (#165,#192,#508,#511)
    215 - [Cocoa] Bugfix: Disabled use of deprecated `CGDisplayModeCopyPixelEncoding`
    216                   function on macOS 10.12+
    217 - [Cocoa] Bugfix: Running in AppSandbox would emit warnings (#816,#882)
    218 - [Cocoa] Bugfix: Windows created after the first were not cascaded (#195)
    219 - [Cocoa] Bugfix: Leaving video mode with `glfwSetWindowMonitor` would set
    220                   incorrect position and size (#748)
    221 - [Cocoa] Bugfix: Iconified full screen windows could not be restored (#848)
    222 - [Cocoa] Bugfix: Value range was ignored for joystick hats and buttons (#888)
    223 - [Cocoa] Bugfix: Full screen framebuffer was incorrectly sized for some video
    224                   modes (#682)
    225 - [Cocoa] Bugfix: A string object for IME was updated non-idiomatically (#1050)
    226 - [WGL] Added support for `WGL_EXT_colorspace` for OpenGL ES contexts
    227 - [WGL] Added support for `WGL_ARB_create_context_no_error`
    228 - [GLX] Added support for `GLX_ARB_create_context_no_error`
    229 - [GLX] Bugfix: Context creation could segfault if no GLXFBConfigs were
    230                 available (#1040)
    231 - [EGL] Added support for `EGL_KHR_get_all_proc_addresses` (#871)
    232 - [EGL] Added support for `EGL_KHR_context_flush_control`
    233 - [EGL] Bugfix: The test for `EGL_RGB_BUFFER` was invalid
    234 
    235 
    236 ## Contact
    237 
    238 On [glfw.org](http://www.glfw.org/) you can find the latest version of GLFW, as
    239 well as news, documentation and other information about the project.
    240 
    241 If you have questions related to the use of GLFW, we have a
    242 [forum](http://discourse.glfw.org/), and the `#glfw` IRC channel on
    243 [Freenode](http://freenode.net/).
    244 
    245 If you have a bug to report, a patch to submit or a feature you'd like to
    246 request, please file it in the
    247 [issue tracker](https://github.com/glfw/glfw/issues) on GitHub.
    248 
    249 Finally, if you're interested in helping out with the development of GLFW or
    250 porting it to your favorite platform, join us on the forum, GitHub or IRC.
    251 
    252 
    253 ## Acknowledgements
    254 
    255 GLFW exists because people around the world donated their time and lent their
    256 skills.
    257 
    258  - Bobyshev Alexander
    259  - artblanc
    260  - arturo
    261  - Matt Arsenault
    262  - Keith Bauer
    263  - John Bartholomew
    264  - Niklas Behrens
    265  - Niklas Bergström
    266  - Denis Bernard
    267  - Doug Binks
    268  - blanco
    269  - Kyle Brenneman
    270  - Martin Capitanio
    271  - David Carlier
    272  - Chi-kwan Chan
    273  - Michał Cichoń
    274  - Lambert Clara
    275  - Andrew Corrigan
    276  - Noel Cower
    277  - Jason Daly
    278  - Jarrod Davis
    279  - Olivier Delannoy
    280  - Paul R. Deppe
    281  - Michael Dickens
    282  - Роман Донченко
    283  - Mario Dorn
    284  - Jonathan Dummer
    285  - Ralph Eastwood
    286  - Siavash Eliasi
    287  - Felipe Ferreira
    288  - Michael Fogleman
    289  - Gerald Franz
    290  - Mário Freitas
    291  - GeO4d
    292  - Marcus Geelnard
    293  - Eloi Marín Gratacós
    294  - Stefan Gustavson
    295  - Sylvain Hellegouarch
    296  - Matthew Henry
    297  - heromyth
    298  - Lucas Hinderberger
    299  - Paul Holden
    300  - Warren Hu
    301  - IntellectualKitty
    302  - Aaron Jacobs
    303  - Erik S. V. Jansson
    304  - Toni Jovanoski
    305  - Arseny Kapoulkine
    306  - Osman Keskin
    307  - Cameron King
    308  - Peter Knut
    309  - Christoph Kubisch
    310  - Konstantin Käfer
    311  - Eric Larson
    312  - Robin Leffmann
    313  - Glenn Lewis
    314  - Shane Liesegang
    315  - Eyal Lotem
    316  - Дмитри Малышев
    317  - Martins Mozeiko
    318  - Tristam MacDonald
    319  - Hans Mackowiak
    320  - Zbigniew Mandziejewicz
    321  - Kyle McDonald
    322  - David Medlock
    323  - Bryce Mehring
    324  - Jonathan Mercier
    325  - Marcel Metz
    326  - Liam Middlebrook
    327  - Jonathan Miller
    328  - Kenneth Miller
    329  - Bruce Mitchener
    330  - Jack Moffitt
    331  - Jeff Molofee
    332  - Jon Morton
    333  - Pierre Moulon
    334  - Julian Møller
    335  - Kristian Nielsen
    336  - Kamil Nowakowski
    337  - Ozzy
    338  - Andri Pálsson
    339  - Peoro
    340  - Braden Pellett
    341  - Arturo J. Pérez
    342  - Anthony Pesch
    343  - Orson Peters
    344  - Emmanuel Gil Peyrot
    345  - Cyril Pichard
    346  - Pieroman
    347  - Philip Rideout
    348  - Jorge Rodriguez
    349  - Ed Ropple
    350  - Aleksey Rybalkin
    351  - Riku Salminen
    352  - Brandon Schaefer
    353  - Sebastian Schuberth
    354  - Matt Sealey
    355  - SephiRok
    356  - Steve Sexton
    357  - Systemcluster
    358  - Yoshiki Shibukawa
    359  - Dmitri Shuralyov
    360  - Daniel Skorupski
    361  - Bradley Smith
    362  - Patrick Snape
    363  - Julian Squires
    364  - Johannes Stein
    365  - Michael Stocker
    366  - Justin Stoecker
    367  - Elviss Strazdins
    368  - Nathan Sweet
    369  - TTK-Bandit
    370  - Sergey Tikhomirov
    371  - Arthur Tombs
    372  - Ioannis Tsakpinis
    373  - Samuli Tuomola
    374  - Matthew Turner
    375  - urraka
    376  - Elias Vanderstuyft
    377  - Jari Vetoniemi
    378  - Ricardo Vieira
    379  - Nicholas Vitovitch
    380  - Simon Voordouw
    381  - Torsten Walluhn
    382  - Patrick Walton
    383  - Xo Wang
    384  - Jay Weisskopf
    385  - Frank Wille
    386  - yuriks
    387  - Ryogo Yoshimura
    388  - Andrey Zholos
    389  - Santi Zupancic
    390  - Jonas Ådahl
    391  - Lasse Öörni
    392  - All the unmentioned and anonymous contributors in the GLFW community, for bug
    393    reports, patches, feedback, testing and encouragement
    394