From 4b7ae4918b3df0e51edcde3e472c36a1d512f2ce Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Sun, 7 Jul 2013 12:06:59 +0200 Subject: [PATCH] Documentation work. --- docs/monitor.dox | 5 ++- docs/quick.dox | 6 +-- docs/window.dox | 97 ++++++++++++++++++++++++++++++++++++++++---- include/GLFW/glfw3.h | 8 +++- 4 files changed, 104 insertions(+), 12 deletions(-) diff --git a/docs/monitor.dox b/docs/monitor.dox index 808dc2cc..a3ada5a1 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -9,6 +9,9 @@ The @ref GLFWmonitor object represents a currently connected monitor. + +@section monitor_monitors Retrieving monitors + The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is usually the user's preferred monitor and the one with global UI elements like task bar or menu bar. @@ -25,7 +28,7 @@ GLFWmonitor** monitors = glfwGetMonitors(&count); @endcode -@section monitor_modes Querying video modes +@section monitor_modes Retrieving 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 diff --git a/docs/quick.dox b/docs/quick.dox index 1899c6a8..aa32ff33 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -140,9 +140,9 @@ full screen, just pass along the monitor handle: GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL); @endcode -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. +Full screen windows cover the entire display area of a monitor, have no border +or decorations, and change the monitor's resolution to the one most closely +matching the requested window size. When you are done with the window, destroy it with the @ref glfwDestroyWindow function. diff --git a/docs/window.dox b/docs/window.dox index 1ff02735..c91a67d9 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -6,7 +6,7 @@ The primary purpose of GLFW is to provide a simple interface to window management and OpenGL and OpenGL ES context creation. GLFW supports multiple -windows, which can be either a normal desktop window or a fullscreen window. +windows, which can be either a normal desktop window or a full screen window. @section window_object Window handles @@ -17,6 +17,51 @@ created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or linked, the object pointer is used as both a context and window handle. +@section window_creation Window creation + +The window and its context are created with @ref glfwCreateWindow, which +returns a handle to the created window object. For example, this creates a 640 +by 480 windowed mode window: + +@code +GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); +@endcode + +If window creation fails, `NULL` will be returned, so you need to check whether +it did. + +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 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. For +more information about monitors, see the @ref monitor. + +@code +GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL); +@endcode + +Full screen windows cover the entire display area of a monitor, have no border +or decorations, and change the monitor's resolution to the one most closely +matching the requested window size. + +For more control over how the window and its context are created, see @ref +window_hints below. + + +@section window_destruction Window destruction + +When you are done with the window, destroy it with the @ref glfwDestroyWindow +function. + +@code +glfwDestroyWindow(window); +@endcode + +Once this function is called, no more events will be delivered for that window +and its handle becomes invalid. + + @section window_hints Window creation hints There are a number of hints that can be set before the creation of a window and @@ -54,14 +99,14 @@ Hints that do not apply to a given type of window or context are ignored. The `GLFW_RESIZABLE` hint specifies whether the window will be resizable *by the user*. The window will still be resizable using the @ref glfwSetWindowSize -function. This hint is ignored for fullscreen windows. +function. This hint is ignored for full screen windows. The `GLFW_VISIBLE` hint specifies whether the window will be initially -visible. This hint is ignored for fullscreen windows. +visible. This hint is ignored for full screen 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. Note that even though a window may lack a close widget, it +full screen windows. Note that even though a window may lack a close widget, it is usually still possible for the user to generate close events. @@ -227,13 +272,11 @@ the system, you can set the size callback with @ref glfwSetWindowSizeCallback. glfwSetWindowSizeCallback(window, window_size_callback); @endcode -The callback function receives the new size of the client area of the window, -which can for example be used to update the viewport. +The callback function receives the new size of the client area of the window. @code void window_size_callback(GLFWwindow* window, int width, int height) { - glViewport(0, 0, width, height); } @endcode @@ -243,9 +286,49 @@ a window. @code int width, height; glfwGetWindowSize(window, &width, &height); +@endcode + + +@section window_fbsize Window 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. + +If you wish to be notified when the framebuffer of a window is resized, whether +by the user or the system, you can set the size callback with @ref +glfwSetFramebufferSizeCallback. + +@code +glfwSetFramebufferSizeCallback(window, framebuffer_size_callback); +@endcode + +The callback function receives the new size of the client area of the window, +which can for example be used to update the OpenGL viewport. + +@code +void framebuffer_size_callback(GLFWwindow* window, int width, int height) +{ + glViewport(0, 0, width, height); +} +@endcode + +There is also @ref glfwGetFramebufferSize for directly retrieving the current +size of the framebuffer of a window. + +@code +int width, height; +glfwGetFramebufferSize(window, &width, &height); glViewport(0, 0, width, height); @endcode +Note that the size of a framebuffer may change independently of the size of +a window, for example if the window is dragged between a regular monitor and +a high-DPI one. + @section window_pos Window position diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 01259e1a..bb97903c 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -1208,10 +1208,16 @@ GLFWAPI void glfwWindowHint(int target, int hint); * attributes of the created window and context, use queries like @ref * glfwGetWindowAttrib and @ref glfwGetWindowSize. * + * To create a full screen window, you need to specify the monitor to use. If + * no monitor is specified, windowed mode will be used. Unless you have a way + * for the user to choose a specific monitor, it is recommended that you pick + * the primary monitor. For more information on how to retrieve monitors, see + * @ref monitor_monitors. + * * To create the window at a specific position, make it initially invisible * using the `GLFW_VISIBLE` window hint, set its position and then show it. * - * If a fullscreen window is active, the screensaver is prohibited from + * If a full screen window is active, the screensaver is prohibited from * starting. * * @param[in] width The desired width, in screen coordinates, of the window.