gls_eyepoint.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsEyePoint class.  Implements eyepoints.

  \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 _GLS_EYEPOINT_H
#define _GLS_EYEPOINT_H

#include "display.h"
#include "disti_metadata.h"
#include "gls_color.h"
#include "gls_cpp_lang_support.h"
#include "gls_include.h"
#include "gls_metadata_attributes.h"

namespace disti
{
/**
    Eye Point Initializers
*/
typedef enum
{
    GLS_EYEPOINT_FOV = GLS_LAST_INITIALIZER + 1,
    GLS_EYEPOINT_ORTHOGRAPHIC,
    GLS_EYEPOINT_ORTHO_SIZE,
    GLS_EYEPOINT_FOV_IS_HORIZONTAL,
    GLS_EYEPOINT_ASPECT,
    GLS_EYEPOINT_NEAR_CLIP,
    GLS_EYEPOINT_FAR_CLIP,
    GLS_EYEPOINT_MAINTAIN_ASPECT,
    GLS_EYEPOINT_VIEW_VECTORS
} GLS_EyePoint_Initializers;

class GlsEyePoint;

/** Eye Point Calc View Callback Base */
class EyePointCalcViewCallbackBase
{
public:
    virtual ~EyePointCalcViewCallbackBase() {}
    virtual void Call( int viewWidth,
        int                viewHeight,
        GlsEyePoint*       thisEye,
        double&            rval1,
        double&            rval2 )
        = 0;
};
template<class T>
/** Eye Point Calc View Callback */
class EyePointCalcViewCallback : public EyePointCalcViewCallbackBase
{
public:
    typedef void ( T::*MethodType )(
        int          viewWidth,
        int          viewHeight,
        GlsEyePoint* thisEye,
        double&      rval1,
        double&      rval2 );
    // The object which contains the method to call
    T*         _container;
    MethodType _method;

    EyePointCalcViewCallback( T* container, MethodType method )
        : _container( container )
        , _method( method )
    {
    }
    void Call( int   viewWidth,
        int          viewHeight,
        GlsEyePoint* thisEye,
        double&      rval1,
        double&      rval2 )
    {
        if( _container )
            ( _container->*( _method ) )( viewWidth, viewHeight, thisEye, rval1, rval2 );
    }
};
/**
  The GlsEyePoint class.  Implements Eyepoints
*/
class GlsEyePoint : public DisplayObject
{
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef DisplayObject _BaseClass;
    typedef DisplayObject BaseClass;
    friend class GlsEyePointEditor;

    typedef enum
    {
        FOV_CONSTRAINT_NONE,
        FOV_CONSTRAINT_GREATER,
        FOV_CONSTRAINT_LESS,
        FOV_CONSTRAINT_EXACTLY
    } FovConstraintType;

private:
    static bool _drawDebugGeometry; /** Causes eyepoints to draw debugging geometry.  Defaults to false. */

protected:
    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              _orthographic;         /** True if orthographic projection, else perspective projection */
    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 */
    bool              _fovIsHorizontal;      /** True if field of view measurement is along horizonal axis, else along vertical axis */
    FovConstraintType _horizontalConstraint; /** The type of constraint in the horizontal direction */
    FovConstraintType _verticalConstraint;   /** The type of constraint in the vertical direction */
    double            _nearClip;             /** Distance from eyepoint to near clipping plane */
    double            _farClip;              /** Distance from eyepoint to far clipping plane */
    Vector            _viewVectors[ 3 ];     /** 3 vectors used to set the orientation of the eyepoint */

    EyePointCalcViewCallbackBase* _alternateCalcOrthographicView; /** Alternate callback for calculating the orthographic view */
    EyePointCalcViewCallbackBase* _alternateCalcPerspectiveView;  /** Alternate callback for calculating the perspective view */

#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    virtual GLS_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif

public:
    /** Set DrawDebugGeometry to true to cause eyepoints to draw at runtime.
      * This affects all eyepoint instances.
      */
    static GLS_EXPORT void DrawDebugGeometry( bool draw ) { _drawDebugGeometry = draw; }

    /* See base class */
    virtual GLS_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;

    /** Allocate a (blank) EyePoint object */
    GLS_EXPORT GlsEyePoint();

    /** The copy constructor for GlsEyePoint
      * 
      * \param that          The GlsEyePoint object that is being copied
      * \param generateNames Whether or not to generate a new instance name
      */
    GLS_EXPORT GlsEyePoint( const GlsEyePoint& that, const bool generateNames );

    /** Destroy an Eyepoint object */
    virtual GLS_EXPORT ~GlsEyePoint( void );

    virtual GLS_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;

    /** Draws does nothing because this object is not a visible object,
      * unless DrawDebugGeometry() is true, then it draws the view frustum. */
    virtual GLS_EXPORT void Draw( void ) DISTI_METHOD_OVERRIDE;

#ifndef GLES
    /** Draws a representation of the frustum.  This is done primarily for the editor.
      * but is available at runtime.  The specific values can be specified to avoid
      * making the editor set them and set them back.*/
    virtual GLS_EXPORT void DrawFrustum(
        bool              selected,
        bool              orthographic,
        bool              fovIsHorizontal,
        double            orthoSize,
        double            otherOrthoSize,
        double            fov,
        double            otherFov,
        FovConstraintType horizontalConstraint,
        FovConstraintType verticalConstraint,
        double            farClip,
        double            nearClip );
#endif

    /* See base class */
    virtual GLS_EXPORT void CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;

#ifndef GLES
    /* See base class */
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLS_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* list ) DISTI_METHOD_OVERRIDE;
#endif

    /* Unhides base class implementation. */
    using BaseClass::Rotate;

    /* See base class */
    virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;

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

    /** Sets the Field Of View for this eyepoint.
      * If FovIsHorizontal, this is the horizontal fov.
      * \param fovDeg  The new field of view, in degrees
      */
    GLS_EXPORT void FOV( double fovDeg );

    /** Sets the Field Of View for this eyepoint.
      * If FovIsHorizontal, this is the vertical fov.
      * \param fovDeg  The new field of view, in degrees
      */
    GLS_EXPORT void OtherFOV( double fovDeg );

    /** Sets whether or not the field of view measurement is along horizontal or vertical axis
      * \param val  True if FOV measurement is along horizonal axis of eyepoint
      */
    GLS_EXPORT void FovIsHorizontal( bool val );

    /** Sets whether the eyepoint uses an orthographic projection or a perspective projection
      * \param val  True if the eypoint uses an orthographic projection.  False if it uses a perspective projection.
      */
    GLS_EXPORT void Orthographic( bool val );

    /** Sets the size of the orthographic projection, in logical units.  
      * The direction this controls is set by FovIsHorizontal.  If true, it is horizontal.
      * \param val The size of the orthographic projection, in logical units
      */
    GLS_EXPORT void OrthoSize( double val );

    /** Sets the size of the orthographic projection, in logical units.  
      * The direction this controls is set by FovIsHorizontal.  If true, it is vertical.
      * \param val The size of the orthographic projection, in logical units
      */
    GLS_EXPORT void OtherOrthoSize( double val );

    /** Sets the distance to the near clipping plane from the eyepoint
      * \param val  Distance to the near clipping plane from the eyepoint in logical units
      */
    GLS_EXPORT void NearClip( double val );

    /** Sets the distance to the far clipping plane from the eyepoint
      * \param val  Distance to the far clipping plane from the eyepoint in logical units
      */
    GLS_EXPORT void FarClip( double val );

    /** Sets the constraint for the horizontal direction
      */
    GLS_EXPORT void HorizontalConstraint( FovConstraintType val );

    /** Sets the constraint for the vertical direction
      */
    GLS_EXPORT void VerticalConstraint( FovConstraintType val );

    /** Allows the view vectors to be set directly.  
      * These are normally controlled by the Orientation call
      */
    GLS_EXPORT void SetViewVectors( const Vector& x, const Vector& y, const Vector& z );

    /** Gets the Field Of View for this eyepoint.  
      * If FovIsHorizontal is true, this is the horizontal fov.
      * \return  The field of view, in degrees
      */
    GLS_EXPORT double FOV( void );

    /** Gets the Field Of View for this eyepoint.  
      * If FovIsHorizontal is true, this is the vertical fov.
      * \return  The field of view, in degrees
      */
    GLS_EXPORT double OtherFOV( void );

    /** Gets whether or not the field of view measurement is along horizontal or vertical axis
      * \return True if FOV measurement is along horizonal axis of eyepoint
      */
    GLS_EXPORT bool FovIsHorizontal( void );

    /** Gets whether the eyepoint uses an orthographic projection or a perspective projection
      * \return  True if the eypoint uses an orthographic projection.  False if it uses a perspective projection.
      */
    GLS_EXPORT bool Orthographic( void );

    /** Sets the size of the orthographic projection, in logical units.  
      * The direction this returns is set by FovIsHorizontal.  If true, it is horizontal.
      */
    GLS_EXPORT double OrthoSize( void );

    /** Sets the size of the orthographic projection, in logical units.  
      * The direction this returns is set by FovIsHorizontal.  If true, it is vertical.
      */
    GLS_EXPORT double OtherOrthoSize( void );

    /** Gets the distance to the near clipping plane from the eyepoint
      * \return  Distance to the near clipping plane from the eyepoint in logical units
      */
    GLS_EXPORT double NearClip( void );

    /** Gets the distance to the far clipping plane from the eyepoint
      * \return  Distance to the far clipping plane from the eyepoint in logical units
      */
    GLS_EXPORT double FarClip( void );

    /** Gets the constraint for the horizontal direction
      */
    GLS_EXPORT FovConstraintType HorizontalConstraint( void );

    /** Gets the constraint for the vertical direction
      */
    GLS_EXPORT FovConstraintType VerticalConstraint( void );

    /** Returns the current view vectors.
      */
    GLS_EXPORT void GetViewVectors( Vector& x, Vector& y, Vector& z );

    /** Sets the orientation of the eyepoint
      * \param direction  A direction vector
      * \param roll  A roll value about the direction vector, in degrees
      * \param upVector defines the "up" direction for the purposes of calculating roll.
      */
    GLS_EXPORT void Orientation( const Vector& direction, float roll, const Vector& upVector = Vector( 0, 1, 0 ) /* Y Axis */ );

    /** Gets the current direction vector of the eyepoint
      * \return The direction vector
      */
    GLS_EXPORT Vector Direction( void );

    /** Gets the current roll angle of the eyepoint
      * \return The current roll
      * \param upVector The "up" direction used for determining roll.
      */
    GLS_EXPORT float Roll( const Vector upVector = Vector( 0, 1, 0 ) /* Y Axis */ );

    /** Called by ApplyViewMatrices() to do the sizing logic 
      */
    virtual GLS_EXPORT void CalcOrthographicView(
        int          viewWidth,
        int          viewHeight,
        GlsEyePoint* thisEye,
        double&      fovY,
        double&      aspect );

    /** Called by ApplyViewMatrices() to do the sizing logic 
      */
    virtual GLS_EXPORT void CalcPerspectiveView(
        int          viewWidth,
        int          viewHeight,
        GlsEyePoint* thisEye,
        double&      fovY,
        double&      aspect );

#ifdef GLES
    /** Calculates and applies the projection and modelview matrices for this eyepoint
     * \param proj   The projection matrix (returned)
     * \param modelView  The modelview matrix (returned)
     * \param width  The current view width
     * \param height  The current view height
     */
    virtual GLS_EXPORT void ApplyViewMatrices( GlsMatrixType& proj, GlsMatrixType& modelView, int width, int height );
#else
    /** Calculates and applies the projection and modelview matrices for this eyepoint */
    virtual GLS_EXPORT void ApplyViewMatrices( void );
#endif

    /** Returns the modelview matrix for this eyepoint.
      * \param modelview Output
      * \param includeEyeToWorld If true, will include all transforms up to the top of the hierarcy.
      */
    virtual GLS_EXPORT void GetModelViewMatrix( GlsMatrixType& modelview, bool includeEyeToWorld = true );
    /** Returns the projection matrix for this eyepoint
      * \param proj The requested projection matrix
      * \param viewW The width of the view in pixels
      * \param viewH The height of the view in pixels
      */
    virtual GLS_EXPORT void GetProjectionMatrix( GlsMatrixType& proj, int viewW, int viewH );

    template<class T>
    static void SetAlternateCalcOrthographicView( GlsEyePoint* eye, T* container, typename EyePointCalcViewCallback<T>::MethodType method )
    {
        if( !eye )
            return;
        if( eye->_alternateCalcOrthographicView )
            delete eye->_alternateCalcOrthographicView;
        eye->_alternateCalcOrthographicView = new EyePointCalcViewCallback<T>( container, method );
    }
    template<class T>
    static void SetAlternateCalcPerspectiveView( GlsEyePoint* eye, T* container, typename EyePointCalcViewCallback<T>::MethodType method )
    {
        if( !eye )
            return;
        if( eye->_alternateCalcPerspectiveView )
            delete eye->_alternateCalcPerspectiveView;
        eye->_alternateCalcPerspectiveView = new EyePointCalcViewCallback<T>( container, method );
    }

private:
    // Returns the 16 doubles representing the ModelView matrix
    // Must set with bool_includeEyeToWorld before reading
    GLS_EXPORT GlsPropString GetModelViewMatrix();
    GLS_EXPORT void          GetModelViewMatrix( const GlsPropString& bool_includeEyeToWorld );
    bool                     _getModelViewMatrixIncludeEyeToWorld;

    // Returns the 16 doubles representing the Projection matrix
    // Must set with int_width_height before reading
    GLS_EXPORT GlsPropString GetProjectionMatrix();
    GLS_EXPORT void          GetProjectionMatrix( const GlsPropString& int_width_height );
    int                      _getProjectionMatrixWidth;
    int                      _getProjectionMatrixHeight;

    /** Assignment operator not implemented. Use CloneObject() or the copy constructor instead. */
    GlsEyePoint& operator=( const GlsEyePoint& that ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsEyePoint( const GlsEyePoint& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};

///////////////////////////////////////////////////////////
// DistiAttributeFovConstraintTypeEnum
///////////////////////////////////////////////////////////
/** Disti Attribute Fov Constrain tType Enum */
class DistiAttributeFovConstraintTypeEnum : public DistiAttributeEnum<GlsEyePoint, GlsEyePoint::FovConstraintType, GlsEyePoint::FovConstraintType>
{
public:
    GLS_EXPORT DistiAttributeFovConstraintTypeEnum( GlsEyePoint* frame, SetMethodType setMethod, GetMethodType getMethod, const AttributeName& name );
    virtual GLS_EXPORT ~DistiAttributeFovConstraintTypeEnum();
};

} // namespace disti

#endif