GL Studio C++ Runtime API
gls_moving_eye.h
Go to the documentation of this file.
1 /*! \file
2  \brief The disti::GlsMovingEye 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 _GLSMOVINGEYE_H
41 #define _GLSMOVINGEYE_H
42 
43 #include <queue>
44 
45 #ifdef __VXWORKS__
46 #define va_list std::va_list
47 #endif
48 
49 #include "gls_cpp_lang_support.h"
50 #include "gls_eyepoint.h"
51 
52 /// Provides support for creating DLLs
53 #if( defined( GLSGEN_EXPORT_GLSMOVINGEYE ) || defined( GLSGEN_IMPORT_GLSMOVINGEYE ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
54  && defined( _MSC_VER )
55 # if defined( GLSGEN_EXPORT_GLSMOVINGEYE ) || defined( GLS_EXPORT_GENERATED )
56 # define GLSGEN_GLSMOVINGEYE_EXPORT __declspec( dllexport )
57 # else
58 # define GLSGEN_GLSMOVINGEYE_EXPORT __declspec( dllimport )
59 # endif
60 #else
61 # define GLSGEN_GLSMOVINGEYE_EXPORT
62 #endif
63 ///////////////////////////////////////////////////////////////////////////////
64 
65 #define LIB_BASE_NAME "gls_moving_eye"
66 #include "gls_auto_lib.h"
67 #undef LIB_BASE_NAME
68 
69 namespace disti
70 {
71 // SetValue enumerations
72 enum
73 {
74  GLS_MOVINGEYE_EMIT_EVENT = GLS_EYEPOINT_VIEW_VECTORS + 1,
75  GLS_MOVINGEYE_LOOK_AT_OBJECT,
76  GLS_MOVINGEYE_MAX_SPEED,
77  GLS_MOVINGEYE_MOVEMENT,
78  GLS_MOVINGEYE_ROUTE,
79  GLS_MOVINGEYE_DISABLE_HISTORY
80 };
81 
82 //------------------------------------------------------------------------
83 /**
84 * Runtime implementation of a GlsMovingEye
85 */
86 class GlsMovingEye : public GlsEyePoint
87 {
88 private:
89  GlsMovingEye& operator=( const GlsMovingEye& ) DISTI_SPECIAL_MEM_FUN_DELETE;
90  GlsMovingEye( const GlsMovingEye& ) DISTI_SPECIAL_MEM_FUN_DELETE;
91 
92 public:
93  typedef GlsEyePoint _BaseClass;
94 
95  /// This specifies the type of route taken from one eyepoint to another.
97  {
98  CONSTANT = 0,
99  SINUSOIDAL = 1
100  };
101 
102  /// This specifies the type of route taken from one eyepoint to another.
103  enum Route_t
104  {
105  DIRECT = 0,
106  ARC = 1
107  };
108 
109  // Name of the event emitted when a move is completed
110  static const char* MOVE_COMPLETE_EVENT_NAME;
111 
112  //------------------------------------------------------------------------
113  /**
114  * Create a new GlsMovingEye.
115  */
117 
118  GLSGEN_GLSMOVINGEYE_EXPORT GlsMovingEye( const GlsMovingEye& that, const bool generateNames );
119 
120  //------------------------------------------------------------------------
121  /**
122  * GlsMovingEyeEditor destructor
123  */
125 
126  //------------------------------------------------------------------------
127  /**
128  * Returns true if the we're at the beginning of the history of movements.
129  */
130  bool AtStartOfHistory() const
131  {
132  return _historyPos == 0;
133  }
134 
135  //------------------------------------------------------------------------
136  /**
137  * Returns true if the we're at the end of the history of movements.
138  */
139  bool AtEndOfHistory() const
140  {
141  return _historyPos == _moveHistory.size() - 1;
142  }
143 
144  //------------------------------------------------------------------------
145  /**
146  * Aborts any move currently in progress.
147  */
149 
150  virtual GLSGEN_GLSMOVINGEYE_EXPORT void SetAvailableAttributes( unsigned int value );
151 
152  //------------------------------------------------------------------------
153  /* See base class */
154  virtual GLSGEN_GLSMOVINGEYE_EXPORT void Calculate( double time );
155 
156  //------------------------------------------------------------------------
157  /* See base class */
160  CloneObject( bool generateNames = false );
161 
162  //------------------------------------------------------------------------
163  /* See base class */
165 
166  //------------------------------------------------------------------------
167  /**
168  * Creates a new, blank GlsMovingEye object.
169  * \return DisplayObject type pointer to the new GlsMovingEye.
170  */
172 
173  //------------------------------------------------------------------------
174  /* See base class */
175  virtual GLSGEN_GLSMOVINGEYE_EXPORT void Draw();
176 
177  //------------------------------------------------------------------------
178  /**
179  * Returns whether or not an event is emitted upon completion of a
180  * commanded movement.
181  */
182  bool EmitEvent() const { return _emitEvent; }
183 
184  //------------------------------------------------------------------------
185  /**
186  * Sets whether or not an event is emitted upon completion of a
187  * commanded movement.
188  */
189  void EmitEvent( bool emitEvent );
190 
191  //------------------------------------------------------------------------
192  /**
193  * Returns whether or not an the move history is disabled.
194  */
195  bool DisableMoveHistory() const { return _disableMoveHistory; }
196 
197  //------------------------------------------------------------------------
198  /**
199  * Sets whether or not the move history is disabled.
200  */
201  void DisableMoveHistory( bool his );
202 
203  //------------------------------------------------------------------------
204  /* See base class */
206 
207 #ifndef GLES
208  //------------------------------------------------------------------------
209  /* See base class */
213  InterfaceListType* addToThisList = 0 );
214 
215  //------------------------------------------------------------------------
216  /* See base class */
218 #endif
219  //------------------------------------------------------------------------
220  /**
221  * \return The name of the object that the eyepoint should be always
222  * looking at.
223  * Lifetime is guaranteed to coincide with the GlsMovingEye's lifetime
224  * or until LookAtObject is changed.
225  */
226  const std::string& LookAtObject() const { return _lookAtObject; }
227 
228  //------------------------------------------------------------------------
229  /**
230  * Sets the name of the object that the eyepoint should be always
231  * looking at.
232  */
233  void LookAtObject( const std::string& name );
234 
235  //------------------------------------------------------------------------
236  /**
237  * Returns the maximum speed in logical units/second which will
238  * be used to achive the transition between eyepoints.
239  */
240  float MaxSpeed() const { return _maxSpeed; }
241 
242  //------------------------------------------------------------------------
243  /**
244  * Sets the maximum speed in logical units/second which will
245  * be used to achive the transition between eyepoints.
246  */
247  void MaxSpeed( float speed );
248 
249  //------------------------------------------------------------------------
250  /**
251  * Returns the type of movement algorithm to use when moving to another
252  * eyepoint.
253  */
254  Movement_t Movement() const { return _movement; }
255 
256  //------------------------------------------------------------------------
257  /**
258  * Sets the type of movement algorithm to use when moving to another
259  * eyepoint.
260  */
261  void Movement( Movement_t movementType );
262 
263  //------------------------------------------------------------------------
264  /**
265  * Moves this eyepoint to the previously set eyepoint. If a move is
266  * already in progress, it will be immediately stopped, and this move
267  * will start.
268  */
270 
271  //------------------------------------------------------------------------
272  /**
273  * Moves this eyepoint to the eyepoint which was last achieved from a
274  * MoveBack(). If a move is already in progress, it will be immediately
275  * stopped, and this move will start.
276  */
278 
279  //------------------------------------------------------------------------
280  /**
281  * Causes this eye to move from its current state to the state specified
282  * by the targetEye. It will take moveTime to get there. If a move is
283  * already in progress, it will be immediately stopped, and this move
284  * will start.
285  */
287  void MoveToEye( GlsEyePoint* eye, float moveTime = 2.0f );
288 
289  //------------------------------------------------------------------------
290  /**
291  * Causes the eye to move from its current state to each eyepoint in the
292  * specified group ending with the last eye in the group. If a move is
293  * already in progress, it will be immediately stopped, and this move
294  * will start.
295  */
297  void MoveToEye( Group* eyeGroup, float moveTime = 2.0f );
298 
299  //------------------------------------------------------------------------
300  /**
301  * Causes the specified eye to be added to the end of the list of eyes
302  * which should be moved through.
303  */
305  void MoveToEyeAdd( GlsEyePoint* eye, float moveTime = 2.0f );
306 
307  //------------------------------------------------------------------------
308  /**
309  * Causes the specified eyes to be added to the end of the list of eyes
310  * which should be moved through.
311  */
313  void MoveToEyeAdd( Group* eyeGroup, float moveTime = 2.0f );
314 
315  //------------------------------------------------------------------------
316  /**
317  * Causes this eye to move to the specified location in the scene without
318  * modifying the view direction or any other eye specific information.
319  */
321  void MoveToLocation( const Vector& location, float moveTime = 2.0f );
322 
323  //------------------------------------------------------------------------
324  /**
325  * Moves the eyepoint in view-relative coordinates by the specified amount,
326  * over the specified time. The units are in relative screen coordinates:
327  * X and Y are pixels, Z is 0->1. See WindowToLogical() or
328  * LogicalToWindow().
329  */
331  const Vector& moveAmount,
332  const Vector& rotation );
333 
334  //------------------------------------------------------------------------
335  /**
336  * Returns the type of route to use when moving to another eyepoint.
337  */
338  Route_t Route() const { return _route; }
339 
340  //------------------------------------------------------------------------
341  /**
342  * Sets the type of route to use when moving to another eyepoint.
343  */
344  void Route( Route_t routeType );
345 
346  //------------------------------------------------------------------------
347  /* See base class */
348  GLSGEN_GLSMOVINGEYE_EXPORT virtual void SetValue( int spec, va_list& args );
349 
350 protected:
351 #ifdef GLES
352  /** Set a single attribute from the GLO file.
353  * \param data The attribute to set and its associated data.
354  */
355  GLSGEN_GLSMOVINGEYE_EXPORT virtual void SetFromGloData( GlsGloFileAttribute& data );
356 #endif
357 
358  /// Type to store eyepoint state information.
359  struct EyeState_t
360  {
361  Vector location;
362  bool orthographic;
363  double FOV;
364  double otherFOV;
365  bool fovIsHorizontal;
366  double orthoSize;
367  double otherOrthoSize;
368  double farClip;
369  double nearClip;
370  FovConstraintType horizontalConstraint;
371  FovConstraintType verticalConstraint;
372  Vector viewVectors[ 3 ];
373 
374  /** Default constructor */
375  EyeState_t();
376 
377  /** Initialize EyeState_t using targetEye parameters.
378  * \param movingEye The GlsMovingEye that the state information is for (needed for coordinate conversions)
379  * \param targetEye The GlsEyePoint to move to
380  */
381  EyeState_t( GlsMovingEye* movingEye, GlsEyePoint* targetEye );
382 
383  inline Vector Direction()
384  {
385  /* Copied from GlsEyePoint::Direction() */
386  return viewVectors[ 2 ];
387  }
388  };
389 
390  /// Type to store eyepoint movement parameters.
391  struct MoveParms_t : public EyeState_t
392  {
393  bool addToHistory;
394  double time;
395  std::string qualifiedEyeName;
396 
397  MoveParms_t(
398  bool storeHistory,
399  double moveTime,
400  GlsMovingEye* movingEye,
401  GlsEyePoint* targetEye );
402  };
403 
404  /// Whether or not to emit an event when the move has completed.
406 
407  /// This is true when a move is occurring and the route segment being
408  /// moved along is the very first one in the queue. This is used during
409  /// sinusoidal movement to smoothly speed up when starting.
411 
412  /// Current position into the history list
413  unsigned _historyPos;
414 
415  /// Flag to keep track of when the object gets initialized.
417 
418  /// Automatically adjust the view direction to point at the specified
419  /// targetObject. This is inactivated when the string is blank.
420  /// While this is active, the move methods will not control the view
421  /// direction. They can still control the position and other eye
422  /// information.
423  std::string _lookAtObject;
424 
425  /// The last up vector provided by the user or the move code.
426  /// Used by the 'look at' algorithm to orient the eyepoint
428 
429  /// The last up vector calculated by the lookAt algorithm.
431 
432  /// Stores a history of visited eyepoints for moving back and forth.
433  std::vector<MoveParms_t> _moveHistory;
434 
435  bool _disableMoveHistory;
436 
437  /// This specifies the maximum speed in logical units / second which will
438  /// be used to achive the transition. If the requested transition cannot
439  /// occur within the requested move time without exceeding the max speed,
440  /// the move time will be longer than requested. In other words, this
441  /// limit has priority over any requested moveTime. A MaxSpeed value of
442  /// < 0.0 means the speed limit is disabled.
443  float _maxSpeed;
444 
445  /// Type of movement algorithm to use when moving to another eyepoint.
447 
448  /// Contains movement parameters for each move that should be performed.
449  /// The last one contains the final eyepoint to stop at.
450  std::queue<MoveParms_t> _moveQ;
451 
452  /// Type of route to take when moving to another eyepoint.
454 
455  /// Stores this eyepoint's current state at the start of a move and is
456  /// used in calculating movement during each execution frame.
458 
459  /// Latest known simulation time.
460  double _simTime;
461 
462  /// Simulation time that a move starts.
463  double _startTime;
464 
465  /// This specifies the up direction and is used when interpolating
466  /// movement to keep the view oriented 'correctly'.
468 
469  /// This specifies a buffer area around _upVector and -_upVector which
470  /// the moving eye will try to avoid. Setting this to non-zero avoids
471  /// flipping problems when orientation passes through _upVector or -_upVector
472  /// during moves.
474 
475  //------------------------------------------------------------------------
476  /**
477  * Calculates the direction to the named object.
478  */
479  //------------------------------------------------------------------------
480  Vector DirectionToObj( const std::string& qualifiedObjName ) const;
481 
482  //------------------------------------------------------------------------
483  /**
484  * Extracts all eyepoint objects from the group hierarchy. The group
485  * can contain other groups and object types.
486  */
487  //------------------------------------------------------------------------
488  void ExtractEyepoints( Group* group, std::vector<GlsEyePoint*>& eyes );
489 
490  //------------------------------------------------------------------------
491  /**
492  * Called when the destination eyepoint is reached to perform actions
493  * necessary to complete the movement.
494  */
495  //------------------------------------------------------------------------
496  void FinishMoving();
497 
498  //------------------------------------------------------------------------
499  /**
500  * Initializes the movement history with the initial state of the eyepoint.
501  */
502  //------------------------------------------------------------------------
503  void Initialize();
504 
505  //------------------------------------------------------------------------
506  /**
507  * Returns an adjusted move time based on the maximum speed setting. If the
508  * speed of moving over distance in desiredTime is greater than the
509  * maximum speed setting, the move time will be lengthened.
510  *
511  * \param distance: distance in logical units that will be moved.
512  * \param desiredTime: time in which we wish to cover the specified
513  * distance.
514  */
515  //------------------------------------------------------------------------
516  float MoveTime( float distance, float desiredTime ) const;
517 
518  //------------------------------------------------------------------------
519  /**
520  * Calculates the distance over the entire route if moving between all
521  * eyepoints in the list.
522  */
523  //------------------------------------------------------------------------
524  float RouteDistance( std::vector<GlsEyePoint*>& eyes ) const;
525 
526  //------------------------------------------------------------------------
527  /**
528  * Queues the move using the passed in movement parameters and sets up
529  * the start time and starting state of the move.
530  */
531  //------------------------------------------------------------------------
532  void StartMoving( const MoveParms_t& moveParms );
533 
534  /// The editor class needs to access this class' privates. :)
535  friend class GlsMovingEyeEditor;
536 };
537 
538 //----------------------------------------------------------------------------
539 inline std::ostream& operator<<( std::ostream& outstr, GlsMovingEye::Movement_t m )
540 {
541  switch( m )
542  {
543  case GlsMovingEye::CONSTANT:
544  outstr << "CONSTANT";
545  break;
546  case GlsMovingEye::SINUSOIDAL:
547  outstr << "SINUSOIDAL";
548  break;
549  default:
550  outstr << "BAD_MOVEMENT";
551  };
552 
553  return outstr;
554 }
555 
556 //----------------------------------------------------------------------------
557 inline std::istream& operator>>( std::istream& instr, GlsMovingEye::Movement_t& m )
558 {
559  std::string str;
560  instr >> str;
561  if( str == "CONSTANT" )
562  {
563  m = GlsMovingEye::CONSTANT;
564  }
565  else if( str == "SINUSOIDAL" )
566  {
567  m = GlsMovingEye::SINUSOIDAL;
568  }
569  return instr;
570 }
571 
572 //----------------------------------------------------------------------------
573 inline std::ostream& operator<<( std::ostream& outstr, GlsMovingEye::Route_t r )
574 {
575  switch( r )
576  {
577  case GlsMovingEye::DIRECT:
578  outstr << "DIRECT";
579  break;
580  case GlsMovingEye::ARC:
581  outstr << "ARC";
582  break;
583  default:
584  outstr << "BAD_ROUTE";
585  };
586 
587  return outstr;
588 }
589 
590 //----------------------------------------------------------------------------
591 inline std::istream& operator>>( std::istream& instr, GlsMovingEye::Route_t& r )
592 {
593  std::string str;
594  instr >> str;
595  if( str == "DIRECT" )
596  {
597  r = GlsMovingEye::DIRECT;
598  }
599  else if( str == "ARC" )
600  {
601  r = GlsMovingEye::ARC;
602  }
603  return instr;
604 }
605 
606 } // namespace disti
607 #endif
unsigned _historyPos
Current position into the history list.
Definition: gls_moving_eye.h:413
Vector DirectionToObj(const std::string &qualifiedObjName) const
void MoveToEye(GlsEyePoint *eye, float moveTime=2.0f)
bool AtEndOfHistory() const
Definition: gls_moving_eye.h:139
Route_t Route() const
Definition: gls_moving_eye.h:338
virtual void GetCppInterfaceDescriptionFree(InterfaceListType *array)
float _bufferAngle
Definition: gls_moving_eye.h:473
virtual ~GlsMovingEye()
Definition: dynamic_array.h:62
Movement_t Movement() const
Definition: gls_moving_eye.h:254
void StartMoving(const MoveParms_t &moveParms)
Definition: display.h:98
bool AtStartOfHistory() const
Definition: gls_moving_eye.h:130
Vector _lookAtCalculatedUpVector
The last up vector calculated by the lookAt algorithm.
Definition: gls_moving_eye.h:430
virtual InterfaceListType * GetCppInterfaceDescription(InterfaceListType *addToThisList=0)
virtual void CopyProperties(DisplayObject *src)
Movement_t
This specifies the type of route taken from one eyepoint to another.
Definition: gls_moving_eye.h:96
void ExtractEyepoints(Group *group, std::vector< GlsEyePoint * > &eyes)
bool _firstSegment
Definition: gls_moving_eye.h:410
#define GLSGEN_GLSMOVINGEYE_EXPORT
Provides support for creating DLLs.
Definition: gls_moving_eye.h:61
virtual void SetAvailableAttributes(unsigned int value)
void MoveToEyeAdd(GlsEyePoint *eye, float moveTime=2.0f)
Definition: gls_glo_file.h:982
bool DisableMoveHistory() const
Definition: gls_moving_eye.h:195
bool EmitEvent() const
Definition: gls_moving_eye.h:182
Vector _upVector
Definition: gls_moving_eye.h:467
Type to store eyepoint state information.
Definition: gls_moving_eye.h:359
float RouteDistance(std::vector< GlsEyePoint * > &eyes) const
virtual void SetValue(int spec, va_list &args)
The disti::GlsEyePoint class. Implements eyepoints.
Route_t _route
Type of route to take when moving to another eyepoint.
Definition: gls_moving_eye.h:453
double _simTime
Latest known simulation time.
Definition: gls_moving_eye.h:460
Definition: gls_eyepoint.h:115
float _maxSpeed
Definition: gls_moving_eye.h:443
virtual void GenerateInstanceName()
void MoveToLocation(const Vector &location, float moveTime=2.0f)
void MoveRelative(const Vector &moveAmount, const Vector &rotation)
Route_t
This specifies the type of route taken from one eyepoint to another.
Definition: gls_moving_eye.h:103
std::queue< MoveParms_t > _moveQ
Definition: gls_moving_eye.h:450
virtual DisplayObject * CloneObject(bool generateNames=false)
double _startTime
Simulation time that a move starts.
Definition: gls_moving_eye.h:463
The gls_auto_lib.
std::vector< MoveParms_t > _moveHistory
Stores a history of visited eyepoints for moving back and forth.
Definition: gls_moving_eye.h:433
Definition: group.h:52
float MaxSpeed() const
Definition: gls_moving_eye.h:240
bool _emitEvent
Whether or not to emit an event when the move has completed.
Definition: gls_moving_eye.h:405
Vector _lookAtReferenceUpVector
Definition: gls_moving_eye.h:427
Definition: vertex.h:83
std::string _lookAtObject
Definition: gls_moving_eye.h:423
const std::string & LookAtObject() const
Definition: gls_moving_eye.h:226
Movement_t _movement
Type of movement algorithm to use when moving to another eyepoint.
Definition: gls_moving_eye.h:446
float MoveTime(float distance, float desiredTime) const
virtual void Draw()
virtual void Calculate(double time)
static DisplayObject * CreateInstance()
Definition: gls_moving_eye.h:86
Macros and helper code to determine what subset of C++11/14/17 is available.
friend class GlsMovingEyeEditor
The editor class needs to access this class' privates. :)
Definition: gls_moving_eye.h:535
bool _initialized
Flag to keep track of when the object gets initialized.
Definition: gls_moving_eye.h:416
Definition: bmpimage.h:46
Type to store eyepoint movement parameters.
Definition: gls_moving_eye.h:391
EyeState_t _start
Definition: gls_moving_eye.h:457