gls_display_object.h

Go to the documentation of this file.

#ifndef _GLS_DISPLAY_OBJECT_H
#define _GLS_DISPLAY_OBJECT_H

/*! \file gls_display_object.h
\brief  This header defines the base class for all graphical objects in
        the GL Studio DO-178B Runtime Library.

\par Copyright Information
Copyright (C) 1999-2012 The DiSTI Corporation<br>
Orlando, FL USA<br>
All rights reserved.<br>

  This file is copyrighted software and contains proprietary trade secrets of
DiSTI, and embodies substantial creative efforts as well as confidential
information, ideas, and expressions.

  Permission to use, and copy this software and its documentation for any
purpose is hereby granted per the Distribution Agreement and/or the Licensing
Agreement signed with DiSTI. This permission is granted provided that:
    1.  The above copyright notice appears in all copies.
    2.  That both the copyright notice and this permission notice appear in
        the supporting documentation.
    3.  That the names DiSTI and GL Studio not be used in advertising or
        publicity pertaining to distribution of the software without specific,
        written prior permission of DiSTI.
 
  Permission to modify the software is granted, but not the right to
distribute the source code whether modified, or non-modified.  Modifying the
software might invalidate the DO-178B certification package.

  Permission to distribute binaries produced by compiling source code, or
modified source code is granted, provided you:
    1.  Provide your name and address as the primary contact for the support
        of your modified version.
    2.  Retain our contact information in regard to use of the base software. 

   DiSTI does not provide warranty for this software or guarantee that it
satisfies any specification or requirement unless otherwise stated in a
specific contractual arrangement between the customer and DiSTI.

*/

#include "gls_include.h"
#include "gls_types.h"
#include "gls_gl.h"
#include "gls_assert.h"
#include "gls_vertex.h"
#include "gls_matrix_affine_double.h"
#include "gls_event.h"

// forward ref
class GlsStateManager;
class GlsInputManager;

/** Base Class for all graphical objects. It is an abstract class.
  *  All drawn objects are derived from this class.
  *  \invariant _dcsMatrix.Invariant(),  _location.IsValid(), GlsDisplayObjectTypeIsValid( _objectType ),
  *             GlsDisplayObjectPickModeIsValid( _pickMode ), _pickRegion.IsValid(),
  *             _rotationPoint.IsValid(), _blinkRate > 0.0f, _drawMatrix.Invariant(), _dynamicRotation.IsValid(),
  *             _dynamicScale.IsValid(), 
  *             ( _dynamicScale.x >= 0.0f ) && ( _dynamicScale.y >= 0.0f ) && ( _dynamicScale.z >= 0.0f ),
  *             _dynamicTranslation.IsValid()
  */
class GlsDisplayObject
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsDisplayObject )

    /** Enumeration for possible base object types */
    enum ObjectType
    {
        OBJECT_TYPE_COMPOSITE,  /**< Object is derived from GlsCompositeObject */
        OBJECT_TYPE_RENDERABLE, /**< Object is dervied from GlsRenderObject */

        #if defined( GLS_DEBUG )
            OBJECT_TYPE_INVALID /**< Invalid object type ( GLS_DEBUG only ) */
        #endif // GLS_DEBUG
    };

    /** Enumeration for possible pick modes */
    enum PickMode
    {
        PICK_MODE_NEVER,      /**< Picking will be disabled for this object */
        PICK_MODE_FIRST,      /**< Picking is based on draw order only.  The first geometry hit wins. */
        PICK_MODE_ALWAYS,     /**< Picking will ignore geometry of this object, and always return a pick as if hit.
                                * This is still only found through normal draw order traversal.*/

        #if defined( GLS_DEBUG )
            PICK_MODE_INVALID /**< Invalid pick mode ( GLS_DEBUG only ) */
        #endif // GLS_DEBUG
    };

    /** describes a 3D rectangular picking region */
    struct PickRegion
    {
        GlsVector3D lowerNearLeft;  /**< lower left near point of region */
        GlsVector3D upperFarRight;  /**< upper right far point of region */

        #if defined( GLS_DEBUG )
            /** Determine if region is valid ( GLS_DEBUG only )
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /** initialization parameters for a GlsDisplayObject */
    struct InitParameters
    {
        const GlsBool                        blinking;         /**< GLS_TRUE if object is initially blinking
                                                                 * else GLS_FALSE */
        const GlsFloat32                     blinkRate;        /**< blinking rate (Hz.) (>0.0) */
        const GlsMatrixAffineD::CStyleMatrix dcsMatrix;        /**< dcs matrix of object */
        const GlsMatrixAffineD::CStyleMatrix dcsMatrixInverse; /**< inverse of dcs matrix */
        const GlsVector3D                    location;         /**< location of object */
        const GlsBool                        needCalculate;    /**< GLS_TRUE if object needs Calculate() method called
                                                                 * else GLS_FALSE */
        const PickMode                       pickMode;         /**< initial pick mode for object */
        const PickRegion                     pickRegion;       /**< pick region for object */
        const GlsVector3D                    rotationPoint;    /**< location, in the object coordinate system,
                                                                 * of the rotation point */
        const GlsBool                        visible;          /**< GLS_TRUE if object is initially visible
                                                                 * else GLS_FALSE */

        #if defined( GLS_DEBUG )
            /** Validate initialization parameters ( GLS_DEBUG only )
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif
    };

    /** Draws this object. Pure virtual method
      * \param gl GL State manager for OpenGL into which object is drawn
      * \param time the elaspsed time in seconds since program start
      * \pre time >= 0.0
      * \post object is drawn to OpenGL if visible and not blinked off
      */
    virtual void Draw( GlsStateManager &gl, const GlsFloat64 time ) = 0;

    /** Provides a mechanism for performing regular calculations, separate 
      * from drawing.  In a standalone applicaton Calculate is recursively 
      * called by the main loop before the objects are drawn.
      * \param time The elaspsed time in seconds since program start
      * \pre time >= 0.0
      * \post calculations (if any) completed
      */
    virtual void Calculate( const GlsFloat64 time );

    /** Perform a pick test of the given point in window coordinates against this object
      * \param windowCoord point in question
      * \param inputManager input manager managing input for this object
      * \param parentDrawMatrix draw matrix used when rendering parent object
      * \return object that is picked by given window coordinate else GLS_NULL
      * \pre windowCoord.IsValid(), GLMatrixAffineFIsValid( parentDrawMatrix )
      * \post none
      */
    virtual GlsDisplayObject* PickTest( const GlsVector2D &windowCoord, GlsInputManager &inputManager,
                                        const GlsMatrixAffineD::GLMatrixAffineF &parentDrawMatrix );

    /** Handle an event
      * \param event event in question
      * \return object that handled event else GLS_NULL
      * \pre event.IsValid()
      * \post event is handled if return value is not GLS_NULL
      */
    GlsDisplayObject* HandleEvent( GlsEvent &event );

    /** Get the type of this object
      * \return type of this object
      * \pre none
      * \post none
      */
    ObjectType GetObjectType( void ) const;

    /** Set the blinking state for this object
      * \param blinking Whether or not to blink this object ( GLS_TRUE, GLS_FALSE )
      * \pre none
      * \post object has new blinking state
      */
    void SetBlinking( const GlsBool blinking );

    /** Set the blinking rate for this object
      * \param blinkRate  Number of times per second to blink this object
      * \pre blinkRate > 0.0, GlsFloatIsValid( blinkRate )
      * \post object has new blink rate
      */
    void SetBlinkRate( const GlsFloat32 blinkRate );

    /** Sets the dynamic rotations to the specified value for all axes (in degrees)
      * \param dynamicRotation Vector containing the new dynamic rotation angles for each axis
      * \pre dynamicRotation.IsValid()
      * \post object has new dynamic rotation
      */
    void SetDynamicRotation( const GlsVector3D &dynamicRotation );

    /** Sets the dynamic scale values for each axis
      * \param dynamicScale The new dynamic scale for the object
      * \pre dynamicScale.IsValid(), dynamicScale.x >= 0.0, dynamicScale.y >= 0.0, dynamicScale.z >= 0.0
      * \post object has new dynamic scale
      */
    void SetDynamicScale( const GlsVector3D &dynamicScale );

    /** Sets the dynamic translation to the specified value for all axes (in logical units)
      * \param dynamicTranslation The new dynamic translation for the X, Y, and Z axes
      * \pre dynamicTranslation.IsValid()
      * \post object has new dynamic translation
      */
    void SetDynamicTranslation( const GlsVector3D &dynamicTranslation );

    /** Set the visiblity state for this object
      * \param visible GLS_TRUE to enable this object for drawing else GLS_FALSE
      * \pre none
      * \post object has new visibility state
      */
    void SetVisibility( const GlsBool visible );

    /** Set the parent object for this object
      * \param parent parent object for this object
      * \pre parent != GLS_NULL
      * \post object has new parent
      */
    void SetParent( GlsDisplayObject* const parent );

    /** Set the pick mode for this object
      * \param pickMode new pick mode
      * \pre GlsDisplayObjectPickModeIsValid( pickMode )
      * \post object has new pick mode
      */
    void SetPickMode( const PickMode pickMode );

    /** Determine if Calculate() needs to be called on this object
      * \return GLS_TRUE if Calculate() needs to be called else GLS_FALSE
      * \pre none
      * \post none
      */
    GlsBool NeedCalculate( void ) const;

    /** Invalidate cached picking screen coordinates
      * \pre none
      * \post cached screen picking coordinates are marked invalid
      */
    void InvalidatePickCache( void );

    #if defined( GLS_UNIT_TEST )
        /** Get the memory offset of the _objectType member of GlsDisplayObject ( GLS_UNIT_TEST only )
          *   This static inline method is only used when unit testing and is not present otherwise.
          * \pre none
          * \post none
          * \return the memory offset of the _objectType member of GlsDisplayObject
          */
        static const void* OffsetOfObjectType( void );
    #endif // defined( GLS_UNIT_TEST )

protected:
    const GlsMatrixAffineD    _dcsMatrix;           /**< The dynamic coordinate system.  The Dynamic changes 
                                                      * to rotation, scale, and translate will 
                                                      * be modified by this and applied to the _drawMatrix. */
    const GlsMatrixAffineD    _dcsMatrixInverse;    /**< inverse of _dcsMatrix */
    const GlsBool             _dcsMatrixIsIdentity; /**< GLS_TRUE if _dscMatrix is identity else GLS_FALSE */
    const GlsVector3D         _location;            /**< The location of the origin point for this object, 
                                                      * in the world coordinate system. */
    const GlsBool             _needCalculate;       /**< GLS_TRUE if Calculate() needs be called on this object
                                                      * else GLS_FALSE. */
    const ObjectType          _objectType;          /**< OBJECT_TYPE_RENDERABLE or OBJECT_TYPE_COMPOSITE */
    const PickRegion          _pickRegion;          /**< pick region for object */
    GlsEventDispatcher* const _eventDispatcher;     /**< dispatcher for received events else GLS_NULL */
    const GlsVector3D         _rotationPoint;       /**< The location, in the object coordinate system, 
                                                      * of the point to rotate this object around when the object is
                                                      * dynamically rotated. So when we want to rotate this object
                                                      * (not just rotate the view), this is the point to rotate about.
                                                      * This point is relative to the _location,
                                                      * which makes in in the objects coordinate system. */ 

    GlsBool          _blinking;              /**< GLS_TRUE if blinking is turned on else GLS_FALSE ) */
    GlsFloat32       _blinkRate;             /**< Number of times per second the object will blink (>0.0) */
    GlsMatrixAffineD::GLMatrixAffineF _drawMatrix; /**< The objects contribution to the OpenGL draw matrix.  
                                                     * This will be multiplied by the current matrix at draw time. 
                                                     * If identity, this object has no contribution 
                                                     * (it is not dynamic) */
    GlsVector3D      _dynamicRotation;       /**< The current (dynamic) rotation of the object, in degrees and relative to 
                                               * the object's rotation point. Order of rotation is x, then y, then z */
    GlsVector3D      _dynamicScale;          /**< The current (dynamic) scale of the object */
    GlsBool          _dynamicScaleIsUnity;   /**< GLS_TRUE if _dynamic scale is unity on all three axes */
    GlsVector3D      _dynamicTranslation;    /**< The current (dynamic) translation of the object, in logical units 
                                               * and relative to the object's DCS. */
    GlsBool          _needCalcDrawMatrix;    /**< GLS_TRUE if CalcDrawMatrix() needs to be called on this object
                                               * else GLS_FALSE. */
    GlsBool          _visible;               /**< GLS_TRUE if object drawing is enabled else GLS_FALSE */
    PickMode         _pickMode;              /**< pick mode for object */
    GlsBool          _windowPickRegionValid; /**< GLS_TRUE if cached window pick region values are valid */
    GlsVector2D      _windowPickLowerLeft;   /**< lower left coord of pick region in window coords if
                                               * _windowPickRegionValid == GLS_TRUE */
    GlsVector2D      _windowPickUpperRight;  /**< upper right coord of pick region in window coords if
                                               * _windowPickRegionValid == GLS_TRUE */
    GlsVector2D      _windowPickUpperLeft;   /**< upper left coord of pick region in window coords if
                                               * _windowPickRegionValid == GLS_TRUE */
    GlsVector2D      _windowPickLowerRight;  /**< lower right coord of pick region in window coords if
                                               * _windowPickRegionValid == GLS_TRUE */
    GlsMatrixAffineD::GLMatrixAffineF _pickMatrix; /**< matrix used to transform window pick region if
                                                     * _windowPickRegionValid == GLS_TRUE */
    GlsDisplayObject *_parent;               /**< parent of this object else GLS_NULL */

    /** Constructor for display objects.  Invoked by constructors of derived classes. 
      * \param initParameters initialization parameters
      * \param objectType object type for this object
      * \param eventDispatcher event dispatcher for this object else GLS_NULL
      * \pre initParameters.IsValid(), GlsDisplayObjectTypeIsValid( objectType )
      * \post object is constructed and initialized
      */
    GlsDisplayObject( const InitParameters &initParameters, const ObjectType objectType,
                      GlsEventDispatcher* const eventDispatcher );

    /** Destructor - shall never be called
      * \pre none
      * \post none
      */
    virtual ~GlsDisplayObject();

    /** Recalculates the _drawMatrix if needed
      * If _dynamicRotation, _dynamicScale, or _dynamicTranslate change you must call CalcDrawMatrix()
      * \param additionalTransform additional transform to apply to calculated draw matrix else 
      *        GLS_NULL for no addition transform
      * \param includeLocation GLS_TRUE to include contribution from _location else GLS_FALSE
      * \return GLS_TRUE if draw matrix was recalculated else GLS_FALSE
      * \pre none
      * \post _drawMatrix is recalculated if needed
      */
    GlsBool CalcDrawMatrix( const GlsMatrixAffineD* const additionalTransform, const GlsBool includeLocation );

    /** Recalculates the window picking region if needed
      * \param inputManager input manager managing input for this object
      * \param parentDrawMatrix draw matrix used when rendering parent object
      * \pre _needCalcDrawMatrix == GLS_FALSE (_drawMatrix is up to date)
      * \post _windowPickLowerLeft, _windowPickUpperRight, _windowPickUpperLeft,
      *       _windowPickLowerRight and _pickMatrix are recalculated
      *       if _windowPickRegionValid == GLS_FALSE, 
      */
    virtual void CalcWindowPickRegion( GlsInputManager &inputManager,
                                       const GlsMatrixAffineD::GLMatrixAffineF &parentDrawMatrix );

    /** Determine if the object is in an "off" blink cycle (invisible)
      * \param time elapsed time in seconds since program start
      * \return GLS_TRUE if blinked off else GLS_FALSE
      * \pre _blinking == TRUE, _blinkRate > 0.0f, time >= 0.0, _blinkRate > 0.0
      * \post none
      */
    GlsBool IsBlinkedOff( const GlsFloat64 time ) const;

private:
    // Disable implicit generated Members
    GlsDisplayObject& operator=( const GlsDisplayObject &rhs );
    GlsDisplayObject( const GlsDisplayObject &src );
};

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given object type is valid
  * \param objectType object type in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsDisplayObjectTypeIsValid( const GlsDisplayObject::ObjectType objectType )
{
    return( ( GlsDisplayObject::OBJECT_TYPE_COMPOSITE  == objectType ) ||
            ( GlsDisplayObject::OBJECT_TYPE_RENDERABLE == objectType ) );

}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG 

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given pick mode is valid
  * \param pickMode pick mode in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsDisplayObjectPickModeIsValid( const GlsDisplayObject::PickMode pickMode )
{
    return( ( GlsDisplayObject::PICK_MODE_NEVER  == pickMode ) || 
            ( GlsDisplayObject::PICK_MODE_FIRST  == pickMode ) ||
            ( GlsDisplayObject::PICK_MODE_ALWAYS == pickMode ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_UNIT_TEST )
#pragma BullseyeCoverage save off
/* Get the memory offset of the _objectType member of GlsDisplayObject ( GLS_UNIT_TEST only )
 *   This static inline method is only used when unit testing and is not present otherwise.
 * \pre none
 * \post none
 * \return the memory offset of the _objectType member of GlsDisplayObject
 */
inline const void* GlsDisplayObject::OffsetOfObjectType( void )
{
    return( &( ( (GlsDisplayObject*) 0 )->_objectType ) );
}
#pragma BullseyeCoverage restore
#endif // defined( GLS_UNIT_TEST )

#endif // _GLS_DISPLAY_OBJECT_H