mirror of
https://github.com/glfw/glfw.git
synced 2024-11-25 11:35:11 +00:00
Documentation work.
This commit is contained in:
parent
3afa831e28
commit
496567d3f1
@ -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
|
||||||
|
|
||||||
|
@ -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
|
|
||||||
|
|
||||||
*/
|
|
@ -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);
|
||||||
|
@ -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
|
||||||
|
@ -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;
|
||||||
|
@ -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);
|
||||||
|
Loading…
Reference in New Issue
Block a user