Debian Codegraph @

src/Graphics/UI/GLUT/Overlay.hs

raw
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)