This file documents the correspondence between the HOpenGL modules and
the official API documentation, and the changes made for this binding.

---------------------------------------------------------------------------

http://www.opengl.org/Documentation/Specs.html, OpenGL 1.2.1 Specification:

GL_Errors           section 2.5    GL Errors
GL_BeginEnd         section 2.6    Begin/End Paradigm
GL_VertexSpec       section 2.7    Vertex Specification
GL_VertexArray      section 2.8    Vertex Arrays
GL_Rectangles       section 2.9    Rectangles
GL_CoordTrans       section 2.10   Coordinate Transformations
GL_Clipping         section 2.11   Clipping
GL_RasterPos        section 2.12   Current Raster Position
GL_Colors           section 2.13   Colors and Coloring
GL_Points           section 3.3    Points
GL_LineSeg          section 3.4    Line Segments
GL_Polygons         section 3.5    Polygons
GL_PixelRect        section 3.6    Pixel Rectangles
GL_Bitmaps          section 3.7    Bitmaps
GL_Texturing        section 3.8    Texturing
GL_Fog              section 3.10   Fog
GL_PerFragment      section 4.1    Per-Fragment Operations
GL_Framebuffer      section 4.2    Whole Framebuffer Operations
GL_MovePixels       section 4.3    Drawing, Reading, and Copying Pixels
GL_Evaluators       section 5.1    Evaluators
GL_Selection        section 5.2    Selection
GL_Feedback         section 5.3    Feedback
GL_DisplayList      section 5.4    Display Lists
GL_FlushFinish      section 5.5    Flush and Finish
GL_Hints            section 5.6    Hints
GL_QueryString      section 6.1.11 Pointer and String Queries
GL_SavResState      section 6.1.12 Saving and Restoring State
GL_QueryCurrent     table   6.5    Current Values and Associated Data
GL_QueryVertexArray table   6.6    Vertex Array Data
GL_QueryTransform   table   6.7    Transformation state
GL_QueryColoring    table   6.8    Coloring
GL_QueryLighting1   table   6.9    Lighting
GL_QueryLighting2   table   6.10   Lighting (cont.)
GL_QueryRaster      table   6.11   Rasterization
GL_QueryTexObj1     table   6.12   Texture Objects
GL_QueryHints       table   6.23   (Hints)

* GL_2_BYTES, GL_3_BYTES, and  GL_4_BYTES are available as TwoBytes,
  ThreeBytes, and FourBytes. Alas, 2Bytes is not a valid Haskell constructor.

* To reduce pattern matching on DisplayList and related display list name
  arithmetic, genLists returns a list of display list names, and deleteLists
  expects a lists of display list names.

---------------------------------------------------------------------------

http://www.opengl.org/Documentation/Specs.html, GLU 1.3 Specification:

GLU_Init     chapter 2 Initialization
GLU_Mipmap   chapter 3 Mipmapping
GLU_Matrix   chapter 4 Matrix manipulation
GLU_Tess     chapter 5 Polygon Tessellation
GLU_Quadrics chapter 6 Quadrics
GLU_NURBS    chapter 7 NURBS
GLU_Errors   chapter 8 Errors

Changes in GLU:

* gluGetString is available via the more general get.

* There is no need for gluCheckExtension with the above interface
  because it boils down to a simple `elem'.

* There is no equivalent for gluDeleteQuadric or gluDeleteTess, Haskell's
  GC takes care of cleaning up those objects.

* quadricCallback has one parameter less than gluQuadricCallback, because
  the second one must be GLU_ERROR anyway.

---------------------------------------------------------------------------

http://reality.sgi.com/mjk/glut3/glut3.html

GLUT_Init     chapters 2 Inititalization and 3 Beginning Event Processing
GLUT_Window   chapter  4 Window Management
GLUT_Overlay  chapter  5 Overlay Management
GLUT_Menu     chapter  6 Menu Management
GLUT_CBWindow chapter  7 Callback Registration, per-window callbacks
GLUT_CBGlobal chapter  7 Callback Registration, global callbacks
GLUT_Colormap chapter  8 Color Index Colormap Management
GLUT_State    chapter  9 State Retrieval
GLUT_Fonts    chapter 10 Font Rendering
GLUT_Objects  chapter 11 Geometric Object Rendering
GLUT_Resize   video resize sub-API, currently undocumented
GLUT_Game     game mode sub-API, currently undocumented

Changes in GLUT:

* GLUT's initialization function can get the program name and arguments for
  the lazy ones between us:

     init :: Maybe (String, [String]) -> IO (String, [String])

* glutInitDisplayString is available via initDisplay, but expects a list
  of display settings, so you can write e.g.:

     initDisplay [ ShouldNotBe Slow, WithDefault Depth, Want Alpha Greater 8 ]

  glutGameModeString has been given an interface in a similar spirit:

     gameMode [ Require GameModeWidth Equals 800,
                Require GameModeHertz Gequal 60 ]

* The window creation enforces a display callback and display modes, and can
  additionally specify an initial position and size.

* The menu handling is completely different, only a single function is 
  needed instead of the 11 functions from GLUT's menu sub-API:

     type MenuAction = IO ()
     data MenuItem = MenuEntry String MenuAction
                   | SubMenu   String [MenuItem]

     attachMenu :: MouseButton -> [MenuItem] -> IO ()

  Detaching can be done via attaching an empty menu.

* Added String versions

     bitmapString :: BitmapFont -> String -> IO ()
     strokeString :: StrokeFont -> String -> IO ()

  as convenience functions for

     bitmapCharacter :: BitmapFont -> Int -> IO ()
     strokeCharacter :: StrokeFont -> Int -> IO ()

  Downside: "Only" 8-bit charactes possible then.

* All state retrieval functions are replaced by a single type class
  Gettable with the single method get:

     glutGet, glutLayerGet, glutDeviceGet, glutGameModeGet, glutVideoResizeGet

  This way the interface is much nicer and far more type safe, e.g.:

     get TransparentIndex :: IO (Maybe Int)
     get HasKeyboard      :: IO Bool
     get NumMouseButtons  :: IO Int
