From 1cbc89e7f0d160768a789482a2b20d3a3a9c74b2 Mon Sep 17 00:00:00 2001 From: fayjf Date: Mon, 5 Sep 2011 13:07:43 +0000 Subject: [PATCH] Putting in Diederick Niehorster's documentation updates per e-mail dated 9/5/2011 at 1:26 AM git-svn-id: https://svn.code.sf.net/p/freeglut/code/trunk@936 7f0cb862-5218-0410-a997-914c9d46530a --- freeglut/web-src/docs/api.php | 184 ++++++++++++++++++++++++++++++---- 1 file changed, 166 insertions(+), 18 deletions(-) diff --git a/freeglut/web-src/docs/api.php b/freeglut/web-src/docs/api.php index de9ba32..1466dbf 100644 --- a/freeglut/web-src/docs/api.php +++ b/freeglut/web-src/docs/api.php @@ -80,7 +80,7 @@ contained herein.
  • glutPositionWindow
  • glutShowWindow, glutHideWindow, glutIconifyWindow
  • glutPushWindow, glutPopWindow
    • -
  • glutFullScreen
    • +
  • glutFullScreen, glutLeaveFullScreen, glutFullScreenToggle
  • Display Functions @@ -261,7 +261,36 @@ specifies the application program interface to the freeglut library.

    3.1 Design Philosophy

    -

    3.2 Conventions

    +

    3.2 Conventions

    + +

    +In developing the freeglut library, we have taken careful steps +to ensure consistency in function operation across the board, in such a +manner as to maintain compatibility with GLUT's behavior whenever +possible. In this section some of the important conventions of FreeGLUT, +and their compatibility with GLUT, are made explicit. +

    + +

    3.2.1 Window placement and size

    + +

    +There is considerable confusion about the "right thing to do" concerning +window size and position. GLUT itself is not consistent between +Windows and UNIX/X11; since platform independence is a virtue for +freeglut, we decided to break with GLUT's behaviour.
    +Under UNIX/X11, it is apparently not possible to get the window border +sizes in order to subtract them off the window's initial position until +some time after the window has been created. Therefore we decided on +the following behavior, both under Windows and under UNIX/X11: +

    +

    3.3 Terminology

    @@ -299,7 +328,15 @@ continue, whether GLUT should return control to the main program, or whether GLUT should simply exit (the default).

    -

    3.4.3 Changes to Callbacks

    +

    3.4.3 Fullscreen windows

    + +

    +Function to leave fullscreen window mode, glutLeaveFullScreen, +or to toggle between fullscreen and normal window mode, +glutFullScreenToggle, have been added. +

    + +

    3.4.4 Changes to Callbacks

    Several new callbacks have been added and several callbacks which were specific @@ -315,7 +352,7 @@ callbacks. If the user has a need for an unsupported callback he should contact the freeglut development team.

    -

    3.4.4 String Rendering

    +

    3.4.5 String Rendering

    New functions have been added to render full character strings (including @@ -324,14 +361,14 @@ functions return the widths of character strings and the font heights, in pixels for bitmapped fonts and in OpenGL units for the stroke fonts.

    -

    3.4.5 Geometry Rendering

    +

    3.4.6 Geometry Rendering

    Two functions have been added to render a wireframe and a solid rhombic dodecahedron.

    -

    3.4.5 Extension Function Queries

    +

    3.4.7 Extension Function Queries

    glutGetProcAddress is a wrapper for the glXGetProcAddressARB and wglGetProcAddress @@ -364,8 +401,8 @@ functions specify a desired position and size for windows that The position is measured in pixels from the upper left hand corner of the screen, with "x" increasing to the right and "y" increasing towards the bottom of the screen. The size is measured in pixels. Freeglut - does not promise to follow these specifications in creating its windows, -it certainly makes an attempt to. +does not promise to follow these specifications in creating its windows, +but it certainly makes an attempt to.

    @@ -373,10 +410,14 @@ The position and size of a window are a matter of some subtlety. Most windows have a usable area surrounded by a border and with a title bar on the top. The border and title bar are commonly called "decorations." The position of the window unfortunately varies with the operating system. -On Linux, it is the coordinates of the upper left-hand corner of its -decorations. On Windows, it is the coordinates of the upper left hand -corner of its usable interior. For both operating systems, the size of -the window is the size of the usable interior. +On both Linux and Windows, you specify the coordinates of the upper +left-hand corner of the window's decorations. Also for both operating +systems, the size of the window is the size of the usable interior.
    +With glutGet information can be acquired about the current +window's size, position and decorations. Note however that according to +FreeGLUT's conventions, the information +returned about the window coordinates does not correspond to the +coordinates used when setting window position.

    @@ -535,7 +576,40 @@ Consortium and ask for the code to be fixed.

    6.9 glutPushWindow, glutPopWindow

    -

    6.10 glutFullScreen

    +

    6.10 glutFullScreen, glutLeaveFullScreen, glutFullScreenToggle

    + +

    +The glutFullScreen, glutLeaveFullScreen and +glutFullScreenToggle functions are used to transition the +current window between fullscreen and normal mode. +

    + +

    Usage

    + +

    void glutFullScreen ( void );
    +void glutLeaveFullScreen ( void );
    +void glutFullScreenToggle ( void ); +

    + +

    Description

    + +

    +The glutFullScreen function causes the current window to enter +fullscreen mode, glutLeaveFullScreen to go back to the window +size and position as it was before entering fullscreen mode, and +glutFullScreenToggle toggles between fullscreen and normal +mode.
    +In multi-monitor setups on Windows 2000 and newer, the window will +become fullscreen on the monitor that it overlaps the most.
    +Calls to these functions are ignored for gamemode and child windows.
    +Use glutGet(GLUT_FULL_SCREEN) to query fullscreen state of +current window. +

    + +

    Changes From GLUT

    + +

    GLUT does not include the glutLeaveFullScreen and +glutFullScreenToggle functions.

    7. Display Functions

    @@ -1132,15 +1206,22 @@ The following state variables may be queried with glutGet. The returned value is an integer.

    +

    +example:
    +int windowLeft = glutGet(GLUT_WINDOW_X); +

    +

    These queries are with respect to the current window:

    @@ -1180,7 +1262,8 @@ These queries do not depend on the current window.

  • GLUT_INIT_WINDOW_HEIGHT - height last set by glutInitWindowSize
  • GLUT_INIT_DISPLAY_MODE - display mode last set by glutInitDisplayMode
  • GLUT_ELAPSED_TIME - time (in milliseconds) elapsed since glutInit or glutGet(GLUT_ELAPSED_TIME) was first called
    • -
  • GLUT_INIT_STATE - ?
    • +
  • GLUT_INIT_STATE - 1 if freeglut has been initialized through + a call to glutInit
  • GLUT_VERSION - Return value will be X*10000+Y*100+Z where X is the major version, Y is the minor version and Z is the patch level. This query is only supported in freeglut (version 2.0.0 or later).
    • @@ -1964,12 +2047,77 @@ at the origin. This is the famous OpenGL teapot [add reference].

    16.1 glutGameModeString

    +

    +Specify the display mode that should be entered when GameMode is +entered. Default is the current display mode of the monitor on which the +GameMode screen will be opened. +

    + +

    Usage
    +A string is passed to this function that specifies a combination of +resolution, pixel depth (ignored on Linux) and refresh rate. Valid +formats are: +

    +Where W, H, D and R are placeholders for horizontal resolution, vertical +resolution, pixel depth and refresh rate respectively, as integers. Note +the "x", ":" and "@" characters. +

    +

    16.2 glutEnterGameMode, glutLeaveGameMode

    +

    +Attempt to change to the requested display mode and open the GameMode +window, or close the GameMode window and return to the original display +mode. +For multi-monitor display setups, freeglut can be told on which +monitor the gamemode window should be opened by providing the +-display command line option to glutInit. +

    +

    16.3 glutGameModeGet

    +

    +The following state variables may be queried with glutGet. +The returned value is an integer. +

    + +

    +example:
    +int windowLeft = glutGet(GLUT_WINDOW_X); +

    + + + +

    +These queries return information about the current display mode if in +GameMode, or about the requested display mode before entering +GameMode: +

    + + +

    17. Video Resize Functions

    +

    These functions are not implemented in freeglut.

    +

    17.1 glutVideoResizeGet

    17.2 glutSetupVideoResizing,