MezzanineEngine 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
billboardsetproxy.h
Go to the documentation of this file.
1 // © Copyright 2010 - 2014 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 #ifndef _graphicsbillboardsetproxy_h
41 #define _graphicsbillboardsetproxy_h
42 
43 /// @file
44 /// @brief This file contains the declaration for the World proxy wrapping billboard functionality.
45 
47 #include "Graphics/graphicsenumerations.h"
48 #include "colourvalue.h"
49 
50 namespace Ogre
51 {
52  class BillboardSet;
53 }
54 
55 namespace Mezzanine
56 {
57  namespace Graphics
58  {
59  class Billboard;
60  ///////////////////////////////////////////////////////////////////////////////
61  /// @brief This is the proxy class for placing and manipulating a set of 2D billboards in the scene.
62  /// @details
63  ///////////////////////////////////////
65  {
66  public:
67  /// @brief Basic container type for Billboard storage by this class.
68  typedef std::list<Billboard*> BillboardContainer;
69  /// @brief Iterator type for Billboard instances stored by this class.
70  typedef BillboardContainer::iterator BillboardIterator;
71  /// @brief Const Iterator type for Billboard instances stored by this class.
72  typedef BillboardContainer::const_iterator ConstBillboardIterator;
73  protected:
74  /// @internal
75  /// @brief Container storing all of the Billboard instances created by this manager.
77  /// @internal
78  /// @brief A pointer to the internal BillboardSet this proxy is based on.
79  Ogre::BillboardSet* GraphicsBillboardSet;
80 
81  /// @internal
82  /// @param InitialPoolSize The number of billboards to reserve space for.
83  /// @brief Creates an internal BillboardSet to be used by the calling instance.
84  virtual void CreateBillboardSet(const UInt32 InitialPoolSize);
85  /// @internal
86  /// @brief Destroys the internal BillboardSet in use by this proxy.
87  virtual void DestroyBillboardSet();
88  public:
89  /// @brief Class constructor.
90  /// @param InitialPoolSize The number of billboards to reserve space for.
91  /// @param Creator A pointer to the manager that created this proxy.
92  BillboardSetProxy(const UInt32 InitialPoolSize, SceneManager* Creator);
93  /// @brief XML constructor.
94  /// @param SelfRoot An XML::Node containing the data to populate this class with.
95  /// @param Creator A pointer to the manager that created this proxy.
96  BillboardSetProxy(const XML::Node& SelfRoot, SceneManager* Creator);
97  /// @brief Class destructor.
98  virtual ~BillboardSetProxy();
99 
100  ///////////////////////////////////////////////////////////////////////////////
101  // Utility
102 
103  /// @copydoc WorldProxy::GetProxyType() const
104  virtual Mezzanine::ProxyType GetProxyType() const;
105 
106  ///////////////////////////////////////////////////////////////////////////////
107  // Billboard Management
108 
109  /// @brief Creates a new Billboard for this set.
110  /// @note In most situations you will want the colour to stay white. The material will still render normally without modification if it is left white.
111  /// @param Location The position relative to the center of the set where this billboard will be placed.
112  /// @param Colour The base colour to give to the created billboard.
113  /// @return Returns a pointer to the created billboard, or NULL if this set has reached it's max billboards and autoextend is disabled.
114  virtual Billboard* CreateBillboard(const Vector3& Location, const ColourValue& Colour = ColourValue::White());
115  /// @brief Gets a Billboard instance by index.
116  /// @param Index The index of the Billboard to be retrieved.
117  /// @return Returns a pointer to the Billboard at the specified index.
118  virtual Billboard* GetBillboard(UInt32 Index);
119  /// @brief Gets the number of Billboard instances in this set.
120  /// @return Returns a UInt32 representing the number of Billboard instances contained in this set.
121  virtual UInt32 GetNumBillboards() const;
122  /// @brief Deletes a Billboard.
123  /// @param ToBeDestroyed A pointer to the Billboard you want deleted.
124  virtual void DestroyBillboard(Billboard* ToBeDestroyed);
125  /// @brief Deletes all stored Billboard instances.
126  virtual void DestroyAllBillboards();
127 
128  ///////////////////////////////////////////////////////////////////////////////
129  // BillboardSet Properties
130 
131  /// @brief Sets whether or not this BillboardSetProxy will increase the size of it's billboard pool automatically when it's limit is reached.
132  /// @param AutoExtend A bool indicating whether or not this proxy is allowed to resize it's own billboard pool.
133  virtual void SetAutoExtend(const Boolean AutoExtend);
134  /// @brief Gets whether or not this BillboardSetProxy will increase the size of it's billboard pool automatically when it's limit is reached.
135  /// @return Returns true if the billboard pool will automatically be resized when it reaches it's limit, false otherwise.
136  virtual Boolean GetAutoExtend() const;
137  /// @brief Sets whether direction vectors will be calculated using a more expensive but more accurate algorithm.
138  /// @param AccFace True to increase accuracy of billboard directions, false for the more efficient method.
139  virtual void SetAccurateFacing(const Boolean AccFace);
140  /// @brief Gets whether direction vectors are being calculated using a more expensive but more accurate algorithm.
141  /// @return Returns true if this BillboardSetProxy is using the more accurate and more expensive method for directional vectors, false otherwise.
142  virtual Boolean GetAccurateFacing() const;
143  /// @brief Sets a new size of the billboard pool in this set.
144  /// @param Size The size the billboard pool in this set should be resized to.
145  virtual void SetPoolSize(const UInt32 Size);
146  /// @brief Gets the current size of the billboard pool in this set.
147  /// @return Returns a UInt32 representing the current size of the billboard pool in this set.
148  virtual UInt32 GetPoolSize() const;
149 
150  /// @brief Sets the part of the billboard that will be treated as the origin for all children of this set.
151  /// @param Origin A BillboardOrigin enum value expressing which part of the billboard will be considered the origin for all billboards in this set.
152  virtual void SetBillboardOrigin(const Graphics::BillboardOrigin Origin);
153  /// @brief Gets the part of the billboard that is currently being treated as the origin for all children of this set.
154  /// @return Returns a BillboardOrigin enum value expressing which part of the billboard is being treated as the origin.
155  virtual Graphics::BillboardOrigin GetBillboardOrigin() const;
156  /// @brief Sets the type of rotation to apply when a rotation is made to a billboard.
157  /// @param Rotation A BillboardRotation enum value expressing the underlying method for rotation in billboards belonging to this set.
158  virtual void SetBillboardRotation(const Graphics::BillboardRotation Rotation);
159  /// @brief Gets the type of rotation to apply when a rotation is made to a billboard.
160  /// @return Returns a BillboardRotation enum value expressing how billboards in this set are to be rotated.
161  virtual Graphics::BillboardRotation GetBillboardRotation() const;
162  /// @brief Sets the type of BillboardSetProxy this is.
163  /// @param Type A BillboardType enum value expressing how billboards in this set are to be oriented.
164  virtual void SetBillboardType(const Graphics::BillboardType Type);
165  /// @brief Gets the type of BillboardSetProxy this is.
166  /// @return Returns a BillboardType enum value expressing how billboards in this set are being oriented.
167  virtual Graphics::BillboardType GetBillboardType() const;
168 
169  /// @brief Sets the default width and height all billboards in this set are to be configured with when constructed.
170  /// @param Width The default width in world units.
171  /// @param Height The default height in world units.
172  virtual void SetDefaultDimensions(const Real Width, const Real Height);
173  /// @brief Sets the default width all billboards in this set are to be configured with when constructed.
174  /// @param Width The default width in world units.
175  virtual void SetDefaultWidth(const Real Width);
176  /// @brief Gets the default width all billboards in this set are constructed with.
177  /// @return Returns a Real representing the default width of all billboards in this set in world units.
178  virtual Real GetDefaultWidth() const;
179  /// @brief Sets the default height all billboards in this set are to be configured with when constructed.
180  /// @param Height The default height in world units.
181  virtual void SetDefaultHeight(const Real Height);
182  /// @brief Gets the default height all billboards in this set are constructed with.
183  /// @return Returns a Real representing the default height of all billboards in this set in world units.
184  virtual Real GetDefaultHeight() const;
185 
186  /// @brief Sets the common facing direction for all billboards in this set.
187  /// @remarks This only needs to be set if this billboard type is set to "BBT_Oriented_Common" or "BBT_Perpendicular_Common".
188  /// @param Dir The facing axis for all billboards in this set.
189  virtual void SetCommonDirection(const Vector3& Dir);
190  /// @brief Gets the common facing direction for all billboards in this set.
191  /// @return Returns a Vector3 representing the forward axis of billboards in this set.
192  virtual Vector3 GetCommonDirection() const;
193  /// @brief Sets the common up direction for all billboards in this set.
194  /// @remarks This only needs to be set if this billboard type is set to "BBT_Perpendicular_Common" or "BBT_Perpendicular_Self".
195  /// @param UpDir The up axis for all billboards in this set.
196  virtual void SetCommonUpVector(const Vector3& UpDir);
197  /// @brief Gets the common up direction for all billboards in this set.
198  /// @return Returns a Vector3 representing the up axis of billboards in this set.
199  virtual Vector3 GetCommonUpVector() const;
200 
201  /// @brief Sets a material for this set by name.
202  /// @todo These by-name methods should be removed when we have a working material wrapper.
203  /// @param MatName The name of the material to apply.
204  virtual void SetMaterialName(const String& MatName);
205  /// @brief Gets the name of the material being used by this set.
206  /// @todo These by-name methods should be removed when we have a working material wrapper.
207  /// @return Returns a string containing the name of the material being used to render this BillboardSetProxy.
208  virtual String GetMaterialName() const;
209 
210  ///////////////////////////////////////////////////////////////////////////////
211  // Serialization
212 
213  /// @copydoc WorldProxy::ProtoSerialize(XML::Node&) const
214  virtual void ProtoSerialize(XML::Node& ParentNode) const;
215  /// @copydoc WorldProxy::ProtoSerializeProperties(XML::Node& SelfRoot) const
216  virtual void ProtoSerializeProperties(XML::Node& SelfRoot) const;
217  /// @brief Convert the Billboards of this class to an XML::Node ready for serialization.
218  /// @param SelfRoot The root node containing all the serialized data for this instance.
219  virtual void ProtoSerializeBillboards(XML::Node& SelfRoot) const;
220 
221  /// @copydoc WorldProxy::ProtoDeSerialize(const XML::Node&)
222  virtual void ProtoDeSerialize(const XML::Node& SelfRoot);
223  /// @copydoc WorldProxy::ProtoDeSerializeProperties(const XML::Node& SelfRoot)
224  virtual void ProtoDeSerializeProperties(const XML::Node& SelfRoot);
225  /// @brief Take the data stored in an XML Node and overwrite the Billboards of this object with it.
226  /// @param SelfRoot An XML::Node containing the data to populate this class with.
227  virtual void ProtoDeSerializeBillboards(const XML::Node& SelfRoot);
228 
229  /// @copydoc WorldProxy::GetDerivedSerializableName() const
230  virtual String GetDerivedSerializableName() const;
231  /// @copydoc WorldProxy::GetSerializableName()
232  static String GetSerializableName();
233 
234  ///////////////////////////////////////////////////////////////////////////////
235  // Internal Methods
236 
237  /// @internal
238  /// @brief Accessor for the internal billboard set.
239  /// @return Returns a pointer to the internal billboard set this proxy is based on.
240  virtual Ogre::BillboardSet* _GetGraphicsObject() const;
241  /// @copydoc RenderableProxy::_GetBaseGraphicsObject() const
242  virtual Ogre::MovableObject* _GetBaseGraphicsObject() const;
243  };//BillboardSetProxy
244  }//Graphics
245 }//Mezzanine
246 
247 #endif