commit | e6bfbba429b3c714dae247d123ad441a8963d208 | [log] [tgz] |
---|---|---|
author | Camilla Berglund <elmindreda@elmindreda.org> | Wed Jun 12 16:06:21 2013 +0200 |
committer | Camilla Berglund <elmindreda@elmindreda.org> | Wed Jun 12 16:06:21 2013 +0200 |
tree | b8bc36163af0f810f7cf8cd61219e3a0eb2116ad | |
parent | 3274dc9a619dee3abed80c1239130c29985876d9 [diff] |
Clarified sticky keys docs.
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, EGL and OpenGL ES support, clipboard text support, an error description callback, gamma ramp control, layout-independent keyboard input and UTF-8 for all strings.
GLFW is now hosted on GitHub.
If you are new to GLFW, you may find the introductory tutorial for GLFW 3 useful. If you have used GLFW 2 in the past, there is a transition guide for moving to the GLFW 3 API.
To compile GLFW and the accompanying example programs, you will need the CMake build system.
To compile GLFW for X11 and GLX, you need to have the X and OpenGL header packages installed. For example, on Ubuntu and other distributions based on Debian GNU/Linux, you need to install the xorg-dev
and libglu1-mesa-dev
packages. Note that using header files from Mesa will not tie your binary to the Mesa implementation of OpenGL.
There are a number of CMake build options for GLFW, although not all are available on all supported platforms. Some of these are de facto standards among CMake users and so have no GLFW_
prefix.
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.
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.
USE_MSVC_RUNTIME_LIBRARY_DLL
determines whether to use the DLL version of the Visual C++ runtime library.
GLFW_USE_EGL
determines whether to use EGL instead of the platform-specific 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.
A rudimentary installation target is provided for all supported platforms via CMake.
There are two aspects to using GLFW:
The first point is covered in the WIP reference manual.
In the files of your program where you use OpenGL or GLFW, you should include the GLFW 3 header file, i.e.:
#include <GLFW/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:
windows.h
or other platform-specific headers unless you plan on using those APIs directlyIf you are using an OpenGL extension loading library such as GLEW, 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.
These macros may be defined before the inclusion of the GLFW header.
GLFW_INCLUDE_GLCOREARB
makes the header include the modern GL/glcorearb.h
header (OpenGL/gl3.h
on Mac OS X) instead of the regular OpenGL header.
GLFW_INCLUDE_ES1
makes the header include the OpenGL ES 1.x GLES/gl.h
header instead of the regular OpenGL header.
GLFW_INCLUDE_ES2
makes the header include the OpenGL ES 2.0 GLES2/gl2.h
header instead of the regular OpenGL header.
GLFW_INCLUDE_ES3
makes the header include the OpenGL ES 3.0 GLES3/gl3.h
header instead of the regular OpenGL header.
GLFW_INCLUDE_NONE
makes the header not include any client API header.
GLFW_INCLUDE_GLU
makes the header include the GLU header. This only makes sense if you are using OpenGL.
GLFW_DLL
is necessary when using the GLFW DLL on Windows.
The GLFW_LIBRARIES
cache variable contains all link-time dependencies of GLFW as it is currently configured, so to link against GLFW simply do:
target_link_libraries(myapp glfw ${GLFW_LIBRARIES})
Note that this does not include GLU, as GLFW does not use it. If your application needs GLU, you can add it to the list of dependencies with the OPENGL_glu_LIBRARY
cache variable.
The static version of the GLFW library is named glfw3
. When using this version, it is also necessary to link with some 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
.
The link library for the GLFW DLL is named glfw3dll
. 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.
A program using the GLFW DLL does not need to link against any of its dependencies, but you still have to link against opengl32
if your program uses OpenGL and glu32
if it uses GLU.
GLFW supports pkg-config, and 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.
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, and 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 and MacPorts, 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 --static --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.
GLFWmonitor
and updated monitor-related functions to take a monitor handleglfwGetMonitors
and glfwGetPrimaryMonitor
for enumerating available monitorsglfwGetMonitorPos
, glfwGetMonitorPhysicalSize
and glfwGetMonitorName
for retrieving monitor propertiesglfwSetMonitorCallback
and GLFWmonitorfun
for notification of changes in the set of available monitorsGLFWwindow
and updated window-related functions and callbacks to take a window handleglfwSetWindowShouldClose
and glfwWindowShouldClose
for setting and retrieving the window close flagglfwGetWindowPos
for retrieving the position of a windowglfwDefaultWindowHints
for resetting all window hints to their default valuesglfwMakeContextCurrent
for making the context of the specified window currentglfwSetErrorCallback
, GLFWerrorfun
and error type tokens for receiving error notificationsglfwSetWindowUserPointer
and glfwGetWindowUserPointer
for per-window user pointersglfwGetVersionString
for determining which code paths were enabled at compile timeglfwGetWindowMonitor
for querying the monitor, if any, of the specified windowglfwGetFramebufferSize
and glfwSetFramebufferSizeCallback
for receiving the current size, in pixels, of the framebufferglfwSetWindowPosCallback
and GLFWwindowposfun
for receiving window position eventsglfwSetWindowFocusCallback
and GLFWwindowfocusfun
for receiving window focus eventsglfwSetWindowIconifyCallback
and GLFWwindowiconifyfun
for receiving window iconification eventsglfwGetClipboardString
and glfwSetClipboardString
for interacting with the system clipboardglfwGetJoystickName
for retrieving the name of a joystickglfwGetCurrentContext
for retrieving the window whose OpenGL context is currentGLFW_SRGB_CAPABLE
for requesting sRGB capable framebuffersGLFW_CLIENT_API
and its values GLFW_OPENGL_API
and GLFW_OPENGL_ES_API
for selecting client APIGLFW_CONTEXT_ROBUSTNESS
and values GLFW_NO_ROBUSTNESS
, GLFW_NO_RESET_NOTIFICATION
and GLFW_LOSE_CONTEXT_ON_RESET
for GL_ARB_robustness
supportGLFW_OPENGL_REVISION
to make up for removal of glfwGetGLVersion
GLFW_INCLUDE_GLCOREARB
macro for including GL/glcorearb.h
instead of GL/gl.h
GLFW_INCLUDE_ES1
macro for telling the GLFW header to use GLES/gl.h
instead of GL/gl.h
GLFW_INCLUDE_ES2
macro for telling the GLFW header to use GLES2/gl2.h
instead of GL/gl.h
GLFW_INCLUDE_NONE
macro for telling the GLFW header to not include any client API headerGLFW_VISIBLE
window hint and parameter for controlling and polling window visibilityGLFW_REPEAT
key action for repeated keysrefreshRate
member to GLFWvidmode
structwindows
simple multi-window test programsharing
simple OpenGL object sharing test programmodes
video mode enumeration and setting test programthreads
simple multi-threaded rendering test programglfw3native.h
header and platform-specific functions for explicit access to native display, window and context handlesglfwSetGamma
, glfwSetGammaRamp
and glfwGetGammaRamp
functions and GLFWgammaramp
type for monitor gamma ramp controlglfwSwapBuffers
glfwOpenWindow
to window hintsglfwCreateWindow
and glfwSetWindowTitle
to use UTF-8 encoded stringsglfwGetProcAddress
to return a (generic) function pointerglfwGetVideoModes
to return a dynamic, unlimited number of video modes for the specified monitorGL
to GLFW
glfw.h
to glfw3.h
to avoid conflicts with 2.x seriesglfwOpenWindowHint
to glfwWindowHint
glfwGetWindowParam
to glfwGetWindowAttrib
GLFW_ACTIVE
to GLFW_FOCUSED
GLFW_FSAA_SAMPLES
to GLFW_SAMPLES
GLFW_WINDOW_NO_RESIZE
to GLFW_RESIZABLE
GLFW_BUILD_DLL
to _GLFW_BUILD_DLL
version
test to glfwinfo
GLFW_NO_GLU
to GLFW_INCLUDE_GLU
and made it disabled by defaultglfwGetJoystickPos
to glfwGetJoystickAxes
to match glfwGetJoystickButtons
glfwOpenWindow
and glfwCloseWindow
with glfwCreateWindow
and glfwDestroyWindow
glfwGetDesktopMode
width glfwGetVideoMode
glfwEnable
and glfwDisable
with glfwGetInputMode
and glfwSetInputMode
joystick
test with graphical versionGLFW_KEY_REPEAT
input optionGLFW_AUTO_POLL_EVENTS
window enableglfwTerminate
with atexit
glfwSleep
functionglfwGetNumberOfProcessors
functionglfwGetGLVersion
functionGLFW_OPENED
window parameterGLFW_WINDOW
and GLFW_FULLSCREEN
GLFWCALL
and GLFWAPIENTRY
macros for stdcall calling conventionGLFW_ACCELERATED
window parameterglfwGetWindowParam
glfwinfo
test was set to 1.1GL_ARB_multisample
NSDate
time source with mach_absolute_time
NSOpenGLPFAFullScreen
pixel format attribute caused creation to fail on some machinesglfwCreateWindow
did not properly enforce the forward-compatible and context profile hintsglfwGetProcAddress
crashglfwInit
changed the current directory for unbundled executablesGLFW_WINDOW_NO_RESIZE
window parameter was always zeroGLX_EXT_swap_control
and GLX_MESA_swap_control
extensions as alternatives to GLX_SGI_swap_control
CLOCK_MONOTONIC
time source as the preferred method_NET_WM_NAME
and _NET_WM_ICON_NAME
EWMH window propertiesglXCreateContextAttribsARB
with an unavailable OpenGL version caused the application to terminate with a BadMatch
Xlib errorglfwSetWindowSize
on a non-resizable windowWGL_ARB_pixel_format
code pathWM_CLOSE
GLFW_WINDOW_NO_RESIZE
window parameter was always zeroThe official website for GLFW is 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, and the IRC channel #glfw
on Freenode.
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 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, or you could join us on #glfw
.
GLFW exists because people around the world donated their time and lent their skills.