GL Studio C++ Runtime API
group.h
Go to the documentation of this file.
1/// \file group.h
2/// \brief The disti::Group class. Implements groups of objects.
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_GROUP_H
40#define INCLUDED_DISTI_GROUP_H
41
42#include "display.h"
43#include "dynamic_array.h"
45
46namespace disti
47{
48/**
49 * The Group class. Implements groups of objects
50 */
51class Group : public DisplayObject
52{
53public:
54 DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
55 typedef DisplayObject _BaseClass; ///< Deprecated typedef for the base class.
56 typedef DisplayObject BaseClass; ///< Typedef for the base class.
57
58private:
59 /** If true, this object will be eligible for culling based on its static extents.
60 * IMPORTANT: The cull will only be acturate within the STATIC extents of the group
61 * If any child moves outside the static extents using Dynamic operations, it will
62 * be over-culled.
63 * The default is false, and only leaf nodes (non-groups) will cull.
64 */
65 bool _performGroupCullCheck;
66
67 /** If true, cull checking will pass on to children of this group.
68 * If false, children will not be culled (if this group is not culled) */
69 bool _cullTestChildren;
70
71 DisplayObject* BestPick( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
72 DisplayObject* FirstPick( const Vector& winLoc, const Vector& logicalCoords, float scale, const Vector& directionVector, Vector& collisionWinLoc /*Returned*/, const OpenGLMatrices& drawnMatrices );
73
74 virtual GLS_EXPORT void onVertexchanged();
75
76 Group& operator=( const Group& ) DISTI_SPECIAL_MEM_FUN_DELETE;
78
79protected:
80 DisplayObjectArray _objects; ///< The objects contained in this group.
81
82 /// Helper method for child classes of group that don't want to call Group::SetAvailableAttributes.
83 /// \param availableAttributes Bit field for attribute types to create.
84 virtual GLS_EXPORT void AddAvailableAttributes( unsigned int availableAttributes );
85
86 /** Grow bounding box to accomodate new object
87 * \param obj The new object in the group
88 * \pre obj Must already be added to the group
89 */
91
92public:
93 friend class GroupEditor;
94
95#ifndef GLES
98#endif
99
100 /** Finds a pointer to the display object in the group, using the object's
101 * instance name as a key.
102 * \note If there are multiple DisplayObjects within the group with the same name,
103 * only the first instance will be found. This can be an issue if a sub-component
104 * contains objects with the same name as the object you are searching for.
105 * \param name Instance name of the object to find
106 * \return A pointer to the object if it is in the group, otherwise NULL
107 */
108 GLS_EXPORT DisplayObject* FindByName( const char* name );
109
110 /** Finds a pointer to the display object in the group, using the object's
111 * instance name as a key.
112 * This does not desend into components, as they are different frames
113 * with possibility for duplicate names as the current frame.
114 * \param name Instance name of the object to find
115 * \return A pointer to the object if it is in the group, otherwise NULL
116 */
117 virtual GLS_EXPORT DisplayObject* FindByNameSameFrame( const char* name );
118
119 /** Finds a pointer to the display object in the group, using the object's
120 * instance name as a key.
121 * \param obj Pointer to the object to find
122 * \return A pointer to the object if it is in the group, otherwise NULL
123 */
125
126 /** Finds a pointer to the DisplayObject in the group using a qualified instance name.
127 * This allows precise searches for an object contained within a sub-component.
128 * (e.g. "cockpit.altimeter.needle"). To find an object in the same DisplayFrame
129 * use just the instance name. (e.g. "cockpit")
130 * The dot denotes crossing of DisplayFrame boundaries.
131 * \sa GetQualifiedInstanceName
132 * \param name Qualified instance name of the object to find
133 * \returns A pointer to the object if it is in the group, otherwise NULL
134 */
136
137 /** Finds a pointer to the display object in the group, using the object's address as a key
138 * \param obj Pointer to the object to find
139 * \return A pointer to the object if it is in the group, otherwise NULL
140 */
142
143 /// \return A reference to the object array for this group.
145
146 /// \return A const reference to the object array for this const group.
147 const DisplayObjectArray& Objects() const { return _objects; }
148
149 /** Returns the DisplayObject at the given group index
150 * \param index The index of the object to find
151 * \return A pointer to the object if it is in the group, otherwise NULL
152 */
153 GLS_EXPORT DisplayObject* Item( unsigned int index );
154
155 /// \return Whether or not this group should be considered for culling.
156 bool PerformGroupCullCheck() const { return _performGroupCullCheck; }
157
158 /// Sets whether or not this group should be considered for culling.
159 /// \param mode The new cull mode for the group.
161
162 /// \return Whether or not this group's children should be considered for culling.
163 bool CullTestChildren() const { return _cullTestChildren; }
164
165 /// Sets whether or not this group's children should be considered for culling.
166 /// \param mode The new cull mode to set.
167 GLS_EXPORT void CullTestChildren( bool mode );
168
169 /** \return The number of objects in this group. (Non recursive count) */
170 unsigned int Count() const { return _objects.Count(); }
171
172 /// Overload of the array index operator to allow you to treat this Group as an array of objects.
173 /// \param index The object index to be returned.
174 /// \return A pointer to the requested object.
175 DisplayObjectPtr operator[]( unsigned int index ) { return _objects[ index ]; }
176
177 /// Overload of the array index operator to allow you to treat this const Group as an array of const objects.
178 /// \param index The object index to be returned.
179 /// \return A pointer to the requested object.
180 const DisplayObject* operator[]( unsigned int index ) const { return _objects[ index ]; }
181
182 /** \return pointer to the first element in the group, or NULL if it doesn't exist */
184
185 /** \return pointer to the last element in the group, or NULL if it doesn't exist */
187
188 /** \return True if this group is empty */
189 bool IsEmpty() const { return ( Count() == 0 ); }
190
191 /** Get the index position of the specified object in the list
192 * \param obj The object to find
193 * \return The index of the object in the list, -1 if it isn't in the list
194 */
195 GLS_EXPORT int Position( const DisplayObject* obj ) const;
196
197 /** Construct a new group.
198 * \param generateInstance Whether or not to generate an instance name for this group
199 */
200 GLS_EXPORT explicit Group( int generateInstance = FALSE );
201
202 /** Copy construct a new group, performing a "deep copy" by cloning objects in the group.
203 * \param group The group to clone.
204 * \param generateNames Whether or not to generate a new instance name for this group and its children.
205 */
206 GLS_EXPORT Group( const Group& group, bool generateNames );
207
208 /** Sets the initial number of entries in a group
209 * \param cnt The initial number of entries
210 */
211 GLS_EXPORT void InitialGroupCount( unsigned int cnt );
212
213 /// \return A pointer to a new Group object.
215
216 /** Destroy a group object */
218
219 /** Actually delete all the children of the group.
220 * This does a recursive "delete" on all the children.
221 * This does NOT just remove them from the group.
222 */
224
226
232 GLS_EXPORT bool Hit( float x, float y, float z, float scale, const Vector& directionVector, Vector* collisionPoint ) DISTI_METHOD_OVERRIDE;
233
234 virtual GLS_EXPORT DisplayObject* Pick3D( const Vector& winLoc,
235 const Vector& logicalCoords,
236 float scale,
237 const Vector& directionVector,
238 Vector& collisionWinLoc /*Returned*/,
239 const OpenGLMatrices& drawnMatrices ) DISTI_METHOD_OVERRIDE;
240
241 using BaseClass::Parent;
243
245
246 /// Recalculates the 3D bounding volume of the object, setting the Group's vertices.
247 /// Affects the results of GetExtents().
248 /// This should be called when a Group's children are modified.
250
251 /* Unhides base class implementation. */
252 using BaseClass::Location;
254 GLS_EXPORT void Location( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
255 GLS_EXPORT void Translate( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
256 GLS_EXPORT void Translate( float transAmount[] ) DISTI_METHOD_OVERRIDE;
257 GLS_EXPORT void TranslateVertices( float x, float y, float z ) DISTI_METHOD_OVERRIDE;
258
259 /// Translates the group by the specified amount my changing the
260 /// vertices instead of changing the _location value, moving all subobjects.
261 /// \param transAmount A pointer to an array of floats representing X, Y, and Z to translate.
262 virtual GLS_EXPORT void TranslateVertices( float transAmount[] );
263
264 GLS_EXPORT void GetExtents( float& x, float& y, float& z, float& x1, float& y1, float& z1 ) DISTI_METHOD_OVERRIDE;
265 GLS_EXPORT void GetTransformedExtents( Vector& min, Vector& max, const GlsMatrixType& matrix, bool resetMinMax = true ) DISTI_METHOD_OVERRIDE;
266
267 /* Unhides base class implementation. */
269 GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;
270
271 /// Scale in X-Y plane using the center of the group as the anchor.
272 /// \param scale_x The X factor to scale by.
273 /// \param scale_y The Y factor to scale by.
274 virtual GLS_EXPORT void Scale( float scale_x, float scale_y );
275 GLS_EXPORT void Scale( float scale_x, float scale_y, float scale_z, Vertex* anchor = NULL, int handle = 0 ) DISTI_METHOD_OVERRIDE;
276
277 /** Adds the specified object into the group, at the end of the list
278 * \param obj A pointer to the object to add
279 * \param reparent Whether or not the object parent should be set to this group
280 * \param recalculateBoundingbox Whether or not to recalculate the bounding box
281 * \param loc Where to insert it (defaults to -1 which means at the end of the list)
282 */
283 virtual GLS_EXPORT void InsertObject( DisplayObject* obj, bool reparent = true, bool recalculateBoundingbox = true, int loc = -1 );
284
285 /** Removes the specified object from this group. Does not delete it.
286 * \param obj The display object to removed
287 * \param recalculateBoundingbox
288 * \return True if the object was found and removed from this group
289 */
290 virtual GLS_EXPORT bool DeleteObject( DisplayObject* obj, bool recalculateBoundingbox = true );
291
292 /** Change the draw order of a child object within this group
293 * \param oldIndex The old index of the object
294 * \param newIndex The new index of the object
295 * \pre oldIndex and newIndex must be valid indices
296 */
297 virtual GLS_EXPORT void ReorderObject( unsigned int oldIndex, unsigned int newIndex );
298
299 /** Adds the specified object into the group, at the head of the list
300 * Treats the list like a stack, hence the name Push
301 * \param obj A pointer to the object to add
302 */
303 virtual GLS_EXPORT void PushObject( DisplayObject* obj );
304
305 /** It is not possible to modify a Group's Vertices. Overriden to disable. */
307
308 /** It is not possible to modify a Group's Vertices. Overriden to disable. */
310
311 /** Copies the given vertex data into the group's location vertex
312 * thereby moving the group's location member without affecting
313 * its child objects.
314 * \param v - Given vertex
315 */
316 virtual GLS_EXPORT void SetGroupLocation( const Vertex& v );
317
318 GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL ) DISTI_METHOD_OVERRIDE;
319
321
324
327
330
333
336
339
340 GLS_EXPORT void DepthTest( unsigned char mode ) DISTI_METHOD_OVERRIDE;
342
345
348
351
354
355 /* Unhides base class implementation. */
357
359
360 /* Unhides base class implementation. */
362
364
365 /* Unhides base class implementation. */
366 using BaseClass::SetColor;
367
369
370 /* Unhides base class implementation. */
371 using BaseClass::GetColor;
372
374
375 /* Unhides base class implementation. */
376 using BaseClass::SetFillColor;
377
379
380 /* Unhides base class implementation. */
381 using BaseClass::GetFillColor;
382
384
387
390
393
396
397 /** Call the Calculate method for all children
398 * \param time The current time
399 */
401
402 /** The following class is provided for GL Studio 2.1 backward compatibility.
403 * This interface is deprecated and should only be used to support legacy code.
404 */
406 {
407 protected:
408 unsigned int _index; ///< The underlying index of this child object.
409 Group* _parentGroup; ///< This group's parent group.
410
411 public:
413
414 /// \return A pointer to the next item in the list.
416
417 /// \return A pointer to the previous item in the list.
419
420 /// \return The underlying object for this list item.
422
423 /// Configure the list for the specified Group.
424 /// \param whichGroup The Group whose compatibility list is to be configured.
425 static GLS_EXPORT void RecalcCompatabilityList( Group* whichGroup );
426 };
427
428 /** \return The first object in this group
429 */
431
432 /** \return The last object in this group
433 */
435
436 DynamicArray<CompatabilityListItem> _compatList; ///< Used for GL Studio 2.1 compatibility only.
437
438private:
439 /** Sets the texturing repeat mode for this object without affecting
440 * the settings of its children.
441 * \param rep The new texture repeat mode for this object (boolean)
442 */
443 virtual GLS_EXPORT void SetGroupTextureRepeat( const int mode );
444};
445
446/// Overload begin() so that range-for loops and other constructs work with Group.
447/// \param group The group whose first element is to be returned.
448/// \return A pointer to the first element.
449inline DisplayObjectPtr* begin( Group& group )
450{
451 return begin( group.Objects() );
452}
453
454/// Overload begin() so that range-for loops and other constructs work with Group.
455/// \param group The group whose first element is to be returned.
456/// \return A pointer to the first element.
457inline const DisplayObjectPtr* begin( const Group& group )
458{
459 return begin( group.Objects() );
460}
461
462/// Overload end() so that range-for loops and other constructs work with Group.
463/// \param group The group whose last element is to be returned.
464/// \return A pointer to the last element.
465inline DisplayObjectPtr* end( Group& group )
466{
467 return end( group.Objects() );
468}
469
470/// Overload end() so that range-for loops and other constructs work with Group.
471/// \param group The group whose last element is to be returned.
472/// \return A pointer to the last element.
473inline const DisplayObjectPtr* end( const Group& group )
474{
475 return end( group.Objects() );
476}
477
478} // namespace disti
479
480#endif
Definition: cull.h:49
Definition: display_frame.h:86
Definition: display.h:95
virtual DisplayObject * handle(DisplayEvent *ev)
unsigned Count() const
Definition: dynamic_array.h:218
Definition: gls_color.h:53
Definition: gls_painter.h:50
Definition: gls_resources.h:49
static void RecalcCompatabilityList(Group *whichGroup)
Group * _parentGroup
This group's parent group.
Definition: group.h:409
unsigned int _index
The underlying index of this child object.
Definition: group.h:408
CompatabilityListItem * Next()
CompatabilityListItem * Prev()
Definition: group.h:52
void PerformGroupCullCheck(bool mode)
int DepthTest() override
bool CullBackFace() override
DisplayObjectPtr operator[](unsigned int index)
Definition: group.h:175
virtual void ReorderObject(unsigned int oldIndex, unsigned int newIndex)
void SetPainter(GlsPainter *painter) override
virtual void DeleteAllChildren()
int PolygonEnd() override
void SetAvailableAttributes(unsigned int value) override
CompatabilityListItem * Last()
void PreDraw(const OpenGLMatrices &current, Culler &culler) override
bool Hit(float x, float y, float z, float scale, const Vector &directionVector, Vector *collisionPoint) override
virtual void SetGroupLocation(const Vertex &v)
virtual void Scale(float scale_x, float scale_y)
bool PerformGroupCullCheck() const
Definition: group.h:156
float LineWidth() override
void CopyProperties(DisplayObject *src) override
int Shading() override
const DisplayObject * operator[](unsigned int index) const
Definition: group.h:180
int LineStippleMultiplier() override
void Translate(float x, float y, float z) override
DisplayObject * LastObject()
DisplayObject * FirstObject()
int PolygonMode() override
DisplayObjectArray _objects
The objects contained in this group.
Definition: group.h:80
const DisplayObjectArray & Objects() const
Definition: group.h:147
void CullTestChildren(bool mode)
int Position(const DisplayObject *obj) const
DisplayObjectArray & Objects()
Definition: group.h:144
unsigned int Count() const
Definition: group.h:170
void CopyGeometry(DisplayObject *src) override
virtual bool DeleteObject(DisplayObject *obj, bool recalculateBoundingbox=true)
DynamicArray< CompatabilityListItem > _compatList
Used for GL Studio 2.1 compatibility only.
Definition: group.h:436
virtual void CalculateBoundingBox()
bool LightingEnabled() override
DisplayObject * FindByName(const char *name)
Group(int generateInstance=0)
InterfaceListType * GetCppInterfaceDescription(InterfaceListType *addToThisList=NULL) override
void SetFillColor(const GlsColor &color) override
int TextureMinificationFilter() override
int LineStipplePattern() override
void Calculate(double time) override
void GetTransformedExtents(Vector &min, Vector &max, const GlsMatrixType &matrix, bool resetMinMax=true) override
DisplayObject * FindNonRecursive(DisplayObject *obj)
static DisplayObject * CreateInstance()
bool IsEmpty() const
Definition: group.h:189
DisplayObject * CloneObject(bool generateNames=false) override
GlsColor GetFillColor() 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
int TextureMappingTechnique() override
void InsertVertexAt(unsigned) override
virtual void InsertObject(DisplayObject *obj, bool reparent=true, bool recalculateBoundingbox=true, int loc=-1)
void CalculateTextureCoordinates() override
Group(const Group &group, bool generateNames)
virtual const Vertex & Location() const
void GetCppInterfaceDescriptionFree(InterfaceListType *array) override
void Rotate(const Vector &orig, float angle, const Vector &axis) override
void SetBlendColor(const GlsColor &color) override
DisplayFrame * Parent() const
Definition: display.h:944
int TextureMagnificationFilter() override
void InitialGroupCount(unsigned int cnt)
virtual void AddAvailableAttributes(unsigned int availableAttributes)
int AlphaMode() override
virtual bool TextureRepeat()
virtual void GrowBoundingBox(DisplayObject *obj)
void DeleteVertexAt(unsigned) override
CompatabilityListItem * First()
GlsColor GetBlendColor() override
DisplayObject * Item(unsigned int index)
bool AntiAlias() override
DisplayObject * FindByName(DisplayObject *obj)
Definition: group.h:124
virtual void PushObject(DisplayObject *obj)
void SetColor(const GlsColor &color) override
virtual ~Group()
virtual DisplayObject * FindByNameSameFrame(const char *name)
DisplayObject * FindByQualifiedName(const char *name)
void GetExtents(float &x, float &y, float &z, float &x1, float &y1, float &z1) override
GlsColor GetColor() override
bool CullTestChildren() const
Definition: group.h:163
void Draw() override
void TranslateVertices(float x, float y, float z) override
Class to contain current OpenGL view, projection and draw matrices.
Definition: util.h:540
Definition: vertex.h:84
Definition: vertex.h:419
The disti::DisplayObject class and global enumerations.
The disti::DynamicArray class. A templated array of objects capable of dynamically growing.
Macros and helper code to determine what subset of C++11/14/17 is available.
#define DISTI_SPECIAL_MEM_FUN_DELETE
Macro to wrap function deletion, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:245
#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
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:50
Definition: bmpimage.h:46
DistiAttribDict::const_iterator begin(const DistiAttribDict &dict)
Definition: disti_metadata.h:970
DistiAttribDict::const_iterator end(const DistiAttribDict &dict)
Definition: disti_metadata.h:975
#define FALSE
False macro, for backward compatibility purposes.
Definition: util.h:104