gwm17/glfw
1
0
Fork 0
mirror of https://github.com/gwm17/glfw.git synced 2024-11-23 10:48:51 -05:00
Code Issues Projects Releases Wiki Activity

Documentation work.

Browse Source
This commit is contained in:
Camilla Berglund 2013-02-04 11:46:55 +01:00
parent c70e2e9c3c
commit b39118408e
1 changed files with 40 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
README.md
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. creating windows and contexts, reading input, handling events, etc.
Version 3.0 brings a new API with many new features such as multiple windows 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 and contexts, multi-monitor support, EGL and OpenGL ES support, clipboard text
description callback, gamma ramp control, layout-independent keyboard input and support, an error description callback, gamma ramp control, layout-independent
UTF-8 for all strings. keyboard input and UTF-8 for all strings.
Certain features like the threading and image loading functions from GLFW 2.x Certain features like the threading and image loading functions from GLFW 2.x
have been [removed](http://wiki.glfw.org/wiki/Rationale_for_removing). have been [removed](http://wiki.glfw.org/wiki/Rationale_for_removing).
@ -57,8 +57,9 @@ Visual C++ runtime library.
#### EGL specific options #### EGL specific options
`GLFW_USE_EGL` determines whether to use EGL as the context creation API. Note `GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific
that EGL is not yet provided on all supported platforms. 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 `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 `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 * Using the GLFW API
* Compiling and linking programs using the GLFW library * Compiling and linking programs using the GLFW library
The first point is covered in the reference manual and user guide, and we The first point is covered in the WIP
suggest that you read at least the user guide, since it's a good introduction to [reference manual](http://www.glfw.org/TEMP/3.0/).
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 ### 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 *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. 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 ### Link with the right libraries
#### Windows static library #### Windows static library
If you link with the static version of GLFW, it is also necessary to link with The static version of the GLFW library is named `glfw`. When using this
some system libraries that GLFW uses. 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 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 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 #### Windows DLL
When compiling a program that uses the DLL version of GLFW, you need to define The link library for the GLFW DLL is named `glfwdll`. When compiling a program
the `GLFW_DLL` macro *before* any inclusion of the GLFW header. This can be that uses the DLL version of GLFW, you need to define the `GLFW_DLL` macro
done either with a compiler switch or by defining it in your source code. *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, A program using the GLFW DLL does not need to link against any of its
the only library you need to link with for GLFW to work is `glfwdll`. dependencies, but you still have to link against `opengl32` if your program uses
You will still have to link against `opengl32` if your program uses OpenGL, and OpenGL and `glu32` if it uses GLU.
`glu32` if it uses GLU.
#### Unix library #### Unix library
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/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 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` with it. You can use it without installation using the `PKG_CONFIG_PATH`
environment variable. See the documentation for pkg-config for more details. environment variable. See the documentation for pkg-config for more details.
@ -176,8 +190,8 @@ as dependencies.
If you are building from the If you are building from the
command-line, it is recommended that you use pkg-config command-line, it is recommended that you use pkg-config
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/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 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` with it. You can use it without installation using the `PKG_CONFIG_PATH`
environment variable. See the documentation for pkg-config for more details. 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 pkg-config available, the command-line for compiling and linking your
program is: 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 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, and libraries to your command-line using the `-l` and `-framework` switches,