1 /* 2 ----------------------------------------------------------------------------- 3 This source file is part of OGRE 4 (Object-oriented Graphics Rendering Engine) 5 For the latest info, see http://www.ogre3d.org/ 6 7 Copyright (c) 2000-2014 Torus Knot Software Ltd 8 9 Permission is hereby granted, free of charge, to any person obtaining a copy 10 of this software and associated documentation files (the "Software"), to deal 11 in the Software without restriction, including without limitation the rights 12 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 13 copies of the Software, and to permit persons to whom the Software is 14 furnished to do so, subject to the following conditions: 15 16 The above copyright notice and this permission notice shall be included in 17 all copies or substantial portions of the Software. 18 19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 22 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 24 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 25 THE SOFTWARE. 26 ----------------------------------------------------------------------------- 27 */ 28 29 #ifndef __Overlay_H__ 30 #define __Overlay_H__ 31 32 #include "OgreOverlayPrerequisites.h" 33 #include "OgreIteratorWrappers.h" 34 #include "OgreMatrix4.h" 35 #include "OgreViewport.h" 36 37 namespace Ogre { 38 class OverlayContainer; 39 class OverlayElement; 40 41 /** \addtogroup Optional 42 * @{ 43 */ 44 /** \defgroup Overlays Overlay 45 * Layers which is rendered on top of the 'normal' scene contents 46 * @{ 47 */ 48 /** Represents a layer which is rendered on top of the 'normal' scene contents. 49 @remarks 50 An overlay is a container for visual components (2D and 3D) which will be 51 rendered after the main scene in order to composite heads-up-displays, menus 52 or other layers on top of the contents of the scene. 53 @par 54 An overlay always takes up the entire size of the viewport, although the 55 components attached to it do not have to. An overlay has no visual element 56 in itself, it it merely a container for visual elements. 57 @par 58 Overlays are created by calling OverlayManager::create, or by defining them 59 in special text scripts (.overlay files). As many overlays 60 as you like can be defined; after creation an overlay is hidden i.e. not 61 visible until you specifically enable it by calling 'show'. This allows you to have multiple 62 overlays predefined (menus etc) which you make visible only when you want. 63 It is possible to have multiple overlays enabled at once; in this case the 64 relative 'zorder' parameter of the overlays determine which one is displayed 65 on top. 66 @par 67 By default overlays are rendered into all viewports. This is fine when you only 68 have fullscreen viewports, but if you have picture-in-picture views, you probably 69 don't want the overlay displayed in the smaller viewports. You turn this off for 70 a specific viewport by calling the Viewport::setDisplayOverlays method. 71 */ 72 class _OgreOverlayExport Overlay : public OverlayAlloc 73 { 74 75 public: 76 typedef std::list<OverlayContainer*> OverlayContainerList; 77 protected: 78 String mName; 79 /// Internal root node, used as parent for 3D objects 80 SceneNode* mRootNode; 81 /** 2D elements 82 OverlayContainers, linked list for easy sorting by zorder later 83 Not a map because sort can be saved since changes infrequent (unlike render queue) */ 84 OverlayContainerList m2DElements; 85 86 /// Degrees of rotation around center 87 Radian mRotate; 88 /// Scroll values, offsets 89 Real mScrollX, mScrollY; 90 /// Scale values 91 Real mScaleX, mScaleY; 92 93 int mLastViewportWidth, mLastViewportHeight; 94 95 mutable Matrix4 mTransform; 96 mutable bool mTransformOutOfDate; 97 bool mTransformUpdated; 98 ulong mZOrder; 99 bool mVisible; 100 bool mInitialised; 101 String mOrigin; 102 /** Internal lazy update method. */ 103 void updateTransform(void) const; 104 /** Internal method for initialising an overlay */ 105 void initialise(void); 106 /** Internal method for updating container elements' Z-ordering */ 107 void assignZOrders(void); 108 109 public: 110 /// Constructor: do not call direct, use OverlayManager::create 111 Overlay(const String& name); 112 virtual ~Overlay(); 113 114 115 OverlayContainer* getChild(const String& name); 116 117 /** Gets the name of this overlay. */ 118 const String& getName(void) const; 119 120 /** Alters the Z-order of this overlay. 121 @remarks 122 Values between 0 and 650 are valid here. 123 */ 124 void setZOrder(ushort zorder); 125 /** Gets the Z-order of this overlay. */ 126 ushort getZOrder(void) const; 127 128 /** Gets whether the overlay is displayed or not. */ 129 bool isVisible(void) const; 130 131 /** Gets whether the overlay is initialised or not. */ isInitialised(void)132 bool isInitialised(void) const { return mInitialised; } 133 134 /** Shows the overlay if it was hidden. */ 135 void show(void); 136 137 /** Hides the overlay if it was visible. */ 138 void hide(void); 139 140 /** Adds a 2D 'container' to the overlay. 141 @remarks 142 Containers are created and managed using the OverlayManager. A container 143 could be as simple as a square panel, or something more complex like 144 a grid or tree view. Containers group collections of other elements, 145 giving them a relative coordinate space and a common z-order. 146 If you want to attach a GUI widget to an overlay, you have to do it via 147 a container. 148 @param cont Pointer to a container to add, created using OverlayManager. 149 */ 150 void add2D(OverlayContainer* cont); 151 152 153 /** Removes a 2D container from the overlay. 154 @remarks 155 NOT FAST. Consider OverlayElement::hide. 156 */ 157 void remove2D(OverlayContainer* cont); 158 159 /** Adds a node capable of holding 3D objects to the overlay. 160 @remarks 161 Although overlays are traditionally associated with 2D elements, there 162 are reasons why you might want to attach 3D elements to the overlay too. 163 For example, if you wanted to have a 3D cockpit, which was overlaid with a 164 HUD, then you would create 2 overlays, one with a 3D object attached for the 165 cockpit, and one with the HUD elements attached (the zorder of the HUD 166 overlay would be higher than the cockpit to ensure it was always on top). 167 @par 168 A SceneNode can have any number of 3D objects attached to it. SceneNodes 169 are usually created using SceneManager::createSceneNode, but in this case 170 you should create a standard SceneNode instance <b>manually</b>; this is 171 because these scene nodes are not managed by the SceneManager and some custom 172 SceneManager plugins will rely on specialist behaviour the overlay does not 173 support. By attaching a SceneNode to an overlay, you indicate that:<OL> 174 <LI>You want the contents of this node to only appear when the overlay is active</LI> 175 <LI>You want the node to inherit a coordinate space relative to the camera, 176 rather than relative to the root scene node</LI> 177 <LI>You want these objects to be rendered after the contents of the main scene 178 to ensure they are rendered on top</LI> 179 </OL> 180 One major consideration when using 3D objects in overlays is the behaviour of 181 the depth buffer. Overlays should use materials with depth checking off, to ensure 182 that their contents are always displayed on top of the main scene (to do 183 otherwise would result in objects 'poking through' the overlay). The problem 184 with using 3D objects is that if they are concave, or self-overlap, then you 185 can get artefacts because of the lack of depth buffer checking. So you should 186 ensure that any 3D objects you us in the overlay are convex, and don't overlap 187 each other. If they must overlap, split them up and put them in 2 overlays. 188 Alternatively, use a 2D element underneath them which will clear the depth buffer 189 values underneath ready for the 3D element to be rendered correctly. 190 */ 191 void add3D(SceneNode* node); 192 193 /** Removes a 3D element from the overlay. */ 194 void remove3D(SceneNode* node); 195 196 /** Clears the overlay of all attached items. */ 197 void clear(); 198 199 /** Sets the scrolling factor of this overlay. 200 @remarks 201 You can use this to set an offset to be used to scroll an 202 overlay around the screen. 203 @param x Horizontal scroll value, where 0 = normal, -0.5 = scroll so that only 204 the right half the screen is visible etc 205 @param y Vertical scroll value, where 0 = normal, 0.5 = scroll down by half 206 a screen etc. 207 */ 208 void setScroll(Real x, Real y); 209 210 /** Gets the current X scroll value */ 211 Real getScrollX(void) const; 212 213 /** Gets the current Y scroll value */ 214 Real getScrollY(void) const; 215 216 /** Scrolls the overlay by the offsets provided. 217 @remarks 218 This method moves the overlay by the amounts provided. As with 219 other methods on this object, a full screen width / height is represented 220 by the value 1.0. 221 */ 222 void scroll(Real xoff, Real yoff); 223 224 /** Sets the rotation applied to this overlay.*/ 225 void setRotate(const Radian& angle); 226 227 /** Gets the rotation applied to this overlay, in degrees.*/ getRotate(void)228 const Radian &getRotate(void) const { return mRotate; } 229 230 /** Adds the passed in angle to the rotation applied to this overlay. */ 231 void rotate(const Radian& angle); 232 233 /** Sets the scaling factor of this overlay. 234 @remarks 235 You can use this to set an scale factor to be used to zoom an 236 overlay. 237 @param x Horizontal scale value, where 1.0 = normal, 0.5 = half size etc 238 @param y Vertical scale value, where 1.0 = normal, 0.5 = half size etc 239 */ 240 void setScale(Real x, Real y); 241 242 /** Gets the current X scale value */ 243 Real getScaleX(void) const; 244 245 /** Gets the current Y scale value */ 246 Real getScaleY(void) const; 247 248 /** Used to transform the overlay when scrolling, scaling etc. */ 249 void _getWorldTransforms(Matrix4* xform) const; 250 251 /** Internal method to put the overlay contents onto the render queue. */ 252 void _findVisibleObjects(Camera* cam, RenderQueue* queue, Viewport* vp); 253 254 /** This returns a OverlayElement at position x,y. */ 255 virtual OverlayElement* findElementAt(Real x, Real y); 256 257 /** Returns all 2D elements in this manager. 258 */ get2DElements()259 const OverlayContainerList& get2DElements() const { 260 return m2DElements; 261 } 262 263 /** Get the origin of this overlay, e.g. a script file name. 264 @remarks 265 This property will only contain something if the creator of 266 this overlay chose to populate it. Script loaders are advised 267 to populate it. 268 */ getOrigin(void)269 const String& getOrigin(void) const { return mOrigin; } 270 /// Notify this overlay of it's origin _notifyOrigin(const String & origin)271 void _notifyOrigin(const String& origin) { mOrigin = origin; } 272 273 274 }; 275 /** @} */ 276 /** @} */ 277 278 } 279 280 281 #endif 282 283