gls_moving_eye.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsMovingEye class.
 
  \par Copyright Information
 
  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>
 
  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.
 
  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
 
  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).
 
  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.
 
*/
#ifndef INCLUDED_GLS_MOVING_EYE_H
#define INCLUDED_GLS_MOVING_EYE_H
 
#include <cstddef>
#include <queue>
 
#ifdef __VXWORKS__
#    define va_list std::va_list
#endif
 
#include "gls_cpp_lang_support.h"
#include "gls_eyepoint.h"
 
/// Provides support for creating DLLs.
#if( defined( GLSGEN_EXPORT_GLSMOVINGEYE ) || defined( GLSGEN_IMPORT_GLSMOVINGEYE ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSMOVINGEYE ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GLSMOVINGEYE_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLSMOVINGEYE_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLSMOVINGEYE_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////
 
/// Automatically link the runtime library plugin (on Windows).
#define LIB_BASE_NAME "gls_moving_eye"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME
 
namespace disti
{
// SetValue enumerations
enum
{
    GLS_MOVINGEYE_EMIT_EVENT = GLS_EYEPOINT_VIEW_VECTORS + 1,
    GLS_MOVINGEYE_LOOK_AT_OBJECT,
    GLS_MOVINGEYE_MAX_SPEED,
    GLS_MOVINGEYE_MOVEMENT,
    GLS_MOVINGEYE_ROUTE,
    GLS_MOVINGEYE_DISABLE_HISTORY
};
 
//------------------------------------------------------------------------
/** 
* Runtime implementation of a GlsMovingEye
*/
class GlsMovingEye : public GlsEyePoint
{
private:
    GlsMovingEye& operator=( const GlsMovingEye& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsMovingEye( const GlsMovingEye& ) DISTI_SPECIAL_MEM_FUN_DELETE;
 
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef GlsEyePoint _BaseClass; ///< Deprecated typedef for the base class.
    typedef GlsEyePoint BaseClass;  ///< Typedef for the base class.
 
    /// This specifies the type of route taken from one eyepoint to another.
    enum Movement_t
    {
        CONSTANT   = 0,
        SINUSOIDAL = 1
    };
 
    /// This specifies the type of route taken from one eyepoint to another.
    enum Route_t
    {
        DIRECT = 0,
        ARC    = 1
    };
 
    static const char* MOVE_COMPLETE_EVENT_NAME; ///< Name of the event emitted when a move is completed
 
    //------------------------------------------------------------------------
    /**
    * Create a new GlsMovingEye.
    */
    GLSGEN_GLSMOVINGEYE_EXPORT GlsMovingEye();
 
    /// Copy constructor
    /// \param that The object to copy from.
    /// \param generateNames Whether or not to generate an instance name for this object.
    GLSGEN_GLSMOVINGEYE_EXPORT GlsMovingEye( const GlsMovingEye& that, const bool generateNames );
 
    //------------------------------------------------------------------------
    /** 
    * GlsMovingEyeEditor destructor 
    */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT ~GlsMovingEye();
 
    /// \return True if the we're at the beginning of the history of movements.
    bool AtStartOfHistory() const
    {
        return _historyPos == 0;
    }
 
    /// \return True if the we're at the end of the history of movements.
    bool AtEndOfHistory() const
    {
        return _historyPos == _moveHistory.size() - 1;
    }
 
    //------------------------------------------------------------------------
    /** 
    * Aborts any move currently in progress.
    */
    GLSGEN_GLSMOVINGEYE_EXPORT void AbortMove();
 
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void Calculate( double time ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSMOVINGEYE_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void           CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
    /// \return A pointer to a new GlsMovingEye object.
    static GLSGEN_GLSMOVINGEYE_EXPORT DisplayObject* CreateInstance();
 
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void Draw() DISTI_METHOD_OVERRIDE;
 
    /// \return Whether or not an event is emitted upon completion of a commanded movement.
    bool EmitEvent() const { return _emitEvent; }
 
    /// Sets whether or not an event is emitted upon completion of a commanded movement.
    /// \param emitEvent The new event emit state.
    void EmitEvent( bool emitEvent );
 
    /// \return Whether or not an the move history is disabled.
    bool DisableMoveHistory() const { return _disableMoveHistory; }
 
    /// Sets whether or not the move history is disabled.
    /// \param his The new move history state.
    void DisableMoveHistory( bool his );
 
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void GenerateInstanceName() DISTI_METHOD_OVERRIDE;
 
#ifndef GLES
    virtual GLSGEN_GLSMOVINGEYE_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = 0 ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
    //------------------------------------------------------------------------
    /** 
    * \return The name of the object that the eyepoint should be always
    * looking at.
    * Lifetime is guaranteed to coincide with the GlsMovingEye's lifetime
    * or until LookAtObject is changed.
    */
    const std::string& LookAtObject() const { return _lookAtObject; }
 
    /// Sets the name of the object that the eyepoint should be always looking at.
    /// \param name The name of the object in question.
    void LookAtObject( const std::string& name );
 
    /// \return The maximum speed in logical units/second which will be used to achive the transition between eyepoints.
    float MaxSpeed() const { return _maxSpeed; }
 
    /// Sets the maximum speed in logical units/second which will be used to achive the transition between eyepoints.
    /// \param speed The new speed to set in logical units/second.
    void MaxSpeed( float speed );
 
    /// \return The type of movement algorithm to use when moving to another eyepoint.
    Movement_t Movement() const { return _movement; }
 
    /// Sets the type of movement algorithm to use when moving to another eyepoint.
    /// \param movementType The new movement algorithm to use.
    void Movement( Movement_t movementType );
 
    //------------------------------------------------------------------------
    /** 
    * Moves this eyepoint to the previously set eyepoint. If a move is 
    * already in progress, it will be immediately stopped, and this move 
    * will start.
    */
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveBack();
 
    //------------------------------------------------------------------------
    /** 
    * Moves this eyepoint to the eyepoint which was last achieved from a 
    * MoveBack(). If a move is already in progress, it will be immediately
    * stopped, and this move will start.
    */
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveForward();
 
    /// Causes this eye to move from its current state to the state specified
    /// by the targetEye.  It will take moveTime to get there.  If a move is
    /// already in progress, it will be immediately stopped, and this move
    /// will start.
    /// \param eye The eyepoint to move to.
    /// \param moveTime The time to take in seconds.
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveToEye( GlsEyePoint* eye, float moveTime = 2.0f );
 
    /// Causes the eye to move from its current state to each eyepoint in the
    /// specified group ending with the last eye in the group.  If a move is
    /// already in progress, it will be immediately stopped, and this move
    /// will start.
    /// \param eyeGroup The group to search recursively for GlsEyepoint objects.
    /// \param moveTime The time to take for each move in seconds.
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveToEye( Group* eyeGroup, float moveTime = 2.0f );
 
    /// Causes the specified eye to be added to the end of the list of eyes
    /// which should be moved through.
    /// \param eye The eyepoint to add to the list.
    /// \param moveTime The time to take in seconds.
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveToEyeAdd( GlsEyePoint* eye, float moveTime = 2.0f );
 
    /// Causes the specified eyes to be added to the end of the list of eyes
    /// which should be moved through.
    /// \param eyeGroup The group to search recursively for GlsEyepoint objects.
    /// \param moveTime The time to take for each move in seconds.
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveToEyeAdd( Group* eyeGroup, float moveTime = 2.0f );
 
    /// Causes this eye to move to the specified location in the scene without
    /// modifying the view direction or any other eye specific information.
    /// \param location The location to move to.
    /// \param moveTime The time to take in seconds.
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveToLocation( const Vector& location, float moveTime = 2.0f );
 
    /// Moves the eyepoint in view-relative coordinates by the specified amount.
    /// The units are in relative screen coordinates:
    /// X and Y are pixels, Z is 0->1.  See WindowToLogical() or LogicalToWindow().
    /// \param moveAmount The amount to move on each axis.
    /// \param rotation The amount to rotate on each axis in degrees.
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveRelative( const Vector& moveAmount, const Vector& rotation );
 
    /// \return The type of route to use when moving to another eyepoint.
    Route_t Route() const { return _route; }
 
    /// Sets the type of route to use when moving to another eyepoint.
    /// \param routeType The new route type to set.
    void Route( Route_t routeType );
 
    GLSGEN_GLSMOVINGEYE_EXPORT virtual void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
 
protected:
#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    GLSGEN_GLSMOVINGEYE_EXPORT virtual void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif
 
    /// Type to store eyepoint state information.
    struct EyeState_t
    {
        Vector            location;             ///< Location of the eyepoint in logical units.
        bool              orthographic;         ///< True if orthographic projection, else perspective projection.
        double            FOV;                  ///< Field of view of eyepoint in Degrees, if fovIsHorizontal is true, this is horizontal.
        double            otherFOV;             ///< Field of view for the other direction, based on fovIsHorizontal.
        bool              fovIsHorizontal;      ///< True if field of view measurement is along horizonal axis, else along vertical axis.
        double            orthoSize;            ///< Size of ortho projection in logical units, if fovIsHorizontal is true, this is horizontal.
        double            otherOrthoSize;       ///< Size of ortho projection for the other direction, based on fovIsHorizontal.
        double            farClip;              ///< Distance from eyepoint to near clipping plane.
        double            nearClip;             ///< Distance from eyepoint to far clipping plane.
        FovConstraintType horizontalConstraint; ///< The type of constraint in the horizontal direction.
        FovConstraintType verticalConstraint;   ///< The type of constraint in the vertical direction.
        Vector            viewVectors[ 3 ];     ///< 3 vectors used to set the orientation of the eyepoint.
 
        /** Default constructor */
        EyeState_t();
 
        /** Initialize EyeState_t using targetEye parameters.
          * \param movingEye The GlsMovingEye that the state information is for (needed for coordinate conversions)
          * \param targetEye The GlsEyePoint to move to
          */
        EyeState_t( GlsMovingEye* movingEye, GlsEyePoint* targetEye );
 
        /// Copied from GlsEyePoint::Direction()
        /// \return The Z view vector for this state.
        inline Vector Direction()
        {
            return viewVectors[ 2 ];
        }
    };
 
    /// Type to store eyepoint movement parameters.
    struct MoveParms_t : public EyeState_t
    {
        bool        addToHistory;     ///< If true, will be added to eyepoint movement history.
        double      time;             ///< The amount of time to move in seconds.
        std::string qualifiedEyeName; ///< The name of the eyepoint object to move to.
 
        /// Constructor
        /// \param storeHistory If true, will be added to eyepoint movement history.
        /// \param moveTime The amount of time to move in seconds.
        /// \param movingEye The eye to move.
        /// \param targetEye The eye to move to.
        MoveParms_t( bool storeHistory, double moveTime, GlsMovingEye* movingEye, GlsEyePoint* targetEye );
    };
 
    /// Whether or not to emit an event when the move has completed.
    bool _emitEvent;
 
    /// This is true when a move is occurring and the route segment being
    /// moved along is the very first one in the queue.  This is used during
    /// sinusoidal movement to smoothly speed up when starting.
    bool _firstSegment;
 
    /// Current position into the history list
    std::size_t _historyPos;
 
    /// Flag to keep track of when the object gets initialized.
    bool _initialized;
 
    /// Automatically adjust the view direction to point at the specified
    /// targetObject.  This is inactivated when the string is blank.
    /// While this is active, the move methods will not control the view
    /// direction.  They can still control the position and other eye
    /// information.
    std::string _lookAtObject;
 
    /// The last up vector provided by the user or the move code.
    /// Used by the 'look at' algorithm to orient the eyepoint
    Vector _lookAtReferenceUpVector;
 
    /// The last up vector calculated by the lookAt algorithm.
    Vector _lookAtCalculatedUpVector;
 
    /// Stores a history of visited eyepoints for moving back and forth.
    std::vector<MoveParms_t> _moveHistory;
 
    bool _disableMoveHistory; ///< If true, move history will not be saved.
 
    /// This specifies the maximum speed in logical units / second which will
    /// be used to achive the transition.  If the requested transition cannot
    /// occur within the requested move time without exceeding the max speed,
    /// the move time will be longer than requested.  In other words, this
    /// limit has priority over any requested moveTime.  A MaxSpeed value of
    /// < 0.0 means the speed limit is disabled.
    float _maxSpeed;
 
    /// Type of movement algorithm to use when moving to another eyepoint.
    Movement_t _movement;
 
    /// Contains movement parameters for each move that should be performed.
    /// The last one contains the final eyepoint to stop at.
    std::queue<MoveParms_t> _moveQ;
 
    /// Type of route to take when moving to another eyepoint.
    Route_t _route;
 
    /// Stores this eyepoint's current state at the start of a move and is
    /// used in calculating movement during each execution frame.
    EyeState_t _start;
 
    /// Latest known simulation time.
    double _simTime;
 
    /// Simulation time that a move starts.
    double _startTime;
 
    /// This specifies the up direction and is used when interpolating
    /// movement to keep the view oriented 'correctly'.
    Vector _upVector;
 
    /// This specifies a buffer area around _upVector and -_upVector which
    /// the moving eye will try to avoid.  Setting this to non-zero avoids
    /// flipping problems when orientation passes through _upVector or -_upVector
    /// during moves.
    float _bufferAngle;
 
    /// Calculates the direction to the named object.
    /// \param qualifiedObjName The name of the object in question.
    /// \return A direction Vector pointing from this object to the target, 0,0,0 if not found.
    Vector DirectionToObj( const std::string& qualifiedObjName ) const;
 
    /// Extracts all eyepoint objects from the group hierarchy.
    /// The group can contain other groups and object types.
    /// \param group The group to search for eyepoints in recursively.
    /// \param eyes The returned list of found eyepoints.
    void ExtractEyepoints( Group* group, std::vector<GlsEyePoint*>& eyes );
 
    //------------------------------------------------------------------------
    /** 
    * Called when the destination eyepoint is reached to perform actions
    * necessary to complete the movement.
    */
    //------------------------------------------------------------------------
    void FinishMoving();
 
    //------------------------------------------------------------------------
    /** 
    * Initializes the movement history with the initial state of the eyepoint.
    */
    //------------------------------------------------------------------------
    void Initialize();
 
    /// Returns an adjusted move time based on the maximum speed setting. If the
    /// speed of moving over distance in desiredTime is greater than the
    /// maximum speed setting, the move time will be lengthened.
    /// \param distance Distance in logical units that will be moved.
    /// \param desiredTime Time in which we wish to cover the specified distance.
    /// \return The adjusted move time in seconds.
    float MoveTime( float distance, float desiredTime ) const;
 
    /// Calculates the distance over the entire route if moving between all eyepoints in the list.
    /// \param eyes The list of eyes to calculate the total route distance.
    /// \return The total distance of the route in logical units.
    float RouteDistance( std::vector<GlsEyePoint*>& eyes ) const;
 
    /// Queues the move using the passed in movement parameters and sets up
    /// the start time and starting state of the move.
    /// \param moveParms The move parameters for this move.
    void StartMoving( const MoveParms_t& moveParms );
 
    friend class GlsMovingEyeEditor;
};
 
/// Stream out operator
/// \param outstr The stream to write to.
/// \param m The value to write to the stream.
/// \return The stream in its current state.
inline std::ostream& operator<<( std::ostream& outstr, GlsMovingEye::Movement_t m )
{
    switch( m )
    {
    case GlsMovingEye::CONSTANT:
        outstr << "CONSTANT";
        break;
    case GlsMovingEye::SINUSOIDAL:
        outstr << "SINUSOIDAL";
        break;
    default:
        outstr << "BAD_MOVEMENT";
    };
 
    return outstr;
}
 
/// Stream in operator
/// \param instr The stream to read from.
/// \param m The returned value read from the stream.
/// \return The stream in its current state.
inline std::istream& operator>>( std::istream& instr, GlsMovingEye::Movement_t& m )
{
    std::string str;
    instr >> str;
    if( str == "CONSTANT" )
    {
        m = GlsMovingEye::CONSTANT;
    }
    else if( str == "SINUSOIDAL" )
    {
        m = GlsMovingEye::SINUSOIDAL;
    }
    return instr;
}
 
/// Stream out operator
/// \param outstr The stream to write to.
/// \param r The value to write to the stream.
/// \return The stream in its current state.
inline std::ostream& operator<<( std::ostream& outstr, GlsMovingEye::Route_t r )
{
    switch( r )
    {
    case GlsMovingEye::DIRECT:
        outstr << "DIRECT";
        break;
    case GlsMovingEye::ARC:
        outstr << "ARC";
        break;
    default:
        outstr << "BAD_ROUTE";
    };
 
    return outstr;
}
 
/// Stream in operator
/// \param instr The stream to read from.
/// \param r The returned value read from the stream.
/// \return The stream in its current state.
inline std::istream& operator>>( std::istream& instr, GlsMovingEye::Route_t& r )
{
    std::string str;
    instr >> str;
    if( str == "DIRECT" )
    {
        r = GlsMovingEye::DIRECT;
    }
    else if( str == "ARC" )
    {
        r = GlsMovingEye::ARC;
    }
    return instr;
}
 
} // namespace disti
#endif