gls_display_object_array.h

Go to the documentation of this file.

#ifndef _GLS_DISPLAY_OBJECT_ARRAY_H
#define _GLS_DISPLAY_OBJECT_ARRAY_H

/*! \file gls_display_object_array.h

\brief  This header defines GlsDisplayObjectArray which encapsulates\
        an array of display object pointers
        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_pointer_array.h"
#include "gls_render_settings.h"
#include "gls_display_object.h"
#include "gls_state_manager.h"
#include "gls_class_invariant.h"

/** This class encapsulates an array of display objects and allows operations to be
  * performed on all of the entries in the array
  * \invariant _objects.Invariant(),
  *            there are no null pointers in the array,
  *            the invariant holds for all objects in the array
  */
class GlsDisplayObjectArray
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsDisplayObjectArray )

    /** initialization parameters for a GlsDisplayObjectArray */
    struct InitParameters
    {
        const GlsUInt32          numObjects;  /**< number of objects in objects array */
        GlsDisplayObject* const *objects;     /**< array of objects to make up the array */

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

    /** Constructor - create an instance
      * \param initParameters initialization parameters
      * \pre initParameters.IsValid()
      * \post instance created
      */
    GlsDisplayObjectArray( InitParameters &initParameters );

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

    /** Draws the objects in the array.
      * \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 contained objects are drawn to OpenGL if visible and not blinked off
      */
    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 objects in array
      */
    void Calculate( const GlsFloat64 time );

    /** Perform a pick test of the given point in window coordinates against the contained objects
      * \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
      */
    GlsDisplayObject* PickChildrenTest( 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
      */
    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
      */
    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
      */
    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
      */
    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
      */
    void SetChildrenPolygonMode( const GlsPolygonMode polygonMode );

    /** Set the parent of the contained objects
      * \param parent parent of contained objects
      * \pre parent != GLS_NULL
      * \post contained objects have new parent
      */
    void SetChildrenParent( GlsDisplayObject* const parent );

    /** Invalidate cached picking screen coordinates for contained objects
      * \pre none
      * \post cached screen picking coordinates are marked invalid for children
      */
    void InvalidateChildrenPickCache( void );

    /** Get the number of display objects in the array
      * \return number of display objects in the array
      * \pre none
      * \post none
      */
    GlsUInt32 GetSize( void ) const;

    /** get a ref to the display object at the given index
      * \param index index of desired object ( index < _objects.GetSize() )
      * \return ref to display object at given index
      * \pre index < _objects.GetSize()
      * \post none
      */
    GlsDisplayObject& GetObject( const GlsUInt32 index );

protected:
    GlsPointerArray _objects;       /**< array of display object pointers */
    GlsBool         _needCalculate; /**< GLS_TRUE if any of the objects needs its Calculate() method called,
                                      * else GLS_FALSE */

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

#endif // _GLS_DISPLAY_OBJECT_ARRAY_H