Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/OgreMain/include/OgreRenderQueueInvocation.h @ 1

Last change on this file since 1 was 1, checked in by landauf, 17 years ago
File size: 8.8 KB
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
24You may alternatively use this source under the terms of a specific version of
25the OGRE Unrestricted License provided you have obtained such a license from
26Torus Knot Software Ltd.
27-----------------------------------------------------------------------------
28*/
29#ifndef __RenderQueueInvocation_H__
30#define __RenderQueueInvocation_H__
31
32#include "OgrePrerequisites.h"
33#include "OgreRenderQueueSortingGrouping.h"
34#include "OgreIteratorWrappers.h"
35
36namespace Ogre {
37
38        /** Class representing the invocation of queue groups in a RenderQueue.
39        @remarks
40                The default behaviour for OGRE's render queue is to render each queue
41                group in turn, dealing with shadows automatically, and rendering solids
42                in grouped passes, followed by transparent objects in descending order.
43                This class, together with RenderQueueInvocationSequence and the ability
44                to associate one with a Viewport, allows you to change that behaviour
45                and render queue groups in arbitrary sequence, repeatedly, and to skip
46                shadows, change the ordering of solids, or even prevent OGRE controlling
47                the render state during a particular invocation for special effects.
48        @par
49                Note that whilst you can change the ordering of rendering solids, you
50                can't change the ordering on transparent objects, since to do this would
51                cause them to render incorrectly.
52        @par
53                As well as using this class directly and using the options it provides you
54                with, you can also provide subclasses of it to a
55                RenderQueueInvocationSequence instance if you want to gain ultimate control.
56        @note
57                Invocations will be skipped if there are scene-level options preventing
58                them being rendered - for example special-case render queues and
59                render queue listeners that dictate this.
60        */
61        class _OgreExport RenderQueueInvocation
62        {
63        protected:
64                /// Target queue group
65                uint8 mRenderQueueGroupID;
66                /// Invocation identifier - used in listeners
67                String mInvocationName;
68                /// Solids ordering mode
69                QueuedRenderableCollection::OrganisationMode mSolidsOrganisation;
70                /// Suppress shadows processing in this invocation?
71                bool mSuppressShadows;
72                /// Suppress OGRE's render state management?
73                bool mSuppressRenderStateChanges;
74        public:
75                /** Constructor
76                @param renderQueueGroupID ID of the queue this will target
77                @param invocationName Optional name to uniquely identify this
78                        invocation from others in a RenderQueueListener
79                */
80                RenderQueueInvocation(uint8 renderQueueGroupID, 
81                        const String& invocationName = StringUtil::BLANK);
82                virtual ~RenderQueueInvocation();
83
84                /// Get the render queue group id
85                virtual uint8 getRenderQueueGroupID(void) const { return mRenderQueueGroupID; }
86
87                /// Get the invocation name (may be blank if not set by creator)
88                virtual const String& getInvocationName(void) const { return mInvocationName; }
89
90                /** Set the organisation mode being used for solids in this queue group
91                invocation.
92                */
93                virtual void setSolidsOrganisation(
94                        QueuedRenderableCollection::OrganisationMode org) 
95                { mSolidsOrganisation = org; }
96
97                /** Get the organisation mode being used for solids in this queue group
98                        invocation.
99                */
100                virtual QueuedRenderableCollection::OrganisationMode
101                        getSolidsOrganisation(void) const { return mSolidsOrganisation; }
102
103                /** Sets whether shadows are suppressed when invoking this queue.
104                @remarks
105                        When doing effects you often will want to suppress shadow processing
106                        if shadows will already have been done by a previous render.
107                */
108                virtual void setSuppressShadows(bool suppress) 
109                { mSuppressShadows =  suppress; }
110
111                /** Gets whether shadows are suppressed when invoking this queue.
112                */
113                virtual bool getSuppressShadows(void) const { return mSuppressShadows; }
114
115                /** Sets whether render state changes are suppressed when invoking this queue.
116                @remarks
117                        When doing special effects you may want to set up render state yourself
118                        and have it apply for the entire rendering of a queue. In that case,
119                        you should call this method with a parameter of 'true', and use a
120                        RenderQueueListener to set the render state directly on RenderSystem
121                        yourself before the invocation.
122                @par
123                        Suppressing render state changes is only intended for advanced use,
124                        don't use it if you're unsure of the effect. The only RenderSystem
125                        calls made are to set the world matrix for each object (note -
126                        view an projection matrices are NOT SET - they are under your control)
127                        and to render the object; it is up to the caller to do everything else,
128                        including enabling any vertex / fragment programs and updating their
129                        parameter state, and binding parameters to the RenderSystem.
130                        We advise you use a RenderQueueListener in order to get a notification
131                        when this invocation is going to happen (use an invocation name to
132                        identify it if you like), at which point you can set the state you
133                        need to apply before the objects are rendered.
134                */
135                virtual void setSuppressRenderStateChanges(bool suppress) 
136                { mSuppressRenderStateChanges =  suppress; }
137
138                /** Gets whether shadows are suppressed when invoking this queue.
139                */
140                virtual bool getSuppressRenderStateChanges(void) const { return mSuppressRenderStateChanges; }
141
142                /** Invoke this class on a concrete queue group.
143                @remarks
144                        Implementation will send the queue group to the target scene manager
145                        after doing what it needs to do.
146                */
147                virtual void invoke(RenderQueueGroup* group, SceneManager* targetSceneManager);
148
149                /// Invocation identifier for shadows
150                static String RENDER_QUEUE_INVOCATION_SHADOWS;
151        };
152
153
154        /// List of RenderQueueInvocations
155        typedef std::vector<RenderQueueInvocation*> RenderQueueInvocationList;
156        typedef VectorIterator<RenderQueueInvocationList> RenderQueueInvocationIterator;
157
158        /** Class to hold a linear sequence of RenderQueueInvocation objects.
159        @remarks
160                This is just a simple data holder class which contains a list of
161                RenderQueueInvocation objects representing the sequence of invocations
162                made for a viewport. It's only real purpose is to ensure that
163                RenderQueueInvocation instances are deleted on shudown, since you can
164                provide your own subclass instances on RenderQueueInvocation. Remember
165                that any invocation instances you give to this class will be deleted
166                by it when it is cleared / destroyed.
167        */
168        class _OgreExport RenderQueueInvocationSequence
169        {
170        protected:
171                String mName;
172                RenderQueueInvocationList mInvocations;
173        public:
174                RenderQueueInvocationSequence(const String& name);
175                virtual ~RenderQueueInvocationSequence();
176
177                /** Get the name of this sequence. */
178                const String& getName(void) const { return mName; }
179
180                /** Add a standard invocation to the sequence.
181                @param renderQueueGroupID The ID of the render queue group
182                @param invocationName Optional name to identify the invocation, useful
183                        for listeners if a single queue group is invoked more than once
184                @returns A new RenderQueueInvocatin instance which you may customise
185                */
186                RenderQueueInvocation* add(uint8 renderQueueGroupID, 
187                        const String& invocationName);
188
189                /** Add a custom invocation to the sequence.
190                @remarks
191                        Use this to add your own custom subclasses of RenderQueueInvocation
192                        to the sequence; just remember that this class takes ownership of
193                        deleting this pointer when it is cleared / destroyed.
194                */
195                void add(RenderQueueInvocation* i);
196
197                /** Get the number of invocations in this sequence. */
198                size_t size(void) const { return mInvocations.size(); }
199
200                /** Clear and delete all invocations in this sequence. */
201                void clear(void);
202
203                /** Gets the details of an invocation at a given index. */
204                RenderQueueInvocation* get(size_t index);
205
206                /** Removes (and deletes) an invocation by index. */
207                void remove(size_t index);
208
209                /** Get an iterator over the invocations. */
210                RenderQueueInvocationIterator iterator(void);
211
212
213        };
214
215}
216
217#endif
218
Note: See TracBrowser for help on using the repository browser.