GLUT for Win32 README
                ---------------------


VERSION/INFO:

    This is GLUT for Win32 version 3.7.6 as of Nov 8th 2001.
    See the COPYRIGHT section for distribution and copyright notices.
    Send all bug reports and questions for this version of GLUT to 
    Nate Robins [nate@pobox.com].

    For more information about GLUT for Win32, see the web page:
    www.pobox.com/~nate/glut.html or subscribe to the GLUT for Win32 
    mailing list by sending e-mail to majordomo@perp.com with 
    "subscribe glut" in the body of the message.

    For general information about GLUT, see the GLUT web page:
    http://reality.sgi.com/opengl/glut3/glut3.html and be sure to
    check the GLUT FAQ first for any questions that you may have:
    http://reality.sgi.com/opengl/glut3/glut-faq.html


COMPILING/INSTALLATION:

    o  Precompiled versions of the DLL and import library can be
       found on the GLUT for Win32 web page mentioned above.

    o  Microsoft Developer Studio 6 workspace and project files have
       been included in the source code distribution.
       
       To build the glut dll: 
       First, open Microsoft Developer Studio.
       Then, select File -> Open Workspace and find the glut.dsw file
       in the file dialog and double-click on it.  
       Finally, select Build -> Build glut32.dll.
       When the build is finished, it will copy:
       glut32.dll to %WinDir%\System, 
       glut32.lib to $(MSDevDir)\..\..\VC98\lib, and 
       glut.h     to $(MSDevDir)\..\..\VC98\include\GL.
       
       Additional workspace files have been included in the progs, test
       and lib directories to build the progs, tests and libs respectively.


BORLAND NOTES:

    From what I understand, Borland supplies a utility that
    converts Microsoft Visual C++ .libs into Borland compatible
    files.  Therefore, the best method for Borland users is
    probably to get the precompiled versions of the library and
    convert the library.  To create an import library for Borland 
    from the DLLs, use the following command (from a command prompt):
          IMPLIB glut32.lib glut32.dll
    If IMPLIB crashes when called this way, try
          IMPLIB glut32.lib glut32.def
    using the glut32.def file in this distribution.


FORTRAN NOTES:

    Bill Mitchell [william.mitchell@nist.gov] has put considerable
    effort into getting GLUT to work with different compilers for
    Fortran 90.  He indicates that you should copy the f90glut.h
    file to your $(MSDevDir)\..\..\VC98\include\GL directory.  
    Then, just build GLUT as usual.  The Fortran 90 interface, f90gl, 
    can be obtained at http://math.nist.gov/f90gl and contains 
    installation instructions and usage examples.


MISC NOTES:

    o  Overlay support is not implemented, nor are there any plans to 
       implement it in the near future.

    o  To customize the windows icon, you can use the resource name
       GLUT_ICON.  For example, create an icon named "glut.ico", and
       create a file called glut.rc that contains the following:
       GLUT_ICON ICON glut.ico
       then compile the glut.rc file with the following:
       rc /r glut
       and link the resulting glut.res file into your executable
       (just like you would an object file).
       Alternatively, you can simply add the glut.rc file to your
       project if you are using Microsoft Developer Studio.


IMPLEMENTATION DEPENDENT DIFFERENCES:

    There are a few differences between the Win32 version of GLUT
    and the X11 version of GLUT.  Those are outlined here.  Note
    that MOST of these differences are allowed by the GLUT
    specification.  Bugs and unsupported features are outlined in
    the UNSUPPORTED/BUGS section.

    o  glutInit:
       The following command line options have no meaning (and are
       ignored) in GLUT for Win32:
       -display, -indirect, -direct, -sync.

    o  glutInitWindowPosition, glutPositionWindow:
       Win32 has two different coordinate systems for windows.
       One is in terms of client space and the other is the whole
       window space (including the decorations).  If you
       glutPositionWindow(0, 0), GLUT for Win32 will place the
       window CLIENT area at 0, 0.  This will cause the window
       decorations (title bar and left edge) to be OFF-SCREEN, but
       it gives the user the most flexibility in positioning.
       HOWEVER, if the user specifies glutInitWindowPosition(0, 0),
       the window is placed relative to window space at 0, 0.
       This will cause the window to be opened in the upper left
       corner with all the decorations showing.  This behaviour is
       acceptable under the current GLUT specification.

    o  glutSetIconTitle, glutSetWindowTitle:
       There is no separation between Icon title and Window title
       in Win32.  Therefore, setting an icon title in Win32 has
       no effect.

    o  glutSetCursor:
       As indicated in the GLUT specification, cursors may be
       different on different platforms.  This is the case in GLUT
       for Win32.  For the most part, the cursors will match the
       meaning, but not necessarily the shape.  Notable exceptions
       are the GLUT_CURSOR_INFO & GLUT_CURSOR_SPRAY which use the
       crosshair cursor and the GLUT_CURSOR_CYCLE which uses the
       'no' or 'destroy' cursor in Win32.

    o  glutVisibilityFunc:
       Win32 seems to be unable to determine if a window is fully
       obscured.  Therefore, the visibility of a GLUT window is
       only reflected by its Iconic, Hidden or Shown state.  That
       is, even if a window is fully obscured, in GLUT for Win32,
       it is still "visible".

    o  glutEntryFunc:
       Window Focus is handled differently in Win32 and X.
       Specifically, the "window manager" in Win32 uses a "click to
       focus" policy.  That is, in order for a window to receive
       focus, a mouse button must be clicked in it.  Likewise, in
       order for a window to loose focus, a mouse button must be
       clicked outside the window (or in another window).
       Therefore, the Enter and Leave notification provided by GLUT
       may behave differently in the Win32 and in X11 versions.
       There is a viable workaround for this.  A program called
       "Tweak UI" is provided by Microsoft which can be used to
       change the focus policy in Win32 to "focus follows mouse".
       It is available from the Microsoft Web Pages:
       http://www.microsoft.com/windows/software/PowerToy.htm

    o  glutCopyColormap:
       GLUT for Win32 always copies the colormap.  There is never
       any sharing of colormaps.  This is probably okay, since
       Win32 merges the logical palette and the physical palette
       anyway, so even if there are two windows with totally
       different colors in their colormaps, Win32 will find a
       (hopefully) good match between them.

    o  glutIdleFunc + menus:
       The glut idle function will NOT be called when a menu is
       active.  This causes all animation to stop when a menu is
       active (in general, this is probably okay).  Timer
       functions will still fire, however.  If the timer callback
       draws into the rendering context, the drawing will not show
       up until after the menu has finished, though.


UNSUPPORTED/BUGS:

    o  glutAttachMenu:
       Win32 only likes to work with left and right mouse buttons.
       Especially so with popup menus.  Therefore, when attaching
       the menu to the middle mouse button, the LEFT mouse button
       must be used to select from the menu.

    o  glutSpaceball*, glutButtonBox*, glutTablet*, glutDials*:
       None of the special input devices are supported at this
       time.

    o  When resizing or moving a GLUT for Win32 window, no updating
       is performed.  This causes the window to leave "tracks" on
       the screen when getting bigger or when previously obscured
       parts are being revealed.  I put in a bit of a kludgy
       workaround for those that absolutely can't have the weird
       lines.  The reshape callback is called multiple times for
       reshapes.  Therefore, in the reshape callback, some drawing
       can be done.  It should probably be limited to a color buffer 
       clear.

    o  The video resizing capabilities of GLUT 3.3+ for X11 is
       currently unimplemented (this is probably ok, since it
       really isn't part of the spec until 4.0).  I doubt that
       this will ever be part of GLUT for Win32, since there is no
       hardware to support it.  A hack could simply change the
       resolution of the desktop.


CHANGES/FIXES:

    (Nov 8, '01)
    x  Released 3.7.6

    (Nov 8, '01)
    x  Changed fullscreen mode from TOPMOST back to simply TOP, since 
       (it turns out) many people use windows atop a GLUT window.

    (Nov 8, '01)
    x  Added code to prevent CPU spiking when no idle function is 
       registered.  Otherwise, if an idle function is registered, spike
       CPU so that the idle function gets all the attention it needs and
       if this is a problem on the program side, the user can stick a 
       sleep() in their idle function.  I believe that this strikes the
       best balance betweeen GLUT being fast, and also being "nice" to 
       other processes.  Thanks to James Wright for reporting this bug.

    (Nov 8, '01)
    x  Fixed bug in motion callback handler which wasn't setting the
       current window, so multiple window apps (e.g., any GLUI app)
       wouldn't get the callback correctly.

    (Oct 4, '01)
    x  Fixed bug in glutEnterGameMode() that caused new windows to not 
       be in "fullscreen" mode, so they got window decorations.

    (Oct 4, '01)
    x  Fixed bug in glutEnterGameMode() that caused new windows to not 
       be in "fullscreen" mode, so they got window decorations.

    (Oct 3, '01)
    x  Fixed bug in getVisualInfoFromString(): visuals not reloaded on 
       display mode change.  Reload visuals each time they are queried.
       This fixes a problem with Win32 because the list of availabe Visuals
       (Pixelformats) changes after a change in displaymode. The problem 
       occurs when switching to gamemode and back.  Thanks to Michael 
       Wimmer for pointing this out & providing the fix.

    (Oct 3, '01)
    x  Fixed bug in XGetVisualInfo(): pixelformats enumerated incorrectly.
       Passing 0 as a pixelformat index to DescribePixelFormat gives
       unpredictible results (e.g., this fails on the Voodoo opengl32.dll 
       and always reports 0 as the last available pixelformat index).
       Thanks to Michael Wimmer for pointing this out & providing the fix.

    (Oct 3, '01)
    x  Fixed bug in glXGetConfig(): pixelformats enumerated incorrectly.  The
       test was OpenGL support OR draw to window, but should be AND.  Thanks
       to Michael Wimmer for pointing this out & providing the fix.

    (Sep 28, '01)
    x  Fixed glutChangeToSubMenu()/glutChangeToMenuEntry() bug where if you 
       went back and forth between a submenu and a plain entry, the submenu 
       wouldn't be updated properly.

    (Sep 28, '01)
    x  glutSetIconTitle() is now a nop.

    (Sep 28, '01)
    x  glutFullScreen() now sets the window as TOPMOST, therefore, the 
    window will always be on top (this essentially disables alt-tabbing).

    (Sep 28, '01)
    x  The key repeat ignore flag is now honored correctly.

    (Sep 28, '01)
    x  Key presses are now reported more accurately and fully, in 
       particular, modified up events (i.e., SHIFT-2) are now reported 
       correctly.

    (Sep 28, '01)
    x  Subwindows nested arbitrarily deep get their keyboard callbacks 
       correctly now.

    (Sep 28, '01)
    x  Major rewrite of the window procedure code to clean it up and make
       way for other bug fixes.

    (Sep 23, '01)
    x  Fixed noof example program to use RAND_MAX instead of assumed
       max of 2147483647.0.  (Now it looks _much_ better!)

    (Sep 22, '01)
    x  Fixed sunlight example program.  globe.raw data file was corrupt,
       added a new one.

    (Sep 22, '01)
    x  Fixed zcomposite example program to print message if overlay
       support is not found (instead of crashing).

    (Jan 22, '01)
    x  Fixed malloc(0) bug in Win32 version of XGetVisualInfo.  Thanks 
       to Kekoa Proudfoot for bringing this to my attention.

    (Dec 12, '00)
    x  Added data files for the advanced & advanced97 programs.

    (Dec 12, '00)
    x  Added Developer Studio 6 project and workspace files for pretty 
       much everything (the stuff left out was usually unix specific).

    (Dec 7, '00)
    x  Fixed several compilation problems & corrupt files.  Thanks to 
       Alexander Stohr for bringing these to my attention and providing 
       detailed fixes.

    (Dec 6, '00)
    x  Fixed compiler support for lcc.  Thanks to Gordon for bringing