Documentation work.

This commit is contained in:
Camilla Berglund 2013-02-04 11:46:55 +01:00
parent c70e2e9c3c
commit b39118408e

View File

@ -7,9 +7,9 @@ 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.
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.
Certain features like the threading and image loading functions from GLFW 2.x
have been [removed](http://wiki.glfw.org/wiki/Rationale_for_removing).
@ -57,8 +57,9 @@ 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_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
@ -80,13 +81,8 @@ 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.
The first point is covered in the WIP
[reference manual](http://www.glfw.org/TEMP/3.0/).
### Include the GLFW header file
@ -123,14 +119,32 @@ If you are using an OpenGL extension loading library such as
*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.
#### GLFW header option macros
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_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.
### 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.
The static version of the GLFW library is named `glfw`. 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
@ -139,21 +153,21 @@ must link with `opengl32`. If you are using GLU, you must also link with
#### 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.
The link library for the GLFW DLL is named `glfwdll`. 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.
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.
#### 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
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/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.
@ -176,8 +190,8 @@ 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
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/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.
@ -187,7 +201,7 @@ 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`
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,