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

Revision 1809, 12.3 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
26// Thanks to Vincent Cantin (karmaGfa) for the original implementation of this
27// class, although it has now been mostly rewritten
28
29#ifndef _BillboardChain_H__
30#define _BillboardChain_H__
31
32#include "OgrePrerequisites.h"
33
34#include "OgreMovableObject.h"
35#include "OgreRenderable.h"
36
37namespace Ogre {
38
39
40        /** Allows the rendering of a chain of connected billboards.
41        @remarks
42                A billboard chain operates much like a traditional billboard, ie its
43                segments always face the camera; the difference being that instead of
44                a set of disconnected quads, the elements in this class are connected
45                together in a chain which must always stay in a continuous strip. This
46                kind of effect is useful for creating effects such as trails, beams,
47                lightning effects, etc.
48        @par
49                A single instance of this class can actually render multiple separate
50                chain segments in a single render operation, provided they all use the
51                same material. To clarify the terminology: a 'segment' is a separate
52                sub-part of the chain with its own start and end (called the 'head'
53                and the 'tail'. An 'element' is a single position / colour / texcoord
54                entry in a segment. You can add items to the head of a chain, and
55                remove them from the tail, very efficiently. Each segment has a max
56                size, and if adding an element to the segment would exceed this size,
57                the tail element is automatically removed and re-used as the new item
58                on the head.
59        @par
60                This class has no auto-updating features to do things like alter the
61                colour of the elements or to automatically add / remove elements over
62                time - you have to do all this yourself as a user of the class.
63                Subclasses can however be used to provide this kind of behaviour
64                automatically. @see RibbonTrail
65        */
66        class _OgreExport BillboardChain : public MovableObject, public Renderable
67        {
68
69        public:
70
71                /** Contains the data of an element of the BillboardChain.
72                */
73                class _OgreExport Element
74                {
75
76                public:
77
78                        Element();
79
80                        Element(Vector3 position,
81                                Real width,
82                                Real texCoord,
83                                ColourValue colour);
84
85                        Vector3 position;
86                        Real width;
87                        /// U or V texture coord depending on options
88                        Real texCoord;
89                        ColourValue colour;
90
91                };
92                typedef std::vector<Element> ElementList;
93
94                /** Constructor (don't use directly, use factory)
95                @param name The name to give this object
96                @param maxElements The maximum number of elements per chain
97                @param numberOfChains The number of separate chain segments contained in this object
98                @param useTextureCoords If true, use texture coordinates from the chain elements
99                @param useVertexColours If true, use vertex colours from the chain elements
100                @param dynamic If true, buffers are created with the intention of being updated
101                */
102                BillboardChain(const String& name, size_t maxElements = 20, size_t numberOfChains = 1,
103                        bool useTextureCoords = true, bool useColours = true, bool dynamic = true);
104                /// destructor
105                virtual ~BillboardChain();
106
107                /** Set the maximum number of chain elements per chain
108                */
109                virtual void setMaxChainElements(size_t maxElements);
110                /** Get the maximum number of chain elements per chain
111                */
112                virtual size_t getMaxChainElements(void) const { return mMaxElementsPerChain; }
113                /** Set the number of chain segments (this class can render multiple chains
114                        at once using the same material).
115                */
116                virtual void setNumberOfChains(size_t numChains);
117                /** Get the number of chain segments (this class can render multiple chains
118                at once using the same material).
119                */
120                virtual size_t getNumberOfChains(void) const { return mChainCount; }
121
122                /** Sets whether texture coordinate information should be included in the
123                        final buffers generated.
124                @note You must use either texture coordinates or vertex colour since the
125                        vertices have no normals and without one of these there is no source of
126                        colour for the vertices.
127                */
128                virtual void setUseTextureCoords(bool use);
129                /** Gets whether texture coordinate information should be included in the
130                        final buffers generated.
131                */
132                virtual bool getUseTextureCoords(void) const { return mUseTexCoords; }
133
134                /** The direction in which texture coordinates from elements of the
135                        chain are used.
136                */
137                enum TexCoordDirection
138                {
139                        /// Tex coord in elements is treated as the 'u' texture coordinate
140                        TCD_U,
141                        /// Tex coord in elements is treated as the 'v' texture coordinate
142                        TCD_V
143                };
144                /** Sets the direction in which texture coords specified on each element
145                        are deemed to run along the length of the chain.
146                @param dir The direction, default is TCD_U.
147                */
148                virtual void setTextureCoordDirection(TexCoordDirection dir);
149                /** Gets the direction in which texture coords specified on each element
150                        are deemed to run.
151                */
152                virtual TexCoordDirection getTextureCoordDirection(void) { return mTexCoordDir; }
153
154                /** Set the range of the texture coordinates generated across the width of
155                        the chain elements.
156                @param start Start coordinate, default 0.0
157                @param end End coordinate, default 1.0
158                */
159                virtual void setOtherTextureCoordRange(Real start, Real end);
160                /** Get the range of the texture coordinates generated across the width of
161                        the chain elements.
162                */
163                virtual const Real* getOtherTextureCoordRange(void) const { return mOtherTexCoordRange; }
164
165                /** Sets whether vertex colour information should be included in the
166                        final buffers generated.
167                @note You must use either texture coordinates or vertex colour since the
168                        vertices have no normals and without one of these there is no source of
169                        colour for the vertices.
170                */
171                virtual void setUseVertexColours(bool use);
172                /** Gets whether vertex colour information should be included in the
173                        final buffers generated.
174                */
175                virtual bool getUseVertexColours(void) const { return mUseVertexColour; }
176
177                /** Sets whether or not the buffers created for this object are suitable
178                        for dynamic alteration.
179                */
180                virtual void setDynamic(bool dyn);
181
182                /** Gets whether or not the buffers created for this object are suitable
183                        for dynamic alteration.
184                */
185                virtual bool getDynamic(void) const { return mDynamic; }
186               
187                /** Add an element to the 'head' of a chain.
188                @remarks
189                        If this causes the number of elements to exceed the maximum elements
190                        per chain, the last element in the chain (the 'tail') will be removed
191                        to allow the additional element to be added.
192                @param chainIndex The index of the chain
193                @param billboardChainElement The details to add
194                */
195                virtual void addChainElement(size_t chainIndex,
196                        const Element& billboardChainElement);
197                /** Remove an element from the 'tail' of a chain.
198                @param chainIndex The index of the chain
199                */
200                virtual void removeChainElement(size_t chainIndex);
201                /** Update the details of an existing chain element.
202                @param chainIndex The index of the chain
203                @param elementIndex The element index within the chain, measured from
204                        the 'head' of the chain
205                @param billboardChainElement The details to set
206                */
207                virtual void updateChainElement(size_t chainIndex, size_t elementIndex,
208                        const Element& billboardChainElement);
209                /** Get the detail of a chain element.
210                @param chainIndex The index of the chain
211                @param elementIndex The element index within the chain, measured from
212                        the 'head' of the chain
213                */
214                virtual const Element& getChainElement(size_t chainIndex, size_t elementIndex) const;
215
216                /** Remove all elements of a given chain (but leave the chain intact). */
217                virtual void clearChain(size_t chainIndex);
218                /** Remove all elements from all chains (but leave the chains themselves intact). */
219                virtual void clearAllChains(void);
220
221                /// Get the material name in use
222                virtual const String& getMaterialName(void) const { return mMaterialName; }
223                /// Set the material name to use for rendering
224                virtual void setMaterialName(const String& name);
225
226
227                // Overridden members follow
228                void _notifyCurrentCamera(Camera* cam);
229                Real getSquaredViewDepth(const Camera* cam) const;
230                Real getBoundingRadius(void) const;
231                const AxisAlignedBox& getBoundingBox(void) const;
232                const MaterialPtr& getMaterial(void) const;
233                const String& getMovableType(void) const;
234                void _updateRenderQueue(RenderQueue *);
235                void getRenderOperation(RenderOperation &);
236                void getWorldTransforms(Matrix4 *) const;
237                const Quaternion& getWorldOrientation(void) const;
238                const Vector3& getWorldPosition(void) const;
239                const LightList& getLights(void) const;
240
241
242
243        protected:
244
245                /// Maximum length of each chain
246                size_t mMaxElementsPerChain;
247                /// Number of chains
248                size_t mChainCount;
249                /// Use texture coords?
250                bool mUseTexCoords;
251                /// Use vertex colour?
252                bool mUseVertexColour;
253                /// Dynamic use?
254                bool mDynamic;
255                /// Vertex data
256                VertexData* mVertexData;
257                /// Index data (to allow multiple unconnected chains)
258                IndexData* mIndexData;
259                /// Is the vertex declaration dirty?
260                bool mVertexDeclDirty;
261                /// Do the buffers need recreating?
262                bool mBuffersNeedRecreating;
263                /// Do the bounds need redefining?
264                mutable bool mBoundsDirty;
265                /// Is the index buffer dirty?
266                bool mIndexContentDirty;
267                /// AABB
268                mutable AxisAlignedBox mAABB;
269                /// Bounding radius
270                mutable Real mRadius;
271                /// Material
272                String mMaterialName;
273                MaterialPtr mMaterial;
274                /// Tetxure coord direction
275                TexCoordDirection mTexCoordDir;
276                /// Other texture coord range
277                Real mOtherTexCoordRange[2];
278
279
280                /// The list holding the chain elements
281                ElementList mChainElementList;
282
283                /** Simple struct defining a chain segment by referencing a subset of
284                        the preallocated buffer (which will be mMaxElementsPerChain * mChainCount
285                        long), by it's chain index, and a head and tail value which describe
286                        the current chain. The buffer subset wraps at mMaxElementsPerChain
287                        so that head and tail can move freely. head and tail are inclusive,
288                        when the chain is empty head and tail are filled with high-values.
289                */
290                struct ChainSegment
291                {
292                        /// The start of this chains subset of the buffer
293                        size_t start;
294                        /// The 'head' of the chain, relative to start
295                        size_t head;
296                        /// The 'tail' of the chain, relative to start
297                        size_t tail;
298                };
299                typedef std::vector<ChainSegment> ChainSegmentList;
300                ChainSegmentList mChainSegmentList;
301
302                /// Setup the STL collections
303                virtual void setupChainContainers(void);
304                /// Setup vertex declaration
305                virtual void setupVertexDeclaration(void);
306                // Setup buffers
307                virtual void setupBuffers(void);
308                /// Update the contents of the vertex buffer
309                virtual void updateVertexBuffer(Camera* cam);
310                /// Update the contents of the index buffer
311                virtual void updateIndexBuffer(void);
312                virtual void updateBoundingBox(void) const;
313
314                /// Chain segment has no elements
315                static const size_t SEGMENT_EMPTY;
316        };
317
318
319        /** Factory object for creating BillboardChain instances */
320        class _OgreExport BillboardChainFactory : public MovableObjectFactory
321        {
322        protected:
323                MovableObject* createInstanceImpl( const String& name, const NameValuePairList* params);
324        public:
325                BillboardChainFactory() {}
326                ~BillboardChainFactory() {}
327
328                static String FACTORY_TYPE_NAME;
329
330                const String& getType(void) const;
331                void destroyInstance( MovableObject* obj); 
332
333        };
334
335
336} // namespace
337
338#endif
339
Note: See TracBrowser for help on using the repository browser.