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

Revision 692, 9.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 (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 __Billboard_H__
27#define __Billboard_H__
28
29#include "OgrePrerequisites.h"
30
31#include "OgreVector3.h"
32#include "OgreColourValue.h"
33#include "OgreCommon.h"
34
35namespace Ogre {
36
37    /** A billboard is a primitive which always faces the camera in every frame.
38        @remarks
39            Billboards can be used for special effects or some other trickery which requires the
40            triangles to always facing the camera no matter where it is. Ogre groups billboards into
41            sets for efficiency, so you should never create a billboard on it's own (it's ok to have a
42            set of one if you need it).
43        @par
44            Billboards have their geometry generated every frame depending on where the camera is. It is most
45            beneficial for all billboards in a set to be identically sized since Ogre can take advantage of this and
46            save some calculations - useful when you have sets of hundreds of billboards as is possible with special
47            effects. You can deviate from this if you wish (example: a smoke effect would probably have smoke puffs
48            expanding as they rise, so each billboard will legitimately have it's own size) but be aware the extra
49            overhead this brings and try to avoid it if you can.
50        @par
51            Billboards are just the mechanism for rendering a range of effects such as particles. It is other classes
52            which use billboards to create their individual effects, so the methods here are quite generic.
53        @see
54            BillboardSet
55    */
56
57    class _OgreExport Billboard
58    {
59        friend class BillboardSet;
60        friend class BillboardParticleRenderer;
61    protected:
62        bool mOwnDimensions;
63        bool mUseTexcoordRect;
64        uint16 mTexcoordIndex;      // index into the BillboardSet array of texture coordinates
65        FloatRect mTexcoordRect;    // individual texture coordinates
66        Real mWidth;
67        Real mHeight;
68    public:
69        // Note the intentional public access to main internal variables used at runtime
70        // Forcing access via get/set would be too costly for 000's of billboards
71        Vector3 mPosition;
72        // Normalised direction vector
73        Vector3 mDirection;
74        BillboardSet* mParentSet;
75        ColourValue mColour;
76        Radian mRotation;
77
78        /** Default constructor.
79        */
80        Billboard();
81
82        /** Default destructor.
83        */
84        ~Billboard();
85
86        /** Normal constructor as called by BillboardSet.
87        */
88        Billboard(const Vector3& position, BillboardSet* owner, const ColourValue& colour = ColourValue::White);
89
90        /** Get the rotation of the billboard.
91            @remarks
92                This rotation is relative to the center of the billboard.
93        */
94        const Radian& getRotation(void) const { return mRotation; }
95
96        /** Set the rotation of the billboard.
97            @remarks
98                This rotation is relative to the center of the billboard.
99        */
100        void setRotation(const Radian& rotation);
101
102        /** Set the position of the billboard.
103            @remarks
104                This position is relative to a point on the quad which is the billboard. Depending on the BillboardSet,
105                this may be the center of the quad, the top-left etc. See BillboardSet::setBillboardOrigin for more info.
106        */
107        void setPosition(const Vector3& position);
108
109        /** Set the position of the billboard.
110            @remarks
111                This position is relative to a point on the quad which is the billboard. Depending on the BillboardSet,
112                this may be the center of the quad, the top-left etc. See BillboardSet::setBillboardOrigin for more info.
113        */
114        void setPosition(Real x, Real y, Real z);
115
116        /** Get the position of the billboard.
117            @remarks
118                This position is relative to a point on the quad which is the billboard. Depending on the BillboardSet,
119                this may be the center of the quad, the top-left etc. See BillboardSet::setBillboardOrigin for more info.
120        */
121        const Vector3& getPosition(void) const;
122
123        /** Sets the width and height for this billboard.
124            @remarks
125                Note that it is most efficient for every billboard in a BillboardSet to have the same dimensions. If you
126                choose to alter the dimensions of an individual billboard the set will be less efficient. Do not call
127                this method unless you really need to have different billboard dimensions within the same set. Otherwise
128                just call the BillboardSet::setDefaultDimensions method instead.
129        */
130        void setDimensions(Real width, Real height);
131
132        /** Resets this Billboard to use the parent BillboardSet's dimensions instead of it's own. */
133        void resetDimensions(void) { mOwnDimensions = false; }
134        /** Sets the colour of this billboard.
135            @remarks
136                Billboards can be tinted based on a base colour. This allows variations in colour irresective of the
137                base colour of the material allowing more varied billboards. The default colour is white.
138                The tinting is effected using vertex colours.
139        */
140        void setColour(const ColourValue& colour);
141
142        /** Gets the colour of this billboard.
143        */
144        const ColourValue& getColour(void) const;
145
146        /** Returns true if this billboard deviates from the BillboardSet's default dimensions (i.e. if the
147            Billboard::setDimensions method has been called for this instance).
148            @see
149                Billboard::setDimensions
150        */
151        bool hasOwnDimensions(void) const;
152
153        /** Retrieves the billboard's personal width, if hasOwnDimensions is true. */
154        Real getOwnWidth(void) const;
155
156        /** Retrieves the billboard's personal width, if hasOwnDimensions is true. */
157        Real getOwnHeight(void) const;
158
159        /** Internal method for notifying the billboard of it's owner.
160        */
161        void _notifyOwner(BillboardSet* owner);
162
163        /** Returns true if this billboard use individual texture coordinate rect (i.e. if the
164            Billboard::setTexcoordRect method has been called for this instance), or returns
165            false if use texture coordinates defined in the parent BillboardSet's texture
166            coordinates array (i.e. if the Billboard::setTexcoordIndex method has been called
167            for this instance).
168            @see
169                Billboard::setTexcoordIndex()
170                Billboard::setTexcoordRect()
171        */
172        bool isUseTexcoordRect(void) const { return mUseTexcoordRect; }
173
174        /** setTexcoordIndex() sets which texture coordinate rect this billboard will use
175            when rendering. The parent billboard set may contain more than one, in which
176            case a billboard can be textured with different pieces of a larger texture
177            sheet very efficiently.
178          @see
179            BillboardSet::setTextureCoords()
180          */
181        void setTexcoordIndex(uint16 texcoordIndex);
182
183        /** getTexcoordIndex() returns the previous value set by setTexcoordIndex().
184            The default value is 0, which is always a valid texture coordinate set.
185            @remarks
186                This value is useful only when isUseTexcoordRect return false.
187          */
188        uint16 getTexcoordIndex(void) const { return mTexcoordIndex; }
189
190        /** setTexcoordRect() sets the individual texture coordinate rect of this billboard
191            will use when rendering. The parent billboard set may contain more than one, in
192            which case a billboard can be textured with different pieces of a larger texture
193            sheet very efficiently.
194        */
195        void setTexcoordRect(const FloatRect& texcoordRect);
196
197        /** setTexcoordRect() sets the individual texture coordinate rect of this billboard
198            will use when rendering. The parent billboard set may contain more than one, in
199            which case a billboard can be textured with different pieces of a larger texture
200            sheet very efficiently.
201        */
202        void setTexcoordRect(Real u0, Real v0, Real u1, Real v1);
203
204        /** getTexcoordRect() returns the previous value set by setTexcoordRect().
205            @remarks
206                This value is useful only when isUseTexcoordRect return true.
207        */
208        const FloatRect& getTexcoordRect(void) const { return mTexcoordRect; }
209    };
210
211}
212
213#endif
Note: See TracBrowser for help on using the repository browser.