gls_input_manager.h

Go to the documentation of this file.

#ifndef _GLS_INPUT_MANAGER_H
#define _GLS_INPUT_MANAGER_H

/*! \file gls_input_manager.h
\brief  This header defines the Input Manager class for managing user input 
        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_matrix_affine_double.h"
#include "gls_display_object.h"
#include "gls_class_invariant.h"

/** This class manages user input.
  * \invariant  GLMatrixAffineFIsValid( _projMatrix  )
  *             GLMatrixAffineFIsValid( _modelMatrix )
  */
class GlsInputManager
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsInputManager )

    /** describes a rectangular render viewport */
    struct Viewport
    {
        GlsInt32  x;      /**< x coord of lower left corner in pixels */
        GlsInt32  y;      /**< y coord of lower left corner in pixels */
        GlsUInt32 width;  /**< width of viewport in pixels */
        GlsUInt32 height; /**< height of viewport in pixels */
    };

    /** initialization parameters for a GlsInputManager */
    struct InitParameters
    {
        const Viewport                           viewport;       /**< initial GL viewport */
        const GlsMatrixAffineD::GLMatrixAffineF  projMatrix;     /**< initial GL projection matrix */
        const GlsMatrixAffineD::GLMatrixAffineF  modelMatrix;    /**< initial GL model matrix */
        GlsDisplayObject                        &topLevelObject; /**< top level object receiving input */

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

    /** Initialize (and create) the singleton GlsInputManager instance.  Can only be called once
      * \param initParameters initialization parameters
      * \pre singleton must not already exist, initParameters.IsValid()
      * \post GlsInputManager singleton instance is created and initialized
      */
    static void Initialize( InitParameters &initParameters );
        
    /** Get the singleton GlsInputManager instance
      * \return the singleton GlsInputManager instance
      * \pre singleton instance must exist ( must have called Initialize() )
      * \post none
      */
    static GlsInputManager& GetInputManager( void );

    /** Handle the given event
      * \param event event in question
      * \return GLS_TRUE if event was handled else GLS_FALSE
      * \pre event.IsValid()
      * \post event is handled if return value is GLS_TRUE
      */
    GlsBool HandleEvent( GlsEvent &event );

    /**  Update the input manager with the current GL viewport. Call if/when
      * GL viewport changes from initial viewport given to Initialize() call.
      * \param viewport updated GL viewport
      * \pre none
      * \post view port is updated
      */
    void UpdateViewport( const Viewport &viewport );    

    /**  Update the input manager with the current GL projection matrix. Call if/when
      * GL projection matrix changes from initial projection matrix given to Initialize() call.
      * \param projMatrix updated projection matrix
      * \pre GLMatrixAffineFIsValid( projMatrix )
      * \post projection matrix is updated
      */
    void UpdateProjectionMatrix( const GlsMatrixAffineD::GLMatrixAffineF &projMatrix );

    /**  Update the input manager with the current top level GL model matrix. Call if/when
      * top level GL model matrix changes from initial model matrix given to Initialize() call.
      * \param modelMatrix updated model matrix
      * \pre GLMatrixAffineFIsValid( modelMatrix )
      * \post model matrix is updated
      */
    void UpdateModelMatrix( const GlsMatrixAffineD::GLMatrixAffineF &modelMatrix );

    /**  Project the given point into screen coordinates using the given GL draw matrix and
      * the current projection matrix and viewport
      * \param p point in question
      * \param drawMatrix GL draw matrix
      * \param projected [out] receives projected point in screen coordinates
      * \pre p.IsValid(), GLMatrixAffineFIsValid( drawMatrix )
      * \post projected contains p projected into screen space
      */
    void ProjectPoint( const GlsVector3D &p, const GlsMatrixAffineD::GLMatrixAffineF &drawMatrix,
                       GlsVector2D &projected ) const;

protected:
    Viewport                           _viewport;        /**< current GL display viewport */
    GlsMatrixAffineD::GLMatrixAffineF  _projMatrix;      /**< current GL projection matrix */
    GlsMatrixAffineD::GLMatrixAffineF  _modelMatrix;     /**< current GL model matrix */
    GlsDisplayObject                  &_topLevelObject;  /**< top level object receiving input */
    GlsDisplayObject                  *_focusObject;     /**< current object with focus else GLS_NULL */
    GlsDisplayObject                  *_dragObject;      /**< current object for dragging else GLS_NULL */

    GlsBool _invalidatePickCache; /**< GLS_TRUE if pick cache of top level component needs to
                                    * be invalidated before the next pick can occur */
    
    /** Constructor - create an instance
      * \param initParameters initialization parameters
      * \pre initParameters.IsValid()
      * \post instance created
      */
    GlsInputManager( InitParameters &initParameters );

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

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

#endif // _GLS_INPUT_MANAGER_H