| 1 |
-------------------------------------------------------------------------------- |
| 2 |
-- | |
| 3 |
-- Module : Graphics.UI.GLUT.Overlay |
| 4 |
-- Copyright : (c) Sven Panne 2002-2018 |
| 5 |
-- License : BSD3 |
| 6 |
-- |
| 7 |
-- Maintainer : Sven Panne <[email protected]> |
| 8 |
-- Stability : stable |
| 9 |
-- Portability : portable |
| 10 |
-- |
| 11 |
-- When overlay hardware is available, GLUT provides a set of routines for |
| 12 |
-- establishing, using, and removing an overlay for GLUT windows. When an |
| 13 |
-- overlay is established, a separate OpenGL context is also established. A |
| 14 |
-- window\'s overlay OpenGL state is kept distinct from the normal planes\' |
| 15 |
-- OpenGL state. |
| 16 |
-- |
| 17 |
-------------------------------------------------------------------------------- |
| 18 |
|
| 19 |
module Graphics.UI.GLUT.Overlay ( |
| 20 |
-- * Overlay creation and destruction |
| 21 |
hasOverlay, overlayPossible, |
| 22 |
|
| 23 |
-- * Showing and hiding an overlay |
| 24 |
overlayVisible, |
| 25 |
|
| 26 |
-- * Changing the /layer in use/ |
| 27 |
Layer(..), layerInUse, |
| 28 |
|
| 29 |
-- * Re-displaying |
| 30 |
postOverlayRedisplay |
| 31 |
) where |
| 32 |
|
| 33 |
import Control.Monad.IO.Class ( MonadIO(..) ) |
| 34 |
import Data.StateVar ( GettableStateVar, makeGettableStateVar |
| 35 |
, SettableStateVar, makeSettableStateVar |
| 36 |
, StateVar, makeStateVar ) |
| 37 |
import Graphics.Rendering.OpenGL ( GLenum ) |
| 38 |
|
| 39 |
import Graphics.UI.GLUT.QueryUtils |
| 40 |
import Graphics.UI.GLUT.Raw |
| 41 |
import Graphics.UI.GLUT.Types |
| 42 |
|
| 43 |
-------------------------------------------------------------------------------- |
| 44 |
|
| 45 |
-- | Controls the overlay for the /current window/. The requested display mode |
| 46 |
-- for the overlay is determined by the /initial display mode/. |
| 47 |
-- 'overlayPossible' can be used to determine if an overlay is possible for the |
| 48 |
-- /current window/ with the current /initial display mode/. Do not attempt to |
| 49 |
-- establish an overlay when one is not possible; GLUT will terminate the |
| 50 |
-- program. |
| 51 |
-- |
| 52 |
-- When 'hasOverlay' is set to 'True' when an overlay already exists, the |
| 53 |
-- existing overlay is first removed, and then a new overlay is established. The |
| 54 |
-- state of the old overlay\'s OpenGL context is discarded. Implicitly, the |
| 55 |
-- window\'s /layer in use/ changes to the overlay immediately after the overlay |
| 56 |
-- is established. |
| 57 |
-- |
| 58 |
-- The initial display state of an overlay is shown, however the overlay is only |
| 59 |
-- actually shown if the overlay\'s window is shown. |
| 60 |
-- |
| 61 |
-- Setting 'hasOverlay' to 'False' is safe even if no overlay is currently |
| 62 |
-- established, nothing happens in this case. Implicitly, the window\'s /layer |
| 63 |
-- in use/ changes to the normal plane immediately once the overlay is removed. |
| 64 |
-- |
| 65 |
-- If the program intends to re-establish the overlay later, it is typically |
| 66 |
-- faster and less resource intensive to use 'overlayVisible' to simply change |
| 67 |
-- the display status of the overlay. |
| 68 |
-- |
| 69 |
-- /X Implementation Notes:/ GLUT for X uses the @SERVER_OVERLAY_VISUALS@ |
| 70 |
-- convention to determine if overlay visuals are available. While the |
| 71 |
-- convention allows for opaque overlays (no transparency) and overlays with the |
| 72 |
-- transparency specified as a bitmask, GLUT overlay management only provides |
| 73 |
-- access to transparent pixel overlays. |
| 74 |
-- |
| 75 |
-- Until RGBA overlays are better understood, GLUT only supports color index |
| 76 |
-- overlays. |
| 77 |
|
| 78 |
hasOverlay :: StateVar Bool |
| 79 |
hasOverlay = makeStateVar getHasOverlay setHasOverlay |
| 80 |
|
| 81 |
setHasOverlay :: Bool -> IO () |
| 82 |
setHasOverlay False = glutRemoveOverlay |
| 83 |
setHasOverlay True = glutEstablishOverlay |
| 84 |
|
| 85 |
getHasOverlay :: IO Bool |
| 86 |
getHasOverlay = layerGet (/= 0) glut_HAS_OVERLAY |
| 87 |
|
| 88 |
-------------------------------------------------------------------------------- |
| 89 |
|
| 90 |
-- | Contains 'True' if an overlay could be established for the /current window/ |
| 91 |
-- given the current /initial display mode/. If it contains 'False', setting |
| 92 |
-- 'hasOverlay' will fail with a fatal error. |
| 93 |
|
| 94 |
overlayPossible :: GettableStateVar Bool |
| 95 |
overlayPossible = makeGettableStateVar $ layerGet (/= 0) glut_OVERLAY_POSSIBLE |
| 96 |
|
| 97 |
-------------------------------------------------------------------------------- |
| 98 |
|
| 99 |
-- | Controls the visibility of the overlay of the /current window/. |
| 100 |
-- |
| 101 |
-- The effect of showing or hiding an overlay takes place immediately. Note that |
| 102 |
-- setting 'overlayVisible' to 'True' will not actually display the overlay |
| 103 |
-- unless the window is also shown (and even a shown window may be obscured by |
| 104 |
-- other windows, thereby obscuring the overlay). It is typically faster and |
| 105 |
-- less resource intensive to use the routines below to control the display |
| 106 |
-- status of an overlay as opposed to removing and re-establishing the overlay. |
| 107 |
|
| 108 |
overlayVisible :: SettableStateVar Bool |
| 109 |
overlayVisible = |
| 110 |
makeSettableStateVar $ \flag -> |
| 111 |
if flag then glutShowOverlay else glutHideOverlay |
| 112 |
|
| 113 |
-------------------------------------------------------------------------------- |
| 114 |
|
| 115 |
-- | The /layer in use/. |
| 116 |
data Layer |
| 117 |
= Normal -- ^ The normal plane. |
| 118 |
| Overlay -- ^ The overlay. |
| 119 |
deriving ( Eq, Ord, Show ) |
| 120 |
|
| 121 |
marshalLayer :: Layer -> GLenum |
| 122 |
marshalLayer x = case x of |
| 123 |
Normal -> glut_NORMAL |
| 124 |
Overlay -> glut_OVERLAY |
| 125 |
|
| 126 |
unmarshalLayer :: GLenum -> Layer |
| 127 |
unmarshalLayer x |
| 128 |
| x == glut_NORMAL = Normal |
| 129 |
| x == glut_OVERLAY = Overlay |
| 130 |
| otherwise = error ("unmarshalLayer: illegal value " ++ show x) |
| 131 |
|
| 132 |
-------------------------------------------------------------------------------- |
| 133 |
|
| 134 |
-- | Controls the per-window /layer in use/ for the /current window/, which can |
| 135 |
-- either be the normal plane or the overlay. Selecting the overlay should only |
| 136 |
-- be done if an overlay exists, however windows without an overlay may still |
| 137 |
-- set the /layer in use/ to 'Normal'. OpenGL commands for the window are |
| 138 |
-- directed to the current /layer in use/. |
| 139 |
|
| 140 |
layerInUse :: StateVar Layer |
| 141 |
layerInUse = |
| 142 |
makeStateVar getLayerInUse setLayerInUse |
| 143 |
|
| 144 |
setLayerInUse :: Layer -> IO () |
| 145 |
setLayerInUse = glutUseLayer . marshalLayer |
| 146 |
|
| 147 |
getLayerInUse :: IO Layer |
| 148 |
getLayerInUse = layerGet (unmarshalLayer . fromIntegral) glut_LAYER_IN_USE |
| 149 |
|
| 150 |
-------------------------------------------------------------------------------- |
| 151 |
|
| 152 |
-- | Mark the overlay of the given window (or the /current window/, if none is |
| 153 |
-- supplied) as needing to be redisplayed. The next iteration through |
| 154 |
-- 'Graphics.UI.GLUT.Begin.mainLoop', the window\'s overlay display callback |
| 155 |
-- (or simply the display callback if no overlay display callback is registered) |
| 156 |
-- will be called to redisplay the window\'s overlay plane. Multiple calls to |
| 157 |
-- 'postOverlayRedisplay' before the next display callback opportunity (or |
| 158 |
-- overlay display callback opportunity if one is registered) generate only a |
| 159 |
-- single redisplay. 'postOverlayRedisplay' may be called within a window\'s |
| 160 |
-- display or overlay display callback to re-mark that window for redisplay. |
| 161 |
-- |
| 162 |
-- Logically, overlay damage notification for a window is treated as a |
| 163 |
-- 'postOverlayRedisplay' on the damaged window. Unlike damage reported by the |
| 164 |
-- window system, 'postOverlayRedisplay' will not set to true the overlay\'s |
| 165 |
-- damaged status (see 'Graphics.UI.GLUT.State.damaged'). |
| 166 |
-- |
| 167 |
-- Also, see 'Graphics.UI.GLUT.Window.postRedisplay'. |
| 168 |
|
| 169 |
postOverlayRedisplay :: MonadIO m => Maybe Window -> m () |
| 170 |
postOverlayRedisplay = |
| 171 |
maybe glutPostOverlayRedisplay (\(Window win) -> glutPostWindowOverlayRedisplay win) |