/usr/share/doc/libghc-glut-doc/html/Graphics-UI-GLUT.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Graphics.UI.GLUT</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Graphics-UI-GLUT.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Graphics-UI-GLUT.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">GLUT-2.4.0.0: A binding for the OpenGL Utility Toolkit</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>portable</td></tr><tr><th>Stability</th><td>stable</td></tr><tr><th>Maintainer</th><td>sven.panne@aedion.de</td></tr><tr><th>Safe Haskell</th><td>None</td></tr></table><p class="caption">Graphics.UI.GLUT</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Legal stuff
</a></li><li><a href="#g:2">Introduction
</a><ul><li><a href="#g:3">Background
</a></li><li><a href="#g:4">Design Philosophy
</a></li><li><a href="#g:5">API Versions
</a></li><li><a href="#g:6">Conventions
</a></li><li><a href="#g:7">Terminology
</a></li></ul></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>A Haskell binding for GLUT, the OpenGL Utility Toolkit, a window system
 independent toolkit for writing OpenGL programs. It includes support for
 the extended functionality available in freeglut (see
 <a href="http://freeglut.sourceforge.net/">http://freeglut.sourceforge.net/</a>) and OpenGLUT (see
 <a href="http://openglut.sourceforge.net/">http://openglut.sourceforge.net/</a>), too.
</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short">module <a href="/usr/share/doc/libghc-opengl-doc/html/Graphics-Rendering-OpenGL.html">Graphics.Rendering.OpenGL</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Initialization.html">Graphics.UI.GLUT.Initialization</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Begin.html">Graphics.UI.GLUT.Begin</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Window.html">Graphics.UI.GLUT.Window</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Overlay.html">Graphics.UI.GLUT.Overlay</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Menu.html">Graphics.UI.GLUT.Menu</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Callbacks.html">Graphics.UI.GLUT.Callbacks</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Colormap.html">Graphics.UI.GLUT.Colormap</a></li><li class="src short">module <a href="Graphics-UI-GLUT-State.html">Graphics.UI.GLUT.State</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Fonts.html">Graphics.UI.GLUT.Fonts</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Objects.html">Graphics.UI.GLUT.Objects</a></li><li class="src short">module <a href="Graphics-UI-GLUT-Debugging.html">Graphics.UI.GLUT.Debugging</a></li><li class="src short">module <a href="Graphics-UI-GLUT-DeviceControl.html">Graphics.UI.GLUT.DeviceControl</a></li><li class="src short">module <a href="Graphics-UI-GLUT-GameMode.html">Graphics.UI.GLUT.GameMode</a></li></ul></div><div id="interface"><h1 id="g:1">Legal stuff
</h1><div class="doc"><p>This documentation is heavily based on the man pages of Mark J. Kilgard's
 GLUT library.
</p><p>OpenGL is a trademark of Silicon Graphics, Inc.
 X Window System is a trademark of X Consortium, Inc.
 Spaceball is a registered trademark of Spatial Systems, Inc.
</p><p>The author has taken care in preparation of this documentation but makes
 no expressed or implied warranty of any kind and assumes no responsibility
 for errors or omissions. No liability is assumed for incidental or
 consequential damages in connection with or arising from the use of
 information or programs contained herein.
</p></div><h1 id="g:2">Introduction
</h1><div class="doc"><p>The OpenGL Utility Toolkit (GLUT) is a programming interface for writing
 window system independent OpenGL programs. Currently there are
 implementations for the X Window System, the Windows family, OS/2, and Mac.
 The toolkit supports the following functionality:
</p><ul><li> Multiple windows for OpenGL rendering.
</li><li> Callback driven event processing.
</li><li> Sophisticated input devices.
</li><li> An <em>idle</em> routine and timers.
</li><li> A simple, cascading pop-up menu facility.
</li><li> Utility routines to generate various solid and wire frame objects.
</li><li> Support for bitmap and stroke fonts.
</li><li> Miscellaneous window management functions, including managing overlays.
</li></ul><p>This documentation serves as both a specification and a programming guide.
 If you are interested in a brief introduction to programming with GLUT,
 have a look at the relevant parts of <a href="http://www.opengl.org/">http://www.opengl.org/</a> and the vast
 amount of books on OpenGL, most of them use GLUT.
</p><p>The remainder of this section describes GLUT's design philosophy and
 usage model. The following sections specify the GLUT routines, grouped by
 functionality. The final sections discuss usage advice and the logical
 programmer visible state maintained by GLUT.
</p></div><h2 id="g:3">Background
</h2><div class="doc"><p>One of the major accomplishments in the specification of OpenGL was
 the isolation of window system dependencies from OpenGL's rendering
 model. The result is that OpenGL is window system independent.
</p><p>Window system operations such as the creation of a rendering window and the
 handling of window system events are left to the native window system to
 define. Necessary interactions between OpenGL and the window system such as
 creating and binding an OpenGL context to a window are described separately
 from the OpenGL specification in a window system dependent specification. For
 example, the GLX specification describes the standard by which OpenGL
 interacts with the X Window System.
</p><p>The predecessor to OpenGL is IRIS GL. Unlike OpenGL, IRIS GL <em>does</em>
 specify how rendering windows are created and manipulated. IRIS GL's
 windowing interface is reasonably popular largely because it is simple to
 use. IRIS GL programmers can worry about graphics programming without needing
 to be an expert in programming the native window system. Experience also
 demonstrated that IRIS GL's windowing interface was high-level enough that
 it could be retargeted to different window systems. Silicon Graphics migrated
 from NeWS to the X Window System without any major changes to IRIS GL's
 basic windowing interface.
</p><p>Removing window system operations from OpenGL is a sound decision because it
 allows the OpenGL graphics system to be retargeted to various systems
 including powerful but expensive graphics workstations as well as
 mass-production graphics systems like video games, set-top boxes for
 interactive television, and PCs.
</p><p>Unfortunately, the lack of a window system interface for OpenGL is a gap in
 OpenGL's utility. Learning native window system APIs such as the X Window
 System's Xlib or Motif can be daunting. Even those familiar with
 native window system APIs need to understand the interface that binds OpenGL
 to the native window system. And when an OpenGL program is written using the
 native window system interface, despite the portability of the program's
 OpenGL rendering code, the program itself will be window system dependent.
</p><p>Testing and documenting OpenGL's functionality lead to the development of
 the <code>tk</code> and <code>aux</code> toolkits. The <code>aux</code> toolkit is used in the examples found
 in the <em>OpenGL Programming Guide</em>. Unfortunately, <code>aux</code> has numerous
 limitations and its utility is largely limited to toy programs. The <code>tk</code>
 library has more functionality than <code>aux</code> but was developed in an <em>ad hoc</em>
 fashion and still lacks much important functionality that IRIS GL programmers
 expect, like pop-up menus and overlays.
</p><p>GLUT is designed to fill the need for a window system independent programming
 interface for OpenGL programs. The interface is designed to be simple yet
 still meet the needs of useful OpenGL programs. Features from the IRIS GL,
 <code>aux</code>, and <code>tk</code> interfaces are included to make it easy for programmers used
 to these interfaces to develop programs for GLUT.
</p></div><h2 id="g:4">Design Philosophy
</h2><div class="doc"><p>GLUT simplifies the implementation of programs using OpenGL rendering. The
 GLUT application programming interface (API) requires very few routines to
 display a graphics scene rendered using OpenGL. The GLUT API (like the OpenGL
 API) is stateful. Most initial GLUT state is defined and the initial state is
 reasonable for simple programs. The GLUT routines also take relatively few
 parameters.
</p><p>The GLUT API is (as much as reasonable) window system independent. For this
 reason, GLUT does not return <em>any</em> native window system handles, pointers, or
 other data structures. More subtle window system dependencies such as
 reliance on window system dependent fonts are avoided by GLUT; instead, GLUT
 supplies its own (limited) set of fonts.
</p><p>For programming ease, GLUT provides a simple menu sub-API. While the menuing
 support is designed to be implemented as pop-up menus, GLUT gives window
 system leeway to support the menu functionality in another manner (pull-down
 menus for example).
</p><p>Two of the most important pieces of GLUT state are the <em>current window</em> and
 <em>current menu</em>. Most window and menu routines affect the <em>current window</em> or
 <em>menu</em> respectively. Most callbacks implicitly set the <em>current window</em> and
 <em>menu</em> to the appropriate window or menu responsible for the callback. GLUT
 is designed so that a program with only a single window and/or menu will not
 need to keep track of any window or menu identifiers. This greatly simplifies
 very simple GLUT programs.
</p><p>GLUT is designed for simple to moderately complex programs focused on OpenGL
 rendering. GLUT implements its own event loop. For this reason, mixing GLUT
 with other APIs that demand their own event handling structure may be
 difficult. The advantage of a builtin event dispatch loop is simplicity.
</p><p>GLUT contains routines for rendering fonts and geometric objects, however
 GLUT makes no claims on the OpenGL display list name space. For this reason,
 none of the GLUT rendering routines use OpenGL display lists. It is up to the
 GLUT programmer to compile the output from GLUT rendering routines into
 display lists if this is desired.
</p><p>GLUT routines are logically organized into several sub-APIs according to
 their functionality. The sub-APIs are:
</p><ul><li> <em>Initialization:</em> Command line processing, window system initialization,
   and initial window creation state are controlled by these routines.
</li><li> <em>Beginning Event Processing:</em> This routine enters GLUT's event processing
   loop. This routine never returns, and it continuously calls GLUT callbacks
   as necessary.
</li><li> <em>Window Management:</em> These routines create and control windows.
</li><li> <em>Overlay Management:</em> These routines establish and manage overlays for
   windows.
</li><li> <em>Menu Management:</em> These routines create and control pop-up menus.
</li><li> <em>Callback Registration:</em> These routines register callbacks to be called by
   the GLUT event processing loop.
</li><li> <em>Color Index Colormap Management:</em> These routines allow the manipulation
   of color index colormaps for windows.
</li><li> <em>State Retrieval:</em> These routines allows programs to retrieve state from
   GLUT.
</li><li> <em>Font Rendering:</em> These routines allow rendering of stroke and bitmap
   fonts.
</li><li> <em>Geometric Shape Rendering:</em> These routines allow the rendering of 3D
   geometric objects including spheres, cones, icosahedrons, and teapots.
</li><li> <em>Debugging:</em> This routine reports any pending GL errors.
</li><li> <em>Device Control:</em> These routines allow setting the key repeat and polling
   the joystick.
</li><li> <em>Game Mode:</em> These routines allow programs to enter/leave a full-screen
   mode with specified properties.
</li></ul></div><h2 id="g:5">API Versions
</h2><div class="doc"><p>The GLUT API has undergone several revisions with increasing functionality.
 This Haskell binding provides access to everything in API version 4,
 although it is not yet officially finalized. Nevertheless, it provides very
 useful things like handling full-screen modes and special keys.
</p></div><h2 id="g:6">Conventions
</h2><div class="doc"><p>GLUT window and screen coordinates are expressed in pixels. The upper
 left hand corner of the screen or a window is (0,0). X coordinates
 increase in a rightward direction; Y coordinates increase in a
 downward direction. Note: This is inconsistent with OpenGL's
 coordinate scheme that generally considers the lower left hand
 coordinate of a window to be at (0,0) but is consistent with most
 popular window systems.
</p></div><h2 id="g:7">Terminology
</h2><div class="doc"><p>A number of terms are used in a GLUT-specific manner throughout this
 document. The GLUT meaning of these terms is independent of the window
 system GLUT is used with. Here are GLUT-specific meanings for the
 following GLUT-specific terms:
</p><ul><li> <em>Callback:</em> A programmer specified routine that can be registered with
   GLUT to be called in response to a specific type of event. Also used to
 refer to a specific callback routine being called.
</li><li> <em>Colormap:</em> A mapping of pixel values to RGB color values. Used by color
   index windows.
</li><li> <em>Dials and button box:</em> A sophisticated input device consisting of a pad
   of buttons and an array of rotating dials, often used by computer-aided
   design programs.
</li><li> <em>Display mode:</em> A set of OpenGL frame buffer capabilities that can be
   attributed to a window.
</li><li> <em>Idle:</em> A state when no window system events are received for processing
   as callbacks and the idle callback, if one is registered, is called.
</li><li> <em>Layer in use:</em> Either the normal plane or overlay. This per-window state
   determines what frame buffer layer OpenGL commands affect.
</li><li> <em>Menu entry:</em> A menu item that the user can select to trigger the menu
   callback for the menu entry's value.
</li><li> <em>Menu item:</em> Either a menu entry or a sub-menu trigger.
</li><li> <em>Modifiers:</em> The Shift, Ctrl, and Alt keys that can be held down
   simultaneously with a key or mouse button being pressed or released.
</li><li> <em>Multisampling:</em> A technique for hardware antialiasing generally available
   only on expensive 3D graphics hardware. Each pixel is composed of a number
   of samples (each containing color and depth information). The samples are
   averaged to determine the displayed pixel color value. Multisampling is
   supported as an extension to OpenGL.
</li><li> <em>Normal plane:</em> The default frame buffer layer where GLUT window state
   resides; as opposed to the <em>overlay</em>.
</li><li> <em>Overlay:</em> A frame buffer layer that can be displayed preferentially to
   the <em>normal plane</em> and supports transparency to display through to the
   <em>normal plane</em>. Overlays are useful for rubber-banding effects, text
   annotation, and other operations, to avoid damaging the normal plane frame
   buffer state. Overlays require hardware support not present on all systems.
</li><li> <em>Pop:</em> The act of forcing a window to the top of the stacking order for
   sibling windows.
</li><li> <em>Pop-up menu:</em> A menu that can be set to appear when a specified mouse
   button is pressed in a window. A pop-menu consists of multiple menu items.
</li><li> <em>Push:</em> The act of forcing a window to the bottom of the stacking order
   for sibling windows.
</li><li> <em>Reshape:</em> The act of changing the size or shape of the window.
</li><li> <em>Spaceball:</em> A sophisticated 3D input device that provides six degrees of
   freedom, three axes of rotation and three axes of translation. It also
   supports a number of buttons. The device is a hand-sized ball attached to
   a base. By cupping the ball with one's hand and applying torsional or
   directional force on the ball, rotations and translationsare generated.
</li><li> <em>Stereo:</em> A frame buffer capability providing left and right color buffers
   for creating stereoscopic renderings. Typically, the user wears LCD
   shuttered goggles synchronized with the alternating display on the screen
   of the left and right color buffers.
</li><li> <em>Sub-menu:</em> A menu cascaded from some sub-menu trigger.
</li><li> <em>Sub-menu trigger:</em> A menu item that the user can enter to cascade another
   pop-up menu.
</li><li> <em>Subwindow:</em> A type of window that is the child window of a top-level
   window or other subwindow. The drawing and visible region of a subwindow
   is limited by its parent window.
</li><li> <em>Tablet:</em> A precise 2D input device. Like a mouse, 2D coordinates are
   returned. The absolute position of the tablet &quot;puck&quot; on the tablet is
   returned. Tablets also support a number of buttons.
</li><li> <em>Timer:</em> A callback that can be scheduled to be called in a specified
   interval of time.
</li><li> <em>Top-level window:</em> A window that can be placed, moved, resized, etc.
   independently from other top-level windows by the user. Subwindows may
   reside within a top-level window.
</li><li> <em>Window:</em> A rectangular area for OpenGL rendering.
</li><li> <em>Window display state:</em> One of shown, hidden, or iconified. A shown window
   is potentially visible on the screen (it may be obscured by other windows
   and not actually visible). A hidden window will never be visible. An
   iconified window is not visible but could be made visible in response to
   some user action like clicking on the window's corresponding icon.
</li><li> <em>Window system:</em> A broad notion that refers to both the mechanism and
   policy of the window system. For example, in the X Window System both the
   window manager and the X server are integral to what GLUT considers the
   window system.
</li></ul></div><div class="top"><p class="src">module <a href="/usr/share/doc/libghc-opengl-doc/html/Graphics-Rendering-OpenGL.html">Graphics.Rendering.OpenGL</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Initialization.html">Graphics.UI.GLUT.Initialization</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Begin.html">Graphics.UI.GLUT.Begin</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Window.html">Graphics.UI.GLUT.Window</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Overlay.html">Graphics.UI.GLUT.Overlay</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Menu.html">Graphics.UI.GLUT.Menu</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Callbacks.html">Graphics.UI.GLUT.Callbacks</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Colormap.html">Graphics.UI.GLUT.Colormap</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-State.html">Graphics.UI.GLUT.State</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Fonts.html">Graphics.UI.GLUT.Fonts</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Objects.html">Graphics.UI.GLUT.Objects</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-Debugging.html">Graphics.UI.GLUT.Debugging</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-DeviceControl.html">Graphics.UI.GLUT.DeviceControl</a></p></div><div class="top"><p class="src">module <a href="Graphics-UI-GLUT-GameMode.html">Graphics.UI.GLUT.GameMode</a></p></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.13.2</p></div></body></html>
libghc-glut-doc 2.4.0.0-1 / usr / share / doc / libghc-glut-doc / html / Graphics-UI-GLUT.html
