<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> <!-- Generated by HsColour, http://www.cs.york.ac.uk/fp/darcs/hscolour/ --> <title>Graphics/UI/GLUT.hs</title> <link type='text/css' rel='stylesheet' href='hscolour.css' /> </head> <body> <pre><a name="line-1"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-2"></a><span class='hs-comment'>-- |</span> <a name="line-3"></a><span class='hs-comment'>-- Module : Graphics.UI.GLUT</span> <a name="line-4"></a><span class='hs-comment'>-- Copyright : (c) Sven Panne 2002-2005</span> <a name="line-5"></a><span class='hs-comment'>-- License : BSD-style (see the file libraries/GLUT/LICENSE)</span> <a name="line-6"></a><span class='hs-comment'>--</span> <a name="line-7"></a><span class='hs-comment'>-- Maintainer : sven.panne@aedion.de</span> <a name="line-8"></a><span class='hs-comment'>-- Stability : stable</span> <a name="line-9"></a><span class='hs-comment'>-- Portability : portable</span> <a name="line-10"></a><span class='hs-comment'>--</span> <a name="line-11"></a><span class='hs-comment'>-- A Haskell binding for GLUT, the OpenGL Utility Toolkit, a window system</span> <a name="line-12"></a><span class='hs-comment'>-- independent toolkit for writing OpenGL programs. It includes support for</span> <a name="line-13"></a><span class='hs-comment'>-- the extended functionality available in freeglut (see</span> <a name="line-14"></a><span class='hs-comment'>-- <<a href="http://freeglut.sourceforge.net/">http://freeglut.sourceforge.net/</a>>) and OpenGLUT (see</span> <a name="line-15"></a><span class='hs-comment'>-- <<a href="http://openglut.sourceforge.net/">http://openglut.sourceforge.net/</a>>), too.</span> <a name="line-16"></a><span class='hs-comment'>--</span> <a name="line-17"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-18"></a> <a name="line-19"></a><span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span> <span class='hs-layout'>(</span> <a name="line-20"></a> <span class='hs-comment'>-- * Legal stuff</span> <a name="line-21"></a> <a name="line-22"></a> <span class='hs-comment'>-- $LegalStuff</span> <a name="line-23"></a> <a name="line-24"></a> <span class='hs-comment'>-- * Introduction</span> <a name="line-25"></a> <a name="line-26"></a> <span class='hs-comment'>-- $Introduction</span> <a name="line-27"></a> <a name="line-28"></a> <span class='hs-comment'>-- ** Background</span> <a name="line-29"></a> <a name="line-30"></a> <span class='hs-comment'>-- $Background</span> <a name="line-31"></a> <a name="line-32"></a> <span class='hs-comment'>-- ** Design Philosophy</span> <a name="line-33"></a> <a name="line-34"></a> <span class='hs-comment'>-- $DesignPhilosophy</span> <a name="line-35"></a> <a name="line-36"></a> <span class='hs-comment'>-- ** API Versions</span> <a name="line-37"></a> <a name="line-38"></a> <span class='hs-comment'>-- $APIVersions</span> <a name="line-39"></a> <a name="line-40"></a> <span class='hs-comment'>-- ** Conventions</span> <a name="line-41"></a> <a name="line-42"></a> <span class='hs-comment'>-- $Conventions</span> <a name="line-43"></a> <a name="line-44"></a> <span class='hs-comment'>-- ** Terminology</span> <a name="line-45"></a> <a name="line-46"></a> <span class='hs-comment'>-- $Terminology</span> <a name="line-47"></a> <a name="line-48"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>Rendering</span><span class='hs-varop'>.</span><span class='hs-conid'>OpenGL</span><span class='hs-layout'>,</span> <a name="line-49"></a> <a name="line-50"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Initialization</span><span class='hs-layout'>,</span> <a name="line-51"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Begin</span><span class='hs-layout'>,</span> <a name="line-52"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Window</span><span class='hs-layout'>,</span> <a name="line-53"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Overlay</span><span class='hs-layout'>,</span> <a name="line-54"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Menu</span><span class='hs-layout'>,</span> <a name="line-55"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Callbacks</span><span class='hs-layout'>,</span> <a name="line-56"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Colormap</span><span class='hs-layout'>,</span> <a name="line-57"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>State</span><span class='hs-layout'>,</span> <a name="line-58"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Fonts</span><span class='hs-layout'>,</span> <a name="line-59"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Objects</span><span class='hs-layout'>,</span> <a name="line-60"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Debugging</span><span class='hs-layout'>,</span> <a name="line-61"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>DeviceControl</span><span class='hs-layout'>,</span> <a name="line-62"></a> <span class='hs-keyword'>module</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>GameMode</span> <a name="line-63"></a><span class='hs-layout'>)</span> <span class='hs-keyword'>where</span> <a name="line-64"></a> <a name="line-65"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>Rendering</span><span class='hs-varop'>.</span><span class='hs-conid'>OpenGL</span> <a name="line-66"></a> <a name="line-67"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Initialization</span> <a name="line-68"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Begin</span> <a name="line-69"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Window</span> <a name="line-70"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Overlay</span> <a name="line-71"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Menu</span> <a name="line-72"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Callbacks</span> <a name="line-73"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Colormap</span> <a name="line-74"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>State</span> <a name="line-75"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Fonts</span> <a name="line-76"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Objects</span> <a name="line-77"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>Debugging</span> <a name="line-78"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>DeviceControl</span> <a name="line-79"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Graphics</span><span class='hs-varop'>.</span><span class='hs-conid'>UI</span><span class='hs-varop'>.</span><span class='hs-conid'>GLUT</span><span class='hs-varop'>.</span><span class='hs-conid'>GameMode</span> <a name="line-80"></a> <a name="line-81"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-82"></a><span class='hs-comment'>-- $LegalStuff</span> <a name="line-83"></a><span class='hs-comment'>-- This documentation is heavily based on the man pages of Mark J. Kilgard\'s</span> <a name="line-84"></a><span class='hs-comment'>-- GLUT library.</span> <a name="line-85"></a><span class='hs-comment'>--</span> <a name="line-86"></a><span class='hs-comment'>-- OpenGL is a trademark of Silicon Graphics, Inc.</span> <a name="line-87"></a><span class='hs-comment'>-- X Window System is a trademark of X Consortium, Inc.</span> <a name="line-88"></a><span class='hs-comment'>-- Spaceball is a registered trademark of Spatial Systems, Inc.</span> <a name="line-89"></a><span class='hs-comment'>--</span> <a name="line-90"></a><span class='hs-comment'>-- The author has taken care in preparation of this documentation but makes</span> <a name="line-91"></a><span class='hs-comment'>-- no expressed or implied warranty of any kind and assumes no responsibility</span> <a name="line-92"></a><span class='hs-comment'>-- for errors or omissions. No liability is assumed for incidental or</span> <a name="line-93"></a><span class='hs-comment'>-- consequential damages in connection with or arising from the use of</span> <a name="line-94"></a><span class='hs-comment'>-- information or programs contained herein.</span> <a name="line-95"></a> <a name="line-96"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-97"></a><span class='hs-comment'>-- $Introduction</span> <a name="line-98"></a><span class='hs-comment'>-- The OpenGL Utility Toolkit (GLUT) is a programming interface for writing</span> <a name="line-99"></a><span class='hs-comment'>-- window system independent OpenGL programs. Currently there are</span> <a name="line-100"></a><span class='hs-comment'>-- implementations for the X Window System, the Windows family, OS\/2, and Mac.</span> <a name="line-101"></a><span class='hs-comment'>-- The toolkit supports the following functionality:</span> <a name="line-102"></a><span class='hs-comment'>--</span> <a name="line-103"></a><span class='hs-comment'>-- * Multiple windows for OpenGL rendering.</span> <a name="line-104"></a><span class='hs-comment'>--</span> <a name="line-105"></a><span class='hs-comment'>-- * Callback driven event processing.</span> <a name="line-106"></a><span class='hs-comment'>--</span> <a name="line-107"></a><span class='hs-comment'>-- * Sophisticated input devices.</span> <a name="line-108"></a><span class='hs-comment'>--</span> <a name="line-109"></a><span class='hs-comment'>-- * An /idle/ routine and timers.</span> <a name="line-110"></a><span class='hs-comment'>--</span> <a name="line-111"></a><span class='hs-comment'>-- * A simple, cascading pop-up menu facility.</span> <a name="line-112"></a><span class='hs-comment'>--</span> <a name="line-113"></a><span class='hs-comment'>-- * Utility routines to generate various solid and wire frame objects.</span> <a name="line-114"></a><span class='hs-comment'>--</span> <a name="line-115"></a><span class='hs-comment'>-- * Support for bitmap and stroke fonts.</span> <a name="line-116"></a><span class='hs-comment'>--</span> <a name="line-117"></a><span class='hs-comment'>-- * Miscellaneous window management functions, including managing overlays.</span> <a name="line-118"></a><span class='hs-comment'>--</span> <a name="line-119"></a><span class='hs-comment'>-- This documentation serves as both a specification and a programming guide.</span> <a name="line-120"></a><span class='hs-comment'>-- If you are interested in a brief introduction to programming with GLUT,</span> <a name="line-121"></a><span class='hs-comment'>-- have a look at the relevant parts of <<a href="http://www.opengl.org/">http://www.opengl.org/</a>> and the vast</span> <a name="line-122"></a><span class='hs-comment'>-- amount of books on OpenGL, most of them use GLUT.</span> <a name="line-123"></a><span class='hs-comment'>--</span> <a name="line-124"></a><span class='hs-comment'>-- The remainder of this section describes GLUT\'s design philosophy and</span> <a name="line-125"></a><span class='hs-comment'>-- usage model. The following sections specify the GLUT routines, grouped by</span> <a name="line-126"></a><span class='hs-comment'>-- functionality. The final sections discuss usage advice and the logical</span> <a name="line-127"></a><span class='hs-comment'>-- programmer visible state maintained by GLUT.</span> <a name="line-128"></a> <a name="line-129"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-130"></a><span class='hs-comment'>-- $Background</span> <a name="line-131"></a><span class='hs-comment'>-- One of the major accomplishments in the specification of OpenGL was</span> <a name="line-132"></a><span class='hs-comment'>-- the isolation of window system dependencies from OpenGL\'s rendering</span> <a name="line-133"></a><span class='hs-comment'>-- model. The result is that OpenGL is window system independent.</span> <a name="line-134"></a><span class='hs-comment'>--</span> <a name="line-135"></a><span class='hs-comment'>-- Window system operations such as the creation of a rendering window and the</span> <a name="line-136"></a><span class='hs-comment'>-- handling of window system events are left to the native window system to</span> <a name="line-137"></a><span class='hs-comment'>-- define. Necessary interactions between OpenGL and the window system such as</span> <a name="line-138"></a><span class='hs-comment'>-- creating and binding an OpenGL context to a window are described separately</span> <a name="line-139"></a><span class='hs-comment'>-- from the OpenGL specification in a window system dependent specification. For</span> <a name="line-140"></a><span class='hs-comment'>-- example, the GLX specification describes the standard by which OpenGL</span> <a name="line-141"></a><span class='hs-comment'>-- interacts with the X Window System.</span> <a name="line-142"></a><span class='hs-comment'>--</span> <a name="line-143"></a><span class='hs-comment'>-- The predecessor to OpenGL is IRIS GL. Unlike OpenGL, IRIS GL /does/</span> <a name="line-144"></a><span class='hs-comment'>-- specify how rendering windows are created and manipulated. IRIS GL\'s</span> <a name="line-145"></a><span class='hs-comment'>-- windowing interface is reasonably popular largely because it is simple to</span> <a name="line-146"></a><span class='hs-comment'>-- use. IRIS GL programmers can worry about graphics programming without needing</span> <a name="line-147"></a><span class='hs-comment'>-- to be an expert in programming the native window system. Experience also</span> <a name="line-148"></a><span class='hs-comment'>-- demonstrated that IRIS GL\'s windowing interface was high-level enough that</span> <a name="line-149"></a><span class='hs-comment'>-- it could be retargeted to different window systems. Silicon Graphics migrated</span> <a name="line-150"></a><span class='hs-comment'>-- from NeWS to the X Window System without any major changes to IRIS GL\'s</span> <a name="line-151"></a><span class='hs-comment'>-- basic windowing interface.</span> <a name="line-152"></a><span class='hs-comment'>--</span> <a name="line-153"></a><span class='hs-comment'>-- Removing window system operations from OpenGL is a sound decision because it</span> <a name="line-154"></a><span class='hs-comment'>-- allows the OpenGL graphics system to be retargeted to various systems</span> <a name="line-155"></a><span class='hs-comment'>-- including powerful but expensive graphics workstations as well as</span> <a name="line-156"></a><span class='hs-comment'>-- mass-production graphics systems like video games, set-top boxes for</span> <a name="line-157"></a><span class='hs-comment'>-- interactive television, and PCs.</span> <a name="line-158"></a><span class='hs-comment'>--</span> <a name="line-159"></a><span class='hs-comment'>-- Unfortunately, the lack of a window system interface for OpenGL is a gap in</span> <a name="line-160"></a><span class='hs-comment'>-- OpenGL\'s utility. Learning native window system APIs such as the X Window</span> <a name="line-161"></a><span class='hs-comment'>-- System\'s Xlib or Motif can be daunting. Even those familiar with</span> <a name="line-162"></a><span class='hs-comment'>-- native window system APIs need to understand the interface that binds OpenGL</span> <a name="line-163"></a><span class='hs-comment'>-- to the native window system. And when an OpenGL program is written using the</span> <a name="line-164"></a><span class='hs-comment'>-- native window system interface, despite the portability of the program\'s</span> <a name="line-165"></a><span class='hs-comment'>-- OpenGL rendering code, the program itself will be window system dependent.</span> <a name="line-166"></a><span class='hs-comment'>--</span> <a name="line-167"></a><span class='hs-comment'>-- Testing and documenting OpenGL\'s functionality lead to the development of</span> <a name="line-168"></a><span class='hs-comment'>-- the @tk@ and @aux@ toolkits. The @aux@ toolkit is used in the examples found</span> <a name="line-169"></a><span class='hs-comment'>-- in the /OpenGL Programming Guide/. Unfortunately, @aux@ has numerous</span> <a name="line-170"></a><span class='hs-comment'>-- limitations and its utility is largely limited to toy programs. The @tk@</span> <a name="line-171"></a><span class='hs-comment'>-- library has more functionality than @aux@ but was developed in an /ad hoc/</span> <a name="line-172"></a><span class='hs-comment'>-- fashion and still lacks much important functionality that IRIS GL programmers</span> <a name="line-173"></a><span class='hs-comment'>-- expect, like pop-up menus and overlays.</span> <a name="line-174"></a><span class='hs-comment'>--</span> <a name="line-175"></a><span class='hs-comment'>-- GLUT is designed to fill the need for a window system independent programming</span> <a name="line-176"></a><span class='hs-comment'>-- interface for OpenGL programs. The interface is designed to be simple yet</span> <a name="line-177"></a><span class='hs-comment'>-- still meet the needs of useful OpenGL programs. Features from the IRIS GL,</span> <a name="line-178"></a><span class='hs-comment'>-- @aux@, and @tk@ interfaces are included to make it easy for programmers used</span> <a name="line-179"></a><span class='hs-comment'>-- to these interfaces to develop programs for GLUT.</span> <a name="line-180"></a> <a name="line-181"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-182"></a><span class='hs-comment'>-- $DesignPhilosophy</span> <a name="line-183"></a><span class='hs-comment'>-- GLUT simplifies the implementation of programs using OpenGL rendering. The</span> <a name="line-184"></a><span class='hs-comment'>-- GLUT application programming interface (API) requires very few routines to</span> <a name="line-185"></a><span class='hs-comment'>-- display a graphics scene rendered using OpenGL. The GLUT API (like the OpenGL</span> <a name="line-186"></a><span class='hs-comment'>-- API) is stateful. Most initial GLUT state is defined and the initial state is</span> <a name="line-187"></a><span class='hs-comment'>-- reasonable for simple programs. The GLUT routines also take relatively few</span> <a name="line-188"></a><span class='hs-comment'>-- parameters.</span> <a name="line-189"></a><span class='hs-comment'>--</span> <a name="line-190"></a><span class='hs-comment'>-- The GLUT API is (as much as reasonable) window system independent. For this</span> <a name="line-191"></a><span class='hs-comment'>-- reason, GLUT does not return /any/ native window system handles, pointers, or</span> <a name="line-192"></a><span class='hs-comment'>-- other data structures. More subtle window system dependencies such as</span> <a name="line-193"></a><span class='hs-comment'>-- reliance on window system dependent fonts are avoided by GLUT; instead, GLUT</span> <a name="line-194"></a><span class='hs-comment'>-- supplies its own (limited) set of fonts.</span> <a name="line-195"></a><span class='hs-comment'>--</span> <a name="line-196"></a><span class='hs-comment'>-- For programming ease, GLUT provides a simple menu sub-API. While the menuing</span> <a name="line-197"></a><span class='hs-comment'>-- support is designed to be implemented as pop-up menus, GLUT gives window</span> <a name="line-198"></a><span class='hs-comment'>-- system leeway to support the menu functionality in another manner (pull-down</span> <a name="line-199"></a><span class='hs-comment'>-- menus for example).</span> <a name="line-200"></a><span class='hs-comment'>--</span> <a name="line-201"></a><span class='hs-comment'>-- Two of the most important pieces of GLUT state are the /current window/ and</span> <a name="line-202"></a><span class='hs-comment'>-- /current menu/. Most window and menu routines affect the /current window/ or</span> <a name="line-203"></a><span class='hs-comment'>-- /menu/ respectively. Most callbacks implicitly set the /current window/ and</span> <a name="line-204"></a><span class='hs-comment'>-- /menu/ to the appropriate window or menu responsible for the callback. GLUT</span> <a name="line-205"></a><span class='hs-comment'>-- is designed so that a program with only a single window and\/or menu will not</span> <a name="line-206"></a><span class='hs-comment'>-- need to keep track of any window or menu identifiers. This greatly simplifies</span> <a name="line-207"></a><span class='hs-comment'>-- very simple GLUT programs.</span> <a name="line-208"></a><span class='hs-comment'>--</span> <a name="line-209"></a><span class='hs-comment'>-- GLUT is designed for simple to moderately complex programs focused on OpenGL</span> <a name="line-210"></a><span class='hs-comment'>-- rendering. GLUT implements its own event loop. For this reason, mixing GLUT</span> <a name="line-211"></a><span class='hs-comment'>-- with other APIs that demand their own event handling structure may be</span> <a name="line-212"></a><span class='hs-comment'>-- difficult. The advantage of a builtin event dispatch loop is simplicity.</span> <a name="line-213"></a><span class='hs-comment'>--</span> <a name="line-214"></a><span class='hs-comment'>-- GLUT contains routines for rendering fonts and geometric objects, however</span> <a name="line-215"></a><span class='hs-comment'>-- GLUT makes no claims on the OpenGL display list name space. For this reason,</span> <a name="line-216"></a><span class='hs-comment'>-- none of the GLUT rendering routines use OpenGL display lists. It is up to the</span> <a name="line-217"></a><span class='hs-comment'>-- GLUT programmer to compile the output from GLUT rendering routines into</span> <a name="line-218"></a><span class='hs-comment'>-- display lists if this is desired.</span> <a name="line-219"></a><span class='hs-comment'>--</span> <a name="line-220"></a><span class='hs-comment'>-- GLUT routines are logically organized into several sub-APIs according to</span> <a name="line-221"></a><span class='hs-comment'>-- their functionality. The sub-APIs are:</span> <a name="line-222"></a><span class='hs-comment'>--</span> <a name="line-223"></a><span class='hs-comment'>-- * /Initialization:/ Command line processing, window system initialization,</span> <a name="line-224"></a><span class='hs-comment'>-- and initial window creation state are controlled by these routines.</span> <a name="line-225"></a><span class='hs-comment'>--</span> <a name="line-226"></a><span class='hs-comment'>-- * /Beginning Event Processing:/ This routine enters GLUT\'s event processing</span> <a name="line-227"></a><span class='hs-comment'>-- loop. This routine never returns, and it continuously calls GLUT callbacks</span> <a name="line-228"></a><span class='hs-comment'>-- as necessary.</span> <a name="line-229"></a><span class='hs-comment'>--</span> <a name="line-230"></a><span class='hs-comment'>-- * /Window Management:/ These routines create and control windows.</span> <a name="line-231"></a><span class='hs-comment'>--</span> <a name="line-232"></a><span class='hs-comment'>-- * /Overlay Management:/ These routines establish and manage overlays for</span> <a name="line-233"></a><span class='hs-comment'>-- windows.</span> <a name="line-234"></a><span class='hs-comment'>--</span> <a name="line-235"></a><span class='hs-comment'>-- * /Menu Management:/ These routines create and control pop-up menus.</span> <a name="line-236"></a><span class='hs-comment'>--</span> <a name="line-237"></a><span class='hs-comment'>-- * /Callback Registration:/ These routines register callbacks to be called by</span> <a name="line-238"></a><span class='hs-comment'>-- the GLUT event processing loop.</span> <a name="line-239"></a><span class='hs-comment'>--</span> <a name="line-240"></a><span class='hs-comment'>-- * /Color Index Colormap Management:/ These routines allow the manipulation</span> <a name="line-241"></a><span class='hs-comment'>-- of color index colormaps for windows.</span> <a name="line-242"></a><span class='hs-comment'>--</span> <a name="line-243"></a><span class='hs-comment'>-- * /State Retrieval:/ These routines allows programs to retrieve state from</span> <a name="line-244"></a><span class='hs-comment'>-- GLUT.</span> <a name="line-245"></a><span class='hs-comment'>--</span> <a name="line-246"></a><span class='hs-comment'>-- * /Font Rendering:/ These routines allow rendering of stroke and bitmap</span> <a name="line-247"></a><span class='hs-comment'>-- fonts.</span> <a name="line-248"></a><span class='hs-comment'>--</span> <a name="line-249"></a><span class='hs-comment'>-- * /Geometric Shape Rendering:/ These routines allow the rendering of 3D</span> <a name="line-250"></a><span class='hs-comment'>-- geometric objects including spheres, cones, icosahedrons, and teapots.</span> <a name="line-251"></a><span class='hs-comment'>--</span> <a name="line-252"></a><span class='hs-comment'>-- * /Debugging:/ This routine reports any pending GL errors.</span> <a name="line-253"></a><span class='hs-comment'>--</span> <a name="line-254"></a><span class='hs-comment'>-- * /Device Control:/ These routines allow setting the key repeat and polling</span> <a name="line-255"></a><span class='hs-comment'>-- the joystick.</span> <a name="line-256"></a><span class='hs-comment'>--</span> <a name="line-257"></a><span class='hs-comment'>-- * /Game Mode:/ These routines allow programs to enter\/leave a full-screen</span> <a name="line-258"></a><span class='hs-comment'>-- mode with specified properties.</span> <a name="line-259"></a> <a name="line-260"></a><span class='hs-comment'>-- Note that the following item has been left out intentionally, its</span> <a name="line-261"></a><span class='hs-comment'>-- implementation is too SGI-specific:</span> <a name="line-262"></a><span class='hs-comment'>-- * /Video Resizing:/ These routines provide a means for doing swap or frame</span> <a name="line-263"></a><span class='hs-comment'>-- synchronous resizing\/panning of the area that is to be magnified (or</span> <a name="line-264"></a><span class='hs-comment'>-- passed through) to the output video resolution.</span> <a name="line-265"></a> <a name="line-266"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-267"></a><span class='hs-comment'>-- $APIVersions</span> <a name="line-268"></a><span class='hs-comment'>-- The GLUT API has undergone several revisions with increasing functionality.</span> <a name="line-269"></a><span class='hs-comment'>-- This Haskell binding provides access to everything in API version 4,</span> <a name="line-270"></a><span class='hs-comment'>-- although it is not yet officially finalized. Nevertheless, it provides very</span> <a name="line-271"></a><span class='hs-comment'>-- useful things like handling full-screen modes and special keys.</span> <a name="line-272"></a> <a name="line-273"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-274"></a><span class='hs-comment'>-- $Conventions</span> <a name="line-275"></a><span class='hs-comment'>-- GLUT window and screen coordinates are expressed in pixels. The upper</span> <a name="line-276"></a><span class='hs-comment'>-- left hand corner of the screen or a window is (0,0). X coordinates</span> <a name="line-277"></a><span class='hs-comment'>-- increase in a rightward direction; Y coordinates increase in a</span> <a name="line-278"></a><span class='hs-comment'>-- downward direction. Note: This is inconsistent with OpenGL\'s</span> <a name="line-279"></a><span class='hs-comment'>-- coordinate scheme that generally considers the lower left hand</span> <a name="line-280"></a><span class='hs-comment'>-- coordinate of a window to be at (0,0) but is consistent with most</span> <a name="line-281"></a><span class='hs-comment'>-- popular window systems.</span> <a name="line-282"></a> <a name="line-283"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span> <a name="line-284"></a><span class='hs-comment'>-- $Terminology</span> <a name="line-285"></a><span class='hs-comment'>-- A number of terms are used in a GLUT-specific manner throughout this</span> <a name="line-286"></a><span class='hs-comment'>-- document. The GLUT meaning of these terms is independent of the window</span> <a name="line-287"></a><span class='hs-comment'>-- system GLUT is used with. Here are GLUT-specific meanings for the</span> <a name="line-288"></a><span class='hs-comment'>-- following GLUT-specific terms:</span> <a name="line-289"></a><span class='hs-comment'>--</span> <a name="line-290"></a><span class='hs-comment'>-- * /Callback:/ A programmer specified routine that can be registered with</span> <a name="line-291"></a><span class='hs-comment'>-- GLUT to be called in response to a specific type of event. Also used to</span> <a name="line-292"></a><span class='hs-comment'>-- refer to a specific callback routine being called.</span> <a name="line-293"></a><span class='hs-comment'>--</span> <a name="line-294"></a><span class='hs-comment'>-- * /Colormap:/ A mapping of pixel values to RGB color values. Used by color</span> <a name="line-295"></a><span class='hs-comment'>-- index windows.</span> <a name="line-296"></a><span class='hs-comment'>--</span> <a name="line-297"></a><span class='hs-comment'>-- * /Dials and button box:/ A sophisticated input device consisting of a pad</span> <a name="line-298"></a><span class='hs-comment'>-- of buttons and an array of rotating dials, often used by computer-aided</span> <a name="line-299"></a><span class='hs-comment'>-- design programs.</span> <a name="line-300"></a><span class='hs-comment'>--</span> <a name="line-301"></a><span class='hs-comment'>-- * /Display mode:/ A set of OpenGL frame buffer capabilities that can be</span> <a name="line-302"></a><span class='hs-comment'>-- attributed to a window.</span> <a name="line-303"></a><span class='hs-comment'>--</span> <a name="line-304"></a><span class='hs-comment'>-- * /Idle:/ A state when no window system events are received for processing</span> <a name="line-305"></a><span class='hs-comment'>-- as callbacks and the idle callback, if one is registered, is called.</span> <a name="line-306"></a><span class='hs-comment'>--</span> <a name="line-307"></a><span class='hs-comment'>-- * /Layer in use:/ Either the normal plane or overlay. This per-window state</span> <a name="line-308"></a><span class='hs-comment'>-- determines what frame buffer layer OpenGL commands affect.</span> <a name="line-309"></a><span class='hs-comment'>--</span> <a name="line-310"></a><span class='hs-comment'>-- * /Menu entry:/ A menu item that the user can select to trigger the menu</span> <a name="line-311"></a><span class='hs-comment'>-- callback for the menu entry\'s value.</span> <a name="line-312"></a><span class='hs-comment'>--</span> <a name="line-313"></a><span class='hs-comment'>-- * /Menu item:/ Either a menu entry or a sub-menu trigger.</span> <a name="line-314"></a><span class='hs-comment'>--</span> <a name="line-315"></a><span class='hs-comment'>-- * /Modifiers:/ The Shift, Ctrl, and Alt keys that can be held down</span> <a name="line-316"></a><span class='hs-comment'>-- simultaneously with a key or mouse button being pressed or released.</span> <a name="line-317"></a><span class='hs-comment'>--</span> <a name="line-318"></a><span class='hs-comment'>-- * /Multisampling:/ A technique for hardware antialiasing generally available</span> <a name="line-319"></a><span class='hs-comment'>-- only on expensive 3D graphics hardware. Each pixel is composed of a number</span> <a name="line-320"></a><span class='hs-comment'>-- of samples (each containing color and depth information). The samples are</span> <a name="line-321"></a><span class='hs-comment'>-- averaged to determine the displayed pixel color value. Multisampling is</span> <a name="line-322"></a><span class='hs-comment'>-- supported as an extension to OpenGL.</span> <a name="line-323"></a><span class='hs-comment'>--</span> <a name="line-324"></a><span class='hs-comment'>-- * /Normal plane:/ The default frame buffer layer where GLUT window state</span> <a name="line-325"></a><span class='hs-comment'>-- resides; as opposed to the /overlay/.</span> <a name="line-326"></a><span class='hs-comment'>--</span> <a name="line-327"></a><span class='hs-comment'>-- * /Overlay:/ A frame buffer layer that can be displayed preferentially to</span> <a name="line-328"></a><span class='hs-comment'>-- the /normal plane/ and supports transparency to display through to the</span> <a name="line-329"></a><span class='hs-comment'>-- /normal plane/. Overlays are useful for rubber-banding effects, text</span> <a name="line-330"></a><span class='hs-comment'>-- annotation, and other operations, to avoid damaging the normal plane frame</span> <a name="line-331"></a><span class='hs-comment'>-- buffer state. Overlays require hardware support not present on all systems.</span> <a name="line-332"></a><span class='hs-comment'>--</span> <a name="line-333"></a><span class='hs-comment'>-- * /Pop:/ The act of forcing a window to the top of the stacking order for</span> <a name="line-334"></a><span class='hs-comment'>-- sibling windows.</span> <a name="line-335"></a><span class='hs-comment'>--</span> <a name="line-336"></a><span class='hs-comment'>-- * /Pop-up menu:/ A menu that can be set to appear when a specified mouse</span> <a name="line-337"></a><span class='hs-comment'>-- button is pressed in a window. A pop-menu consists of multiple menu items.</span> <a name="line-338"></a><span class='hs-comment'>--</span> <a name="line-339"></a><span class='hs-comment'>-- * /Push:/ The act of forcing a window to the bottom of the stacking order</span> <a name="line-340"></a><span class='hs-comment'>-- for sibling windows.</span> <a name="line-341"></a><span class='hs-comment'>--</span> <a name="line-342"></a><span class='hs-comment'>-- * /Reshape:/ The act of changing the size or shape of the window.</span> <a name="line-343"></a><span class='hs-comment'>--</span> <a name="line-344"></a><span class='hs-comment'>-- * /Spaceball:/ A sophisticated 3D input device that provides six degrees of</span> <a name="line-345"></a><span class='hs-comment'>-- freedom, three axes of rotation and three axes of translation. It also</span> <a name="line-346"></a><span class='hs-comment'>-- supports a number of buttons. The device is a hand-sized ball attached to</span> <a name="line-347"></a><span class='hs-comment'>-- a base. By cupping the ball with one\'s hand and applying torsional or</span> <a name="line-348"></a><span class='hs-comment'>-- directional force on the ball, rotations and translationsare generated.</span> <a name="line-349"></a><span class='hs-comment'>--</span> <a name="line-350"></a><span class='hs-comment'>-- * /Stereo:/ A frame buffer capability providing left and right color buffers</span> <a name="line-351"></a><span class='hs-comment'>-- for creating stereoscopic renderings. Typically, the user wears LCD</span> <a name="line-352"></a><span class='hs-comment'>-- shuttered goggles synchronized with the alternating display on the screen</span> <a name="line-353"></a><span class='hs-comment'>-- of the left and right color buffers.</span> <a name="line-354"></a><span class='hs-comment'>--</span> <a name="line-355"></a><span class='hs-comment'>-- * /Sub-menu:/ A menu cascaded from some sub-menu trigger.</span> <a name="line-356"></a><span class='hs-comment'>--</span> <a name="line-357"></a><span class='hs-comment'>-- * /Sub-menu trigger:/ A menu item that the user can enter to cascade another</span> <a name="line-358"></a><span class='hs-comment'>-- pop-up menu.</span> <a name="line-359"></a><span class='hs-comment'>--</span> <a name="line-360"></a><span class='hs-comment'>-- * /Subwindow:/ A type of window that is the child window of a top-level</span> <a name="line-361"></a><span class='hs-comment'>-- window or other subwindow. The drawing and visible region of a subwindow</span> <a name="line-362"></a><span class='hs-comment'>-- is limited by its parent window.</span> <a name="line-363"></a><span class='hs-comment'>--</span> <a name="line-364"></a><span class='hs-comment'>-- * /Tablet:/ A precise 2D input device. Like a mouse, 2D coordinates are</span> <a name="line-365"></a><span class='hs-comment'>-- returned. The absolute position of the tablet \"puck\" on the tablet is</span> <a name="line-366"></a><span class='hs-comment'>-- returned. Tablets also support a number of buttons.</span> <a name="line-367"></a><span class='hs-comment'>--</span> <a name="line-368"></a><span class='hs-comment'>-- * /Timer:/ A callback that can be scheduled to be called in a specified</span> <a name="line-369"></a><span class='hs-comment'>-- interval of time.</span> <a name="line-370"></a><span class='hs-comment'>--</span> <a name="line-371"></a><span class='hs-comment'>-- * /Top-level window:/ A window that can be placed, moved, resized, etc.</span> <a name="line-372"></a><span class='hs-comment'>-- independently from other top-level windows by the user. Subwindows may</span> <a name="line-373"></a><span class='hs-comment'>-- reside within a top-level window.</span> <a name="line-374"></a><span class='hs-comment'>--</span> <a name="line-375"></a><span class='hs-comment'>-- * /Window:/ A rectangular area for OpenGL rendering.</span> <a name="line-376"></a><span class='hs-comment'>--</span> <a name="line-377"></a><span class='hs-comment'>-- * /Window display state:/ One of shown, hidden, or iconified. A shown window</span> <a name="line-378"></a><span class='hs-comment'>-- is potentially visible on the screen (it may be obscured by other windows</span> <a name="line-379"></a><span class='hs-comment'>-- and not actually visible). A hidden window will never be visible. An</span> <a name="line-380"></a><span class='hs-comment'>-- iconified window is not visible but could be made visible in response to</span> <a name="line-381"></a><span class='hs-comment'>-- some user action like clicking on the window\'s corresponding icon.</span> <a name="line-382"></a><span class='hs-comment'>--</span> <a name="line-383"></a><span class='hs-comment'>-- * /Window system:/ A broad notion that refers to both the mechanism and</span> <a name="line-384"></a><span class='hs-comment'>-- policy of the window system. For example, in the X Window System both the</span> <a name="line-385"></a><span class='hs-comment'>-- window manager and the X server are integral to what GLUT considers the</span> <a name="line-386"></a><span class='hs-comment'>-- window system.</span> </pre></body> </html>
