From 496567d3f13782487b213007d037fc2906fc1de6 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Tue, 7 Oct 2014 23:37:59 +0200 Subject: [PATCH] Documentation work. --- docs/Doxyfile.in | 1 - docs/common.dox | 18 ------------------ docs/input.dox | 26 ++++++++++++++++++++------ docs/intro.dox | 25 +++++++++++++++---------- docs/monitor.dox | 33 ++++++++++++++++++--------------- docs/window.dox | 35 ++++++++++++++++++++--------------- 6 files changed, 73 insertions(+), 65 deletions(-) delete mode 100644 docs/common.dox diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index aef79748..8410a850 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -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 diff --git a/docs/common.dox b/docs/common.dox deleted file mode 100644 index e1d7e8b8..00000000 --- a/docs/common.dox +++ /dev/null @@ -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 - -*/ diff --git a/docs/input.dox b/docs/input.dox index ba7ee70e..e5655148 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -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); diff --git a/docs/intro.dox b/docs/intro.dox index 5ad070eb..5304678e 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -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. -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 diff --git a/docs/monitor.dox b/docs/monitor.dox index 28e3ffb5..a42d195b 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -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; diff --git a/docs/window.dox b/docs/window.dox index 1de4ba81..35031607 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -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);