mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-22 13:04:35 +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/window.dox \
@GLFW_SOURCE_DIR@/docs/input.dox \
@GLFW_SOURCE_DIR@/docs/common.dox \
@GLFW_SOURCE_DIR@/docs/rift.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).
@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
glfwSetCharCallback(window, character_callback);
@endcode
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
void character_callback(GLFWwindow* window, unsigned int codepoint)
@ -163,9 +177,9 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
}
@endcode
If you wish to receive all Unicode code point events generated by the system, or
just want to know exactly what modifier keys were used, set a character with
modifiers callback.
If you wish to receive even those Unicode code points generated with modifier
key combinations that a plain text field would ignore, or just want to know
exactly what modifier keys were used, set a character with modifiers callback.
@code
glfwSetCharCallback(window, charmods_callback);

25
docs/intro.dox
View File

@ -114,19 +114,24 @@ keep the description string.
@section coordinate_systems Coordinate systems
GLFW has two primary coordinate systems: the _virtual screen_ and the window
_client area_. Both use the same unit: _virtual screen coordinates_, or just
_screen coordinates_, which don't necessarily correspond to pixels.
_client area_ or _content area_. Both use the same unit: _virtual screen
coordinates_, or just _screen coordinates_, which don't necessarily correspond
to pixels.
<img src="spaces.svg" width="90%" />
Window and monitor positions are specified relative to the upper-left corners of
their content areas, while cursor positions are specified relative to the window
client area.
Both the virtual screen and the client area coordinate systems have the X-axis
pointing to the right and the Y-axis pointing down.
The origin of the window client area coordinate system is also the position of
the window, meaning you can translate client area coordinates to the virtual
screen by adding the window position. The window frame, when present, extend
out from the client area but does not affect the window position.
Window and monitor positions are specified as the position of the upper-left
corners of their content areas relative to the virtual screen, while cursor
positions are specified relative to a window's client area.
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
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
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
which monitor the window is currently on.
which monitor the window is currently considered to be on.
@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 gamma ramp. One of the monitors is the primary monitor.
The virtual position of a monitor is in screen coordinates and, together with
the current video mode, describes the viewports that the connected monitors
provide into the virtual desktop that spans them.
The virtual position of a monitor is in
[screen coordinates](@ref coordinate_systems) and, together with the current
video mode, describes the viewports that the connected monitors provide into the
virtual desktop that spans them.
@subsection monitor_monitors Retrieving monitors
@ -86,15 +87,13 @@ a gamma ramp.
@subsection monitor_modes Video modes
Although GLFW generally does a good job at selecting a suitable video
mode for you when you open a full screen window, it is sometimes useful to
know exactly which modes are available on a certain system. For example,
you may want to present the user with a list of video modes to select
from.
GLFW generally does a good job selecting a suitable video mode when you create
a full screen window, but it is sometimes useful to know exactly which video
modes are supported.
To get a list of supported video modes, you can use the function @ref
glfwGetVideoModes. See the reference documentation for the lifetime of the
returned array.
Video modes are represented as @ref GLFWvidmode structures. You can get an
array of the video modes supported by a monitor with @ref glfwGetVideoModes.
See the reference documentation for the lifetime of the returned array.
@code
int count;
@ -102,16 +101,19 @@ GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
@endcode
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
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@endcode
The resolution of a video mode is specified in
[screen coordinates](@ref coordinate_systems), not pixels.
@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
current _resolution_, i.e. the width and height of its current
[video mode](@ref monitor_modes).
@ -131,8 +133,9 @@ const double dpi = mode->width / (widthMM / 25.4);
@subsection monitor_pos Virtual position
The position of the monitor on the virtual desktop, in screen coordinates, can
be retrieved with @ref glfwGetMonitorPos.
The position of the monitor on the virtual desktop, in
[screen coordinates](@ref coordinate_systems), can be retrieved with @ref
glfwGetMonitorPos.
@code
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
preference.
@note Accumulation buffers are a legacy OpenGL feature and should not be used in
new code.
@par
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_DONT_CARE` means the application has no preference.
@note Auxiliary buffers are a legacy OpenGL feature and should not be used in
new code.
@par
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
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 is 3.0 or above. If OpenGL S is requested, this hint is ignored.
@par
Forward-compatibility is described in detail in the
[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,
this hint is ignored.
@par
OpenGL profiles are described in detail in the
[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
not be flushed on release.
@par
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)
extension.
@ -384,8 +389,9 @@ void window_close_callback(GLFWwindow* window)
@subsection window_size Size
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
window. The window system may impose limits on window size.
mode windows, this sets the size, in
[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
glfwSetWindowSize(window, 640, 480);
@ -403,8 +409,8 @@ the system, set a size callback.
glfwSetWindowSizeCallback(window, window_size_callback);
@endcode
The callback function receives the new size of the client area of the window
when it is resized.
The callback function receives the new size, in screen coordinates, of the
client area of the window when it is resized.
@code
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
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
and not screen coordinates. On some platforms screen coordinates and pixels are
the same, but this is not the case on all platforms supported by GLFW. There is
a second set of functions to retrieve the size in pixels of the framebuffer of
a window.
pixels. The size you pass into `glViewport`, for example, should be in pixels.
On some machines screen coordinates and pixels are the same, but on others they
will not be. There is a second set of functions to retrieve the size, in
pixels, of the framebuffer of a window.
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.
@ -483,8 +488,8 @@ a high-DPI one.
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
client area has the specified screen coordinates. The window system may put
limitats on window placement.
client area has the specified [screen coordinates](@ref coordinate_systems).
The window system may put limitats on window placement.
@code
glfwSetWindowPos(window, 100, 100);