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 _GLSMOVINGEYE_H
#define _GLSMOVINGEYE_H

#include <queue>

#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
///////////////////////////////////////////////////////////////////////////////

#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:
    typedef GlsEyePoint _BaseClass;

    /// 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
    };

    // Name of the event emitted when a move is completed
    static const char* MOVE_COMPLETE_EVENT_NAME;

    //------------------------------------------------------------------------
    /**
    * Create a new GlsMovingEye.
    */
    GLSGEN_GLSMOVINGEYE_EXPORT GlsMovingEye();

    GLSGEN_GLSMOVINGEYE_EXPORT GlsMovingEye( const GlsMovingEye& that, const bool generateNames );

    //------------------------------------------------------------------------
    /** 
    * GlsMovingEyeEditor destructor 
    */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT ~GlsMovingEye();

    //------------------------------------------------------------------------
    /** 
    * Returns true if the we're at the beginning of the history of movements.
    */
    bool AtStartOfHistory() const
    {
        return _historyPos == 0;
    }

    //------------------------------------------------------------------------
    /** 
    * Returns 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 );

    //------------------------------------------------------------------------
    /* See base class */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void Calculate( double time );

    //------------------------------------------------------------------------
    /* See base class */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT
        DisplayObject*
        CloneObject( bool generateNames = false );

    //------------------------------------------------------------------------
    /* See base class */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void CopyProperties( DisplayObject* src );

    //------------------------------------------------------------------------
    /** 
    * Creates a new, blank GlsMovingEye object.
    * \return DisplayObject type pointer to the new GlsMovingEye.
    */
    static GLSGEN_GLSMOVINGEYE_EXPORT DisplayObject* CreateInstance();

    //------------------------------------------------------------------------
    /* See base class */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void Draw();

    //------------------------------------------------------------------------
    /** 
    * Returns 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. 
    */
    void EmitEvent( bool emitEvent );

    //------------------------------------------------------------------------
    /** 
    * Returns whether or not an the move history is disabled. 
    */
    bool DisableMoveHistory() const { return _disableMoveHistory; }

    //------------------------------------------------------------------------
    /** 
    * Sets whether or not the move history is disabled. 
    */
    void DisableMoveHistory( bool his );

    //------------------------------------------------------------------------
    /* See base class */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void GenerateInstanceName();

#ifndef GLES
    //------------------------------------------------------------------------
    /* See base class */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT
        InterfaceListType*
        GetCppInterfaceDescription(
            InterfaceListType* addToThisList = 0 );

    //------------------------------------------------------------------------
    /* See base class */
    virtual GLSGEN_GLSMOVINGEYE_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array );
#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. 
    */
    void LookAtObject( const std::string& name );

    //------------------------------------------------------------------------
    /** 
    * Returns 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.  
    */
    void MaxSpeed( float speed );

    //------------------------------------------------------------------------
    /** 
    * Returns 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.
    */
    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.
    */
    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.
    */
    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.
    */
    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.
    */
    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.  
    */
    GLSGEN_GLSMOVINGEYE_EXPORT
    void MoveToLocation( const Vector& location, float moveTime = 2.0f );

    //------------------------------------------------------------------------
    /** 
    * Moves the eyepoint in view-relative coordinates by the specified amount,
    * over the specified time.  The units are in relative screen coordinates:
    * X and Y are pixels, Z is 0->1.  See WindowToLogical() or 
    * LogicalToWindow().
    */
    GLSGEN_GLSMOVINGEYE_EXPORT void MoveRelative(
        const Vector& moveAmount,
        const Vector& rotation );

    //------------------------------------------------------------------------
    /** 
    * Returns 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.
    */
    void Route( Route_t routeType );

    //------------------------------------------------------------------------
    /* See base class */
    GLSGEN_GLSMOVINGEYE_EXPORT virtual void SetValue( int spec, va_list& args );

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 );
#endif

    /// Type to store eyepoint state information.
    struct EyeState_t
    {
        Vector            location;
        bool              orthographic;
        double            FOV;
        double            otherFOV;
        bool              fovIsHorizontal;
        double            orthoSize;
        double            otherOrthoSize;
        double            farClip;
        double            nearClip;
        FovConstraintType horizontalConstraint;
        FovConstraintType verticalConstraint;
        Vector            viewVectors[ 3 ];

        /** 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 );

        inline Vector Direction()
        {
            /*  Copied from GlsEyePoint::Direction() */
            return viewVectors[ 2 ];
        }
    };

    /// Type to store eyepoint movement parameters.
    struct MoveParms_t : public EyeState_t
    {
        bool        addToHistory;
        double      time;
        std::string qualifiedEyeName;

        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
    unsigned _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;

    /// 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.
    */
    //------------------------------------------------------------------------
    Vector DirectionToObj( const std::string& qualifiedObjName ) const;

    //------------------------------------------------------------------------
    /** 
    * Extracts all eyepoint objects from the group hierarchy.  The group
    * can contain other groups and object types.
    */
    //------------------------------------------------------------------------
    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.
    */
    //------------------------------------------------------------------------
    float MoveTime( float distance, float desiredTime ) const;

    //------------------------------------------------------------------------
    /** 
    * Calculates the distance over the entire route if moving between all
    * eyepoints in the list.
    */
    //------------------------------------------------------------------------
    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.
    */
    //------------------------------------------------------------------------
    void StartMoving( const MoveParms_t& moveParms );

    /// The editor class needs to access this class' privates. :)
    friend class GlsMovingEyeEditor;
};

//----------------------------------------------------------------------------
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;
}

//----------------------------------------------------------------------------
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;
}

//----------------------------------------------------------------------------
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;
}

//----------------------------------------------------------------------------
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