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

Revision 692, 12.0 KB checked in by mattausch, 18 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 (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                /// Get the material name in use
216                virtual const String& getMaterialName(void) const { return mMaterialName; }
217                /// Set the material name to use for rendering
218                virtual void setMaterialName(const String& name);
219
220
221                // Overridden members follow
222                void _notifyCurrentCamera(Camera* cam);
223                Real getSquaredViewDepth(const Camera* cam) const;
224                Real getBoundingRadius(void) const;
225                const AxisAlignedBox& getBoundingBox(void) const;
226                const MaterialPtr& getMaterial(void) const;
227                const String& getMovableType(void) const;
228                void _updateRenderQueue(RenderQueue *);
229                void getRenderOperation(RenderOperation &);
230                void getWorldTransforms(Matrix4 *) const;
231                const Quaternion& getWorldOrientation(void) const;
232                const Vector3& getWorldPosition(void) const;
233                const LightList& getLights(void) const;
234
235
236
237        protected:
238
239                /// Maximum length of each chain
240                size_t mMaxElementsPerChain;
241                /// Number of chains
242                size_t mChainCount;
243                /// Use texture coords?
244                bool mUseTexCoords;
245                /// Use vertex colour?
246                bool mUseVertexColour;
247                /// Dynamic use?
248                bool mDynamic;
249                /// Vertex data
250                VertexData* mVertexData;
251                /// Index data (to allow multiple unconnected chains)
252                IndexData* mIndexData;
253                /// Is the vertex declaration dirty?
254                bool mVertexDeclDirty;
255                /// Do the buffers need recreating?
256                bool mBuffersNeedRecreating;
257                /// Do the bounds need redefining?
258                mutable bool mBoundsDirty;
259                /// Is the index buffer dirty?
260                bool mIndexContentDirty;
261                /// AABB
262                mutable AxisAlignedBox mAABB;
263                /// Bounding radius
264                mutable Real mRadius;
265                /// Material
266                String mMaterialName;
267                MaterialPtr mMaterial;
268                /// Tetxure coord direction
269                TexCoordDirection mTexCoordDir;
270                /// Other texture coord range
271                Real mOtherTexCoordRange[2];
272
273
274                /// The list holding the chain elements
275                ElementList mChainElementList;
276
277                /** Simple struct defining a chain segment by referencing a subset of
278                        the preallocated buffer (which will be mMaxElementsPerChain * mChainCount
279                        long), by it's chain index, and a head and tail value which describe
280                        the current chain. The buffer subset wraps at mMaxElementsPerChain
281                        so that head and tail can move freely. head and tail are inclusive,
282                        when the chain is empty head and tail are filled with high-values.
283                */
284                struct ChainSegment
285                {
286                        /// The start of this chains subset of the buffer
287                        size_t start;
288                        /// The 'head' of the chain, relative to start
289                        size_t head;
290                        /// The 'tail' of the chain, relative to start
291                        size_t tail;
292                };
293                typedef std::vector<ChainSegment> ChainSegmentList;
294                ChainSegmentList mChainSegmentList;
295
296                /// Setup the STL collections
297                virtual void setupChainContainers(void);
298                /// Setup vertex declaration
299                virtual void setupVertexDeclaration(void);
300                // Setup buffers
301                virtual void setupBuffers(void);
302                /// Update the contents of the vertex buffer
303                virtual void updateVertexBuffer(Camera* cam);
304                /// Update the contents of the index buffer
305                virtual void updateIndexBuffer(void);
306                virtual void updateBoundingBox(void) const;
307
308                /// Chain segment has no elements
309                static const size_t SEGMENT_EMPTY;
310        };
311
312
313        /** Factory object for creating BillboardChain instances */
314        class _OgreExport BillboardChainFactory : public MovableObjectFactory
315        {
316        protected:
317                MovableObject* createInstanceImpl( const String& name, const NameValuePairList* params);
318        public:
319                BillboardChainFactory() {}
320                ~BillboardChainFactory() {}
321
322                static String FACTORY_TYPE_NAME;
323
324                const String& getType(void) const;
325                void destroyInstance( MovableObject* obj); 
326
327        };
328
329
330} // namespace
331
332#endif
333
Note: See TracBrowser for help on using the repository browser.