= Gloss = Gloss hides the pain of drawing simple vector graphics behind a nice data type and a few display functions. Gloss uses OpenGL and GLUT under the hood, but you won't have to worry about any of that. Get something cool on the screen in under 10 minutes. Gloss is a fork and cleanup of ANUPlot, which was used for teaching first year computer science at the [http://cs.anu.edu.au ANU] some time ago. Its main goal is to allow total beginners to get something working with a minimum of fuss. == Examples == These are some of the examples included in the [http://hackage.haskell.org/package/gloss-examples gloss-examples] package: || Hello || Lifespan || Styrene || Tree || Clock || Zen || || [[Image(WikiStart:gloss-hello-thumb.png)]] || [[Image(WikiStart:gloss-lifespan-thumb.png)]] || [[Image(WikiStart:gloss-styrene-thumb.png)]] || [[Image(WikiStart:gloss-tree-thumb.png)]] || [[Image(WikiStart:gloss-clock-thumb.png)]] || [[Image(WikiStart:gloss-zen-thumb.png)]] || || [http://code.ouroborus.net/gloss/gloss-head.old-darcs/gloss-examples/picture/Hello/Main.hs code] [http://code.ouroborus.net/gloss/wiki/images/gloss-hello.png result] || [http://code.ouroborus.net/gloss/gloss-head.old-darcs/gloss-examples/picture/Lifespan/ code] [http://code.ouroborus.net/gloss/wiki/images/gloss-lifespan.png result] || [http://code.ouroborus.net/gloss/gloss-head.old-darcsgloss-examples/picture/Styrene/ code] [http://code.ouroborus.net/gloss/wiki/images/gloss-styrene.png result] || [http://code.ouroborus.net/gloss/gloss-head.old-darcs/gloss-examples/picture/Tree/Main.hs code] [http://code.ouroborus.net/gloss/wiki/images/gloss-tree.png result] || [http://code.ouroborus.net/gloss/gloss-head.old-darcs/gloss-examples/picture/Clock/Main.hs code] [http://code.ouroborus.net/gloss/wiki/images/gloss-clock.png result] || [http://code.ouroborus.net/gloss/gloss-head.old-darcs/gloss-examples/picture/Zen/Main.hs code] [http://www.youtube.com/watch?v=vm78Tkc-KhM video] || == Download == === From Hackage === * [http://hackage.haskell.org/package/gloss gloss] * [http://hackage.haskell.org/package/gloss-raster gloss-raster] * [http://hackage.haskell.org/package/gloss-examples gloss-examples] === With cabal === If you have cabal installed you should be able to: {{{ cabal update cabal install gloss-examples gloss-styrene }}} === From the darcs repo === The source repos are at http://code.ouroborus.net/gloss {{{ darcs get http://code.ouroborus.net/gloss/gloss-stable cd gloss-stable cd gloss cabal install }}} Then again for the `examples` directory in that same repo. == Further Information == To report bugs or request features, post in the [http://groups.google.com/group/haskell-gloss haskell-gloss] Google group. We're also interested in cool examples you come up with. Contributed examples can be added to the gloss-examples package and posted on this page. To get an account on the trac, send email to `gloss [wibble] ouroborus.net` == Active Related Projects == * [http://hackage.haskell.org/package/diagrams diagrams] a Domain Specific Language for drawing 2D graphics. * [http://mahrz.github.com/craftwerk.html craftwerk] a graphics library with TikZ output. == Frequently Asked Questions (FAQ) == '''Q: Why doesn't the lastest version of Gloss build with the Haskell Platform?'''[[br]] A: Because the Haskell Platform (HP) doesn't use the latest version of GHC. The [http://hackage.haskell.org/package/gloss-examples gloss-examples] package depends on [http://hackage.haskell.org/package/repa repa] via the [http://hackage.haskell.org/package/gloss-raster gloss-raster] package. Repa itself is tightly coupled to a particular version of GHC because it depends on properties of the GHC simplifier for good performance. When the HP does not use the latest GHC we provide a specific Gloss package for it, whose API should be identical to the most recent version. For the Haskell Platform 2012.04 you should use [http://hackage.haskell.org/package/gloss-1.7.7.201204.1 gloss-1.7.7.201204.1]. '''Q: Gloss crashes at startup.'''[[br]] A0: On Windows there is a known issue with the version of freeglut that comes with the Haskell Platform 2012.2.0.0. Upgrade your Haskell Platform or install freeglut >= 2.8.0.[[br]] A1: On other systems, you can also try upgrading freeglut to the latest version. If doing this solves a crash-bug on a non-Windows machine then please email me about it `gloss [wibble] ouroborus.net`and I'll update this wiki. '''Q: Gloss freezes in `ghci`. It tries to draw the window but I don't get a picture and must kill the process.'''[[br]] A0: Upgrade to at least GHC 7.4[[br]] A1: Start `ghci` with `-fno-ghci-sandbox`. This is because OpenGL uses thread local state, which doesn't work when the running program is in a different thread.[[br]] A2: Try installing gloss to use the GLFW window manager interface instead of GLUT: `cabal install gloss --flags="GLFW -GLUT"` '''Q: I tried to draw a polygon shaped like a star, but it looks wrong.'''[[br]] A: Gloss does not support non-convex polygons. You'll need to break up your picture into several separate convex polygons (eg, triangles). Gloss calls OpenGL directly to draw polygons, and the API doesn't handle non-convex ones. To fix this we'll need to write a triangulation function (#11). '''Q: I'm getting an "internal stack overflow" or "internal stack underflow" error from OpenGL when running a program that draws a picture recursively.'''[[br]] A: Your GPU hardware has a fixed sized transform matrix stack. Each time you use a more deeply nested 'rotate' 'translate' or 'scale' transform then a matrix is pushed on this stack. When the stack is full you should get an overflow error and the OpenGL library should kill the process. If your OpenGL library was poorly implemented then matrices pushed onto a full stack will be silently discarded, and then when Gloss tries to pop the full number this will cause an underflow. The OpenGL specification requires implementations to support at least 32 entries on the transform stack, so you should be able to apply this many nested 'rotate' 'translate' and 'scale' transforms to your picture. If this isn't enough then you can probably refactor your program so it doesn't use so many nested transforms. This problem with a fixed size transform stack is discussed further in Section 4 of [http://www.opengl.org/archives/resources/features/KilgardTechniques/oglpitfall/ Avoiding common OpenGL pitfalls]. Gloss tries not to use the stack when it doesn't have to, but we don't know of any way to spill the stack to main memory to allow more entries. If you know how to solve this problem without giving up on hardware acceleration and doing the transforms in software, then please let us know on the mailing list. '''Q: Animations seem jerky.'''[[br]] A: Make sure you're compiling with {{{-O2 -threaded}}}. Without the threaded runtime, the code that manages the frame rate will behave badly. This is because GHC takes too long to reschedule the gloss process after the sleep timer has expired. With the threaded runtime, most simple animations should run at about 100fps, which is our internal frame-rate cap. '''Q: On my !MacBook Pro under OSX, gloss programs freeze after displaying the first few frames'''.[[br]] A: This can happen on dual GPU systems when the OS switches from the integrated GPU (baked into the processor) to the discrete one (separate from the main processor). The gloss program can sometimes draw a few frames before getting stuck, otherwise it just shows a black window. This is probably a bug in OSX not switching the graphics context properly. The work-around is to disable automatic GPU switching under System Preferences / Energy Saver. '''Q: On Windows, when I try to run a gloss program it says `user error (unknown GLUT entry glutInit)`.'''[[br]] A1: You need to install `glut32.dll`. Copy it into `\Windows\System32` (for 32-bit installs) or `\Windows\SysWOW64` (for 64-bit installs). Alternatively, you can just copy it into the same directory as the `Main.exe` executable you are trying to run. '''Q: On Windows, how do I turn off the console window when the Gloss program runs?''' [[br]] A: Pass GHC the flag `-optl-mwindows` when compiling the program. At runtime, if your program tries to write to `stdout` or `stderr` then Windows will kill the process. '''Q: With Xmonad, the Gloss window doesn't resize properly.'''[[br]] A: Use the GLFW window manager interface instead, or prod the Xmonad people about it. This is probably an incompatibility between Xmonad and GLUT, but the main Gloss developer doesn't use Xmonad.