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

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

adding ogre 1.2 and dependencies

RevLine 
[692]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#ifndef __BillboardSet_H__
27#define __BillboardSet_H__
28
29#include "OgrePrerequisites.h"
30
31#include "OgreMovableObject.h"
32#include "OgreRenderable.h"
33#include "OgreRadixSort.h"
34#include "OgreCommon.h"
35
36namespace Ogre {
37
38    /** Enum covering what exactly a billboard's position means (center,
39        top-left etc).
40        @see
41            BillboardSet::setBillboardOrigin
42    */
43    enum BillboardOrigin
44    {
45        BBO_TOP_LEFT,
46        BBO_TOP_CENTER,
47        BBO_TOP_RIGHT,
48        BBO_CENTER_LEFT,
49        BBO_CENTER,
50        BBO_CENTER_RIGHT,
51        BBO_BOTTOM_LEFT,
52        BBO_BOTTOM_CENTER,
53        BBO_BOTTOM_RIGHT
54    };
55    /** The rotation type of billboard. */
56    enum BillboardRotationType
57    {
58        /// Rotate the billboard's vertices around their facing direction
59        BBR_VERTEX,
60        /// Rotate the billboard's texture coordinates
61        BBR_TEXCOORD
62    };
63    /** The type of billboard to use. */
64    enum BillboardType
65    {
66        /// Standard point billboard (default), always faces the camera completely and is always upright
67        BBT_POINT,
68        /// Billboards are oriented around a shared direction vector (used as Y axis) and only rotate around this to face the camera
69        BBT_ORIENTED_COMMON,
70        /// Billboards are oriented around their own direction vector (their own Y axis) and only rotate around this to face the camera
71        BBT_ORIENTED_SELF,
72        /// Billboards are perpendicular to a shared direction vector (used as Z axis, the facing direction) and X, Y axis are determined by a shared up-vertor
73        BBT_PERPENDICULAR_COMMON,
74        /// Billboards are perpendicular to their own direction vector (their own Z axis, the facing direction) and X, Y axis are determined by a shared up-vertor
75        BBT_PERPENDICULAR_SELF
76    };
77
78    /** A collection of billboards (faces which are always facing the given direction) with the same (default) dimensions, material
79        and which are fairly close proximity to each other.
80        @remarks
81            Billboards are rectangles made up of 2 tris which are always facing the given direction. They are typically used
82            for special effects like particles. This class collects together a set of billboards with the same (default) dimensions,
83            material and relative locality in order to process them more efficiently. The entire set of billboards will be
84            culled as a whole (by default, although this can be changed if you want a large set of billboards
85            which are spread out and you want them culled individually), individual Billboards have locations which are relative to the set (which itself derives it's
86            position from the SceneNode it is attached to since it is a MoveableObject), they will be rendered as a single rendering operation,
87            and some calculations will be sped up by the fact that they use the same dimensions so some workings can be reused.
88        @par
89            A BillboardSet can be created using the SceneManager::createBillboardSet method. They can also be used internally
90            by other classes to create effects.
91                @note
92                        Billboard bounds are only automatically calculated when you create them.
93                        If you modify the position of a billboard you may need to call
94                        _updateBounds if the billboard moves outside the original bounds.
95                        Similarly, the bounds do no shrink when you remove a billboard,
96                        if you want them to call _updateBounds, but note this requires a
97                        potentially expensive examination of every billboard in the set.
98    */
99    class _OgreExport BillboardSet : public MovableObject, public Renderable
100    {
101    protected:
102        /** Private constructor (instances cannot be created directly).
103        */
104        BillboardSet();
105
106        /// Bounds of all billboards in this set
107        AxisAlignedBox mAABB;
108                /// Bounding radius
109                Real mBoundingRadius;
110
111        /// Origin of each billboard
112        BillboardOrigin mOriginType;
113        /// Rotation type of each billboard
114        BillboardRotationType mRotationType;
115
116        /// Default width of each billboard
117        Real mDefaultWidth;
118        /// Default height of each billboard
119        Real mDefaultHeight;
120
121        /// Name of the material to use
122        String mMaterialName;
123        /// Pointer to the material to use
124        MaterialPtr mpMaterial;
125
126        /// True if no billboards in this set have been resized - greater efficiency.
127        bool mAllDefaultSize;
128
129        /// Flag indicating whether to autoextend pool
130        bool mAutoExtendPool;
131
132                /// Flag indicating whether the billboards has to be sorted
133                bool mSortingEnabled;
134
135        // Use 'true' billboard to cam position facing, rather than camera direcion
136        bool mAccurateFacing;
137
138        bool mAllDefaultRotation;
139        bool mWorldSpace;
140
141        typedef std::list<Billboard*> ActiveBillboardList;
142        typedef std::list<Billboard*> FreeBillboardList;
143        typedef std::vector<Billboard*> BillboardPool;
144
145        /** Active billboard list.
146            @remarks
147                This is a linked list of pointers to billboards in the billboard pool.
148            @par
149                This allows very fast instertions and deletions from anywhere in the list to activate / deactivate billboards
150                (required for particle systems etc)    as well as resuse of Billboard instances in the pool
151                without construction & destruction which avoids memory thrashing.
152        */
153        ActiveBillboardList mActiveBillboards;
154
155        /** Free billboard queue.
156            @remarks
157                This contains a list of the billboards free for use as new instances
158                as required by the set. Billboard instances are preconstructed up to the estimated size in the
159                mBillboardPool vector and are referenced on this deque at startup. As they get used this deque
160                reduces, as they get released back to to the set they get added back to the deque.
161        */
162        FreeBillboardList mFreeBillboards;
163
164        /** Pool of billboard instances for use and reuse in the active billboard list.
165            @remarks
166                This vector will be preallocated with the estimated size of the set,and will extend as required.
167        */
168        BillboardPool mBillboardPool;
169
170        /// The vertex position data for all billboards in this set.
171        VertexData* mVertexData;
172        /// Shortcut to main buffer (positions, colours, texture coords)
173        HardwareVertexBufferSharedPtr mMainBuf;
174        /// Locked pointer to buffer
175        float* mLockPtr;
176        /// Boundary offsets based on origin and camera orientation
177        /// Vector3 vLeftOff, vRightOff, vTopOff, vBottomOff;
178        /// Final vertex offsets, used where sizes all default to save calcs
179        Vector3 mVOffset[4];
180        /// Current camera
181        Camera* mCurrentCamera;
182        // Parametric offsets of origin
183        Real mLeftOff, mRightOff, mTopOff, mBottomOff;
184        // Camera axes in billboard space
185        Vector3 mCamX, mCamY;
186        // Camera direction in billboard space
187        Vector3 mCamDir;
188        // Camera orientation in billboard space
189        Quaternion mCamQ;
190        // Camera position in billboard space
191        Vector3 mCamPos;
192
193        /// The vertex index data for all billboards in this set (1 set only)
194        //unsigned short* mpIndexes;
195        IndexData* mIndexData;
196
197        /// Flag indicating whether each billboard should be culled separately (default: false)
198        bool mCullIndividual;
199
200        typedef std::vector< Ogre::FloatRect > TextureCoordSets;
201        TextureCoordSets mTextureCoords;
202
203        /// The type of billboard to render
204        BillboardType mBillboardType;
205
206        /// Common direction for billboards of type BBT_ORIENTED_COMMON and BBT_PERPENDICULAR_COMMON
207        Vector3 mCommonDirection;
208        /// Common up-vector for billboards of type BBT_PERPENDICULAR_SELF and BBT_PERPENDICULAR_COMMON
209        Vector3 mCommonUpVector;
210
211        /// Internal method for culling individual billboards
212        inline bool billboardVisible(Camera* cam, const Billboard& bill);
213
214        // Number of visible billboards (will be == getNumBillboards if mCullIndividual == false)
215        unsigned short mNumVisibleBillboards;
216
217        /// Internal method for increasing pool size
218        virtual void increasePool(unsigned int size);
219
220
221        //-----------------------------------------------------------------------
222        // The internal methods which follow are here to allow maximum flexibility as to
223        //  when various components of the calculation are done. Depending on whether the
224        //  billboards are of fixed size and whether they are point or oriented type will
225        //  determine how much calculation has to be done per-billboard. NOT a one-size fits all approach.
226        //-----------------------------------------------------------------------
227        /** Internal method for generating billboard corners.
228        @remarks
229            Optional parameter pBill is only present for type BBT_ORIENTED_SELF and BBT_PERPENDICULAR_SELF
230        */
231        void genBillboardAxes(Vector3* pX, Vector3 *pY, const Billboard* pBill = 0);
232
233        /** Internal method, generates parametric offsets based on origin.
234        */
235        void getParametricOffsets(Real& left, Real& right, Real& top, Real& bottom);
236
237        /** Internal method for generating vertex data.
238        @param offsets Array of 4 Vector3 offsets
239        @param bb Referenceto billboard
240        */
241        void genVertices(const Vector3* const offsets, const Billboard& pBillboard);
242
243        /** Internal method generates vertex offsets.
244        @remarks
245            Takes in parametric offsets as generated from getParametericOffsets, width and height values
246            and billboard x and y axes as generated from genBillboardAxes.
247            Fills output array of 4 vectors with vector offsets
248            from origin for left-top, right-top, left-bottom, right-bottom corners.
249        */
250        void genVertOffsets(Real inleft, Real inright, Real intop, Real inbottom,
251            Real width, Real height,
252            const Vector3& x, const Vector3& y, Vector3* pDestVec);
253
254
255        /** Sort by direction functor */
256        struct SortByDirectionFunctor
257        {
258            /// Direction to sort in
259            Vector3 sortDir;
260
261            SortByDirectionFunctor(const Vector3& dir);
262            float operator()(Billboard* bill) const;
263        };
264
265        /** Sort by distance functor */
266        struct SortByDistanceFunctor
267        {
268            /// Position to sort in
269            Vector3 sortPos;
270
271            SortByDistanceFunctor(const Vector3& pos);
272            float operator()(Billboard* bill) const;
273        };
274
275                static RadixSort<ActiveBillboardList, Billboard*, float> mRadixSorter;
276
277                /// Use point rendering?
278                bool mPointRendering;
279
280
281
282    private:
283        /// Flag indicating whether the HW buffers have been created.
284        bool mBuffersCreated;
285        /// The number of billboard in the pool.
286        unsigned int mPoolSize;
287        /// Is external billboard data in use?
288        bool mExternalData;
289
290        /** Internal method creates vertex and index buffers.
291        */
292        void _createBuffers(void);
293        /** Internal method destroys vertex and index buffers.
294        */
295        void _destroyBuffers(void);
296
297    public:
298
299        /** Usual constructor - this is called by the SceneManager.
300            @param
301                name The name to give the billboard set (must be unique)
302            @param
303                poolSize The initial size of the billboard pool. Estimate of the number of billboards
304                which will be required, and pass it using this parameter. The set will
305                preallocate this number to avoid memory fragmentation. The default behaviour
306                once this pool has run out is to double it.
307            @param
308                externalDataSource If true, the source of data for drawing the
309                billboards will not be the internal billboard list, but external
310                data. When driving thebillboard from external data, you must call
311                _notifyCurrentCamera to reorient the billboards, setPoolSize to set
312                the maximum billboards you want to use, beginBillboards to
313                start the update, and injectBillboard per billboard,
314                followed by endBillboards.
315            @see
316                BillboardSet::setAutoextend
317        */
318        BillboardSet( const String& name, unsigned int poolSize = 20,
319            bool externalDataSource = false);
320
321        virtual ~BillboardSet();
322
323        /** Creates a new billboard and adds it to this set.
324            @remarks
325                Behaviour once the billboard pool has been exhausted depends on the
326                BillboardSet::setAutoextendPool option.
327            @param
328                position The position of the new billboard realtive to the certer of the set
329            @param
330                colour Optional base colour of the billboard.
331            @returns
332                On success, a pointer to a newly created Billboard is
333                returned.
334            @par
335                On failiure (i.e. no more space and can't autoextend),
336                <b>NULL</b> is returned.
337            @see
338                BillboardSet::setAutoextend
339        */
340        Billboard* createBillboard(
341            const Vector3& position,
342            const ColourValue& colour = ColourValue::White );
343
344        /** Creates a new billboard and adds it to this set.
345            @remarks
346                Behaviour once the billboard pool has been exhausted depends on the
347                BillboardSet::setAutoextendPool option.
348            @param
349                x
350            @param
351                y
352            @param
353                z The position of the new billboard realtive to the certer of the set
354            @param
355                colour Optional base colour of the billboard.
356            @returns
357                On success, a pointer to a newly created Billboard is
358                returned.
359            @par
360                On failiure (i.e. no more space and can't autoextend),
361                <b>NULL</b> is returned.
362            @see
363                BillboardSet::setAutoextend
364        */
365        Billboard* createBillboard(
366            Real x, Real y, Real z,
367            const ColourValue& colour = ColourValue::White );
368
369        /** Returns the number of active billboards which currently make up this set.
370        */
371        virtual int getNumBillboards(void) const;
372
373        /** Tells the set whether to allow automatic extension of the pool of billboards.
374            @remarks
375                A BillboardSet stores a pool of pre-constructed billboards which are used as needed when
376                a new billboard is requested. This allows applications to create / remove billboards efficiently
377                without incurring construction / destruction costs (a must for sets with lots of billboards like
378                particle effects). This method allows you to configure the behaviour when a new billboard is requested
379                but the billboard pool has been exhausted.
380            @par
381                The default behaviour is to allow the pool to extend (typically this allocates double the current
382                pool of billboards when the pool is expended), equivalent to calling this method with
383                autoExtend = true. If you set the parameter to false however, any attempt to create a new billboard
384                when the pool has expired will simply fail silently, returning a null pointer.
385            @param autoextend true to double the pool every time it runs out, false to fail silently.
386        */
387        virtual void setAutoextend(bool autoextend);
388
389        /** Returns true if the billboard pool automatically extends.
390            @see
391                BillboardSet::setAutoextend
392        */
393        virtual bool getAutoextend(void) const;
394
395                /** Enables sorting for this BillboardSet. (default: off)
396                        @param sortenable true to sort the billboards according to their distance to the camera
397                */
398                virtual void setSortingEnabled(bool sortenable);
399
400                /** Returns true if sorting of billboards is enabled based on their distance from the camera
401                    @see
402                                BillboardSet::setSortingEnabled
403                */
404                virtual bool getSortingEnabled(void) const;
405
406        /** Adjusts the size of the pool of billboards available in this set.
407            @remarks
408                See the BillboardSet::setAutoextend method for full details of the billboard pool. This method adjusts
409                the preallocated size of the pool. If you try to reduce the size of the pool, the set has the option
410                of ignoring you if too many billboards are already in use. Bear in mind that calling this method will
411                incur significant construction / destruction calls so should be avoided in time-critical code. The same
412                goes for auto-extension, try to avoid it by estimating the pool size correctly up-front.
413            @param
414                size The new size for the pool.
415        */
416        virtual void setPoolSize(unsigned int size);
417
418        /** Returns the current size of the billboard pool.
419            @returns
420                The current size of the billboard pool.
421            @see
422                BillboardSet::setAutoextend
423        */
424        virtual unsigned int getPoolSize(void) const;
425
426
427        /** Empties this set of all billboards.
428        */
429        virtual void clear();
430
431        /** Returns a pointer to the billboard at the supplied index.
432            @note
433                This method requires linear time since the billboard list is a linked list.
434            @param
435                index The index of the billboard that is requested.
436            @returns
437                On success, a valid pointer to the requested billboard is
438                returned.
439            @par
440                On failiure, <b>NULL</b> is returned.
441        */
442        virtual Billboard* getBillboard(unsigned int index) const;
443
444        /** Removes the billboard at the supplied index.
445            @note
446                This method requires linear time since the billboard list is a linked list.
447        */
448        virtual void removeBillboard(unsigned int index);
449
450        /** Removes a billboard from the set.
451            @note
452                This version is more efficient than removing by index.
453        */
454        virtual void removeBillboard(Billboard* pBill);
455
456        /** Sets the point which acts as the origin point for all billboards in this set.
457            @remarks
458                This setting controls the fine tuning of where a billboard appears in relation to it's
459                position. It could be that a billboard's position represents it's center (e.g. for fireballs),
460                it could mean the center of the bottom edge (e.g. a tree which is positioned on the ground),
461                the top-left corner (e.g. a cursor).
462            @par
463                The default setting is BBO_CENTER.
464            @param
465                origin A member of the BillboardOrigin enum specifying the origin for all the billboards in this set.
466        */
467        virtual void setBillboardOrigin(BillboardOrigin origin);
468
469        /** Gets the point which acts as the origin point for all billboards in this set.
470            @returns
471                A member of the BillboardOrigin enum specifying the origin for all the billboards in this set.
472        */
473        virtual BillboardOrigin getBillboardOrigin(void) const;
474
475        /** Sets billboard rotation type.
476            @remarks
477                This setting controls the billboard rotation type, you can deciding rotate the billboard's vertices
478                around their facing direction or rotate the billboard's texture coordinates.
479            @par
480                The default settings is BBR_TEXCOORD.
481            @param
482                rotationType A member of the BillboardRotationType enum specifying the rotation type for all the billboards in this set.
483        */
484        virtual void setBillboardRotationType(BillboardRotationType rotationType);
485
486        /** Sets billboard rotation type.
487            @returns
488                A member of the BillboardRotationType enum specifying the rotation type for all the billboards in this set.
489        */
490        virtual BillboardRotationType getBillboardRotationType(void) const;
491
492        /** Sets the default dimensions of the billboards in this set.
493            @remarks
494                All billboards in a set are created with these default dimensions. The set will render most efficiently if
495                all the billboards in the set are the default size. It is possible to alter the size of individual
496                billboards at the expense of extra calculation. See the Billboard class for more info.
497            @param width
498                The new default width for the billboards in this set.
499            @param height
500                The new default height for the billboards in this set.
501        */
502        virtual void setDefaultDimensions(Real width, Real height);
503
504        /** See setDefaultDimensions - this sets 1 component individually. */
505        virtual void setDefaultWidth(Real width);
506        /** See setDefaultDimensions - this gets 1 component individually. */
507        virtual Real getDefaultWidth(void) const;
508        /** See setDefaultDimensions - this sets 1 component individually. */
509        virtual void setDefaultHeight(Real height);
510        /** See setDefaultDimensions - this gets 1 component individually. */
511        virtual Real getDefaultHeight(void) const;
512
513        /** Sets the name of the material to be used for this billboard set.
514            @param
515                name The new name of the material to use for this set.
516        */
517        virtual void setMaterialName(const String& name);
518
519        /** Sets the name of the material to be used for this billboard set.
520            @returns The name of the material that is used for this set.
521        */
522        virtual const String& getMaterialName(void) const;
523
524        /** Overridden from MovableObject
525            @see
526                MovableObject
527        */
528        virtual void _notifyCurrentCamera(Camera* cam);
529
530        /** Begin injection of billboard data; applicable when
531            constructing the BillboardSet for external data use.
532        */
533        void beginBillboards(void);
534        /** Define a billboard. */
535        void injectBillboard(const Billboard& bb);
536        /** Finish defining billboards. */
537        void endBillboards(void);
538                /** Set the bounds of the BillboardSet.
539                @remarks
540                        You may need to call this if you're injecting billboards manually,
541                        and you're relying on the BillboardSet to determine culling.
542                */
543                void setBounds(const AxisAlignedBox& box, Real radius);
544
545
546        /** Overridden from MovableObject
547            @see
548                MovableObject
549        */
550        virtual const AxisAlignedBox& getBoundingBox(void) const;
551
552        /** Overridden from MovableObject
553            @see
554                MovableObject
555        */
556        virtual Real getBoundingRadius(void) const;
557        /** Overridden from MovableObject
558            @see
559                MovableObject
560        */
561        virtual void _updateRenderQueue(RenderQueue* queue);
562
563        /** Overridden from MovableObject
564            @see
565                MovableObject
566        */
567        virtual const MaterialPtr& getMaterial(void) const;
568
569        /** Overridden from MovableObject
570            @see
571                MovableObject
572        */
573        virtual void getRenderOperation(RenderOperation& op);
574
575        /** Overridden from MovableObject
576            @see
577                MovableObject
578        */
579        virtual void getWorldTransforms(Matrix4* xform) const;
580
581        /** @copydoc Renderable::getWorldOrientation */
582        const Quaternion& getWorldOrientation(void) const;
583        /** @copydoc Renderable::getWorldPosition */
584        const Vector3& getWorldPosition(void) const;
585        /** Internal callback used by Billboards to notify their parent that they have been resized.
586        */
587        virtual void _notifyBillboardResized(void);
588
589        /** Internal callback used by Billboards to notify their parent that they have been rotated..
590        */
591        virtual void _notifyBillboardRotated(void);
592
593        /** Returns whether or not billbards in this are tested individually for culling. */
594        virtual bool getCullIndividually(void) const;
595        /** Sets whether culling tests billboards in this individually as well as in a group.
596        @remarks
597            Billboard sets are always culled as a whole group, based on a bounding box which
598            encloses all billboards in the set. For fairly localised sets, this is enough. However, you
599            can optionally tell the set to also cull individual billboards in the set, i.e. to test
600            each individual billboard before rendering. The default is not to do this.
601        @par
602            This is useful when you have a large, fairly distributed set of billboards, like maybe
603            trees on a landscape. You probably still want to group them into more than one
604            set (maybe one set per section of landscape), which will be culled coarsely, but you also
605            want to cull the billboards individually because they are spread out. Whilst you could have
606            lots of single-tree sets which are culled separately, this would be inefficient to render
607            because each tree would be issued as it's own rendering operation.
608        @par
609            By calling this method with a parameter of true, you can have large billboard sets which
610            are spaced out and so get the benefit of batch rendering and coarse culling, but also have
611            fine-grained culling so unnecessary rendering is avoided.
612        @param cullIndividual If true, each billboard is tested before being sent to the pipeline as well
613            as the whole set having to pass the coarse group bounding test.
614        */
615        virtual void setCullIndividually(bool cullIndividual);
616
617        /** Sets the type of billboard to render.
618        @remarks
619            The default sort of billboard (BBT_POINT), always has both x and y axes parallel to
620            the camera's local axes. This is fine for 'point' style billboards (e.g. flares,
621            smoke, anything which is symmetrical about a central point) but does not look good for
622            billboards which have an orientation (e.g. an elongated raindrop). In this case, the
623            oriented billboards are more suitable (BBT_ORIENTED_COMMON or BBT_ORIENTED_SELF) since
624            they retain an independant Y axis and only the X axis is generated, perpendicular to both
625            the local Y and the camera Z.
626        @par
627            In some case you might want the billboard has fixed Z axis and doesn't need to face to
628            camera (e.g. an aureola around the player and parallel to the ground). You can use
629            BBT_PERPENDICULAR_SELF which the billboard plane perpendicular to the billboard own
630            direction. Or BBT_PERPENDICULAR_COMMON which the billboard plane perpendicular to the
631            common direction.
632        @note
633            BBT_PERPENDICULAR_SELF and BBT_PERPENDICULAR_COMMON can't guarantee counterclockwise, you might
634            use double-side material (<b>cull_hardware node</b>) to ensure no billboard are culled.
635        @param bbt The type of billboard to render
636        */
637        virtual void setBillboardType(BillboardType bbt);
638
639        /** Returns the billboard type in use. */
640        virtual BillboardType getBillboardType(void) const;
641
642        /** Use this to specify the common direction given to billboards of type BBT_ORIENTED_COMMON or BBT_PERPENDICULAR_COMMON.
643        @remarks
644            Use BBT_ORIENTED_COMMON when you want oriented billboards but you know they are always going to
645            be oriented the same way (e.g. rain in calm weather). It is faster for the system to calculate
646            the billboard vertices if they have a common direction.
647        @par
648            The common direction also use in BBT_PERPENDICULAR_COMMON, in this case the common direction
649            treat as Z axis, and an additional common up-vector was use to determine billboard X and Y
650            axis.
651            @see setCommonUpVector
652        @param vec The direction for all billboards.
653        @note
654            The direction are use as is, never normalised in internal, user are supposed to normalise it himself.
655        */
656        virtual void setCommonDirection(const Vector3& vec);
657
658        /** Gets the common direction for all billboards (BBT_ORIENTED_COMMON) */
659        virtual const Vector3& getCommonDirection(void) const;
660
661        /** Use this to specify the common up-vector given to billboards of type BBT_PERPENDICULAR_SELF or BBT_PERPENDICULAR_COMMON.
662        @remarks
663            Use BBT_PERPENDICULAR_SELF or BBT_PERPENDICULAR_COMMON when you want oriented billboards
664            perpendicular to specify direction vector (or, Z axis), and doesn't face to camera.
665            In this case, we need an additional up-vector to determine the billboard X and Y axis.
666            The generated billboard plane and X-axis guarantee perpendicular to specify direction.
667            @see setCommonDirection
668        @par
669            The specify direction is billboard own direction when billboard type is BBT_PERPENDICULAR_SELF,
670            and it's shared common direction when billboard type is BBT_PERPENDICULAR_COMMON.
671        @param vec The up-vector for all billboards.
672        @note
673            The up-vector are use as is, never normalised in internal, user are supposed to normalise it himself.
674        */
675        virtual void setCommonUpVector(const Vector3& vec);
676
677        /** Gets the common up-vector for all billboards (BBT_PERPENDICULAR_SELF and BBT_PERPENDICULAR_COMMON) */
678        virtual const Vector3& getCommonUpVector(void) const;
679       
680        /** Sets whether or not billboards should use an 'accurate' facing model
681            based on the vector from each billboard to the camera, rather than
682            an optimised version using just the camera direction.
683        @remarks
684            By default, the axes for all billboards are calulated using the
685            camera's view direction, not the vector from the camera position to
686            the billboard. The former is faster, and most of the time the difference
687            is not noticeable. However for some purposes (e.g. very large, static
688            billboards) the changing billboard orientation when rotating the camera
689            can be off putting, therefore you can enable this option to use a
690            more expensive, but more accurate version.
691        @param acc True to use the slower but more accurate model. Default is false.
692        */
693        virtual void setUseAccurateFacing(bool acc) { mAccurateFacing = acc; }
694        /** Gets whether or not billboards use an 'accurate' facing model
695            based on the vector from each billboard to the camera, rather than
696            an optimised version using just the camera direction.
697        */
698        virtual bool getUseAccurateFacing(void) const { return mAccurateFacing; }
699
700        /** Overridden from MovableObject */
701        virtual const String& getMovableType(void) const;
702
703        /** Overridden, see Renderable */
704        Real getSquaredViewDepth(const Camera* cam) const;
705
706        /** Update the bounds of the billboardset */
707        virtual void _updateBounds(void);
708        /** @copydoc Renderable::getLights */
709        const LightList& getLights(void) const;
710
711        /** Sort the billboard set. Only called when enabled via setSortingEnabled */
712                virtual void _sortBillboards( Camera* cam);
713
714        /** Gets the sort mode of this billboard set */
715        virtual SortMode _getSortMode(void) const;
716
717        /** Sets whether billboards should be treated as being in world space.
718        @remarks
719            This is most useful when you are driving the billboard set from
720            an external data source.
721        */
722        virtual void setBillboardsInWorldSpace(bool ws) { mWorldSpace = ws; }
723
724        /** BillboardSet can use custom texture coordinates for various billboards.
725            This is useful for selecting one of many particle images out of a tiled
726            texture sheet, or doing flipbook animation within a single texture.
727          @par
728            The generic functionality is setTextureCoords(), which will copy the
729            texture coordinate rects you supply into internal storage for the
730            billboard set. If your texture sheet is a square grid, you can also
731            use setTextureStacksAndSlices() for more convenience, which will construct
732            the set of texture coordinates for you.
733          @par
734            When a Billboard is created, it can be assigned a texture coordinate
735            set from within the sets you specify (that set can also be re-specified
736            later). When drawn, the billboard will use those texture coordinates,
737            rather than the full 0-1 range.
738          @par
739          @param coords is a vector of texture coordinates (in UV space) to choose
740            from for each billboard created in the set.
741          @param numCoords is how many such coordinate rectangles there are to
742            choose from.
743          @remarks
744            Set 'coords' to 0 and/or 'numCoords' to 0 to reset the texture coord
745            rects to the initial set of a single rectangle spanning 0 through 1 in
746            both U and V (i e, the entire texture).
747          @see
748            BillboardSet::setTextureStacksAndSlices()
749            Billboard::setTexcoordIndex()
750          */
751        virtual void setTextureCoords( Ogre::FloatRect const * coords, uint16 numCoords );
752
753        /** setTextureStacksAndSlices() will generate texture coordinate rects as if the
754            texture for the billboard set contained 'stacks' rows of 'slices'
755            images each, all equal size. Thus, if the texture size is 512x512
756            and 'stacks' is 4 and 'slices' is 8, each sub-rectangle of the texture
757            would be 128 texels tall and 64 texels wide.
758          @remarks
759            This function is short-hand for creating a regular set and calling
760            setTextureCoords() yourself. The numbering used for Billboard::setTexcoordIndex()
761            counts first across, then down, so top-left is 0, the one to the right
762            of that is 1, and the lower-right is stacks*slices-1.
763          @see
764            BillboardSet::setTextureCoords()
765          */
766        virtual void setTextureStacksAndSlices( uchar stacks, uchar slices );
767
768        /** getTextureCoords() returns the current texture coordinate rects in
769            effect. By default, there is only one texture coordinate rect in the
770            set, spanning the entire texture from 0 through 1 in each direction.
771          @see
772            BillboardSet::setTextureCoords()
773          */
774        virtual Ogre::FloatRect const * getTextureCoords( uint16 * oNumCoords );
775
776                /** Set whether or not the BillboardSet will use point rendering
777                        rather than manually generated quads.
778                @remarks
779                        By default a billboardset is rendered by generating geometry for a
780                        textured quad in memory, taking into account the size and
781                        orientation settings, and uploading it to the video card.
782                        The alternative is to use hardware point rendering, which means that
783                        only one position needs to be sent per billboard rather than 4 and
784                        the hardware sorts out how this is rendered based on the render
785                        state.
786                @par
787                        Using point rendering is faster than generating quads manually, but
788                        is more restrictive. The following restrictions apply:
789                        \li Only the BBT_POINT type is supported
790                        \li Size and appearance of each billboard is controlled by the
791                                material (Pass::setPointSize, Pass::setPointSizeAttenuation,
792                                Pass::setPointSpritesEnabled)
793                        \li Per-billboard size is not supported (stems from the above)
794                        \li Per-billboard rotation is not supported, this can only be
795                                controlled through texture unit rotation
796                        \li Only BBO_CENTER origin is supported
797                        \li Per-billboard texture coordinates are not supported
798
799                @par
800                        You will almost certainly want to enable in your material pass
801                        both point attenuation and point sprites if you use this option.
802                @param enabled True to enable point rendering, false otherwise
803                */
804                virtual void setPointRenderingEnabled(bool enabled);
805
806                /** Returns whether point rendering is enabled. */
807                virtual bool isPointRenderingEnabled(void) const
808                { return mPointRendering; }
809               
810                /// Override to return specific type flag
811                uint32 getTypeFlags(void) const;
812
813    };
814
815        /** Factory object for creating BillboardSet instances */
816        class _OgreExport BillboardSetFactory : public MovableObjectFactory
817        {
818        protected:
819                MovableObject* createInstanceImpl( const String& name, const NameValuePairList* params);
820        public:
821                BillboardSetFactory() {}
822                ~BillboardSetFactory() {}
823
824                static String FACTORY_TYPE_NAME;
825
826                const String& getType(void) const;
827                void destroyInstance( MovableObject* obj); 
828
829        };
830
831
832}
833
834
835#endif
Note: See TracBrowser for help on using the repository browser.