GL Studio C++ Runtime API
component_base.h
Go to the documentation of this file.
1 /*! \file
2  \brief The disti::ComponentBase class.
3 
4  \par Copyright Information
5 
6  Copyright (c) 2017 by The DiSTI Corporation.<br>
7  11301 Corporate Blvd; Suite 100<br>
8  Orlando, Florida 32817<br>
9  USA<br>
10  <br>
11  All rights reserved.<br>
12 
13  This Software contains proprietary trade secrets of DiSTI and may not be
14 reproduced, in whole or part, in any form, or by any means of electronic,
15 mechanical, or otherwise, without the written permission of DiSTI. Said
16 permission may be derived through the purchase of applicable DiSTI product
17 licenses which detail the distribution rights of this content and any
18 Derivative Works based on this or other copyrighted DiSTI Software.
19 
20  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21 AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22 PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23 AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24 IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25 PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26 
27  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28 IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29 INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30 DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31 INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32 INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33 OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34 EXCEED FIVE DOLLARS (US$5.00).
35 
36  The aforementioned terms and restrictions are governed by the laws of the
37 State of Florida and the United States of America.
38 
39 */
40 #ifndef _COMPONENT_BASE_H
41 #define _COMPONENT_BASE_H
42 
43 #include "display_frame.h"
44 #include "gls_include.h"
45 #include "gls_version.h"
46 #include "group.h"
47 
48 namespace disti
49 {
50 class LiveComponentAccessor;
51 
52 /** Sets the default value for absolute placent. If not set, the default will be true.
53  * Typically only used for backwards compatibility with previous versions of GL Studio
54  * \param value true if the absolute placement default should be true, false otherwise.
55  */
56 GLS_EXPORT void SetAbsolutePlacementDefault( bool value );
57 
58 /** Gets the default value for absolute placent.
59  */
60 GLS_EXPORT bool GetAbsolutePlacementDefault();
61 
62 /** The ComponentBase class is derived from Group and DisplayFrame.
63  It is capable of containing objects as well as drawing them.
64  It is used for encapsulating object geometry and behavior.
65  The behavior is defined when this object is derived.
66  */
67 class ComponentBase : public Group
68  , public DisplayFrame
69 {
70 public:
71  DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
72  typedef Group _BaseClass;
73  typedef Group BaseClass;
74  friend class disti::LiveComponentAccessor;
75 
76  /** Constructor
77  * \param generateInstance If true generates a new unique instance name
78  */
79  GLS_EXPORT ComponentBase( int generateInstance = FALSE );
80 
81  /** Cleans up the object and destructs it.
82  * Don't call "delete yourComponent", instead call yourComponent->Destroy().
83  * If this is an RSO, it will be completely destroyed, including the DLL.
84  */
85  virtual GLS_EXPORT ~ComponentBase();
86 
87  /** Create RSO static
88  * This will load the specified DLL and try to create the specified class.
89  * It will return the ComponentBase* on success, and NULL on failure.
90  * Internally, this uses a LiveComponentAccessor. If more control is needed,
91  * it is recommended to create a LiveComponentAccessor.
92  * \param fileName The name of the DLL
93  * \param className The class name to create. If NULL, the default class will be created.
94  * \param performCreate If true, CreateObjects() will be called, otherwise it will not.
95  * \param callingVersion
96  * \return NULL on failure.*/
97  static GLS_EXPORT ComponentBase* CreateLiveComponent( const char* fileName = NULL, const char* className = NULL, bool performCreate = true, const GlsBuiltVersionInfo& callingVersion = GlsBuiltVersionInfo() );
98 
99  /** Returns true if version checks ok, false if there MIGHT be a problem.
100  * The consequences of version mismatches depend on the methods that will be
101  * called on the object. This will emit warnings to stdout.
102  * \param comp RSO
103  * \param callingVersion Leave this as the default and it will use the calling function's version information.
104  * \return true If version is considered OK.
105  */
106  static GLS_EXPORT bool CheckLiveVersion( ComponentBase* comp, const GlsBuiltVersionInfo& callingVersion = GlsBuiltVersionInfo() );
107 
108  /** Creates a new component of the templated type
109  */
110  template<class T>
111  static T* CreateComponent( DisplayObject::AvailableAttributesEnum availableAttributes = DisplayObject::GLS_ATTRIBUTES_ALL )
112  {
113  T* comp = new T();
114  comp->SetAvailableAttributes( availableAttributes );
115  comp->CreateObjects();
116  return comp;
117  }
118 
119  virtual GLS_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
120 
121  /** Gets the value for Absolute Placement.
122  * If true, the component will be left in the generated location. Otherwise it will be moved
123  * based on its extents
124  */
125  bool AbsolutePlacement() const { return _absolutePlacement; }
126 
127  virtual GLS_EXPORT void ChangedAbsolutePlacement( bool val );
128 
129  /** Sets the value for Absolute Placement. This affects what happens
130  * durring the call to CreateObjects().
131  * If true, the component will be left in the generated location. Otherwise it will be moved
132  * based on its extents
133  */
134  virtual GLS_EXPORT void AbsolutePlacement( bool val );
135 
136  /* See base class */
137  virtual GLS_EXPORT void CalculateBoundingBox( void ) DISTI_METHOD_OVERRIDE;
138 
139  /** Call this before deleting objects which may be being kept
140  * by the drag or focus objects. */
141  virtual GLS_EXPORT void ClearDragAndFocus() DISTI_METHOD_OVERRIDE;
142 
143  /* See base class */
144  virtual GLS_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
145 
146  /* Copies the geometry information from one object to another.
147  * In a ComponentBase, this does nothing.
148  * \param src The object to copy geometry from.
149  */
150  virtual GLS_EXPORT void CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
151 
152  /* See base class */
153  virtual GLS_EXPORT void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
154 
155 #ifndef GLES
156  /* See base class */
157  virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
158 
159  /* See base class */
160  virtual GLS_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
161 #endif
162 
163  /** In derived classes this creates all the geometry for the component */
164  virtual GLS_EXPORT void CreateObjects();
165 
166  /** Overriden to avoid children getting deleted until object deletion. */
167  virtual GLS_EXPORT void DeleteAllChildren() DISTI_METHOD_OVERRIDE;
168 
169  /** Draws this object and all its contained objects in the current OpenGL pipeline.
170  This can be overloaded to perform any special effects.
171  If PreDraw and Draw are needed, call DisplayFrame::Draw() */
172  virtual GLS_EXPORT void Draw() DISTI_METHOD_OVERRIDE;
173 
174  /** Finds a pointer to the display object in the group, using the object's
175  * instance name as a key.
176  * Because this is a component, it will always return NULL.
177  * \param name Instance name of the object to find
178  * \return A pointer to the object if it is in the group, otherwise NULL
179  */
180  virtual GLS_EXPORT DisplayObject* FindByNameSameFrame( const char* name ) DISTI_METHOD_OVERRIDE;
181 
182  /* Figure out the min and max x&y extents for the object.
183  * Modify results by _scale
184  * \param x Gets the minimum x extent
185  * \param y Gets the minimum y extent
186  * \param z Gets the minimum z extent
187  * \param x1 Gets the maximum x extent
188  * \param y1 Gets the maximum y extent
189  * \param z1 Gets the maximum z extent
190  */
191  virtual GLS_EXPORT void GetExtents( float& x, float& y, float& z, float& x1, float& y1, float& z1 ) DISTI_METHOD_OVERRIDE;
192 
193  /** Determines the extents of geometry projected to the XY plane of an arbirary coordinate system.
194  * \param min Returns the minimum values found in the traversal
195  * \param max Returns the maximum values found in the traversal
196  * \param matrix Transformation matrix from world coordinates to the desired coordinate system.
197  * \param resetMinMax Normally not specified by user. Should be true for the initial call.
198  */
199  virtual GLS_EXPORT void GetTransformedExtents( Vector& min, Vector& max, const GlsMatrixType& matrix, bool resetMinMax = true ) DISTI_METHOD_OVERRIDE;
200 
201  /** Handles input events.
202  * It traverses the hierarchy with Pick3D.
203  * Then THE picked object is given the handle() call.
204  * \param ev The event data.
205  * \returns The object that handled the input.
206  */
207  virtual GLS_EXPORT DisplayObject* HandleInput( DisplayEvent* ev );
208 
209  /** Peforms post creation tasks including reparenting all objects.
210  * and adjusting their position.
211  * It checks the value of _absolutePlacement to determine if movement of the
212  * generated objects is necessary
213  * /see AbsolutePlacement
214  */
215  virtual GLS_EXPORT void Init();
216 
217  /** The GL Studio code generator allways derives a new Initialize method for the user
218  This is called after all the objects are created.
219  */
220  virtual GLS_EXPORT void Initialize();
221 
222  /** If this component was loaded from an RSO library,
223  * this method returns the object's library reference.
224  * The library reference should be deleted AFTER the component is deleted.
225  * If the component was not loaded from an RSO library,
226  * this method returns NULL.
227  */
229 
230  using Group::Location;
231  virtual GLS_EXPORT const Vertex& Location( void ) const DISTI_METHOD_OVERRIDE { return Group::Location(); }
232 
233  /* See base class */
234  virtual GLS_EXPORT void Location( const Vertex& v ) DISTI_METHOD_OVERRIDE;
235 
236  /* See base class */
237  virtual GLS_EXPORT void Location( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
238 
239  /* Unhides base class implementation. */
240  // force inheritance
241  using Group::Parent;
242 
243  /** Sets the DisplayFrame for this object.
244  * It does not set the specified parent for all the children.
245  * Instead, it sets all the children's parent to 'this'. And
246  * saves the argument 'par' in _parentDisplayFrame. This
247  * allows special traversals, which traverse out of the ComponentBase
248  * to the ComponentBase's parent.
249  * \param par The parent which will be saved in _parentDisplayFrame
250  * \see ParentDisplayFrame
251  */
252  virtual GLS_EXPORT void Parent( DisplayFrame* par ) DISTI_METHOD_OVERRIDE;
253 
254  /** Gets the value of the DisplayFrame containing this component
255  * \return the value of the DisplayFrame containing this component.
256  * Returns NULL if there is no parent DisplayFrame
257  */
259 
260  /** Sets the parent DisplayFrame for this object. This is normally only set by a
261  * call to Parent().
262  * \param val The new val for _parentDisplayFrame
263  * \see ComponentBase::Parent()
264  */
265  inline void ParentDisplayFrame( DisplayFrame* val ) { _parentDisplayFrame = val; }
266 
267  /* See base class */
268  virtual GLS_EXPORT DisplayObject* Pick3D( const Vector& winLoc,
269  const Vector& logicalCoords,
270  float scale,
271  const Vector& directionVector,
272  Vector& collisionWinLoc /*Returned*/,
273  const OpenGLMatrices& drawnMatrices ) DISTI_METHOD_OVERRIDE;
274 
275  /* See base class */
276  virtual GLS_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler ) DISTI_METHOD_OVERRIDE;
277 
278  /* See base class */
279  virtual GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL ) DISTI_METHOD_OVERRIDE;
280 
281  /* See base class */
282  virtual GLS_EXPORT DistiAttributeBase& Resource( const char* name ) DISTI_METHOD_OVERRIDE;
283 
284  /* Unhides base class implementation. */
285  using Group::Rotate;
286  using Group::Scale;
287 
288  /* See base class */
289  virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;
290 
291  /* See base class */
292  virtual GLS_EXPORT void Scale( float px, float py, float pz, Vertex* parentAnchor, int handleBar = 0 ) DISTI_METHOD_OVERRIDE;
293 
294  /** This will call our parent display frame's SetRedraw() causing
295  this component to be redrawn in the future.
296  */
297  virtual GLS_EXPORT void SetRedraw( void ) DISTI_METHOD_OVERRIDE;
298 
299  /* See base class */
300  virtual GLS_EXPORT void Translate( float tr[] ) DISTI_METHOD_OVERRIDE;
301 
302  /* See base class */
303  virtual GLS_EXPORT void Translate( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
304 
305  /** If UseParentsLighting is true, the component will add
306  * it's lights to those already set by it's parent.
307  * If false, the component will only use it's own lights.
308  */
309  virtual GLS_EXPORT void UseParentsLighting( const bool& );
310 
311  /** If UseParentsLighting is true, the component will add
312  * it's lights to those already set by it's parent.
313  * If false, the component will only use it's own lights.
314  */
315  virtual GLS_EXPORT bool UseParentsLighting();
316 
317  /** Overridden so we will always get -1 for our texture index.
318  * This keeps our children from trying to draw with our texture
319  * index which would be for the wrong palette.
320  */
321  virtual GLS_EXPORT int TextureIndex() DISTI_METHOD_OVERRIDE;
322  virtual GLS_EXPORT void TextureIndex( int index ) DISTI_METHOD_OVERRIDE
323  {
324  BaseClass::TextureIndex( index );
325  }
326 
327  /* See base class */
328  GLS_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
329 
330  /** \see DisplayFrame
331  * Returns the parents input handler if a parent exists, else returns this component's input handler
332  */
333  virtual GLS_EXPORT InputHandler* GetInputHandler() DISTI_METHOD_OVERRIDE;
334 
335  /** overrides DisplayObject::NotifyAttributeChanged */
336  GLS_EXPORT void NotifyAttributeChanged( const AttributeName& name ) DISTI_METHOD_OVERRIDE;
337 
338 protected:
339  LiveComponentAccessor* _liveAccessor; /**< /see ComponentBase::LiveAccessor */
340  bool _absolutePlacement; /**< /see ComponentBase::AbsolutePlacement */
341  Vertex _absolutePlacementDelta; /** The delta vector used when using relative placemnt */
342  DisplayFrame* _parentDisplayFrame; /**< /see ComponentBase::ParentDisplayFrame */
343  GlsMatrixType _editorTransformMatrix; /**< The static transformation from the internal component coordinates to the parent's coordinate system */
344 
345  /** Overridden from base class
346  * This adds the _editorTransformMatrix to the DCS. You will need to call CalcDrawMatrix whenever the _editorTransformMatrix changes.*/
347  virtual GLS_EXPORT void CalcDrawMatrix() DISTI_METHOD_OVERRIDE;
348 
349  /* Overridden from base class */
350  virtual GLS_EXPORT void CalculateMatrices( const OpenGLMatrices& newMatrices ) DISTI_METHOD_OVERRIDE;
351  GLS_EXPORT void EditorTransformMatrix( const GlsMatrixType& matrix );
352  GLS_EXPORT const GlsMatrixType& EditorTransformMatrix() const;
353 
354 #ifdef GLES
355  /** Set a single attribute from the GLO file.
356  * \param data The attribute to set and its associated data.
357  */
358  virtual GLS_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
359 #endif
360 
361 private:
362  DisplayObject* PickFirst( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
363  DisplayObject* PickBest( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
364 };
365 
366 typedef ComponentBase* ( *ComponentBaseCreateFunc )();
367 /** Returns the directory of the .dll or .so that calls this function. */
368 #ifdef WIN32
369 GLS_EXPORT std::string GetComponentDirectory( HINSTANCE module );
370 #else
371 GLS_EXPORT std::string GetComponentDirectory( void* module );
372 #endif
373 } // namespace disti
374 
375 #endif
Definition: cull.h:49
Definition: display_frame.h:85
virtual void CopyProperties(DisplayObject *src) override
virtual void GetResources(std::ostream &outstr, GlsResourceFilter *filter=NULL) override
virtual DisplayObject * Pick3D(const Vector &winLoc, const Vector &logicalCoords, float scale, const Vector &directionVector, Vector &collisionWinLoc, const OpenGLMatrices &drawnMatrices) override
std::string GetComponentDirectory(void *module)
virtual void SetAvailableAttributes(unsigned int value) override
virtual const Vertex & Location(void) const
Definition: vertex.h:409
#define DISTI_DEPRECATED(msg)
Defines whether this compiler supports the C++14 deprecated attribute.
Definition: gls_cpp_lang_support.h:436
virtual void Draw() override
Definition: dynamic_array.h:66
The disti::Group class. Implements groups of objects.
Class to contain current OpenGL view, projection and draw matrices.
Definition: util.h:471
ComponentBase(int generateInstance=0)
virtual void GetTransformedExtents(Vector &min, Vector &max, const GlsMatrixType &matrix, bool resetMinMax=true) override
DisplayFrame * Parent(void) const
Definition: display.h:932
virtual DisplayObject * CloneObject(bool generateNames=false) override
Definition: display.h:98
virtual InputHandler * GetInputHandler() override
GlsMatrixType _editorTransformMatrix
Definition: component_base.h:343
virtual void CalculateMatrices(const OpenGLMatrices &newMatrices) override
LiveComponentAccessor * LiveAccessor()
Definition: component_base.h:228
void SetAbsolutePlacementDefault(bool value)
LiveComponentAccessor * _liveAccessor
Definition: component_base.h:339
A file for all GL Studio files to include.
Definition: gls_glo_file.h:988
Used for matching version of libraries and headers.
bool GetAbsolutePlacementDefault()
virtual void Init()
static ComponentBase * CreateLiveComponent(const char *fileName=NULL, const char *className=NULL, bool performCreate=true, const GlsBuiltVersionInfo &callingVersion=GlsBuiltVersionInfo())
virtual void GetCppInterfaceDescriptionFree(InterfaceListType *array) override
virtual DisplayObject * FindByNameSameFrame(const char *name) override
virtual void SetRedraw(void) override
virtual void Translate(float tr[]) override
Definition: component_base.h:67
virtual void DeleteAllChildren() override
virtual ~ComponentBase()
virtual DisplayObject * HandleInput(DisplayEvent *ev)
virtual void PreDraw(const OpenGLMatrices &current, Culler &culler) override
void ParentDisplayFrame(DisplayFrame *val)
Definition: component_base.h:265
virtual void CalcDrawMatrix() override
virtual int TextureIndex(void)
DisplayFrame * _parentDisplayFrame
Definition: component_base.h:342
void NotifyAttributeChanged(const AttributeName &name) override
virtual const Vertex & Location(void) const override
Definition: component_base.h:231
void SetValue(int spec, va_list &args) override
static bool CheckLiveVersion(ComponentBase *comp, const GlsBuiltVersionInfo &callingVersion=GlsBuiltVersionInfo())
Definition: input_handler.h:177
bool _absolutePlacement
Definition: component_base.h:340
Definition: disti_metadata.h:186
Definition: events.h:112
virtual int TextureIndex() override
virtual void Initialize()
Definition: gls_version.h:208
The disti::DisplayFrame class.
virtual void GetExtents(float &x, float &y, float &z, float &x1, float &y1, float &z1) override
virtual InterfaceListType * GetCppInterfaceDescription(InterfaceListType *addToThisList=NULL) override
Definition: group.h:52
virtual float Scale(void)
Definition: display_frame.h:135
virtual void Rotate(const Vector &orig, float angle, const Vector &axis) override
Definition: vertex.h:84
Definition: live_component_accessor.h:54
static T * CreateComponent(DisplayObject::AvailableAttributesEnum availableAttributes=DisplayObject::GLS_ATTRIBUTES_ALL)
Definition: component_base.h:111
virtual void CopyGeometry(DisplayObject *src) override
Definition: gls_resources.h:50
DisplayFrame * ParentDisplayFrame() const
Definition: component_base.h:258
bool AbsolutePlacement() const
Definition: component_base.h:125
AvailableAttributesEnum
Definition: display.h:131
Definition: disti_metadata.h:85
virtual bool UseParentsLighting()
Definition: bmpimage.h:46
virtual DistiAttributeBase & Resource(const char *name) override
virtual void ClearDragAndFocus() override
virtual void CreateObjects()