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_EnumQueries1 section 6.1.3  (Enumerated Queries)
GL_EnumQueries2 section 6.1.3  (Enumerated Queries)
GL_EnumQueries3 section 6.1.3  (Enumerated Queries)
GL_EnumQueries4 section 6.1.3  (Enumerated Queries)
GL_EnumQueries5 section 6.1.3  (Enumerated Queries)
GL_EnumQueries6 section 6.1.3  (Enumerated Queries)
GL_EnumQueries7 section 6.1.3  (Enumerated Queries)
GL_SavResState  section 6.1.12 (Saving and Restoring State)

* 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
