    -----------------------------------------------------------------------------
    -- |
    -- Module      :  Graphics.UI.GLUT
    -- Copyright   :  (c) Sven Panne 2002-2005
    -- License     :  BSD-style (see the file libraries/GLUT/LICENSE)
    --
    -- Maintainer  :  sven.panne@aedion.de
    -- Stability   :  stable
    -- Portability :  portable
    --
    -- A Haskell binding for GLUT, the OpenGL Utility Toolkit, a window system
    -- independent toolkit for writing OpenGL programs. It includes support for
    -- the extended functionality available in freeglut (see
    -- <http://freeglut.sourceforge.net/>) and OpenGLUT (see
    -- <http://openglut.sourceforge.net/>), too.
    --
    -----------------------------------------------------------------------------

    module Graphics.UI.GLUT (
       -- * Legal stuff

       -- $LegalStuff

       -- * Introduction

       -- $Introduction

       -- ** Background

       -- $Background

       -- ** Design Philosophy

       -- $DesignPhilosophy

       -- ** API Versions

       -- $APIVersions

       -- ** Conventions

       -- $Conventions

       -- ** Terminology

       -- $Terminology

       module Graphics.Rendering.OpenGL,

       module Graphics.UI.GLUT.Initialization,
       module Graphics.UI.GLUT.Begin,
       module Graphics.UI.GLUT.Window,
       module Graphics.UI.GLUT.Overlay,
       module Graphics.UI.GLUT.Menu,
       module Graphics.UI.GLUT.Callbacks,
       module Graphics.UI.GLUT.Colormap,
       module Graphics.UI.GLUT.State,
       module Graphics.UI.GLUT.Fonts,
       module Graphics.UI.GLUT.Objects,
       module Graphics.UI.GLUT.Debugging,
       module Graphics.UI.GLUT.DeviceControl,
       module Graphics.UI.GLUT.GameMode
    )  where

    import Graphics.Rendering.OpenGL

    import Graphics.UI.GLUT.Initialization
    import Graphics.UI.GLUT.Begin
    import Graphics.UI.GLUT.Window
    import Graphics.UI.GLUT.Overlay
    import Graphics.UI.GLUT.Menu
    import Graphics.UI.GLUT.Callbacks
    import Graphics.UI.GLUT.Colormap
    import Graphics.UI.GLUT.State
    import Graphics.UI.GLUT.Fonts
    import Graphics.UI.GLUT.Objects
    import Graphics.UI.GLUT.Debugging
    import Graphics.UI.GLUT.DeviceControl
    import Graphics.UI.GLUT.GameMode

    -----------------------------------------------------------------------------
    -- $LegalStuff
    -- This documentation is heavily based on the man pages of Mark J. Kilgard\'s
    -- GLUT library.
    --
    -- OpenGL is a trademark of Silicon Graphics, Inc.
    -- X Window System is a trademark of X Consortium, Inc.
    -- Spaceball is a registered trademark of Spatial Systems, Inc.
    --
    -- The author has taken care in preparation of this documentation but makes
    -- no expressed or implied warranty of any kind and assumes no responsibility
    -- for errors or omissions. No liability is assumed for incidental or
    -- consequential damages in connection with or arising from the use of
    -- information or programs contained herein.

    -----------------------------------------------------------------------------
    -- $Introduction
    -- The OpenGL Utility Toolkit (GLUT) is a programming interface for writing
    -- window system independent OpenGL programs. Currently there are
    -- implementations for the X Window System, the Windows family, OS\/2, and Mac.
    -- The toolkit supports the following functionality:
    --
    -- * Multiple windows for OpenGL rendering.
    --
    -- * Callback driven event processing.
    --
    -- * Sophisticated input devices.
    --
    -- * An /idle/ routine and timers.
    --
    -- * A simple, cascading pop-up menu facility.
    --
    -- * Utility routines to generate various solid and wire frame objects.
    --
    -- * Support for bitmap and stroke fonts.
    --
    -- * Miscellaneous window management functions, including managing overlays.
    --
    -- This documentation serves as both a specification and a programming guide.
    -- If you are interested in a brief introduction to programming with GLUT,
    -- have a look at the relevant parts of <http://www.opengl.org/> and the vast
    -- amount of books on OpenGL, most of them use GLUT.
    --
    -- The remainder of this section describes GLUT\'s design philosophy and
    -- usage model. The following sections specify the GLUT routines, grouped by
    -- functionality. The final sections discuss usage advice and the logical
    -- programmer visible state maintained by GLUT.

    -----------------------------------------------------------------------------
    -- $Background
    -- One of the major accomplishments in the specification of OpenGL was
    -- the isolation of window system dependencies from OpenGL\'s rendering
    -- model. The result is that OpenGL is window system independent.
    --
    -- Window system operations such as the creation of a rendering window and the
    -- handling of window system events are left to the native window system to
    -- define. Necessary interactions between OpenGL and the window system such as
    -- creating and binding an OpenGL context to a window are described separately
    -- from the OpenGL specification in a window system dependent specification. For
    -- example, the GLX specification describes the standard by which OpenGL
    -- interacts with the X Window System.
    --
    -- The predecessor to OpenGL is IRIS GL. Unlike OpenGL, IRIS GL /does/
    -- specify how rendering windows are created and manipulated. IRIS GL\'s
    -- windowing interface is reasonably popular largely because it is simple to
    -- use. IRIS GL programmers can worry about graphics programming without needing
    -- to be an expert in programming the native window system. Experience also
    -- demonstrated that IRIS GL\'s windowing interface was high-level enough that
    -- it could be retargeted to different window systems. Silicon Graphics migrated
    -- from NeWS to the X Window System without any major changes to IRIS GL\'s
    -- basic windowing interface.
    --
    -- Removing window system operations from OpenGL is a sound decision because it
    -- allows the OpenGL graphics system to be retargeted to various systems
    -- including powerful but expensive graphics workstations as well as
    -- mass-production graphics systems like video games, set-top boxes for
    -- interactive television, and PCs.
    --
    -- Unfortunately, the lack of a window system interface for OpenGL is a gap in
    -- OpenGL\'s utility. Learning native window system APIs such as the X Window
    -- System\'s Xlib or Motif can be daunting. Even those familiar with
    -- native window system APIs need to understand the interface that binds OpenGL
    -- to the native window system. And when an OpenGL program is written using the
    -- native window system interface, despite the portability of the program\'s
    -- OpenGL rendering code, the program itself will be window system dependent.
    --
    -- Testing and documenting OpenGL\'s functionality lead to the development of
    -- the @tk@ and @aux@ toolkits. The @aux@ toolkit is used in the examples found
    -- in the /OpenGL Programming Guide/. Unfortunately, @aux@ has numerous
    -- limitations and its utility is largely limited to toy programs. The @tk@
    -- library has more functionality than @aux@ but was developed in an /ad hoc/
    -- fashion and still lacks much important functionality that IRIS GL programmers
    -- expect, like pop-up menus and overlays.
    --
    -- GLUT is designed to fill the need for a window system independent programming
    -- interface for OpenGL programs. The interface is designed to be simple yet
    -- still meet the needs of useful OpenGL programs. Features from the IRIS GL,
    -- @aux@, and @tk@ interfaces are included to make it easy for programmers used
    -- to these interfaces to develop programs for GLUT.

    -----------------------------------------------------------------------------
    -- $DesignPhilosophy
    -- GLUT simplifies the implementation of programs using OpenGL rendering. The
    -- GLUT application programming interface (API) requires very few routines to
    -- display a graphics scene rendered using OpenGL. The GLUT API (like the OpenGL
    -- API) is stateful. Most initial GLUT state is defined and the initial state is
    -- reasonable for simple programs. The GLUT routines also take relatively few
    -- parameters.
    --
    -- The GLUT API is (as much as reasonable) window system independent. For this
    -- reason, GLUT does not return /any/ native window system handles, pointers, or
    -- other data structures. More subtle window system dependencies such as
    -- reliance on window system dependent fonts are avoided by GLUT; instead, GLUT
    -- supplies its own (limited) set of fonts.
    --
    -- For programming ease, GLUT provides a simple menu sub-API. While the menuing
    -- support is designed to be implemented as pop-up menus, GLUT gives window
    -- system leeway to support the menu functionality in another manner (pull-down
    -- menus for example).
    --
    -- Two of the most important pieces of GLUT state are the /current window/ and
    -- /current menu/. Most window and menu routines affect the /current window/ or
    -- /menu/ respectively. Most callbacks implicitly set the /current window/ and
    -- /menu/ to the appropriate window or menu responsible for the callback. GLUT
    -- is designed so that a program with only a single window and\/or menu will not
    -- need to keep track of any window or menu identifiers. This greatly simplifies
    -- very simple GLUT programs.
    --
    -- GLUT is designed for simple to moderately complex programs focused on OpenGL
    -- rendering. GLUT implements its own event loop. For this reason, mixing GLUT
    -- with other APIs that demand their own event handling structure may be
    -- difficult. The advantage of a builtin event dispatch loop is simplicity.
    --
    -- GLUT contains routines for rendering fonts and geometric objects, however
    -- GLUT makes no claims on the OpenGL display list name space. For this reason,
    -- none of the GLUT rendering routines use OpenGL display lists. It is up to the
    -- GLUT programmer to compile the output from GLUT rendering routines into
    -- display lists if this is desired.
    --
    -- GLUT routines are logically organized into several sub-APIs according to
    -- their functionality. The sub-APIs are:
    --
    -- * /Initialization:/ Command line processing, window system initialization,
    --   and initial window creation state are controlled by these routines.
    --
    -- * /Beginning Event Processing:/ This routine enters GLUT\'s event processing
    --   loop. This routine never returns, and it continuously calls GLUT callbacks
    --   as necessary.
    --
    -- * /Window Management:/ These routines create and control windows.
    --
    -- * /Overlay Management:/ These routines establish and manage overlays for
    --   windows.
    --
    -- * /Menu Management:/ These routines create and control pop-up menus.
    --
    -- * /Callback Registration:/ These routines register callbacks to be called by
    --   the GLUT event processing loop.
    --
    -- * /Color Index Colormap Management:/ These routines allow the manipulation
    --   of color index colormaps for windows.
    --
    -- * /State Retrieval:/ These routines allows programs to retrieve state from
    --   GLUT.
    --
    -- * /Font Rendering:/ These routines allow rendering of stroke and bitmap
    --   fonts.
    --
    -- * /Geometric Shape Rendering:/ These routines allow the rendering of 3D
    --   geometric objects including spheres, cones, icosahedrons, and teapots.
    --
    -- * /Debugging:/ This routine reports any pending GL errors.
    --
    -- * /Device Control:/ These routines allow setting the key repeat and polling
    --   the joystick.
    --
    -- * /Game Mode:/ These routines allow programs to enter\/leave a full-screen
    --   mode with specified properties.

    -- Note that the following item has been left out intentionally, its
    -- implementation is too SGI-specific:
    -- * /Video Resizing:/ These routines provide a means for doing swap or frame
    --   synchronous resizing\/panning of the area that is to be magnified (or
    --   passed through) to the output video resolution.

    -----------------------------------------------------------------------------
    -- $APIVersions
    -- The GLUT API has undergone several revisions with increasing functionality.
    -- This Haskell binding provides access to everything in API version 4,
    -- although it is not yet officially finalized. Nevertheless, it provides very
    -- useful things like handling full-screen modes and special keys.

    -----------------------------------------------------------------------------
    -- $Conventions
    -- GLUT window and screen coordinates are expressed in pixels. The upper
    -- left hand corner of the screen or a window is (0,0). X coordinates
    -- increase in a rightward direction; Y coordinates increase in a
    -- downward direction. Note: This is inconsistent with OpenGL\'s
    -- coordinate scheme that generally considers the lower left hand
    -- coordinate of a window to be at (0,0) but is consistent with most
    -- popular window systems.

    -----------------------------------------------------------------------------
    -- $Terminology
    -- A number of terms are used in a GLUT-specific manner throughout this
    -- document. The GLUT meaning of these terms is independent of the window
    -- system GLUT is used with. Here are GLUT-specific meanings for the
    -- following GLUT-specific terms:
    --
    -- * /Callback:/ A programmer specified routine that can be registered with
    --   GLUT to be called in response to a specific type of event. Also used to
    -- refer to a specific callback routine being called.
    --
    -- * /Colormap:/ A mapping of pixel values to RGB color values. Used by color
    --   index windows.
    --
    -- * /Dials and button box:/ A sophisticated input device consisting of a pad
    --   of buttons and an array of rotating dials, often used by computer-aided
    --   design programs.
    --
    -- * /Display mode:/ A set of OpenGL frame buffer capabilities that can be
    --   attributed to a window.
    --
    -- * /Idle:/ A state when no window system events are received for processing
    --   as callbacks and the idle callback, if one is registered, is called.
    --
    -- * /Layer in use:/ Either the normal plane or overlay. This per-window state
    --   determines what frame buffer layer OpenGL commands affect.
    --
    -- * /Menu entry:/ A menu item that the user can select to trigger the menu
    --   callback for the menu entry\'s value.
    --
    -- * /Menu item:/ Either a menu entry or a sub-menu trigger.
    --
    -- * /Modifiers:/ The Shift, Ctrl, and Alt keys that can be held down
    --   simultaneously with a key or mouse button being pressed or released.
    --
    -- * /Multisampling:/ A technique for hardware antialiasing generally available
    --   only on expensive 3D graphics hardware. Each pixel is composed of a number
    --   of samples (each containing color and depth information). The samples are
    --   averaged to determine the displayed pixel color value. Multisampling is
    --   supported as an extension to OpenGL.
    --
    -- * /Normal plane:/ The default frame buffer layer where GLUT window state
    --   resides; as opposed to the /overlay/.
    --
    -- * /Overlay:/ A frame buffer layer that can be displayed preferentially to
    --   the /normal plane/ and supports transparency to display through to the
    --   /normal plane/. Overlays are useful for rubber-banding effects, text
    --   annotation, and other operations, to avoid damaging the normal plane frame
    --   buffer state. Overlays require hardware support not present on all systems.
    --
    -- * /Pop:/ The act of forcing a window to the top of the stacking order for
    --   sibling windows.
    --
    -- * /Pop-up menu:/ A menu that can be set to appear when a specified mouse
    --   button is pressed in a window. A pop-menu consists of multiple menu items.
    --
    -- * /Push:/ The act of forcing a window to the bottom of the stacking order
    --   for sibling windows.
    --
    -- * /Reshape:/ The act of changing the size or shape of the window.
    --
    -- * /Spaceball:/ A sophisticated 3D input device that provides six degrees of
    --   freedom, three axes of rotation and three axes of translation. It also
    --   supports a number of buttons. The device is a hand-sized ball attached to
    --   a base. By cupping the ball with one\'s hand and applying torsional or
    --   directional force on the ball, rotations and translationsare generated.
    --
    -- * /Stereo:/ A frame buffer capability providing left and right color buffers
    --   for creating stereoscopic renderings. Typically, the user wears LCD
    --   shuttered goggles synchronized with the alternating display on the screen
    --   of the left and right color buffers.
    --
    -- * /Sub-menu:/ A menu cascaded from some sub-menu trigger.
    --
    -- * /Sub-menu trigger:/ A menu item that the user can enter to cascade another
    --   pop-up menu.
    --
    -- * /Subwindow:/ A type of window that is the child window of a top-level
    --   window or other subwindow. The drawing and visible region of a subwindow
    --   is limited by its parent window.
    --
    -- * /Tablet:/ A precise 2D input device. Like a mouse, 2D coordinates are
    --   returned. The absolute position of the tablet \"puck\" on the tablet is
    --   returned. Tablets also support a number of buttons.
    --
    -- * /Timer:/ A callback that can be scheduled to be called in a specified
    --   interval of time.
    --
    -- * /Top-level window:/ A window that can be placed, moved, resized, etc.
    --   independently from other top-level windows by the user. Subwindows may
    --   reside within a top-level window.
    --
    -- * /Window:/ A rectangular area for OpenGL rendering.
    --
    -- * /Window display state:/ One of shown, hidden, or iconified. A shown window
    --   is potentially visible on the screen (it may be obscured by other windows
    --   and not actually visible). A hidden window will never be visible. An
    --   iconified window is not visible but could be made visible in response to
    --   some user action like clicking on the window\'s corresponding icon.
    --
    -- * /Window system:/ A broad notion that refers to both the mechanism and
    --   policy of the window system. For example, in the X Window System both the
    --   window manager and the X server are integral to what GLUT considers the
    --   window system.