GL Studio 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) 2015 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 #include "gls_eyepoint.h"
46 #include "gls_cpp_lang_support.h"
47 
48 /// Provides support for creating DLLs
49 #if (defined(GLSGEN_EXPORT_GLSMOVINGEYE) || \
50  defined(GLSGEN_IMPORT_GLSMOVINGEYE) || \
51  defined(GLS_EXPORT_GENERATED) || \
52  defined(GLS_IMPORT_GENERATED)) \
53  && defined(_MSC_VER)
54 # if defined(GLSGEN_EXPORT_GLSMOVINGEYE) || defined(GLS_EXPORT_GENERATED)
55 # define GLSGEN_GLSMOVINGEYE_EXPORT __declspec(dllexport)
56 # else
57 # define GLSGEN_GLSMOVINGEYE_EXPORT __declspec(dllimport)
58 # endif
59 #else
60 # define GLSGEN_GLSMOVINGEYE_EXPORT
61 #endif
62 ///////////////////////////////////////////////////////////////////////////////
63 
64 #define LIB_BASE_NAME "gls_moving_eye"
65 #include "gls_auto_lib.h"
66 #undef LIB_BASE_NAME
67 
68 namespace disti
69 {
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 */
159  DisplayObject* CloneObject(bool generateNames = false);
160 
161  //------------------------------------------------------------------------
162  /* See base class */
164  void CopyProperties(DisplayObject* src);
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 */
205  virtual GLSGEN_GLSMOVINGEYE_EXPORT void GenerateInstanceName();
206 
207 #ifndef GLES
208  //------------------------------------------------------------------------
209  /* See base class */
212  InterfaceListType* addToThisList = 0);
213 
214  //------------------------------------------------------------------------
215  /* 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 
352 #ifdef GLES
353  /** Set a single attribute from the GLO file.
354  * \param data The attribute to set and its associated data.
355  */
356  GLSGEN_GLSMOVINGEYE_EXPORT virtual void SetFromGloData(GlsGloFileAttribute &data);
357 #endif
358 
359  /// Type to store eyepoint state information.
360  struct EyeState_t
361  {
362  Vector location;
363  bool orthographic;
364  double FOV;
365  double otherFOV;
366  bool fovIsHorizontal;
367  double orthoSize;
368  double otherOrthoSize;
369  double farClip;
370  double nearClip;
371  FovConstraintType horizontalConstraint;
372  FovConstraintType verticalConstraint;
373  Vector viewVectors[3];
374 
375  /** Default constructor */
376  EyeState_t();
377 
378  /** Initialize EyeState_t using targetEye parameters.
379  * \param movingEye The GlsMovingEye that the state information is for (needed for coordinate conversions)
380  * \param targetEye The GlsEyePoint to move to
381  */
382  EyeState_t(GlsMovingEye* movingEye, GlsEyePoint* targetEye);
383 
384  inline Vector Direction()
385  {
386  /* Copied from GlsEyePoint::Direction() */
387  return viewVectors[2];
388  }
389 
390  };
391 
392  /// Type to store eyepoint movement parameters.
393  struct MoveParms_t : public EyeState_t
394  {
395  bool addToHistory;
396  double time;
397  std::string qualifiedEyeName;
398 
399  MoveParms_t(
400  bool storeHistory,
401  double moveTime,
402  GlsMovingEye* movingEye,
403  GlsEyePoint* targetEye);
404  };
405 
406  /// Whether or not to emit an event when the move has completed.
407  bool _emitEvent;
408 
409  /// This is true when a move is occurring and the route segment being
410  /// moved along is the very first one in the queue. This is used during
411  /// sinusoidal movement to smoothly speed up when starting.
413 
414  /// Current position into the history list
415  unsigned _historyPos;
416 
417  /// Flag to keep track of when the object gets initialized.
419 
420  /// Automatically adjust the view direction to point at the specified
421  /// targetObject. This is inactivated when the string is blank.
422  /// While this is active, the move methods will not control the view
423  /// direction. They can still control the position and other eye
424  /// information.
425  std::string _lookAtObject;
426 
427  /// The last up vector provided by the user or the move code.
428  /// Used by the 'look at' algorithm to orient the eyepoint
430 
431  /// The last up vector calculated by the lookAt algorithm.
433 
434  /// Stores a history of visited eyepoints for moving back and forth.
435  std::vector<MoveParms_t> _moveHistory;
436 
437  bool _disableMoveHistory;
438 
439  /// This specifies the maximum speed in logical units / second which will
440  /// be used to achive the transition. If the requested transition cannot
441  /// occur within the requested move time without exceeding the max speed,
442  /// the move time will be longer than requested. In other words, this
443  /// limit has priority over any requested moveTime. A MaxSpeed value of
444  /// < 0.0 means the speed limit is disabled.
445  float _maxSpeed;
446 
447  /// Type of movement algorithm to use when moving to another eyepoint.
449 
450  /// Contains movement parameters for each move that should be performed.
451  /// The last one contains the final eyepoint to stop at.
452  std::queue<MoveParms_t> _moveQ;
453 
454  /// Type of route to take when moving to another eyepoint.
456 
457  /// Stores this eyepoint's current state at the start of a move and is
458  /// used in calculating movement during each execution frame.
460 
461  /// Latest known simulation time.
462  double _simTime;
463 
464  /// Simulation time that a move starts.
465  double _startTime;
466 
467  /// This specifies the up direction and is used when interpolating
468  /// movement to keep the view oriented 'correctly'.
470 
471  /// This specifies a buffer area around _upVector and -_upVector which
472  /// the moving eye will try to avoid. Setting this to non-zero avoids
473  /// flipping problems when orientation passes through _upVector or -_upVector
474  /// during moves.
476 
477  //------------------------------------------------------------------------
478  /**
479  * Calculates the direction to the named object.
480  */
481  //------------------------------------------------------------------------
482  Vector DirectionToObj(const std::string& qualifiedObjName) const;
483 
484  //------------------------------------------------------------------------
485  /**
486  * Extracts all eyepoint objects from the group hierarchy. The group
487  * can contain other groups and object types.
488  */
489  //------------------------------------------------------------------------
490  void ExtractEyepoints(Group* group, std::vector<GlsEyePoint*>& eyes);
491 
492  //------------------------------------------------------------------------
493  /**
494  * Called when the destination eyepoint is reached to perform actions
495  * necessary to complete the movement.
496  */
497  //------------------------------------------------------------------------
498  void FinishMoving();
499 
500  //------------------------------------------------------------------------
501  /**
502  * Initializes the movement history with the initial state of the eyepoint.
503  */
504  //------------------------------------------------------------------------
505  void Initialize();
506 
507  //------------------------------------------------------------------------
508  /**
509  * Returns an adjusted move time based on the maximum speed setting. If the
510  * speed of moving over distance in desiredTime is greater than the
511  * maximum speed setting, the move time will be lengthened.
512  *
513  * \param distance: distance in logical units that will be moved.
514  * \param desiredTime: time in which we wish to cover the specified
515  * distance.
516  */
517  //------------------------------------------------------------------------
518  float MoveTime(float distance, float desiredTime) const;
519 
520  //------------------------------------------------------------------------
521  /**
522  * Calculates the distance over the entire route if moving between all
523  * eyepoints in the list.
524  */
525  //------------------------------------------------------------------------
526  float RouteDistance(std::vector<GlsEyePoint*>& eyes) const;
527 
528  //------------------------------------------------------------------------
529  /**
530  * Queues the move using the passed in movement parameters and sets up
531  * the start time and starting state of the move.
532  */
533  //------------------------------------------------------------------------
534  void StartMoving(const MoveParms_t& moveParms);
535 
536 
537  /// The editor class needs to access this class' privates. :)
538  friend class GlsMovingEyeEditor;
539 };
540 
541 //----------------------------------------------------------------------------
542 inline
543 std::ostream& operator<<(std::ostream& outstr, GlsMovingEye::Movement_t m)
544 {
545  switch (m)
546  {
547  case GlsMovingEye::CONSTANT:
548  outstr << "CONSTANT";
549  break;
550  case GlsMovingEye::SINUSOIDAL:
551  outstr << "SINUSOIDAL";
552  break;
553  default:
554  outstr << "BAD_MOVEMENT";
555  };
556 
557  return outstr;
558 }
559 
560 //----------------------------------------------------------------------------
561 inline
562 std::istream& operator>>(std::istream& instr, GlsMovingEye::Movement_t& m)
563 {
564  std::string str;
565  instr >> str;
566  if (str == "CONSTANT")
567  {
568  m = GlsMovingEye::CONSTANT;
569  }
570  else if (str == "SINUSOIDAL")
571  {
572  m = GlsMovingEye::SINUSOIDAL;
573  }
574  return instr;
575 }
576 
577 //----------------------------------------------------------------------------
578 inline
579 std::ostream& operator<<(std::ostream& outstr, GlsMovingEye::Route_t r)
580 {
581  switch (r)
582  {
583  case GlsMovingEye::DIRECT:
584  outstr << "DIRECT";
585  break;
586  case GlsMovingEye::ARC:
587  outstr << "ARC";
588  break;
589  default:
590  outstr << "BAD_ROUTE";
591  };
592 
593  return outstr;
594 }
595 
596 //----------------------------------------------------------------------------
597 inline
598 std::istream& operator>>(std::istream& instr, GlsMovingEye::Route_t& r)
599 {
600  std::string str;
601  instr >> str;
602  if (str == "DIRECT")
603  {
604  r = GlsMovingEye::DIRECT;
605  }
606  else if (str == "ARC")
607  {
608  r = GlsMovingEye::ARC;
609  }
610  return instr;
611 }
612 
613 } // namespace disti
614 #endif
615 
unsigned _historyPos
Current position into the history list.
Definition: gls_moving_eye.h:415
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:475
virtual ~GlsMovingEye()
Definition: dynamic_array.h:63
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:432
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:412
#define GLSGEN_GLSMOVINGEYE_EXPORT
Provides support for creating DLLs.
Definition: gls_moving_eye.h:60
virtual void SetAvailableAttributes(unsigned int value)
void MoveToEyeAdd(GlsEyePoint *eye, float moveTime=2.0f)
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:469
Type to store eyepoint state information.
Definition: gls_moving_eye.h:360
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:455
double _simTime
Latest known simulation time.
Definition: gls_moving_eye.h:462
Definition: gls_eyepoint.h:115
float _maxSpeed
Definition: gls_moving_eye.h:445
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:452
virtual DisplayObject * CloneObject(bool generateNames=false)
double _startTime
Simulation time that a move starts.
Definition: gls_moving_eye.h:465
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:435
Definition: group.h:53
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:407
Vector _lookAtReferenceUpVector
Definition: gls_moving_eye.h:429
Definition: vertex.h:84
std::string _lookAtObject
Definition: gls_moving_eye.h:425
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:448
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:538
bool _initialized
Flag to keep track of when the object gets initialized.
Definition: gls_moving_eye.h:418
Definition: bmpimage.h:46
Type to store eyepoint movement parameters.
Definition: gls_moving_eye.h:393
EyeState_t _start
Definition: gls_moving_eye.h:459