From 3f0221ccc0672c6fe30ca14a40eb874f6d3cbd83 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Wed, 8 Sep 2010 14:54:21 +0200 Subject: [PATCH] Replaced outdated Lite readme with quick rework of 2.7 version. --- readme.html | 639 ++++++++++++++++++++++++++++------------------------ 1 file changed, 343 insertions(+), 296 deletions(-) diff --git a/readme.html b/readme.html index e304949d..88b8840f 100644 --- a/readme.html +++ b/readme.html @@ -1,122 +1,113 @@ - - - - + + + GLFW Readme File - -

GLFW 2.7 Lite

+

GLFW 3.0 source distribution

    -
  1. Introduction
    2. -
  2. Compiling GLFW and the example programs
    3. -
  3. Installing GLFW
    4. -
  4. Using GLFW
    5. -
  5. Frequently Asked Questions
    6. -
  6. Version history
    7. -
  7. Directory structure of the GLFW distribution
    8. -
  8. Contacting the project
    9. -
  9. Acknowledgements
    10. +
  10. Introduction
    11. +
  11. Compiling GLFW and the example programs
    12. +
  12. Installing GLFW
    13. +
  13. Using GLFW
    14. +
  14. Version history
    15. +
  15. Directory structure of the GLFW distribution
    16. +
  16. Contacting the project
    17. +
  17. Acknowledgements
- +

1. Introduction

-

Welcome to version 2.7 Lite of the GLFW OpenGL framework. GLFW is -a free, open source, portable framework for OpenGL application development. In -short, it is a library that constitutes a powerful API for handling operating -system specific tasks, such as opening an OpenGL window, reading keyboard and -mouse input, and more.

+

Welcome to version 3.0 of the GLFW library. GLFW is a free, open source, +portable library for OpenGL application development. It provides a powerful +API for handling operating system specific tasks, such as opening an OpenGL +window, reading keyboard, mouse, joystick and time input, and more.

-

Please note that this is the Lite version of GLFW, which -means that some areas of functionality present in 2.x mainline versions of GLFW -have been removed.

+

This is an experimental series intended to allow the new API to +settle.

- +

Note that the threading and image loading APIs from the 2.x +series have been removed.

+ +

2. Compiling GLFW and the example programs

-

To compile GLFW and the accompanying example programs, you will need the CMake build system.

+

To compile GLFW and the accompanying example programs, you will need the +CMake build system.

- +

3. Installing GLFW

A rudimentary installation target is provided for all supported platforms via the CMake build system.

-

For Unix-like platforms, the command is:

- -

$ make install

- -

Note that you may need to run this command as root or via -sudo(1) in order to install GLFW into the various system -directories.

- -

For Visual C++ and other integrated development environments, an installation -target should appear in the by CMake generated project files.

- - +

4. Using GLFW

-

There are two aspects to using GLFW: +

There are two aspects to using GLFW:

-

    -
  1. How the GLFW API works
    2. +
  2. How does the GLFW API work
  3. How to compile programs that use GLFW
-

The first point is covered in the GLFW -Users Guide and the GLFW Reference -Manual, and we suggest that you read at least the Users Guide, since -it's a good introduction to the GLFW API.

+

The first point is covered in the +GLFW Users Guide and the +GLFW Reference Manual, and we suggest +that you read at least the Users 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.

-

4.1 Include GL/glfw.h

+

4.1 Include the GLFW header file

-

In your program, you should include GL/glfw.h like this:

+

In the files of your program where you use OpenGL or GLFW, you should +include the GL/glfw.h header file, i.e.:

-

#include <GL/glfw.h>

+
#include <GL/glfw.h>
-

This include file defines all the necessary constants, types and prototypes -that are used to interact with the GLFW API. It also includes -GL/gl.h and GL/glu.h, and - it defines all the -necessary constants and types that are necessary for OpenGL to work on +

This defines all the constants, types and function prototypes of the GLFW +API. It also includes the gl.h and GL/glu.h header +files, and - this is very important - it defines all the necessary +constants and types that are necessary for the OpenGL headers to work on different platforms.

-

For instance, under Windows you are normally required to include -windows.h before you include GL/gl.h. If you write -such a program, it would not compile under e.g. Linux since -windows.h does not exist under Linux. GL/glfw.h -takes care of these things for you. Note however that it does not actually -include windows.h, it merely mimics the parts of it that are -needed for GL/gl.h and GL/glu.h (this way we do not -get the thousands of constants, types and prototypes that could otherwise -possibly interfere with our own declarations).

+

For example, under Microsoft Windows you are normally required to include +windows.h before you include GL/gl.h. This would +however make your code dependent on the Windows platform, or at least require +your program to check which platform it is being compiled on. + +The GLFW header file takes care of this for you, not by including +windows.h, but rather by itself duplicating the necessary parts of +it. This way, the namespace won't be cluttered by the entire Windows API.

In other words:

-

4.2 Link with the correct libraries

+

Also note that if you are using an OpenGL extension loading library such as +GLEW, you should include the GLEW +header before the GLFW one. The GLEW header defines macros that +disable any gl.h that the GLFW header includes and GLEW will work +as expected.

+ + + +

4.2 Link with the right libraries

4.2.1 Windows static library

@@ -125,15 +116,15 @@ link with some system libraries that GLFW uses.

When linking a program under Windows that uses the static version of GLFW, you must also link with the following libraries: opengl32, -user32 and kernel32. Some of these libraries may be +user32 and kernel32. Some of these libraries may be linked with by default by your compiler. In the table below you can see the minimum required link options for each supported Windows compiler (you may want to add other libraries as well, such as glu32):

- - - - +
CompilerLink options
+ + + @@ -159,22 +150,18 @@ to add other libraries as well, such as glu32):

- - - -
CompilerLink options
Borland C++ Builder OpenWatcom glfw.lib opengl32.lib user32.lib
Pelles Cglfw.lib opengl32.lib user32.lib kernel32.lib

4.2.2 Windows DLL

-

To compile a program that uses the DLL version of GLFW, you need to define -the GLFW_DLL constant. This can either be done with a compiler switch, -typically by adding -DGLFW_DLL to the list of compiler options. You can -also do it by adding the following line to all your source files that include -glfw.h, before including it:

+

To compile a program that uses the DLL version of GLFW, you need to +define the GLFW_DLL constant. This can either be done with a +compiler switch, typically by adding -DGLFW_DLL to the list of +compiler options. You can also do it by adding the following line to all your +source files before including the GLFW header file:

-

#define GLFW_DLL

+
#define GLFW_DLL

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. @@ -182,10 +169,10 @@ In the table below you can see the minimum required link options for each supported Windows compiler (you may want to add other libraries as well, such as opengl32 and glu32):

- - - - +
CompilerLink options
+ + + @@ -211,120 +198,164 @@ such as opengl32 and glu32):

- - - -
CompilerLink options
Borland C++ Builder OpenWatcom glfwdll.lib
Pelles Cglfwdll.lib
+ +

4.2.3 Unix static library

-

GLFW now supports -pkgconfig, -and a libglfw.pc file is generated and installed when you install the library. -For systems that do not provide pkgconfig, you should look in this file for the -proper compile and link flags for your system, as determined by compile.sh at -compile time.

+

GLFW supports +pkg-config, +and a libglfw.pc file is generated and installed when you install +the library. For systems that do not provide pkg-config, you should look in +this file for the proper compile and link flags for your system, as determined +by compile.sh at compile time.

-

A typical compile and link command line may look like this (using GCC):

+

A typical compile and link command-line may look like this:

-

gcc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`

+
cc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`
+ +

If you use GLU functions in your program you should also add +-lGLU to your link flags.

-

If you use GLU functions in your program then you should also add the --lGLU flag.

4.2.5 Mac OS X static library

When compiling and linking a program under Mac OS X that uses GLFW, you -must also link with the following frameworks: Carbon.framework, -AGL.framework and OpenGL.framework. +must also link with Cocoa and OpenGL frameworks. -

If you are using Xcode, you simply add the GLFW library -libglfw.a and these frameworks to your project. If, however, you -are building your program from the command line, there are two methods for -correctly linking your GLFW program.

+

If you are using Xcode, you simply add the GLFW library libglfw.a and +these frameworks to your project. If, however, you are building your program +from the command-line, there are two methods for correctly linking your GLFW +program.

-

GLFW now supports pkgconfig, and a pkgconfig -file named libglfw.pc is generated and installed when you install the library. -You can find pkgconfig in most packaging systems, such as Fink and DarwinPorts, so if you have one -of them installed, simply install pkgconfig. Once you have pkgconfig available, -the command line for compiling and linking your program is:

+

GLFW supports +pkg-config, and a +libglfw.pc file is generated and installed when you install the library. You +can find pkg-config in most packaging 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:

-

gcc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`

+
cc `pkg-config --cflags libglfw` -o myprog myprog.c `pkg-config --libs libglfw`
-

If you do not wish to use pkgconfig, you will need to add the required -frameworks and libraries to your command line using the -l and +

If you do not wish to use pkg-config, you will need to add the required +frameworks and libraries to your command-line using the -l and -framework switches, i.e.:

-

gcc -o myprog myprog.c -lglfw -framework Carbon -framework AGL -framework OpenGL

+
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL

Note that you do not add the .framework extension to a framework when adding -it from the command line.

+it from the command-line.

-

These frameworks contain all GL and GLU functions, so there is no need to +

These frameworks contain all OpenGL and GLU functions, so there is no need to add additional libraries or frameworks when using GLU functionality. Also note -that even though your machine may have Unix-style GL libraries, they are for -use with the X Window System, and will not work with the Mac OS X -native version of GLFW.

+that even though your machine may have Unix-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.

- -

9. Frequently Asked Questions

- - +

5. Version history

-

2.7 Lite

+

v3.0

    -
  • Removed all threading support
    • -
  • Removed all image and texture loading support
    • -
  • Removed all build files not related to CMake
    • -
  • Removed D, Delphi and Lua bindings
    • -
  • Imported CMake work from pre-3.0 branch
    • +
  • Replaced ad hoc build system with CMake
    • +
  • Removed threading API
    • +
  • Removed image loading API
-

2.7

+

v2.7

    -
  • Added GLFW_OPENGL_VERSION_MAJOR, - GLFW_OPENGL_VERSION_MINOR and - GLFW_OPENGL_FORWARD_COMPAT hints for versioned context - creation support
    • -
  • Added GLFW_NO_GLU macro for disabling the inclusion of the - GLU header
    • -
  • Added the proper DEF file to the Visual C++ DLL project file
    • -
  • Added a rudimentary joystick API testing example
    • +
  • Added GLFW_OPENGL_VERSION_MAJOR and GLFW_OPENGL_VERSION_MINOR + hints for versioned context creation
    • +
  • Added GLFW_OPENGL_FORWARD_COMPAT hint for forward compatible context creation
    • +
  • Added GLFW_OPENGL_DEBUG_CONTEXT hint for debug context creation
    • +
  • Added GLFW_OPENL_PROFILE hint for context creation using profiles
    • +
  • Added GLFW_NO_GLU macro for disabling the inclusion of the GLU header by the GLFW header
    • +
  • Added platform-independent pixel format selection (not used on Mac OS X)
    • +
  • Added support and symbols for several additional keys, including Windows/Command keys, Pause, Caps Lock and Menu
    • +
  • Added conservative value clamping to glfwOpenWindowHint
    • +
  • Added a number of test programs mostly useful to developers of GLFW
    • +
  • Added error messages and graceful failure to example programs
    • +
  • Added Cocoa port for Mac OS X 10.5 Leopard and later
    • +
  • Added vsync to all relevant example programs
    • +
  • Added a rudimentary OpenGL 3.2+ core profile example program
    • +
  • Updated Pascal (formerly Delphi) bindings to support more compilers
    • +
  • Clarified and expanded the User's Guide and Reference Manual
    • +
  • Fixed a number of compiler warnings in the example programs
    • +
  • OpenGL version is now only parsed once, at window creation time
    • +
  • Changed glfwSwapBuffers to call glfwPollEvents after buffer swap
  • Changed all comments in public header file to plain C style
    • -
  • Removed all deprecated platforms
    • -
  • [X11] Added x11-distro-install install target, intended for packagers
    • -
  • [X11] Removed support for GLX version 1.3 and below
    • +
  • Removed the keytest example program, as it was superseded by the events test
    • +
  • Removed deprecated AmigaOS and DOS ports
    • +
  • Removed all FPS counters from example programs
    • +
  • Removed all unmaintained language bindings
    • +
  • Removed support for Pelles C
    • +
  • Removed broken Microsoft Visual C++ 6.0 build path
    • +
  • [X11] Added x11-dist-install install target, intended for packagers of GLFW
    • +
  • [X11] Added x11-dist-clean build target, intended for developers of GLFW
    • +
  • [X11] Added support for GLX_SGIX_fbconfig
    • +
  • [X11] Added support for user-specified compilation flags via CFLAGS
    • +
  • [X11] Added documentation of configuration macros
    • +
  • [X11] Implemented support for GLFW_SYSTEM_KEYS
    • +
  • [X11] Improved configuration and makefile creation logic
    • +
  • [X11] Removed support for GLX version 1.2 and below
    • +
  • [X11] Removed unnecessary calls to XSync
    • +
  • [X11] Removed use of legacy window style atoms
    • +
  • [X11] Bugfix: Repeated keys would sometimes leak through despite key repeat being disabled
    • +
  • [X11] Bugfix: Fullscreen window resizing would cause color buffer clearing without taking framebuffer objects into account
    • +
  • [X11] Bugfix: AltGr was not reported as right Alt
    • +
  • [X11] Bugfix: Window colormap was not freed
    • +
  • [X11] Bugfix: Close callback was called for glfwCloseWindow
  • [X11] Bugfix: Misspelt struct member in XF86VidMode code path
    • -
  • [MacOSX] Bugfix: Key repeat events were ignored on 10.5 Leopard
    • +
  • [X11] Bugfix: Window decorations would not appear using certain versions of Compiz on Intel hardware
    • +
  • [X11] Bugfix: Numeric keypad key symbols would change depending on Num Lock state
    • +
  • [X11] Bugfix: Hidden cursor position snapped back when halfway from window center to edge
    • +
  • [X11] Bugfix: Not properly verifying that the window was mapped before making certain calls caused a BadMatch error
    • +
  • [X11] Bugfix: The response to _NET_WM_PING events was malformed
    • +
  • [X11] Bugfix: Hidden cursor mode interfered with other applications when GLFW window was unfocused
    • +
  • [X11] Bugfix: The invisible cursor objects used for hidden cursor mode were not freed
    • +
  • [X11] Bugfix: EWMH-compliant window managers were incorrectly detected
    • +
  • [X11] Bugfix: The EWMH code path for fullscreen windows did not present the window using _NET_ACTIVE_WINDOW
    • +
  • [X11] Bugfix: The EWMH code path for fullscreen windows did not send a _NET_WM_STATE client message
    • +
  • [Carbon] Added Universal Binary build targets for all examples
    • +
  • [Carbon] Renamed MacOSX port to Carbon
    • +
  • [Carbon] Removed support for 10.2 Jaguar
    • +
  • [Carbon] Deprecated Carbon port
    • +
  • [Carbon] Bugfix: Using the Dock or menu Quit command did not call the close callback
    • +
  • [Carbon] Bugfix: Key repeat events were not caught on 10.5 Leopard
    • +
  • [Carbon] Bugfix: Certain keys were not reported
    • +
  • [Carbon] Bugfix: Missing -m32 flag caused build failure on 10.6 Snow Leopard
    • +
  • [Carbon] Bugfix: Missing -mmacosx-version-min flag caused build failure on 10.5 Leopard
    • +
  • [Carbon] Bugfix: glfwOpenWindow did not call glClear
    • +
  • [Win32] Added Visual C++ project files for all examples and test programs
    • +
  • [Win32] Removed iterative context re-creation attempts for FSAA sample count
    • +
  • [Win32] Bugfix: The Visual C++ GLFW DLL project file did not use the correct DEF file
    • +
  • [Win32] Bugfix: WGL extensions were not detected and/or used correctly
  • [Win32] Bugfix: Improper use of wParam for WM_SYSCOMMAND
    • -
  • [Win32] Bugfix: Derivatives of stream.c not cleaned up by compile.bat
    • +
  • [Win32] Bugfix: Derivatives of stream.c were not cleaned up by compile.bat
  • [Win32] Bugfix: Pointer for GetExtensionsStringARB was not initialized
    • -
  • [Win32] Bugfix: Updated API version in makefiles
    • +
  • [Win32] Bugfix: Makefiles contained the wrong GLFW API version
    • +
  • [Win32] Bugfix: Numeric keypad key symbols would change depending on Num Lock state
    • +
  • [Win32] Bugfix: DllMain performed a number of forbidden actions (by calling glfwTerminate)
-

2.6

+

v2.6

 -

2.5

+

v2.5

-

2.4.2

+

v2.4.2

-

2.4.1

+

v2.4.1

-

2.4

+

v2.4

-

2.3.2

+

v2.3.2

-

2.3.1

+

v2.3.1

-

2.3

+

v2.3

-

2.2.3

+

v2.2.3

-

2.2.2

+

v2.2.2

-

2.2.1

+

v2.2.1

-

2.2

+

v2.2

-

2.1

+

v2.1

-

2.0.3

+

v2.0.3

-

2.0.2

+

v2.0.2

-

2.0.1

+

v2.0.1

-

2.0

+

v2.0

-

1.0.2

+

v1.0.2

-

1.0.1

+

v1.0.1

-

1.0.0

+

v1.0.0

- +

6. Directory structure of the GLFW distribution

Here is an overview of the directory structure of the GLFW distribution: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

+

DirectoryContents
docsGLFW manuals in PDF format
examplesSeveral example programs in C
include/GLThe GLFW C/C++ header file
libThe source code for GLFW
lib/macosx - Mac OS X-specific code
lib/win32 - Windows-specific code
lib/x11Unix/X11-specific code
+ + + + + + + + + + + + +
docs GLFW manuals in PDF format
examples Several example programs in C
include  
   GL Here is the GLFW C/C++ include file
lib The source code for GLFW
   cocoa Mac OS X/Cocoa specific implementation
   win32 Windows specific implementation
   x11 Unix/X11 specific implementation
support  
   d D support
   msvc90 Project files for Visual C++ 9.0
   pascal Pascal support
tests Several test programs in C
- +

7. Contacting the project

-

The official GLFW web site can be found here: http://glfw.sourceforge.net/. It -contains the latest version of GLFW, news and other information that is useful -for OpenGL development.

+

The official website for GLFW is glfw.org. +It contains the latest version of GLFW, news and other information that is +useful for OpenGL development.

-

If you have questions related to the use of GLFW, we have a user's web -forum, and a user's mailing -list on SF.net, and the IRC channel #glfw on Freenode.

+

If you have questions related to the use of GLFW, we have a +user's web forum, +and a +user's mailing list +on SF.net, and the registered IRC channel #glfw on +Freenode.

-

If you have a bug to report or a feature you'd like to request, please file -it in the SF.net -trackers.

+

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 +GLFW 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. +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. - +

8. Acknowledgements

-

GLFW would not be what it is today without the help from: +

GLFW exists because people around the world donated their time and lent +their skills. Special thanks go out to:

+