gls_clipping_group.h

Go to the documentation of this file.

#ifndef INCLUDED_GLS_CLIPPING_GROUP_H
#define INCLUDED_GLS_CLIPPING_GROUP_H
 
/*! \file gls_clipping_group.h
 
\brief  This header defines the GlsClippingGroup class
        in the GL Studio DO-178B Runtime Library.
 
\par Copyright Information
Copyright (C) 2019-2025 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.
 
*** NOTICE *** This source code is not encompassed by the DO-178B certication
package.
 
*/
 
#include "gls_include.h"
 
#include "gls_class_invariant.h"
#include "gls_group.h"
 
/** This class facilitates regions that clip geometry within a given boundary
  * \invariant base class invariant holds
  */
class GlsClippingGroup : public GlsGroup
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsClippingGroup )
 
    /** intialization parameters for a GlsClippingGroup */
    struct InitParameters
    {
        GlsGroup::InitParameters groupInitParameters; /**< base class init parameters */
 
        const GlsBool     clippingActive; /**< determines if geometry will be clipped between blc and trc */
        const GlsVector3D blc;            /**< bottom left corner of the clip region in logical units */
        const GlsVector3D trc;            /**< top right corner of the clip region in logical units */
 
        /** create a copy of the init parameters with the object array init
          *    objects array replaced with the given array of objects
          * \param newObjects new array of ojects
          * \return copy of given init parameters with object array init objects array replaced
          * \pre newObjects != GLS_NULL,
          *      newObjects array has initParameters.groupInitParameters.objectArrayInitParameters.numObjects elements
          * \post none
          */
        InitParameters CopyWithObjectsArray( GlsDisplayObject* const* newObjects ) const;
 
#if defined( GLS_DEBUG )
        /** Determine if the initialization 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
    };
 
    /** Constructor - create an instance
      * \param initParameters initialization parameters
      * \param eventDispatcher event dispatcher for this object else GLS_NULL
      * \pre initParameters.IsValid()
      * \post instance created
      */
    GlsClippingGroup( InitParameters& initParameters, GlsEventDispatcher* const eventDispatcher );
 
    /** Draws the objects in the clipping group.
      * \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
      */
    virtual void Draw( GlsStateManager& gl, 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 );
 
    /** Get the current active state for the clipping region
      * \return GlsBool current active state
      * \pre class invariant
      * \post none
      */
    GlsBool GetClippingActive();
 
    /** Set the current active state for the clipping region
      * \param value GlsBool new active state to set
      * \pre class invariant
      * \post active state set to incoming value
      */
    void SetClippingActive( const GlsBool value );
 
    /** Get the bottom left corner of the clipping region
      * \return GlsVector3D current bottom left corner location
      * \pre class invariant
      * \post none
      */
    GlsVector3D GetBlc();
 
    /** Set the bottom left corner of the clipping region
      * \param value GlsVector3D new bottom left corner to set
      * \pre class invariant
      * \post none
      */
    void SetBlc( const GlsVector3D& value );
 
    /** Get the top right corner of the clipping region
      * \return GlsVector3D current top right corner location
      * \pre class invariant
      * \post none
      */
    GlsVector3D GetTrc();
 
    /** Set the top right corner of the clipping region
      * \param value GlsVector3D new top right corner to set
      * \pre class invariant
      * \post none
      */
    void SetTrc( const GlsVector3D& value );
 
protected:
    GlsBool     _clippingActive; /**< determines if geometry will be clipped between blc and trc */
    GlsVector3D _blc;            /**< bottom left corner of the clip region in logical units */
    GlsVector3D _trc;            /**< top right corner of the clip region in logical units */
 
    /** Destructor - shall never be called
      * \pre none
      * \post none
      */
    virtual ~GlsClippingGroup();
 
    /* 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 );
 
    /** Draws the clipping polygon to the stencil buffer.
      * \param gl GL State manager for OpenGL into which object is drawn
      * \pre class invariant
      * \post clipping polygon is drawn to OpenGL
      */
    void DrawClippingPolygon( GlsStateManager& gl );
 
private:
    typedef GlsGroup BaseClass; /**< base class alias */
 
    // Disable implicit generated Members
    GlsClippingGroup& operator=( const GlsClippingGroup& rhs );
    GlsClippingGroup( const GlsClippingGroup& src );
};
 
#endif // _GLS_CLIPPING_GROUP_H