mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-12 17:51:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work.

Browse Source
This commit is contained in:
Camilla Berglund 2014-10-07 23:37:59 +02:00
parent 3afa831e28
commit 496567d3f1
6 changed files with 73 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Doxyfile.in
View File

@ -666,7 +666,6 @@ INPUT = @GLFW_INTERNAL_DOCS@ \
@GLFW_SOURCE_DIR@/docs/monitor.dox \ @GLFW_SOURCE_DIR@/docs/monitor.dox \
@GLFW_SOURCE_DIR@/docs/window.dox \ @GLFW_SOURCE_DIR@/docs/window.dox \
@GLFW_SOURCE_DIR@/docs/input.dox \ @GLFW_SOURCE_DIR@/docs/input.dox \
@GLFW_SOURCE_DIR@/docs/common.dox \
@GLFW_SOURCE_DIR@/docs/rift.dox \ @GLFW_SOURCE_DIR@/docs/rift.dox \
@GLFW_SOURCE_DIR@/docs/compat.dox @GLFW_SOURCE_DIR@/docs/compat.dox

18
docs/common.dox
View File

@ -1,18 +0,0 @@
/*!
@page common Common tasks
@tableofcontents
This guide explains how to
@section common_full_screen Windowed full screen mode
@section common_window_pos Initial window position
GLFW comes with the `windows` test program, which illustrates this method.
@section common_fps_camera First-person camera controls
*/

26
docs/input.dox
View File

@ -146,16 +146,30 @@ The `GLFW_KEY_LAST` constant holds the highest value of any
[named key](@ref keys). [named key](@ref keys).
@subsection input_char Unicode character input @subsection input_char Text input
If you wish to receive Unicode code point input, set a character callback. GLFW supports text input in the form of a stream of
[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
operating system text input system. Unlike key input, text input obeys keyboard
layouts and modifier keys and supports composing characters using
[dead keys](https://en.wikipedia.org/wiki/Dead_key). Once received, you can
encode the code points into
[UTF-8](https://en.wikipedia.org/wiki/UTF-8) or any other encoding you prefer.
Because an `unsigned int` is 32 bits long on all platforms supported by GLFW,
you can treat the code point argument as native endian
[UTF-32](https://en.wikipedia.org/wiki/UTF-32).
There are two callbacks for receiving Unicode code points. If you wish to
offer regular text input, set a character callback.
@code @code
glfwSetCharCallback(window, character_callback); glfwSetCharCallback(window, character_callback);
@endcode @endcode
The callback function receives Unicode code points for key events that would The callback function receives Unicode code points for key events that would
have led to regular text input on that platform. have led to regular text input and generally behaves as a standard text field on
that platform.
@code @code
void character_callback(GLFWwindow* window, unsigned int codepoint) void character_callback(GLFWwindow* window, unsigned int codepoint)
@ -163,9 +177,9 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
} }
@endcode @endcode
If you wish to receive all Unicode code point events generated by the system, or If you wish to receive even those Unicode code points generated with modifier
just want to know exactly what modifier keys were used, set a character with key combinations that a plain text field would ignore, or just want to know
modifiers callback. exactly what modifier keys were used, set a character with modifiers callback.
@code @code
glfwSetCharCallback(window, charmods_callback); glfwSetCharCallback(window, charmods_callback);

25
docs/intro.dox
View File

@ -114,19 +114,24 @@ keep the description string.
@section coordinate_systems Coordinate systems @section coordinate_systems Coordinate systems
GLFW has two primary coordinate systems: the _virtual screen_ and the window GLFW has two primary coordinate systems: the _virtual screen_ and the window
_client area_. Both use the same unit: _virtual screen coordinates_, or just _client area_ or _content area_. Both use the same unit: _virtual screen
_screen coordinates_, which don't necessarily correspond to pixels. coordinates_, or just _screen coordinates_, which don't necessarily correspond
to pixels.
<img src="spaces.svg" width="90%" /> <img src="spaces.svg" width="90%" />
Window and monitor positions are specified relative to the upper-left corners of Both the virtual screen and the client area coordinate systems have the X-axis
their content areas, while cursor positions are specified relative to the window pointing to the right and the Y-axis pointing down.
client area.
The origin of the window client area coordinate system is also the position of Window and monitor positions are specified as the position of the upper-left
the window, meaning you can translate client area coordinates to the virtual corners of their content areas relative to the virtual screen, while cursor
screen by adding the window position. The window frame, when present, extend positions are specified relative to a window's client area.
out from the client area but does not affect the window position.
Because the origin of the window's client area coordinate system is also the
point from which the window position is specified, you can translate client area
coordinates to the virtual screen by adding the window position. The window
frame, when present, extends out from the client area but does not affect the
window position.
Almost all positions and sizes in GLFW are measured in screen coordinates Almost all positions and sizes in GLFW are measured in screen coordinates
relative to one of the two origins above. This includes cursor positions, relative to one of the two origins above. This includes cursor positions,
@ -140,7 +145,7 @@ measured in pixels.
Pixels and screen coordinates may map 1:1 on your machine, but they won't on Pixels and screen coordinates may map 1:1 on your machine, but they won't on
every other machine, for example on a Mac with a Retina display. The ratio every other machine, for example on a Mac with a Retina display. The ratio
between screen coordinates and pixels may also change at run-time depending on between screen coordinates and pixels may also change at run-time depending on
which monitor the window is currently on. which monitor the window is currently considered to be on.
@section guarantees_limitations Guarantees and limitations @section guarantees_limitations Guarantees and limitations

33
docs/monitor.dox
View File

@ -28,9 +28,10 @@ Each monitor has a current video mode, a list of supported video modes,
a virtual position, a human-readable name, an estimated physical size and a virtual position, a human-readable name, an estimated physical size and
a gamma ramp. One of the monitors is the primary monitor. a gamma ramp. One of the monitors is the primary monitor.
The virtual position of a monitor is in screen coordinates and, together with The virtual position of a monitor is in
the current video mode, describes the viewports that the connected monitors [screen coordinates](@ref coordinate_systems) and, together with the current
provide into the virtual desktop that spans them. video mode, describes the viewports that the connected monitors provide into the
virtual desktop that spans them.
@subsection monitor_monitors Retrieving monitors @subsection monitor_monitors Retrieving monitors
@ -86,15 +87,13 @@ a gamma ramp.
@subsection monitor_modes Video modes @subsection monitor_modes Video modes
Although GLFW generally does a good job at selecting a suitable video GLFW generally does a good job selecting a suitable video mode when you create
mode for you when you open a full screen window, it is sometimes useful to a full screen window, but it is sometimes useful to know exactly which video
know exactly which modes are available on a certain system. For example, modes are supported.
you may want to present the user with a list of video modes to select
from.
To get a list of supported video modes, you can use the function @ref Video modes are represented as @ref GLFWvidmode structures. You can get an
glfwGetVideoModes. See the reference documentation for the lifetime of the array of the video modes supported by a monitor with @ref glfwGetVideoModes.
returned array. See the reference documentation for the lifetime of the returned array.
@code @code
int count; int count;
@ -102,16 +101,19 @@ GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
@endcode @endcode
To get the current video mode of a monitor call @ref glfwGetVideoMode. See the To get the current video mode of a monitor call @ref glfwGetVideoMode. See the
reference documentation for the lifetime of the returned structure. reference documentation for the lifetime of the returned pointer.
@code @code
const GLFWvidmode* mode = glfwGetVideoMode(monitor); const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@endcode @endcode
The resolution of a video mode is specified in
[screen coordinates](@ref coordinate_systems), not pixels.
@subsection monitor_size Physical size @subsection monitor_size Physical size
The physical size in millimetres of a monitor, or an estimation of it, can be The physical size of a monitor in millimetres, or an estimation of it, can be
retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its
current _resolution_, i.e. the width and height of its current current _resolution_, i.e. the width and height of its current
[video mode](@ref monitor_modes). [video mode](@ref monitor_modes).
@ -131,8 +133,9 @@ const double dpi = mode->width / (widthMM / 25.4);
@subsection monitor_pos Virtual position @subsection monitor_pos Virtual position
The position of the monitor on the virtual desktop, in screen coordinates, can The position of the monitor on the virtual desktop, in
be retrieved with @ref glfwGetMonitorPos. [screen coordinates](@ref coordinate_systems), can be retrieved with @ref
glfwGetMonitorPos.
@code @code
int xpos, ypos; int xpos, ypos;

35
docs/window.dox
View File

@ -187,14 +187,16 @@ application has no preference.
of the accumulation buffer. `GLFW_DONT_CARE` means the application has no of the accumulation buffer. `GLFW_DONT_CARE` means the application has no
preference. preference.
@note Accumulation buffers are a legacy OpenGL feature and should not be used in @par
new code. Accumulation buffers are a legacy OpenGL feature and should not be used in new
code.
`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers. `GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
`GLFW_DONT_CARE` means the application has no preference. `GLFW_DONT_CARE` means the application has no preference.
@note Auxiliary buffers are a legacy OpenGL feature and should not be used in @par
new code. Auxiliary buffers are a legacy OpenGL feature and should not be used in new
code.
`GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard `GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard
constraint. constraint.
@ -251,6 +253,7 @@ forward-compatible, i.e. one where all functionality deprecated in the requested
version of OpenGL is removed. This may only be used if the requested OpenGL version of OpenGL is removed. This may only be used if the requested OpenGL
version is 3.0 or above. If OpenGL S is requested, this hint is ignored. version is 3.0 or above. If OpenGL S is requested, this hint is ignored.
@par
Forward-compatibility is described in detail in the Forward-compatibility is described in detail in the
[OpenGL Reference Manual](https://www.opengl.org/registry/). [OpenGL Reference Manual](https://www.opengl.org/registry/).
@ -265,6 +268,7 @@ a specific profile. If requesting an OpenGL version below 3.2,
`GLFW_OPENGL_ANY_PROFILE` must be used. If another OpenGL ES is requested, `GLFW_OPENGL_ANY_PROFILE` must be used. If another OpenGL ES is requested,
this hint is ignored. this hint is ignored.
@par
OpenGL profiles are described in detail in the OpenGL profiles are described in detail in the
[OpenGL Reference Manual](https://www.opengl.org/registry/). [OpenGL Reference Manual](https://www.opengl.org/registry/).
@ -282,6 +286,7 @@ the pipeline will be flushed whenever the context is released from being the
current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
not be flushed on release. not be flushed on release.
@par
Context release behaviors are described in detail by the Context release behaviors are described in detail by the
[GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt) [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
extension. extension.
@ -384,8 +389,9 @@ void window_close_callback(GLFWwindow* window)
@subsection window_size Size @subsection window_size Size
The size of a window can be changed with @ref glfwSetWindowSize. For windowed The size of a window can be changed with @ref glfwSetWindowSize. For windowed
mode windows, this sets the size of the _client area_ or _content area_ of the mode windows, this sets the size, in
window. The window system may impose limits on window size. [screen coordinates](@ref coordinate_systems) of the _client area_ or _content
area_ of the window. The window system may impose limits on window size.
@code @code
glfwSetWindowSize(window, 640, 480); glfwSetWindowSize(window, 640, 480);
@ -403,8 +409,8 @@ the system, set a size callback.
glfwSetWindowSizeCallback(window, window_size_callback); glfwSetWindowSizeCallback(window, window_size_callback);
@endcode @endcode
The callback function receives the new size of the client area of the window The callback function receives the new size, in screen coordinates, of the
when it is resized. client area of the window when it is resized.
@code @code
void window_size_callback(GLFWwindow* window, int width, int height) void window_size_callback(GLFWwindow* window, int width, int height)
@ -442,11 +448,10 @@ distances and not coordinates, they are always zero or positive.
@subsection window_fbsize Framebuffer size @subsection window_fbsize Framebuffer size
While the size of a window is measured in screen coordinates, OpenGL works with While the size of a window is measured in screen coordinates, OpenGL works with
pixels. The size you pass into `glViewport`, for example, should be in pixels pixels. The size you pass into `glViewport`, for example, should be in pixels.
and not screen coordinates. On some platforms screen coordinates and pixels are On some machines screen coordinates and pixels are the same, but on others they
the same, but this is not the case on all platforms supported by GLFW. There is will not be. There is a second set of functions to retrieve the size, in
a second set of functions to retrieve the size in pixels of the framebuffer of pixels, of the framebuffer of a window.
a window.
If you wish to be notified when the framebuffer of a window is resized, whether If you wish to be notified when the framebuffer of a window is resized, whether
by the user or the system, set a size callback. by the user or the system, set a size callback.
@ -483,8 +488,8 @@ a high-DPI one.
The position of a windowed-mode window can be changed with @ref The position of a windowed-mode window can be changed with @ref
glfwSetWindowPos. This moves the window so that the upper-left corner of its glfwSetWindowPos. This moves the window so that the upper-left corner of its
client area has the specified screen coordinates. The window system may put client area has the specified [screen coordinates](@ref coordinate_systems).
limitats on window placement. The window system may put limitats on window placement.
@code @code
glfwSetWindowPos(window, 100, 100); glfwSetWindowPos(window, 100, 100);