GL Studio C++ Runtime API
component_base.h
Go to the documentation of this file.
1/// \file component_base.h
2/// \brief The disti::ComponentBase class.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<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#ifndef INCLUDED_DISTI_COMPONENT_BASE_H
40#define INCLUDED_DISTI_COMPONENT_BASE_H
41
42#include "display_frame.h"
43#include "gls_include.h"
44#include "gls_version.h"
45#include "group.h"
46
47namespace disti
48{
49class LiveComponentAccessor;
50
51/** Sets the default value for absolute placement. If not set, the default will be true.
52 * Typically only used for backwards compatibility with previous versions of GL Studio
53 * \param value true if the absolute placement default should be true, false otherwise.
54 */
56
57/// \return The default value for absolute placement.
59
60/** The ComponentBase class is derived from Group and DisplayFrame.
61 It is capable of containing objects as well as drawing them.
62 It is used for encapsulating object geometry and behavior.
63 The behavior is defined when this object is derived.
64 */
65class ComponentBase : public Group
66 , public DisplayFrame
67{
68public:
69 DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
70 typedef Group _BaseClass; ///< Deprecated typedef for the base class.
71 typedef Group BaseClass; ///< Typedef for the base class.
72 friend class disti::LiveComponentAccessor;
73
74 /** Constructor
75 * \param generateInstance If true generates a new unique instance name
76 */
77 GLS_EXPORT ComponentBase( int generateInstance = FALSE );
78
79 /** Cleans up the object and destructs it.
80 * Don't call "delete yourComponent", instead call yourComponent->Destroy().
81 * If this is an RSO, it will be completely destroyed, including the DLL.
82 */
84
85 /** Create RSO static
86 * This will load the specified DLL and try to create the specified class.
87 * It will return the ComponentBase* on success, and NULL on failure.
88 * Internally, this uses a LiveComponentAccessor. If more control is needed,
89 * it is recommended to create a LiveComponentAccessor.
90 * \param fileName The name of the DLL
91 * \param className The class name to create. If NULL, the default class will be created.
92 * \param performCreate If true, CreateObjects() will be called, otherwise it will not.
93 * \param callingVersion
94 * \return NULL on failure.*/
95 static GLS_EXPORT ComponentBase* CreateLiveComponent( const char* fileName = NULL, const char* className = NULL, bool performCreate = true, const GlsBuiltVersionInfo& callingVersion = GlsBuiltVersionInfo() );
96
97 /** Returns true if version checks ok, false if there MIGHT be a problem.
98 * The consequences of version mismatches depend on the methods that will be
99 * called on the object. This will emit warnings to stdout.
100 * \param comp RSO
101 * \param callingVersion Leave this as the default and it will use the calling function's version information.
102 * \return true If version is considered OK.
103 */
104 static GLS_EXPORT bool CheckLiveVersion( ComponentBase* comp, const GlsBuiltVersionInfo& callingVersion = GlsBuiltVersionInfo() );
105
106 /// Creates a new component of the templated type
107 /// \param availableAttributes The value to call SetAvailableAttributes() with.
108 /// \return A pointer to the newly created component instance.
109 template<class T>
110 static T* CreateComponent( DisplayObject::AvailableAttributesEnum availableAttributes = DisplayObject::GLS_ATTRIBUTES_ALL )
111 {
112 T* comp = new T();
113 comp->SetAvailableAttributes( availableAttributes );
114 comp->CreateObjects();
115 return comp;
116 }
117
119
120 /// \return The value for Absolute Placement.
121 /// If true, the component will be left in the generated location.
122 /// Otherwise it will be moved based on its extents.
123 bool AbsolutePlacement() const { return _absolutePlacement; }
124
125 /// Sets the value for absolute placement.
126 /// \param val The new value for absolute placement.
127 /// \see AbsolutePlacement
128 virtual GLS_EXPORT void ChangedAbsolutePlacement( bool val );
129
130 /// Sets the value for Absolute Placement.
131 /// \param val If true, the component will be left in the generated location, otherwise it will be moved based on its extents.
132 virtual GLS_EXPORT void AbsolutePlacement( bool val );
133
135
136 /** Call this before deleting objects which may be being kept
137 * by the drag or focus objects. */
139
141
142 /* Copies the geometry information from one object to another.
143 * In a ComponentBase, this does nothing.
144 * \param src The object to copy geometry from.
145 */
147
149
150#ifndef GLES
151
154#endif
155
156 /** \deprecated Geometry creation for a generated component occurs in the component's constructor */
157 virtual GLS_EXPORT void CreateObjects();
158
159 /** Overriden to avoid children getting deleted until object deletion. */
161
162 /** Draws this object and all its contained objects in the current OpenGL pipeline.
163 This can be overloaded to perform any special effects.
164 If PreDraw and Draw are needed, call DisplayFrame::Draw() */
166
167 /** Finds a pointer to the display object in the group, using the object's
168 * instance name as a key.
169 * Because this is a component, it will always return NULL.
170 * \param name Instance name of the object to find
171 * \return A pointer to the object if it is in the group, otherwise NULL
172 */
174
175 /* Figure out the min and max x&y extents for the object.
176 * Modify results by _scale
177 * \param x Gets the minimum x extent
178 * \param y Gets the minimum y extent
179 * \param z Gets the minimum z extent
180 * \param x1 Gets the maximum x extent
181 * \param y1 Gets the maximum y extent
182 * \param z1 Gets the maximum z extent
183 */
184 GLS_EXPORT void GetExtents( float& x, float& y, float& z, float& x1, float& y1, float& z1 ) DISTI_METHOD_OVERRIDE;
185
186 /** Determines the extents of geometry projected to the XY plane of an arbirary coordinate system.
187 * \param min Returns the minimum values found in the traversal
188 * \param max Returns the maximum values found in the traversal
189 * \param matrix Transformation matrix from world coordinates to the desired coordinate system.
190 * \param resetMinMax Normally not specified by user. Should be true for the initial call.
191 */
192 GLS_EXPORT void GetTransformedExtents( Vector& min, Vector& max, const GlsMatrixType& matrix, bool resetMinMax = true ) DISTI_METHOD_OVERRIDE;
193
194 /** Handles input events.
195 * It traverses the hierarchy with Pick3D.
196 * Then THE picked object is given the handle() call.
197 * \param ev The event data.
198 * \returns The object that handled the input.
199 */
201
202 /** Peforms post creation tasks including reparenting all objects.
203 * and adjusting their position.
204 * It checks the value of _absolutePlacement to determine if movement of the
205 * generated objects is necessary
206 * /see AbsolutePlacement
207 */
208 virtual GLS_EXPORT void Init();
209
210 /** The GL Studio code generator allways derives a new Initialize method for the user
211 This is called after all the objects are created.
212 */
213 virtual GLS_EXPORT void Initialize();
214
215 /// If this component was loaded from an RSO library,
216 /// this method returns the object's library reference.
217 /// The library reference should be deleted AFTER the component is deleted.
218 /// If the component was not loaded from an RSO library,
219 /// this method returns NULL.
220 /// \return A pointer to component's library reference, if it was loaded from an RSO, else NULL.
222
223 using Group::Location;
226 GLS_EXPORT void Location( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
227
228 /* Unhides base class implementation. */
229 // force inheritance
230 using Group::Parent;
231
232 /** Sets the DisplayFrame for this object.
233 * It does not set the specified parent for all the children.
234 * Instead, it sets all the children's parent to 'this'. And
235 * saves the argument 'par' in _parentDisplayFrame. This
236 * allows special traversals, which traverse out of the ComponentBase
237 * to the ComponentBase's parent.
238 * \param par The parent which will be saved in _parentDisplayFrame
239 * \see ParentDisplayFrame
240 */
242
243 /** Gets the value of the DisplayFrame containing this component
244 * \return the value of the DisplayFrame containing this component.
245 * Returns NULL if there is no parent DisplayFrame
246 */
248
249 /** Sets the parent DisplayFrame for this object. This is normally only set by a
250 * call to Parent().
251 * \param val The new val for _parentDisplayFrame
252 * \see ComponentBase::Parent()
253 */
255
256 virtual GLS_EXPORT DisplayObject* Pick3D( const Vector& winLoc,
257 const Vector& logicalCoords,
258 float scale,
259 const Vector& directionVector,
260 Vector& collisionWinLoc /*Returned*/,
261 const OpenGLMatrices& drawnMatrices ) DISTI_METHOD_OVERRIDE;
262
264 GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL ) DISTI_METHOD_OVERRIDE;
266
268 using Group::Rotate;
269 using Group::Scale;
270
271 GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;
272 GLS_EXPORT void Scale( float px, float py, float pz, Vertex* parentAnchor, int handleBar = 0 ) DISTI_METHOD_OVERRIDE;
273
274 /** This will call our parent display frame's SetRedraw() causing
275 this component to be redrawn in the future.
276 */
278
280 GLS_EXPORT void Translate( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
281
282 /** If UseParentsLighting is true, the component will add
283 * its lights to those already set by its parent.
284 * If false, the component will only use its own lights.
285 */
286 virtual GLS_EXPORT void UseParentsLighting( const bool& );
287
288 /// If UseParentsLighting is true, the component will add
289 /// its lights to those already set by its parent.
290 /// If false, the component will only use its own lights.
291 /// \return The current use parent's lighting value.
293
294 /// Overridden so we will always get -1 for our texture index.
295 /// This keeps our children from trying to draw with our texture
296 /// index which would be for the wrong palette.
297 /// \return -1
300 {
302 }
303
304 GLS_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
305
306 /// \see DisplayFrame
307 /// \return the parents input handler if a parent exists, else returns this component's input handler
309
311
312protected:
313 LiveComponentAccessor* _liveAccessor; /**< /see ComponentBase::LiveAccessor */
314 bool _absolutePlacement; /**< /see ComponentBase::AbsolutePlacement */
315 Vertex _absolutePlacementDelta; ///< The delta vector used when using relative placement.
316 DisplayFrame* _parentDisplayFrame; /**< /see ComponentBase::ParentDisplayFrame */
317 GlsMatrixType _editorTransformMatrix; /**< The static transformation from the internal component coordinates to the parent's coordinate system */
318
319 /** Overridden from base class
320 * This adds the _editorTransformMatrix to the DCS. You will need to call CalcDrawMatrix whenever the _editorTransformMatrix changes.*/
322
323 /* Overridden from base class */
325
326 /// EditorTransformMatrix is an extra transformation added in addition to the DCS matrix.
327 /// This is used for scaling, rotation, and placement of component instances in the editor and at runtime.
328 /// \param matrix The new transform matrix value to use.
330
331 /// \return A const reference to the the current editor transform matrix.
333
334#ifdef GLES
335 /** Set a single attribute from the GLO file.
336 * \param data The attribute to set and its associated data.
337 */
338 GLS_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
339#endif
340
341private:
342 DisplayObject* PickFirst( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
343 DisplayObject* PickBest( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
344};
345
346/// \return The directory of the shared library that calls this function.
347/// \param moduleName The pointer to the shared library in question.
348#ifdef WIN32
349GLS_EXPORT std::string GetComponentDirectory( HINSTANCE moduleName );
350#else
351GLS_EXPORT std::string GetComponentDirectory( void* moduleName );
352#endif
353} // namespace disti
354
355#endif
Definition: disti_metadata.h:87
Definition: component_base.h:67
void CalcDrawMatrix() override
GlsMatrixType _editorTransformMatrix
Definition: component_base.h:317
virtual void CreateObjects()
virtual void ChangedAbsolutePlacement(bool val)
static T * CreateComponent(DisplayObject::AvailableAttributesEnum availableAttributes=DisplayObject::GLS_ATTRIBUTES_ALL)
Definition: component_base.h:110
void CalculateMatrices(const OpenGLMatrices &newMatrices) override
virtual bool UseParentsLighting()
void SetAvailableAttributes(unsigned int value) override
void Translate(float tr[]) override
void ClearDragAndFocus() override
void PreDraw(const OpenGLMatrices &current, Culler &culler) override
void SetRedraw() override
void CopyProperties(DisplayObject *src) override
Vertex _absolutePlacementDelta
The delta vector used when using relative placement.
Definition: component_base.h:315
void DeleteAllChildren() override
virtual void Init()
const GlsMatrixType & EditorTransformMatrix() const
static bool CheckLiveVersion(ComponentBase *comp, const GlsBuiltVersionInfo &callingVersion=GlsBuiltVersionInfo())
bool _absolutePlacement
Definition: component_base.h:314
void CopyGeometry(DisplayObject *src) override
int TextureIndex() override
DistiAttributeBase & Resource(const char *name) override
void SetValue(int spec, va_list &args) override
virtual DisplayObject * HandleInput(DisplayEvent *ev)
InterfaceListType * GetCppInterfaceDescription(InterfaceListType *addToThisList=NULL) override
DisplayFrame * _parentDisplayFrame
Definition: component_base.h:316
void GetTransformedExtents(Vector &min, Vector &max, const GlsMatrixType &matrix, bool resetMinMax=true) override
DisplayObject * CloneObject(bool generateNames=false) override
LiveComponentAccessor * _liveAccessor
Definition: component_base.h:313
void Scale(float px, float py, float pz, Vertex *parentAnchor, int handleBar=0) override
void NotifyAttributeChanged(const AttributeName &name) override
void Location(const Vertex &v) override
virtual DisplayObject * Pick3D(const Vector &winLoc, const Vector &logicalCoords, float scale, const Vector &directionVector, Vector &collisionWinLoc, const OpenGLMatrices &drawnMatrices) override
void GetResources(std::ostream &outstr, GlsResourceFilter *filter=NULL) override
virtual void Initialize()
const Vertex & Location() const override
Definition: component_base.h:224
void GetCppInterfaceDescriptionFree(InterfaceListType *array) override
DisplayFrame * ParentDisplayFrame() const
Definition: component_base.h:247
void Rotate(const Vector &orig, float angle, const Vector &axis) override
virtual void AbsolutePlacement(bool val)
void CalculateBoundingBox() override
DisplayObject * FindByNameSameFrame(const char *name) override
void Location(float x, float y, float z) override
bool AbsolutePlacement() const
Definition: component_base.h:123
LiveComponentAccessor * LiveAccessor()
Definition: component_base.h:221
void Parent(DisplayFrame *par) override
InputHandler * GetInputHandler() override
void ParentDisplayFrame(DisplayFrame *val)
Definition: component_base.h:254
static ComponentBase * CreateLiveComponent(const char *fileName=NULL, const char *className=NULL, bool performCreate=true, const GlsBuiltVersionInfo &callingVersion=GlsBuiltVersionInfo())
void GetExtents(float &x, float &y, float &z, float &x1, float &y1, float &z1) override
void Draw() override
Definition: cull.h:49
Definition: events.h:111
Definition: display_frame.h:86
virtual float Scale()
Definition: display_frame.h:133
Definition: display.h:95
AvailableAttributesEnum
Definition: display.h:130
virtual int TextureIndex()
Definition: disti_metadata.h:220
Definition: dynamic_array.h:79
Definition: gls_version.h:223
Definition: gls_glo_file.h:1241
Definition: gls_resources.h:49
Definition: group.h:52
virtual void Scale(float scale_x, float scale_y)
virtual const Vertex & Location() const
void Rotate(const Vector &orig, float angle, const Vector &axis) override
DisplayFrame * Parent() const
Definition: display.h:944
Definition: input_handler.h:185
Definition: live_component_accessor.h:53
Class to contain current OpenGL view, projection and draw matrices.
Definition: util.h:540
Definition: vertex.h:84
Definition: vertex.h:419
The disti::DisplayFrame class.
#define DISTI_DEPRECATED(msg)
Defines whether this compiler supports the C++14 deprecated attribute.
Definition: gls_cpp_lang_support.h:487
#define DISTI_METHOD_OVERRIDE
Macro to wrap the override keyword, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:221
A file for all GL Studio files to include.
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:50
Used for matching version of libraries and headers.
The disti::Group class. Implements groups of objects.
Definition: bmpimage.h:46
void SetAbsolutePlacementDefault(bool value)
bool GetAbsolutePlacementDefault()
std::string GetComponentDirectory(void *moduleName)
#define FALSE
False macro, for backward compatibility purposes.
Definition: util.h:104