source: OGRE/trunk/ogrenew/OgreMain/include/OgreRenderQueueInvocation.h @ 692

Revision 692, 8.7 KB checked in by mattausch, 19 years ago (diff)

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