mirror of
https://github.com/glfw/glfw.git
synced 2024-11-10 00:51:47 +00:00
Replaced readme.html with README.md.
Removed historic changelog, updated build and use documentation, reformatted contributor list, removed structure table, etc.
This commit is contained in:
Camilla Berglund
parent
107e20233d
commit
c70e2e9c3c
452
README.md
Normal file
452
README.md
Normal file
@ -0,0 +1,452 @@
|
||||
# GLFW 3.0
|
||||
|
||||
## Introduction
|
||||
|
||||
GLFW is a free, Open Source, portable library for OpenGL and OpenGL ES
|
||||
application development. It provides a simple, platform-independent API for
|
||||
creating windows and contexts, reading input, handling events, etc.
|
||||
|
||||
Version 3.0 brings a new API with many new features such as multiple windows
|
||||
and contexts, multi-monitor support, clipboard text support, an error
|
||||
description callback, gamma ramp control, layout-independent keyboard input and
|
||||
UTF-8 for all strings.
|
||||
|
||||
Certain features like the threading and image loading functions from GLFW 2.x
|
||||
have been [removed](http://wiki.glfw.org/wiki/Rationale_for_removing).
|
||||
|
||||
|
||||
## Compiling GLFW
|
||||
|
||||
To compile GLFW and the accompanying example programs, you will need the
|
||||
[CMake](http://www.cmake.org/) build system.
|
||||
|
||||
### CMake options
|
||||
|
||||
There are a number of CMake build options for GLFW, although not all are
|
||||
available on all supported platforms.
|
||||
|
||||
#### Shared options
|
||||
|
||||
`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
|
||||
library or as a DLL / shared library / dynamic library.
|
||||
|
||||
`LIB_SUFFIX` affects where the GLFW shared /dynamic library is
|
||||
installed. If it is empty, it is installed to `$PREFIX/lib`. If it is set to
|
||||
`64`, it is installed to `$PREFIX/lib64`.
|
||||
|
||||
`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
|
||||
along with the library.
|
||||
|
||||
`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
|
||||
built along with the library.
|
||||
|
||||
#### Mac OS X specific options
|
||||
|
||||
`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
|
||||
directory of bundled applications to the `Contents/Resources` directory.
|
||||
|
||||
`GLFW_USE_MENUBAR` determines whether the first call to
|
||||
`glfwCreateWindow` sets up a minimal menu bar.
|
||||
|
||||
`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
|
||||
|
||||
#### Windows specific options
|
||||
|
||||
`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version of the
|
||||
Visual C++ runtime library.
|
||||
|
||||
#### EGL specific options
|
||||
|
||||
`GLFW_USE_EGL` determines whether to use EGL as the context creation API. Note
|
||||
that EGL is not yet provided on all supported platforms.
|
||||
|
||||
`GLFW_CLIENT_LIBRARY` determines which client API library to use. If set to
|
||||
`opengl` the OpenGL library is used, if set to `glesv1` for the OpenGL ES 1.x
|
||||
library is used, or if set to `glesv2` the OpenGL ES 2.0 library is used. The
|
||||
selected library and its header files must be present on the system for this to
|
||||
work.
|
||||
|
||||
|
||||
## Installing GLFW
|
||||
|
||||
A rudimentary installation target is provided for all supported platforms via
|
||||
CMake.
|
||||
|
||||
|
||||
## Using GLFW
|
||||
|
||||
There are two aspects to using GLFW:
|
||||
|
||||
* Using the GLFW API
|
||||
* Compiling and linking programs using the GLFW library
|
||||
|
||||
The first point is covered in the reference manual and user guide, and we
|
||||
suggest that you read at least the user guide, since it's a good introduction to
|
||||
the GLFW API.
|
||||
|
||||
Designing and compiling programs that use GLFW is not very difficult.
|
||||
A few rules for successfully designing GLFW-based programs are presented
|
||||
in the following sections.
|
||||
|
||||
|
||||
### Include the GLFW header file
|
||||
|
||||
In the files of your program where you use OpenGL or GLFW, you should include
|
||||
the GLFW 3 header file, i.e.:
|
||||
|
||||
#include <GL/glfw3.h>
|
||||
|
||||
This defines all the constants, types and function prototypes of the GLFW API.
|
||||
It also includes the chosen client API header files (by default OpenGL), and
|
||||
defines all the constants and types necessary for those headers to work on that
|
||||
platform.
|
||||
|
||||
For example, under Windows you are normally required to include `windows.h`
|
||||
before including `GL/gl.h`. This would make your source file tied to Windows
|
||||
and pollute your code's namespace with the whole Win32 API.
|
||||
|
||||
Instead, the GLFW header takes care of this for you, not by including
|
||||
`windows.h`, but rather by itself duplicating only the necessary parts of it.
|
||||
It does this only where needed, so if `windows.h` *is* included, the GLFW header
|
||||
does not try to redefine those symbols.
|
||||
|
||||
In other words:
|
||||
|
||||
* Do *not* include the OpenGL headers yourself, as GLFW does this for you
|
||||
* Do *not* include `windows.h` or other platform-specific headers unless you
|
||||
plan on using those APIs directly
|
||||
* If you *do* need to include such headers, do it *before* including
|
||||
the GLFW and it will detect this
|
||||
|
||||
If you are using an OpenGL extension loading library such as
|
||||
[GLEW](http://glew.sourceforge.net/), the GLEW header should also be included
|
||||
*before* the GLFW one. The GLEW header defines macros that disable any OpenGL
|
||||
header that the GLFW header includes and GLEW will work as expected.
|
||||
|
||||
|
||||
### Link with the right libraries
|
||||
|
||||
|
||||
#### Windows static library
|
||||
|
||||
If you link with the static version of GLFW, it is also necessary to link with
|
||||
some system libraries that GLFW uses.
|
||||
|
||||
When linking a program under Windows that uses the static version of GLFW, you
|
||||
must link with `opengl32`. If you are using GLU, you must also link with
|
||||
`glu32`.
|
||||
|
||||
|
||||
#### Windows DLL
|
||||
|
||||
When compiling a program that uses the DLL version of GLFW, you need to define
|
||||
the `GLFW_DLL` macro *before* any inclusion of the GLFW header. This can be
|
||||
done either with a compiler switch or by defining it in your source code.
|
||||
|
||||
When linking a program under Windows that uses the DLL version of GLFW,
|
||||
the only library you need to link with for GLFW to work is `glfwdll`.
|
||||
You will still have to link against `opengl32` if your program uses OpenGL, and
|
||||
`glu32` if it uses GLU.
|
||||
|
||||
|
||||
|
||||
#### Unix library
|
||||
|
||||
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/).
|
||||
A `glfw3.pc` file is generated when the library is built and installed along
|
||||
with it. You can use it without installation using the `PKG_CONFIG_PATH`
|
||||
environment variable. See the documentation for pkg-config for more details.
|
||||
|
||||
A typical compile and link command-line when using the static may look like this:
|
||||
|
||||
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
|
||||
|
||||
If you are using the shared library, simply omit the `--static` flag.
|
||||
|
||||
If you are using GLU, you should also add `-lGLU` to your link flags.
|
||||
|
||||
|
||||
#### Mac OS X static library
|
||||
|
||||
GLFW on Mac OS X uses the Cocoa, OpenGL and IOKit frameworks.
|
||||
|
||||
If you are using Xcode, you can simply add the GLFW library and these frameworks
|
||||
as dependencies.
|
||||
|
||||
If you are building from the
|
||||
command-line, it is recommended that you use pkg-config
|
||||
|
||||
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/).
|
||||
A `glfw3.pc` file is generated when the library is built and installed along
|
||||
with it. You can use it without installation using the `PKG_CONFIG_PATH`
|
||||
environment variable. See the documentation for pkg-config for more details.
|
||||
|
||||
You can find pkg-config in most package systems such as
|
||||
[Fink](http://www.finkproject.org/) and [MacPorts](http://www.macports.org/), so
|
||||
if you have one of them installed, simply install pkg-config. Once you have
|
||||
pkg-config available, the command-line for compiling and linking your
|
||||
program is:
|
||||
|
||||
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
|
||||
|
||||
If you do not wish to use pkg-config, you need to add the required frameworks
|
||||
and libraries to your command-line using the `-l` and `-framework` switches,
|
||||
i.e.:
|
||||
|
||||
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit
|
||||
|
||||
Note that you do not add the `.framework` extension to a framework when adding
|
||||
it from the command-line.
|
||||
|
||||
The OpenGL framework contains both the OpenGL and GLU APIs, so there is no need
|
||||
to add additional libraries or frameworks when using GLU. Also note that even
|
||||
though your machine may have `libGL`-style OpenGL libraries, they are for use
|
||||
with the X Window System and will *not* work with the Mac OS X native version of
|
||||
GLFW.
|
||||
|
||||
|
||||
## Changes for version 3.0
|
||||
|
||||
* Added `GLFWmonitor` and updated monitor-related functions to take a monitor
|
||||
handle
|
||||
* Added `glfwGetMonitors` and `glfwGetPrimaryMonitor` for enumerating available
|
||||
monitors
|
||||
* Added `glfwGetMonitorParam` and `glfwGetMonitorName` for retrieving monitor
|
||||
properties
|
||||
* Added `glfwSetMonitorCallback` and `GLFWmonitorfun` for notification of
|
||||
changes in the set of available monitors
|
||||
* Added `GLFWwindow` and updated window-related functions and callbacks to take
|
||||
a window handle
|
||||
* Added `glfwDefaultWindowHints` for resetting all window hints to their
|
||||
default values
|
||||
* Added `glfwMakeContextCurrent` for making the context of the specified window
|
||||
current
|
||||
* Added `glfwSetErrorCallback`, `GLFWerrorfun` and error type tokens for
|
||||
receiving error notifications
|
||||
* Added `glfwSetWindowUserPointer` and `glfwGetWindowUserPointer` for
|
||||
per-window user pointers
|
||||
* Added `glfwGetVersionString` for determining which code paths were enabled at
|
||||
compile time
|
||||
* Added `glfwGetWindowMonitor` for querying the monitor, if any, of the
|
||||
specified window
|
||||
* Added `glfwSetWindowPosCallback` and `GLFWwindowposfun` for receiving window
|
||||
position events
|
||||
* Added `glfwSetWindowFocusCallback` and `GLFWwindowfocusfun` for receiving
|
||||
window focus events
|
||||
* Added `glfwSetWindowIconifyCallback` and `GLFWwindowiconifyfun` for receiving
|
||||
window iconification events
|
||||
* Added `glfwGetClipboardString` and `glfwSetClipboardString` for interacting
|
||||
with the system clipboard
|
||||
* Added `glfwGetJoystickName` for retrieving the name of a joystick
|
||||
* Added `glfwGetCurrentContext` for retrieving the window whose OpenGL context
|
||||
is current
|
||||
* Added `GLFW_SRGB_CAPABLE` for requesting sRGB capable framebuffers
|
||||
* Added `GLFW_CLIENT_API` and its values `GLFW_OPENGL_API` and
|
||||
`GLFW_OPENGL_ES_API` for selecting client API
|
||||
* Added `GLFW_CONTEXT_ROBUSTNESS` and values `GLFW_NO_ROBUSTNESS`,
|
||||
`GLFW_NO_RESET_NOTIFICATION` and `GLFW_LOSE_CONTEXT_ON_RESET` for
|
||||
`GL_ARB_robustness` support
|
||||
* Added `GLFW_OPENGL_REVISION` to make up for removal of `glfwGetGLVersion`
|
||||
* Added `GLFW_INCLUDE_GLCOREARB` macro for including `GL/glcorearb.h` instead of
|
||||
`GL/gl.h`
|
||||
* Added `GLFW_INCLUDE_ES1` macro for telling the GLFW header to use `GLES/gl.h`
|
||||
instead of `GL/gl.h`
|
||||
* Added `GLFW_INCLUDE_ES2` macro for telling the GLFW header to use
|
||||
`GLES2/gl2.h` instead of `GL/gl.h`
|
||||
* Added `GLFW_VISIBLE` window hint and parameter for controlling and polling
|
||||
window visibility
|
||||
* Added `GLFW_POSITION_X` and `GLFW_POSITION_Y` window hints and parameter for
|
||||
controlling and polling window position
|
||||
* Added `windows` simple multi-window test program
|
||||
* Added `sharing` simple OpenGL object sharing test program
|
||||
* Added `modes` video mode enumeration and setting test program
|
||||
* Added `threads` simple multi-threaded rendering test program
|
||||
* Added `glfw3native.h` header and platform-specific functions for explicit
|
||||
access to native display, window and context handles
|
||||
* Added `glfwSetGamma`, `glfwSetGammaRamp` and `glfwGetGammaRamp` functions and
|
||||
`GLFWgammaramp` type for monitor gamma ramp control
|
||||
* Added window parameter to `glfwSwapBuffers`
|
||||
* Changed buffer bit depth parameters of `glfwOpenWindow` to window hints
|
||||
* Changed `glfwOpenWindow` and `glfwSetWindowTitle` to use UTF-8 encoded
|
||||
strings
|
||||
* Changed `glfwGetProcAddress` to return a (generic) function pointer
|
||||
* Changed `glfwGetVideoModes` to return a dynamic, unlimited number of video
|
||||
modes for the specified monitor
|
||||
* Renamed `glfw.h` to `glfw3.h` to avoid conflicts with 2.x series
|
||||
* Renamed `glfwOpenWindowHint` to `glfwWindowHint`
|
||||
* Renamed `GLFW_ACTIVE` to `GLFW_FOCUSED`
|
||||
* Renamed `GLFW_FSAA_SAMPLES` to `GLFW_SAMPLES`
|
||||
* Renamed `GLFW_WINDOW_NO_RESIZE` to `GLFW_RESIZABLE`
|
||||
* Renamed `GLFW_BUILD_DLL` to `_GLFW_BUILD_DLL`
|
||||
* Renamed `version` test to `glfwinfo`
|
||||
* Renamed `GLFW_NO_GLU` to `GLFW_INCLUDE_GLU` and made it disabled by default
|
||||
* Renamed `glfwGetJoystickPos` to `glfwGetJoystickAxes` to match
|
||||
`glfwGetJoystickButtons`
|
||||
* Renamed mouse position functions to cursor position equivalents
|
||||
* Replaced `glfwOpenWindow` and `glfwCloseWindow` with `glfwCreateWindow` and
|
||||
`glfwDestroyWindow`
|
||||
* Replaced `glfwGetDesktopMode` width `glfwGetVideoMode`
|
||||
* Replaced ad hoc build system with CMake
|
||||
* Replaced layout-dependent key codes with single, platform-independent set
|
||||
based on US layout
|
||||
* Replaced mouse wheel interface with two-dimensional, floating point scrolling
|
||||
interface
|
||||
* Replaced `glfwEnable` and `glfwDisable` with `glfwGetInputMode` and
|
||||
`glfwSetInputMode`
|
||||
* Replaced `joystick` test with graphical version
|
||||
* Replaced automatic closing of windows with `GLFW_SHOULD_CLOSE` window
|
||||
parameter
|
||||
* Removed the `GLFW_KEY_REPEAT` input option
|
||||
* Removed event auto-polling and the `GLFW_AUTO_POLL_EVENTS` window enable
|
||||
* Removed the Win32 port .def files
|
||||
* Removed the entire threading API
|
||||
* Removed the entire image loading API
|
||||
* Removed deprecated Carbon port
|
||||
* Removed registering `glfwTerminate` with `atexit`
|
||||
* Removed `glfwSleep` function
|
||||
* Removed `glfwGetNumberOfProcessors` function
|
||||
* Removed `glfwGetGLVersion` function
|
||||
* Removed `GLFW_OPENED` window parameter
|
||||
* Removed `GLFW_WINDOW` and `GLFW_FULLSCREEN`
|
||||
* Removed nonsensical key actions for Unicode character input
|
||||
* Removed `GLFWCALL` and `GLFWAPIENTRY` macros for stdcall calling convention
|
||||
* Removed `GLFW_ACCELERATED` window parameter
|
||||
* Removed default framebuffer attributes from `glfwGetWindowParam`
|
||||
* Bugfix: The default OpenGL version in the `glfwinfo` test was set to 1.1
|
||||
* Bugfix: The OpenGL profile and forward-compatibility window parameters were
|
||||
not saved after context creation
|
||||
* Bugfix: The FSAA test did not check for the availability of
|
||||
`GL_ARB_multisample`
|
||||
* Bugfix: Cursor centering upon leaving captured cursor mode was reported
|
||||
before the mode was changed to non-captured
|
||||
* [Cocoa] Added support for OpenGL 3.2 core profile in 10.7 Lion and above
|
||||
* [Cocoa] Added support for joysticks
|
||||
* [Cocoa] Postponed menu creation to first window creation
|
||||
* [Cocoa] Replaced `NSDate` time source with `mach_absolute_time`
|
||||
* [Cocoa] Replaced all deprecated CoreGraphics calls with non-deprecated
|
||||
counterparts
|
||||
* [Cocoa] Bugfix: The `NSOpenGLPFAFullScreen` pixel format attribute caused
|
||||
creation to fail on some machines
|
||||
* [Cocoa] Bugfix: `glfwOpenWindow` did not properly enforce the
|
||||
forward-compatible and context profile hints
|
||||
* [Cocoa] Bugfix: The loop condition for saving video modes used the wrong
|
||||
index variable
|
||||
* [Cocoa] Bugfix: The OpenGL framework was not retrieved, making
|
||||
glfwGetProcAddress crash
|
||||
* [Cocoa] Bugfix: `glfwInit` changed the current directory for unbundled
|
||||
executables
|
||||
* [Cocoa] Bugfix: The `GLFW_WINDOW_NO_RESIZE` window parameter was always zero
|
||||
* [Cocoa] Bugfix: The cursor position incorrectly rounded during conversion
|
||||
* [Cocoa] Bugfix: Cursor positioning led to nonsensical results for fullscreen
|
||||
windows
|
||||
* [Cocoa] Bugfix: The GLFW window was flagged as restorable
|
||||
* [X11] Added support for the `GLX_EXT_swap_control` and
|
||||
`GLX_MESA_swap_control` extensions as alternatives to
|
||||
`GLX_SGI_swap_control`
|
||||
* [X11] Added the POSIX `CLOCK_MONOTONIC` time source as the preferred method
|
||||
* [X11] Added dependency on libm, where present
|
||||
* [X11] Added support for the `_NET_WM_NAME` and `_NET_WM_ICON_NAME` EWMH
|
||||
window properties
|
||||
* [X11] Made client-side RandR and Xf86VidMode extensions required
|
||||
* [X11] Bugfix: Some window properties required by the ICCCM were not set
|
||||
* [X11] Bugfix: Calling `glXCreateContextAttribsARB` with an unavailable OpenGL
|
||||
version caused the application to terminate with a `BadMatch`
|
||||
Xlib error
|
||||
* [X11] Bugfix: A synchronization point necessary for jitter-free locked cursor
|
||||
mode was incorrectly removed
|
||||
* [X11] Bugfix: The window size hints were not updated when calling
|
||||
`glfwSetWindowSize` on a non-resizable window
|
||||
* [Win32] Changed port to use Unicode mode only
|
||||
* [Win32] Removed explicit support for versions of Windows older than Windows
|
||||
XP
|
||||
* [Win32] Bugfix: Window activation and iconification did not work as expected
|
||||
* [Win32] Bugfix: Software rasterizer pixel formats were not discarded by the
|
||||
WGL_ARB_pixel_format code path
|
||||
* [Win32] Bugfix: The array for WGL context attributes was too small and could
|
||||
overflow
|
||||
* [Win32] Bugfix: Alt+F4 hot key was not translated into `WM_CLOSE`
|
||||
* [Win32] Bugfix: The `GLFW_WINDOW_NO_RESIZE` window parameter was always zero
|
||||
* [Win32] Bugfix: A test was missing for whether all available pixel formats
|
||||
had been disqualified
|
||||
|
||||
|
||||
## Contact
|
||||
|
||||
The official website for GLFW is [glfw.org](http://www.glfw.org/). There you
|
||||
can find the latest version of GLFW, as well as news, documentation and other
|
||||
information about the project.
|
||||
|
||||
If you have questions related to the use of GLFW, we have a
|
||||
[support forum](https://sourceforge.net/p/glfw/discussion/247562/), and the IRC
|
||||
channel `#glfw` on [Freenode](http://freenode.net/).
|
||||
|
||||
If you have a bug to report, a patch to submit or a feature you'd like to
|
||||
request, please file it in one of the
|
||||
[issue trackers](https://sourceforge.net/p/glfw/_list/tickets) on SF.net.
|
||||
|
||||
Finally, if you're interested in helping out with the development of GLFW or
|
||||
porting it to your favorite platform, we have a
|
||||
[developer's mailing list](https://lists.stacken.kth.se/mailman/listinfo/glfw-dev),
|
||||
or you could join us on `#glfw`.
|
||||
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
GLFW exists because people around the world donated their time and lent their
|
||||
skills.
|
||||
|
||||
* Bobyshev Alexander
|
||||
* artblanc
|
||||
* Keith Bauer
|
||||
* John Bartholomew
|
||||
* blanco
|
||||
* Lambert Clara
|
||||
* Jarrod Davis
|
||||
* Olivier Delannoy
|
||||
* Paul R. Deppe
|
||||
* Jonathan Dummer
|
||||
* Ralph Eastwood
|
||||
* Gerald Franz
|
||||
* GeO4d
|
||||
* Marcus Geelnard
|
||||
* Stefan Gustavson
|
||||
* Sylvain Hellegouarch
|
||||
* heromyth
|
||||
* Toni Jovanoski
|
||||
* Cameron King
|
||||
* Peter Knut
|
||||
* Robin Leffmann
|
||||
* Glenn Lewis
|
||||
* Shane Liesegang
|
||||
* Дмитри Малышев
|
||||
* Martins Mozeiko
|
||||
* Tristam MacDonald
|
||||
* Hans Mackowiak
|
||||
* David Medlock
|
||||
* Marcel Metz
|
||||
* Kenneth Miller
|
||||
* Jeff Molofee
|
||||
* Julian Møller
|
||||
* Ozzy at Orkysquad
|
||||
* Peoro
|
||||
* Arturo J. Pérez
|
||||
* Riku Salminen
|
||||
* Sebastian Schuberth
|
||||
* Matt Sealey
|
||||
* Steve Sexton
|
||||
* Dmitri Shuralyov
|
||||
* Daniel Skorupski
|
||||
* Bradley Smith
|
||||
* Julian Squires
|
||||
* Johannes Stein
|
||||
* TTK-Bandit
|
||||
* Sergey Tikhomirov
|
||||
* Samuli Tuomola
|
||||
* Torsten Walluhn
|
||||
* Frank Wille
|
||||
* yuriks
|
||||
* Santi Zupancic
|
||||
* Lasse Öörni
|
||||
* All the unmentioned and anonymous contributors in the GLFW community, for bug
|
||||
reports, patches, feedback, testing and encouragement
|
||||
|
||||
1017
readme.html
1017
readme.html
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user