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

Revision 1809, 10.8 KB checked in by gumbau, 18 years ago (diff)
Line 
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#ifndef __RenderQueue_H__
26#define __RenderQueue_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreIteratorWrappers.h"
30
31namespace Ogre {
32
33    /** Enumeration of queue groups, by which the application may group queued renderables
34        so that they are rendered together with events in between
35        @remarks
36                When passed into methods these are actually passed as a uint8 to allow you
37                to use values in between if you want to.
38    */
39    enum RenderQueueGroupID
40    {
41        /// Use this queue for objects which must be rendered first e.g. backgrounds
42        RENDER_QUEUE_BACKGROUND = 0,
43        /// First queue (after backgrounds), used for skyboxes if rendered first
44        RENDER_QUEUE_SKIES_EARLY = 5,
45        RENDER_QUEUE_1 = 10,
46        RENDER_QUEUE_2 = 20,
47                RENDER_QUEUE_WORLD_GEOMETRY_1 = 25,
48        RENDER_QUEUE_3 = 30,
49        RENDER_QUEUE_4 = 40,
50                /// The default render queue
51        RENDER_QUEUE_MAIN = 50,
52        RENDER_QUEUE_6 = 60,
53        RENDER_QUEUE_7 = 70,
54                RENDER_QUEUE_WORLD_GEOMETRY_2 = 75,
55        RENDER_QUEUE_8 = 80,
56        RENDER_QUEUE_9 = 90,
57        /// Penultimate queue(before overlays), used for skyboxes if rendered last
58        RENDER_QUEUE_SKIES_LATE = 95,
59        /// Use this queue for objects which must be rendered last e.g. overlays
60        RENDER_QUEUE_OVERLAY = 100
61    };
62
63    #define OGRE_RENDERABLE_DEFAULT_PRIORITY  100
64
65    /** Class to manage the scene object rendering queue.
66        @remarks
67            Objects are grouped by material to minimise rendering state changes. The map from
68            material to renderable object is wrapped in a class for ease of use.
69        @par
70            This class now includes the concept of 'queue groups' which allows the application
71            adding the renderable to specifically schedule it so that it is included in
72            a discrete group. Good for separating renderables into the main scene,
73            backgrounds and overlays, and also could be used in the future for more
74            complex multipass routines like stenciling.
75    */
76    class _OgreExport RenderQueue
77    {
78    public:
79        typedef std::map< uint8, RenderQueueGroup* > RenderQueueGroupMap;
80        /// Iterator over queue groups
81        typedef MapIterator<RenderQueueGroupMap> QueueGroupIterator;
82                /** Class to listen in on items being added to the render queue.
83                @remarks
84                        Use RenderQueue::setRenderableListener to get callbacks when an item
85                        is added to the render queue.
86                */
87                class _OgreExport RenderableListener
88                {
89                public:
90                        RenderableListener() {}
91                        virtual ~RenderableListener() {}
92
93                        /** Method called when a Renderable is added to the queue.
94                        @remarks
95                                You can use this event hook to alter the Technique used to
96                                render a Renderable as the item is added to the queue. This is
97                                a low-level way to override the material settings for a given
98                                Renderable on the fly.
99                        @param rend The Renderable being added to the queue
100                        @param groupID The render queue group this Renderable is being added to
101                        @param priority The priority the Renderable has been given
102                        @param ppTech A pointer to the pointer to the Technique that is
103                                intended to be used; you can alter this to an alternate Technique
104                                if you so wish (the Technique doesn't have to be from the same
105                                Material either).
106                        @returns true to allow the Renderable to be added to the queue,
107                                false if you want to prevent it being added
108                        */
109                        virtual bool renderableQueued(Renderable* rend, uint8 groupID,
110                                ushort priority, Technique** ppTech) = 0;
111                };
112    protected:
113        RenderQueueGroupMap mGroups;
114        /// The current default queue group
115        uint8 mDefaultQueueGroup;
116        /// The default priority
117        ushort mDefaultRenderablePriority;
118
119        bool mSplitPassesByLightingType;
120        bool mSplitNoShadowPasses;
121                bool mShadowCastersCannotBeReceivers;
122
123                RenderableListener* mRenderableListener;
124    public:
125        RenderQueue();
126        virtual ~RenderQueue();
127
128        /** Empty the queue - should only be called by SceneManagers.
129                @param destroyPassMaps Set to true to destroy all pass maps so that
130                        the queue is completely clean (useful when switching scene managers)
131        */
132        void clear(bool destroyPassMaps = false);
133
134                /** Get a render queue group.
135                @remarks
136                        OGRE registers new queue groups as they are requested,
137                        therefore this method will always return a valid group.
138                */
139                RenderQueueGroup* getQueueGroup(uint8 qid);
140
141        /** Add a renderable object to the queue.
142        @remarks
143            This methods adds a Renderable to the queue, which will be rendered later by
144            the SceneManager. This is the advanced version of the call which allows the renderable
145            to be added to any queue.
146        @note
147            Called by implementation of MovableObject::_updateRenderQueue.
148        @param
149            pRend Pointer to the Renderable to be added to the queue
150        @param
151            groupID The group the renderable is to be added to. This
152            can be used to schedule renderable objects in separate groups such that the SceneManager
153            respects the divisions between the groupings and does not reorder them outside these
154            boundaries. This can be handy for overlays where no matter what you want the overlay to
155            be rendered last.
156        @param
157            priority Controls the priority of the renderable within the queue group. If this number
158            is raised, the renderable will be rendered later in the group compared to it's peers.
159            Don't use this unless you really need to, manually ordering renderables prevents OGRE
160            from sorting them for best efficiency. However this could be useful for ordering 2D
161            elements manually for example.
162        */
163        void addRenderable(Renderable* pRend, uint8 groupID, ushort priority);
164
165        /** Add a renderable object to the queue.
166        @remarks
167            This methods adds a Renderable to the queue, which will be rendered later by
168            the SceneManager. This is the simplified version of the call which does not
169            require a priority to be specified. The queue priority is take from the
170            current default (see setDefaultRenderablePriority).
171        @note
172            Called by implementation of MovableObject::_updateRenderQueue.
173        @param
174            pRend Pointer to the Renderable to be added to the queue
175                @param
176            groupID The group the renderable is to be added to. This
177            can be used to schedule renderable objects in separate groups such that the SceneManager
178            respects the divisions between the groupings and does not reorder them outside these
179            boundaries. This can be handy for overlays where no matter what you want the overlay to
180            be rendered last.
181        */
182        void addRenderable(Renderable* pRend, uint8 groupId);
183
184        /** Add a renderable object to the queue.
185        @remarks
186            This methods adds a Renderable to the queue, which will be rendered later by
187            the SceneManager. This is the simplified version of the call which does not
188            require a queue or priority to be specified. The queue group is taken from the
189            current default (see setDefaultQueueGroup).  The queue priority is take from the
190            current default (see setDefaultRenderablePriority).
191        @note
192            Called by implementation of MovableObject::_updateRenderQueue.
193        @param
194            pRend Pointer to the Renderable to be added to the queue
195        */
196        void addRenderable(Renderable* pRend);
197       
198        /** Gets the current default queue group, which will be used for all renderable which do not
199            specify which group they wish to be on.
200        */
201        uint8 getDefaultQueueGroup(void) const;
202
203        /** Sets the current default renderable priority,
204            which will be used for all renderables which do not
205            specify which priority they wish to use.
206        */
207        void setDefaultRenderablePriority(ushort priority);
208
209        /** Gets the current default renderable priority, which will be used for all renderables which do not
210            specify which priority they wish to use.
211        */
212        ushort getDefaultRenderablePriority(void) const;
213
214        /** Sets the current default queue group, which will be used for all renderable which do not
215            specify which group they wish to be on.
216        */
217        void setDefaultQueueGroup(uint8 grp);
218       
219        /** Internal method, returns an iterator for the queue groups. */
220        QueueGroupIterator _getQueueGroupIterator(void);
221        /** Sets whether or not the queue will split passes by their lighting type,
222            ie ambient, per-light and decal.
223        */
224        void setSplitPassesByLightingType(bool split);
225        /** Sets whether or not the queue will split passes which have shadow receive
226        turned off (in their parent material), which is needed when certain shadow
227        techniques are used.
228        */
229        void setSplitNoShadowPasses(bool split);
230                /** Sets whether or not objects which cast shadows should be treated as
231                never receiving shadows.
232                */
233                void setShadowCastersCannotBeReceivers(bool ind);
234
235                /** Set a renderable listener on the queue.
236                @remarks
237                        There can only be a single renderable listener on the queue, since
238                        that listener has complete control over the techniques in use.
239                */
240                void setRenderableListener(RenderableListener* listener)
241                { mRenderableListener = listener; }
242
243                RenderableListener* getRenderableListener(void) const
244                { return mRenderableListener; }
245
246    };
247
248
249}
250
251
252#endif
Note: See TracBrowser for help on using the repository browser.