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;
 
/// The EyePointCalcViewCallbackBase class.
class EyePointCalcViewCallbackBase
{
public:
    virtual ~EyePointCalcViewCallbackBase() {}
 
    /// The callback method interface, used for custom user callbacks to configure the eyepoint's view.
    /// \param viewWidth The view width in pixels.
    /// \param viewHeight The view height in pixels.
    /// \param thisEye The GlsEyePoint associated with this callback.
    /// \param rval1 Returned user defined value.
    /// \param rval2 Another returned user defined value.
    virtual void Call( int viewWidth, int viewHeight, GlsEyePoint* thisEye, double& rval1, double& rval2 ) = 0;
};
 
/// The EyePointCalcViewCallback class.
template<class T>
class EyePointCalcViewCallback : public EyePointCalcViewCallbackBase
{
public:
    typedef void ( T::*MethodType )( int viewWidth, int viewHeight, GlsEyePoint* thisEye, double& rval1, double& rval2 ); ///< Typedef for the callback function pointer.
 
    T*         _container; ///< The object which contains the method to call.
    MethodType _method;    ///< The callback method function pointer.
 
    /// Construct a new EyePointCalcViewCallback object.
    /// \param container The object containing the callback method.
    /// \param method The callback function pointer to call.
    EyePointCalcViewCallback( T* container, MethodType method )
        : _container( container )
        , _method( method )
    {
    }
 
    void Call( int viewWidth, int viewHeight, GlsEyePoint* thisEye, double& rval1, double& rval2 ) DISTI_METHOD_OVERRIDE
    {
        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; ///< Deprecated typedef for the base class.
    typedef DisplayObject BaseClass;  ///< Typedef for the base class.
    friend class GlsEyePointEditor;
 
    /// The FovConstraintType enum. Defines view constraint behavior.
    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.
    /// \note This affects all eyepoint instances.
    /// \param draw The new debug state to set.
    static GLS_EXPORT void DrawDebugGeometry( bool draw ) { _drawDebugGeometry = draw; }
 
    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();
 
    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() 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.
    /// \param selected If true, this object is currently selected.
    /// \param orthographic If true, this eyepoint is orthographic, otherwise it is perspective.
    /// \param fovIsHorizontal If true the field of view is horizontal, otherwise it is vertical.
    /// \param orthoSize The width of the orthographic view in pixels.
    /// \param otherOrthoSize The height of the orthographic view in pixels.
    /// \param fov The width of the view in degrees, height if fovIsHorizontal is true.
    /// \param otherFov The height of the view in degrees, width if fovIsHorizontal is true.
    /// \param horizontalConstraint The horizontal constraint behavior.
    /// \param verticalConstraint The vertical constraint behavior.
    /// \param farClip The far clip distance.
    /// \param nearClip The near clip distance.
    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
 
    virtual GLS_EXPORT void CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
#ifndef GLES
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* list ) DISTI_METHOD_OVERRIDE;
#endif
 
    /* Unhides base class implementation. */
    using BaseClass::Rotate;
    virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;
 
    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.
    /// \param val The new horizontal constraint behavior to set.
    GLS_EXPORT void HorizontalConstraint( FovConstraintType val );
 
    /// Sets the constraint for the vertical direction.
    /// \param val The new vertical constraint behavior to set.
    GLS_EXPORT void VerticalConstraint( FovConstraintType val );
 
    /// Allows the view vectors to be set directly.
    /// \note These are normally controlled by the Orientation call.
    /// \param x The new X view vector to set.
    /// \param y The new Y view vector to set.
    /// \param z The new Z view vector to set.
    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();
 
    /** 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();
 
    /** 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();
 
    /** 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();
 
    /// The direction this returns is set by FovIsHorizontal. If true, it is horizontal.
    /// \return The size of the orthographic projection, in logical units.
    GLS_EXPORT double OrthoSize();
 
    /// The direction this returns is set by FovIsHorizontal. If true, it is vertical.
    /// \return The size of the orthographic projection, in logical units.
    GLS_EXPORT double OtherOrthoSize();
 
    /** 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();
 
    /** 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();
 
    /// \return the constraint for the horizontal direction
    GLS_EXPORT FovConstraintType HorizontalConstraint();
 
    /// \return the constraint for the vertical direction
    GLS_EXPORT FovConstraintType VerticalConstraint();
 
    /// Returns the current view vectors.
    /// \param x The returned X view vector.
    /// \param y The returned Y view vector.
    /// \param z The returned Z view vector.
    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();
 
    /** 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.
    /// \param viewWidth The width of the view in pixels.
    /// \param viewHeight The height of the view in pixels.
    /// \param thisEye The associated eyepoint (this).
    /// \param fovY The vertical field of view in degrees.
    /// \param aspect The aspect ratio width / height.
    virtual GLS_EXPORT void CalcOrthographicView( int viewWidth, int viewHeight, GlsEyePoint* thisEye, double& fovY, double& aspect );
 
    /// Called by ApplyViewMatrices() to do the sizing logic.
    /// \param viewWidth The width of the view in pixels.
    /// \param viewHeight The height of the view in pixels.
    /// \param thisEye The associated eyepoint (this).
    /// \param fovY The vertical field of view in degrees.
    /// \param aspect The aspect ratio width / height.
    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();
#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 );
 
    /// Assigns a custom user defined callback to be called to configure the orthographic view instead of GlsEyePoint's default behavior.
    /// \param eye The associated eyepoint.
    /// \param container The object containing the callback method.
    /// \param method The callback function pointer to call.
    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 );
    }
 
    /// Assigns a custom user defined callback to be called to configure the perspective view instead of GlsEyePoint's default behavior.
    /// \param eye The associated eyepoint.
    /// \param container The object containing the callback method.
    /// \param method The callback function pointer to call.
    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
///////////////////////////////////////////////////////////
/// The DistiAttributeFovConstraintTypeEnum class.
class DistiAttributeFovConstraintTypeEnum : public DistiAttributeEnum<GlsEyePoint, GlsEyePoint::FovConstraintType, GlsEyePoint::FovConstraintType>
{
public:
    /// Create a new DistiAttributeFovConstraintTypeEnum object.
    /// \param frame The GlsEyePoint object holding the Fov constraint property.
    /// \param setMethod The set method function pointer.
    /// \param getMethod The get method function pointer.
    /// \param name The name of the associated property.
    GLS_EXPORT DistiAttributeFovConstraintTypeEnum( GlsEyePoint* frame, SetMethodType setMethod, GetMethodType getMethod, const AttributeName& name );
 
    virtual GLS_EXPORT ~DistiAttributeFovConstraintTypeEnum();
};
 
} // namespace disti
 
#endif