source: GTP/trunk/Lib/Geom/OgreStuff/include/OgreOverlay.h @ 1809

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