Commit 8282a8fb authored by Camilla Berglund's avatar Camilla Berglund
Browse files

Documentation work.

parent 7b5b33ee
......@@ -307,7 +307,7 @@ GLFW.
`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
* Changed `glfwCreateWindow` 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
......@@ -367,7 +367,7 @@ GLFW.
counterparts
* [Cocoa] Bugfix: The `NSOpenGLPFAFullScreen` pixel format attribute caused
creation to fail on some machines
* [Cocoa] Bugfix: `glfwOpenWindow` did not properly enforce the
* [Cocoa] Bugfix: `glfwCreateWindow` 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
......
......@@ -37,8 +37,8 @@ process events. If the running window manager does not support this protocol,
the user will not be notified if the application locks up.
GLFW uses the EWMH `_NET_WM_STATE` protocol to tell the window manager to make
the GLFW window fullscreen. If the running window manager does not support this
protocol, fullscreen windows may not work properly. GLFW has a fallback code
the GLFW window full screen. If the running window manager does not support this
protocol, full screen windows may not work properly. GLFW has a fallback code
path in case this protocol is unavailable, but every window manager behaves
slightly differently in this regard.
......@@ -86,7 +86,7 @@ neither is available, no other extensions are used and many GLFW features
related to context creation will have no effect or cause errors when used.
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
synchronization (or "vsync"). Where this extension is unavailable, calling @ref
synchronization (or 'vsync'). Where this extension is unavailable, calling @ref
glfwSwapInterval will have no effect.
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
......
......@@ -5,10 +5,10 @@
@tableofcontents
This is a transition guide for moving from GLFW 2 to 3. It describes what has
changed or been removed, but does *not* include entirely new features unless
they are required when moving an existing code base onto the new API. For example,
use of the new multi-monitor functions are required to create fullscreen windows
with GLFW 3.
changed or been removed, but does *not* include
[new features](@ref news) unless they are required when moving an existing code
base onto the new API. For example, use of the new multi-monitor functions are
required to create full screen windows with GLFW 3.
@section moving_removed Removed features
......@@ -31,8 +31,9 @@ TinyCThread.
However, GLFW 3 has better support for *use from multiple threads* than GLFW
2 had. Contexts can be made current on and rendered with from secondary
threads, and the documentation explicitly states which functions may or may not
be used from secondary threads.
threads, and the documentation explicitly states which functions may be used
from secondary threads and which may only be used from the main thread, i.e. the
thread that calls main.
@subsection moving_image Image and texture loading
......@@ -92,8 +93,8 @@ The Win32 port of GLFW 3 will not compile in
However, because the use of the Unicode version of the Win32 API doesn't affect
the process as a whole, but only those windows created using it, it's perfectly
possible to call MBCS functions from other parts of the same application.
Therefore, even if an application using GLFW uses MBCS mode, there's no need for
GLFW itself to support it.
Therefore, even if an application using GLFW has MBCS mode code, there's no need
for GLFW itself to support it.
@subsection moving_windows Support for versions of Windows older than XP
......@@ -121,7 +122,7 @@ version of Windows.
The ability to disable and capture system-wide hotkeys like Alt+Tab has been
removed. Modern applications, whether they're games, scientific visualisations
or something else, are nowadays expected to be good desktop citizens and allow
these hotkeys to function even when running in fullscreen mode.
these hotkeys to function even when running in full screen mode.
@subsection moving_autopoll Automatic polling of events
......@@ -159,7 +160,7 @@ to an opaque struct.
@subsection moving_monitor Multi-monitor support
GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
type and a set of related functions. To request a fullscreen mode window,
type and a set of related functions. To request a full screen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
similar to that of GLFW 2.
......@@ -211,9 +212,9 @@ having to remember whether to check for `'a'` or `'A'`, you now check for
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
now returns all available modes for a specific monitor instead of requiring you
to guess how large an array you need. The `glfwGetDesktopMode` function has
been replaced by @ref glfwGetVideoMode, which returns the current mode of
a monitor.
to guess how large an array you need. The `glfwGetDesktopMode` function, which
had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
returns the current mode of a monitor.
@subsection moving_cursor Cursor positioning
......
......@@ -32,7 +32,7 @@ select which context is current on a given thread.
GLFW now explicitly supports multiple monitors. They can be enumerated with
@ref glfwGetMonitors, queried with @ref glfwGetVideoModes, @ref
glfwGetMonitorPos, @ref glfwGetMonitorName and @ref glfwGetMonitorPhysicalSize,
and specified at window creation to make the newly created window fullscren on
and specified at window creation to make the newly created window full screen on
that specific monitor.
......@@ -65,9 +65,9 @@ GLFW now supports the creation of OpenGL ES contexts, by setting the
contexts are supported. Note that GLFW *does not implement* OpenGL ES, so your
driver must provide support in a way usable by GLFW. Modern nVidia and Intel
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
AMD currently only provides an EGL implementation.
AMD provides an EGL implementation instead.
GLFW now has an (experimental) EGL context creation backend, which can be
GLFW now has an (experimental) EGL context creation back end, which can be
selected through CMake options.
......@@ -118,7 +118,7 @@ to @ref glfwCreateWindow.
Windows can now be hidden with @ref glfwHideWindow, shown using @ref
glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint.
This allows for offscreen rendering in a way compatible with most drivers, as
This allows for off-screen rendering in a way compatible with most drivers, as
well as moving a window to a specific position before showing it.
*/
......@@ -110,8 +110,8 @@ glfwSetErrorCallback(error_callback);
@section quick_create_window Creating a window and context
The window (and its context) is created with @ref glfwCreateWindow, which
returns a handle to the created window. For example, this creates an 640 by 480
pixels windowed mode window:
returns a handle to the created window. For example, this creates a 640 by 480
windowed mode window:
@code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
......@@ -131,16 +131,16 @@ if (!window)
This handle is then passed to all window related functions, and is provided to
you along with input events, so you know which window received the input.
To create a fullscreen window, you need to specify which monitor the window
To create a full screen window, you need to specify which monitor the window
should use. In most cases, the user's primary monitor is a good choice. You
can get this with @ref glfwGetPrimaryMonitor. To make the above window
fullscreen, just pass along the monitor handle:
full screen, just pass along the monitor handle:
@code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
@endcode
Fullscreen windows cover the entire screen, have no border or decorations, and
Full screen windows cover the entire screen, have no border or decorations, and
change the monitor's resolution to the one most closely matching the requested
window size.
......@@ -272,8 +272,8 @@ keyboard input, it's possible to create a simple program.
@snippet simple.c code
This program creates a 640 by 480 pixels window and runs a loop clearing the
screen, rendering a triangle and processing events until the user closes the
This program creates a 640 by 480 windowed mode window and runs a loop clearing
the screen, rendering a triangle and processing events until the user closes the
window. It can be found in the source distribution as `examples/simple.c`, and
is by default compiled along with all other examples when you build GLFW.
......
......@@ -9,7 +9,11 @@ a fullscreen window.
@section window_object Window objects
Text here.
The @ref GLFWwindow object encapsulates both a window and a context. They are
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
@ref glfwTerminate, if any remain). As the window and context are inseparably
linked, the window handle (i.e. window object pointer) is used as a context
handle as well, for example when calling @ref glfwMakeContextCurrent.
@section window_hints Window hints
......@@ -79,9 +83,13 @@ with.
For OpenGL, these hints are *not* hard constraints, as they don't have to
match exactly, but @ref glfwCreateWindow will still fail if the resulting
OpenGL version is less than the one requested. It is therefore perfectly
safe to use the default of version 1.0 for legacy code and you will still
safe to use the default of version 1.0 for legacy code and you may still
get backwards-compatible contexts of version 3.0 and above when available.
While there is no way to ask the driver for a context of the highest supported
version, most drivers provide this when you ask GLFW for a version
1.0 context.
For OpenGL ES, these hints are hard constraints, as there is no backward
compatibility between OpenGL ES versions.
......@@ -120,7 +128,8 @@ visible. This hint is ignored for fullscreen windows.
The `GLFW_DECORATED` hint specifies whether the window will have window
decorations such as a border, a close widget, etc. This hint is ignored for
fullscreen windows.
fullscreen windows. Note that even though a window may lack a close widget, it
is usually still possible for the user to generate close events.
@subsection window_hints_values Supported and default values
......@@ -155,7 +164,14 @@ fullscreen windows.
@section window_closing Window closing
Text here.
When the user attempts to close the window, for example by clicking the close
widget or using a key chord like Alt+F4, the window's close flag is set and then
its close callback is called. The window is not actually destroyed and, unless
you are monitoring the close flag, nothing further happens.
If you do not want the close flag to be set, it can be cleared again from the
close callback (or from any other point in your program) with @ref
glfwSetWindowShouldClose.
@section window_dims Window dimensions
......
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment