Copyright	(c) Sven Panne 2002-2013
License	BSD3
Maintainer	Sven Panne <svenpanne@gmail.com>
Stability	stable
Portability	portable
Safe Haskell	None
Language	Haskell2010

Graphics.UI.GLUT.Initialization

Contents

Primary initialization
Initial window geometry
Setting the initial display mode (I)
Setting the initial display mode (II)
Controlling the creation of rendering contexts
Direct/indirect rendering
OpenGL 3.x context support

Description

Actions and state variables in this module are used to initialize GLUT state. The primary initialization routine is initialize, which should only be called exactly once in a GLUT program. No other GLUT or OpenGL actions should be called before initialize, apart from getting or setting the state variables in this module.

The reason is that these state variables can be used to set default window initialization state that might be modified by the command processing done in initialize. For example, initialWindowSize can be set to (Size 400 400) before initialize is called to indicate 400 by 400 is the program's default window size. Setting the initial window size or position before initialize allows the GLUT program user to specify the initial size or position using command line arguments.

Synopsis

Primary initialization

initialize Source

Arguments

:: MonadIO m
=> String	The program name.
-> [String]	The command line arguments
-> m [String]	Non-GLUT command line arguments

Given the program name and command line arguments, initialize the GLUT library and negotiate a session with the window system. During this process, initialize may cause the termination of the GLUT program with an error message to the user if GLUT cannot be properly initialized. Examples of this situation include the failure to connect to the window system, the lack of window system support for OpenGL, and invalid command line options.

initialize also processes command line options, but the specific options parsed are window system dependent. Any command line arguments which are not GLUT-specific are returned.

X Implementation Notes: The X Window System specific options parsed by initialize are as follows:

-display DISPLAY: Specify the X server to connect to. If not specified, the value of the DISPLAY environment variable is used.
-geometry WxH+X+Y: Determines where windows should be created on the screen. The parameter following -geometry should be formatted as a standard X geometry specification. The effect of using this option is to change the GLUT initial size and initial position the same as if initialWindowSize or initialWindowPosition were modified directly.
-iconic: Requests all top-level windows be created in an iconic state.
-indirect: Force the use of indirect OpenGL rendering contexts.
-direct: Force the use of direct OpenGL rendering contexts (not all GLX implementations support direct rendering contexts). A fatal error is generated if direct rendering is not supported by the OpenGL implementation. If neither -indirect or -direct are used to force a particular behavior, GLUT will attempt to use direct rendering if possible and otherwise fallback to indirect rendering.
-gldebug: After processing callbacks and/or events, call reportErrors to check if there are any pending OpenGL errors. Using this option is helpful in detecting OpenGL run-time errors.
-sync: Enable synchronous X protocol transactions. This option makes it easier to track down potential X protocol errors.

getArgsAndInitialize :: MonadIO m => m (String, [String]) Source

Convenience action: Initialize GLUT, returning the program name and any non-GLUT command line arguments.

exit :: MonadIO m => m () Source

(freeglut only) De-initialize GLUT. After this, one has to use initialize or getArgsAndInitialize to initialize GLUT again.

Initial window geometry

initialWindowPosition :: StateVar Position Source

Controls the initial window position. Windows created by createWindow will be requested to be created with the current initial window position. The initial value of the /initial window position/ GLUT state is Position (-1) (-1). If either the X or Y component of the initial window position is negative, the actual window position is left to the window system to determine.

The intent of the initial window position is to provide a suggestion to the window system for a window's initial position. The window system is not obligated to use this information. Therefore, GLUT programs should not assume the window was created at the specified position.

initialWindowSize :: StateVar Size Source

Controls the initial window size. Windows created by createWindow will be requested to be created with the current initial window size. The initial value of the /initial window size/ GLUT state is Size 300 300. If either the width or the height component of the initial window size is non-positive, the actual window size is left to the window system to determine.

The intent of the initial window size is to provide a suggestion to the window system for a window's initial size. The window system is not obligated to use this information. Therefore, GLUT programs should not assume the window was created at the specified size. A GLUT program should use the window's reshape callback to determine the true size of the window.

Setting the initial display mode (I)

data DisplayMode Source

A single aspect of a window which is to be created, used in conjunction with initialDisplayMode.

Constructors

RGBAMode	Select an RGBA mode window. This is the default if neither `RGBAMode` nor `IndexMode` are specified.
RGBMode	An alias for `RGBAMode`.
IndexMode	Select a color index mode window. This overrides `RGBAMode` if it is also specified.
LuminanceMode	Select a window with a "luminance" color model. This model provides the functionality of OpenGL's RGBA color model, but the green and blue components are not maintained in the frame buffer. Instead each pixel's red component is converted to an index between zero and `numColorMapEntries` and looked up in a per-window color map to determine the color of pixels within the window. The initial colormap of `LuminanceMode` windows is initialized to be a linear gray ramp, but can be modified with GLUT's colormap actions. Implementation Notes: `LuminanceMode` is not supported on most OpenGL platforms.
WithAlphaComponent	Select a window with an alpha component to the color buffer(s).
WithAccumBuffer	Select a window with an accumulation buffer.
WithDepthBuffer	Select a window with a depth buffer.
WithStencilBuffer	Select a window with a stencil buffer.
WithAuxBuffers Int	(freeglut only) Select a window with n (1 .. 4) auxiliary buffers. Any n outside the range 1 .. 4 is a fatal error.
SingleBuffered	Select a single buffered window. This is the default if neither `DoubleBuffered` nor `SingleBuffered` are specified.
DoubleBuffered	Select a double buffered window. This overrides `SingleBuffered` if it is also specified.
Multisampling	Select a window with multisampling support. If multisampling is not available, a non-multisampling window will automatically be chosen. Note: both the OpenGL client-side and server-side implementations must support the `GLX_SAMPLE_SGIS` extension for multisampling to be available. Deprecated, use `WithSamplesPerPixel`.
WithSamplesPerPixel Int	Select a window with multisampling, using the given samples per pixel.
Stereoscopic	Select a stereo window.
Captionless	Select a window without a caption (freeglut only).
Borderless	Select a window without any borders (freeglut only).
SRGBMode	Select an sRGB mode window (freeglut only).

Instances

Eq DisplayMode Source
Ord DisplayMode Source
Show DisplayMode Source

initialDisplayMode :: StateVar [DisplayMode] Source

Controls the initial display mode used when creating top-level windows, subwindows, and overlays to determine the OpenGL display mode for the to-be-created window or overlay.

Note that RGBAMode selects the RGBA color model, but it does not request any bits of alpha (sometimes called an alpha buffer or destination alpha) be allocated. To request alpha, specify WithAlphaComponent. The same applies to LuminanceMode.

displayModePossible :: GettableStateVar Bool Source

Contains True if the current display mode is supported, False otherwise.

Setting the initial display mode (II)

data DisplayCapability Source

Capabilities for initialDisplayCapabilities, most of them are extensions of the constructors of DisplayMode.

Constructors

DisplayRGBA	Number of bits of red, green, blue, and alpha in the RGBA color buffer. Default is "`IsAtLeast` `1`" for red, green, blue, and alpha capabilities, and "`IsEqualTo` `1`" for the RGBA color model capability.
DisplayRGB	Number of bits of red, green, and blue in the RGBA color buffer and zero bits of alpha color buffer precision. Default is "`IsAtLeast` `1`" for the red, green, and blue capabilities, and "`IsNotLessThan` `0`" for alpha capability, and "`IsEqualTo` `1`" for the RGBA color model capability.
DisplayRed	Red color buffer precision in bits. Default is "`IsAtLeast` `1`".
DisplayGreen	Green color buffer precision in bits. Default is "`IsAtLeast` `1`".
DisplayBlue	Blue color buffer precision in bits. Default is "`IsAtLeast` `1`".
DisplayIndex	Boolean if the color model is color index or not. True is color index. Default is "`IsAtLeast` `1`".
DisplayBuffer	Number of bits in the color index color buffer. Default is "`IsAtLeast` `1`".
DisplaySingle	Boolean indicate the color buffer is single buffered. Default is "`IsEqualTo` `1`".
DisplayDouble	Boolean indicating if the color buffer is double buffered. Default is "`IsEqualTo` `1`".
DisplayAccA	Red, green, blue, and alpha accumulation buffer precision in bits. Default is "`IsAtLeast` `1`" for red, green, blue, and alpha capabilities.
DisplayAcc	Red, green, and green accumulation buffer precision in bits and zero bits of alpha accumulation buffer precision. Default is "`IsAtLeast` `1`" for red, green, and blue capabilities, and "`IsNotLessThan` `0`" for the alpha capability.
DisplayAlpha	Alpha color buffer precision in bits. Default is "`IsAtLeast` `1`".
DisplayDepth	Number of bits of precsion in the depth buffer. Default is "`IsAtLeast` `12`".
DisplayStencil	Number of bits in the stencil buffer. Default is "`IsNotLessThan` `1`".
DisplaySamples	Indicates the number of multisamples to use based on GLX's `SGIS_multisample` extension (for antialiasing). Default is "`IsNotGreaterThan` `4`". This default means that a GLUT application can request multisampling if available by simply specifying "`With` `DisplaySamples`".
DisplayStereo	Boolean indicating the color buffer is supports OpenGL-style stereo. Default is "`IsEqualTo` `1`".
DisplayLuminance	Number of bits of red in the RGBA and zero bits of green, blue (alpha not specified) of color buffer precision. Default is "`IsAtLeast` `1`" for the red capabilitis, and "`IsEqualTo` `0`" for the green and blue capabilities, and "`IsEqualTo` `1`" for the RGBA color model capability, and, for X11, "`IsEqualTo` `1`" for the `DisplayXStaticGray` capability. SGI InfiniteReality (and other future machines) support a 16-bit luminance (single channel) display mode (an additional 16-bit alpha channel can also be requested). The red channel maps to gray scale and green and blue channels are not available. A 16-bit precision luminance display mode is often appropriate for medical imaging applications. Do not expect many machines to support extended precision luminance display modes.
DisplayAux	(freeglut only) Number of auxiliary buffers. Default is "`IsEqualTo` `1`".
DisplayNum	A special capability name indicating where the value represents the Nth frame buffer configuration matching the description string. When not specified, `initialDisplayCapabilities` also uses the first (best matching) configuration. `Num` requires a relation and numeric value.
DisplayConformant	Boolean indicating if the frame buffer configuration is conformant or not. Conformance information is based on GLX's `EXT_visual_rating` extension if supported. If the extension is not supported, all visuals are assumed conformant. Default is "`IsEqualTo` `1`".
DisplaySlow	Boolean indicating if the frame buffer configuration is slow or not. Slowness information is based on GLX's `EXT_visual_rating` extension if supported. If the extension is not supported, all visuals are assumed fast. Note that slowness is a relative designation relative to other frame buffer configurations available. The intent of the slow capability is to help programs avoid frame buffer configurations that are slower (but perhaps higher precision) for the current machine. Default is "`IsAtLeast` `0`". This default means that slow visuals are used in preference to fast visuals, but fast visuals will still be allowed.
DisplayWin32PFD	Only recognized on GLUT implementations for Win32, this capability name matches the Win32 Pixel Format Descriptor by number. `DisplayWin32PFD` can only be used with `Where`.
DisplayXVisual	Only recongized on GLUT implementations for the X Window System, this capability name matches the X visual ID by number. `DisplayXVisual` requires a relation and numeric value.
DisplayXStaticGray	Only recongized on GLUT implementations for the X Window System, boolean indicating if the frame buffer configuration's X visual is of type `StaticGray`. Default is "`IsEqualTo` `1`".
DisplayXGrayScale	Only recongized on GLUT implementations for the X Window System, boolean indicating if the frame buffer configuration's X visual is of type `GrayScale`. Default is "`IsEqualTo` `1`".
DisplayXStaticColor	Only recongized on GLUT implementations for the X Window System, boolean indicating if the frame buffer configuration's X visual is of type `StaticColor`. Default is "`IsEqualTo` `1`".
DisplayXPseudoColor	Only recongized on GLUT implementations for the X Window System, boolean indicating if the frame buffer configuration's X visual is of type `PsuedoColor`. Default is "`IsEqualTo` `1`".
DisplayXTrueColor	Only recongized on GLUT implementations for the X Window System, boolean indicating if the frame buffer configuration's X visual is of type `TrueColor`. Default is "`IsEqualTo` `1`".
DisplayXDirectColor	Only recongized on GLUT implementations for the X Window System, boolean indicating if the frame buffer configuration's X visual is of type `DirectColor`. Default is "`IsEqualTo` `1`".

Instances

Eq DisplayCapability Source
Ord DisplayCapability Source
Show DisplayCapability Source

data Relation Source

A relation between a DisplayCapability and a numeric value.

Constructors

IsEqualTo	Equal.
IsNotEqualTo	Not equal.
IsLessThan	Less than and preferring larger difference (the least is best).
IsNotGreaterThan	Less than or equal and preferring larger difference (the least is best).
IsGreaterThan	Greater than and preferring larger differences (the most is best).
IsAtLeast	Greater than or equal and preferring more instead of less. This relation is useful for allocating resources like color precision or depth buffer precision where the maximum precision is generally preferred. Contrast with `IsNotLessThan` relation.
IsNotLessThan	Greater than or equal but preferring less instead of more. This relation is useful for allocating resources such as stencil bits or auxillary color buffers where you would rather not over-allocate.

Instances

Eq Relation Source
Ord Relation Source
Show Relation Source

data DisplayCapabilityDescription Source

A single capability description for initialDisplayCapabilities.

Constructors

Where DisplayCapability Relation Int	A description of a capability with a specific relation to a numeric value.
With DisplayCapability	When the relation and numeric value are not specified, each capability has a different default, see the different constructors of `DisplayCapability`.

Instances

Eq DisplayCapabilityDescription Source
Ord DisplayCapabilityDescription Source
Show DisplayCapabilityDescription Source

initialDisplayCapabilities :: SettableStateVar [DisplayCapabilityDescription] Source

Controls the initial display mode used when creating top-level windows, subwindows, and overlays to determine the OpenGL display mode for the to-be-created window or overlay. It is described by a list of zero or more capability descriptions, which are translated into a set of criteria used to select the appropriate frame buffer configuration. The criteria are matched in strict left to right order of precdence. That is, the first specified criterion (leftmost) takes precedence over the later criteria for non-exact criteria (IsGreaterThan, IsLessThan, etc.). Exact criteria (IsEqualTo, IsNotEqualTo) must match exactly so precedence is not relevant.

Unspecified capability descriptions will result in unspecified criteria being generated. These unspecified criteria help initialDisplayCapabilities behave sensibly with terse display mode descriptions.

Here is an example using initialDisplayCapabilities:

   initialDisplayCapabilities $= [ With  DisplayRGB,
                                   Where DisplayDepth IsAtLeast 16,
                                   With  DisplaySamples,
                                   Where DisplayStencil IsNotLessThan 2,
                                   With  DisplayDouble ]

The above call requests a window with an RGBA color model (but requesting no bits of alpha), a depth buffer with at least 16 bits of precision but preferring more, multisampling if available, at least 2 bits of stencil (favoring less stencil to more as long as 2 bits are available), and double buffering.

Controlling the creation of rendering contexts

data RenderingContext Source

How rendering context for new windows are created.

Constructors

CreateNewContext	Create a new context via `glXCreateContext` or `wglCreateContext` (default).
UseCurrentContext	Re-use the current rendering context.

Instances

Eq RenderingContext Source
Ord RenderingContext Source
Show RenderingContext Source

renderingContext :: StateVar RenderingContext Source

(freeglut only) Controls the creation of rendering contexts for new windows.

Direct/indirect rendering

data DirectRendering Source

The kind of GLX rendering context used. Direct rendering provides a performance advantage in some implementations. However, direct rendering contexts cannot be shared outside a single process, and they may be unable to render to GLX pixmaps.

Constructors

ForceIndirectContext	Rendering is always done through the X server. This corresponds to the command line argument `-indirect`, see `initialize`.
AllowDirectContext	Try to use direct rendering, silently using indirect rendering if this is not possible.
TryDirectContext	Try to use direct rendering, issue a warning and use indirect rendering if this is not possible.
ForceDirectContext	Try to use direct rendering, issue an error and terminate the program if this is not possible.This corresponds to the command line argument `-direct`, see `initialize`.

Instances

Eq DirectRendering Source
Ord DirectRendering Source
Show DirectRendering Source

directRendering :: StateVar DirectRendering Source

(freeglut on X11 only) Controls which kind of rendering context is created when a new one is required.

OpenGL 3.x context support

initialContextVersion :: StateVar (Int, Int) Source

(freeglut only) Controls the API major/minor version of the OpenGL context. If a version less than or equal to 2.1 is requested, the context returned may implement any version no less than that requested and no greater than 2.1. If version 3.0 is requested, the context returned must implement exactly version 3.0. Versioning behavior once GL versions beyond 3.0 are defined will be defined by an amendment to the OpenGL specification to define dependencies on such GL versions.

glVersion and majorMinor will return the actual version supported by a context.

The default context version is (1, 0), which will typically return an OpenGL 2.1 context, if one is available.

data ContextFlag Source

A flag affecting the rendering context to create, used in conjunction with initialContextFlags.

Constructors

DebugContext	Debug contexts are intended for use during application development, and provide additional runtime checking, validation, and logging functionality while possibly incurring performance penalties. The additional functionality provided by debug contexts may vary according to the implementation. In some cases a debug context may be identical to a non-debug context.
ForwardCompatibleContext	Forward-compatible contexts are defined only for OpenGL versions 3.0 and later. They must not support functionality marked as deprecated by that version of the API, while a non-forward-compatible context must support all functionality in that version, deprecated or not.

Instances

Eq ContextFlag Source
Ord ContextFlag Source
Show ContextFlag Source

initialContextFlags :: StateVar [ContextFlag] Source

(freeglut only) Controls the set of flags for the rendering context.

data ContextProfile Source

An OpenGL API profile, affecting the rendering context to create, used in conjunction with initialContextProfile.

Constructors

CoreProfile	The OpenGL core profile, which all OpenGL 3.2 implementations are required to support.
CompatibilityProfile	The OpenGL compatibility profile, which is optional for OpenGL 3.2 implementations.

Instances

Eq ContextProfile Source
Ord ContextProfile Source
Show ContextProfile Source

initialContextProfile :: StateVar [ContextProfile] Source

(freeglut only) Controls the set of profiles for the rendering context.