gls_component_base.h

Go to the documentation of this file.

#ifndef _GLS_COMPONENT_BASE_H
#define _GLS_COMPONENT_BASE_H

/*! \file gls_component_base.h

\brief  This header defines GlsComponentBase which serves as a base
        class for all user derived display components
        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_composite_object.h"
#include "gls_matrix_affine_double.h"
#include "gls_texture_palette.h"
#include "gls_display_object_array.h"
#include "gls_class_invariant.h"

/** This class serves as an abstract base class for all user derived display components.
  * \invariant base class invariant holds, _componentTransformMatrix invariant holds,
  *            _clipPlanes array has valid elements
  */
class GlsComponentBase : public GlsCompositeObject
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsComponentBase )

    /** initialization parameters for a component */
    struct InitParameters
    {
        const GlsCompositeObject::InitParameters compositeInitParameters; /**< base class init parameters */

        const GlsMatrixAffineD::CStyleMatrix componentTransformMatrix; /**< Contains the rotation, and scaling that
                                                                         * the parent did to this component */

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

    /** Called after objects in the component are created. This allows a derived class to
      * have custom initialization code.
      * \pre none
      * \post custom initialization (if any) is complete
      */
    virtual void Initialize( void ) = 0;

    /** Enable and configure the six clipping planes ( left, right, top, bottom, front, back ) against
      *  which the component will be clipped when rendered.  The clipping planes are defined by the
      *  3D box described by the given points.
      * \param lowerFarLeft lower far left side point of 3D box describing clip planes
      * \param upperNearRight upper near right side point of 3D box describing clip planes
      * \pre lowerFarLeft.IsValid(), upperNearRight.IsValid(), no child of this component can have
      *      its clip planes enabled
      * \post the component will be clipped against the clip planes described by the given points
      *       when drawn
      */
    void SetClipPlanes( const GlsVector3D &lowerFarLeft, const GlsVector3D &upperNearRight );

    /** Draws the component
      * \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 component drawn to OpenGL if visible and not blinked off
      */
    virtual void Draw( GlsStateManager &gl, const GlsFloat64 time );

    /** Provides a mechanism for performing regular calculations, separate 
      * from drawing. 
      * \param time The elaspsed time in seconds since program start
      * \pre time >= 0.0
      * \post calculations (if any) completed for all contained objects
      */
    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 );

    /** Set the alpha mode of the contained objects
      * \param alphaMode desired alpha mode
      * \pre GlsAlphaModeIsValid( alphaMode )
      * \post contained objects have new alpha mode
      */
    virtual void SetChildrenAlphaMode( const GlsAlphaMode alphaMode );

    /** Set the fill color of the contained objects
      * \param fillColor desired fill color
      * \pre fillColor.IsValid()
      * \post contained objects have new fill color
      */
    virtual void SetChildrenFillColor( const GlsColor &fillColor );

    /** Set the line color of the contained objects
      * \param lineColor desired line color
      * \pre lineColor.IsValid()
      * \post contained objects have new line color
      */
    virtual void SetChildrenLineColor( const GlsColor &lineColor );

    /** Set the line width of the contained objects
      * \param lineWidth new line width,
      *        GlsRenderObject::LINE_WIDTH_MIN <= lineWidth <= GlsRenderObject::LINE_WIDTH_MAX
      * \pre GlsLineWidthIsValid( lineWidth )
      * \post contained objects have new line width
      */
    virtual void SetChildrenLineWidth( const GlsFloat32 lineWidth );

    /** Set the polygon mode of the contained objects
      * \param polygonMode new polygon mode
      * \pre GlsPolygonModeIsValid( polygonMode )
      * \post contained objects have new polygon mode
      */
    virtual void SetChildrenPolygonMode( const GlsPolygonMode polygonMode );

protected:
    /** desribes available clip planes */
    enum
    {
        CLIP_PLANE_LEFT    = 0u,
        CLIP_PLANE_RIGHT,
        CLIP_PLANE_TOP,
        CLIP_PLANE_BOTTOM,
        CLIP_PLANE_FRONT,
        CLIP_PLANE_BACK,
        NUM_CLIP_PLANES
    };

    /** describes clip plane eqn coefficients */
    enum
    {
        PLANE_EQN_COEFF_A  = 0u,
        PLANE_EQN_COEFF_B,
        PLANE_EQN_COEFF_C,
        PLANE_EQN_COEFF_D,
        NUM_PLANE_COEFF
    };

    /** Constructor - create an instance, can only be called by a derived class
      * \param initParameters initialization parameters
      * \param eventDispatcher event dispatcher for this object else GLS_NULL
      * \pre initParameters.IsValid()
      * \post instance created
      */
    GlsComponentBase( const InitParameters &initParameters, GlsEventDispatcher* const eventDispatcher );

    /** Activate the GL clip planes described by _clipPlanes
      * \pre none of the GL clip planes are activated
      * \post GL clip planes described _clipPlanes are activated
      */
    void ActivateClipPlanes( void ) const;

    /** Deactivate the GL clip planes 
      * \pre none 
      * \post GL clip planes are deactivated
      */
    void DeactivateClipPlanes( void ) const;

    /** Get the object array that contains all of the objects in the component
      * \return the object array that contains all of the objects in the component
      * \pre none
      * \post none
      */
    virtual GlsDisplayObjectArray& GetObjects( void ) = 0;

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

    GlsMatrixAffineD  _componentTransformMatrix; /**< The static transformation from the internal component
                                                   * coordinates to the parent's coordinate system.
                                                   * the rotation, and scaling that the parent
                                                   * did to this component, including translation for
                                                   * _location*/

    GlsBool  _clippingEnabled;                                  /**< GLS_TRUE if clipping is enabled when drawing
                                                                  * else GLS_FALSE */
    GLdouble _clipPlanes[ NUM_CLIP_PLANES ][ NUM_PLANE_COEFF ]; /**< plane equation coefficients for each plane */

private:
    typedef GlsCompositeObject _BaseClass; /**< base class alias */

    // Disable implicit generated Members
    GlsComponentBase& operator=( const GlsComponentBase &rhs );
    GlsComponentBase( const GlsComponentBase &src );
};

#endif // _GLS_COMPONENT_BASE_H