/usr/share/doc/libghc-glut-doc/html/src/Graphics-UI-GLUT.html is in libghc-glut-doc 2.7.0.12-1build5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 | <?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://code.haskell.org/~malcolm/hscolour/ -->
<title>src/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-2013</span>
<a name="line-5"></a><span class='hs-comment'>-- License : BSD3</span>
<a name="line-6"></a><span class='hs-comment'>--</span>
<a name="line-7"></a><span class='hs-comment'>-- Maintainer : Sven Panne <svenpanne@gmail.com></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>
|