gls_odometer.h

Go to the documentation of this file.

#ifndef _GLS_ODOMETER_H
#define _GLS_ODOMETER_H

/*! \file gls_odometer.h

\brief  This header defines the GlsOdometer class
        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_group.h"
#include "gls_class_invariant.h"

/** This class facilitates building rolling odometer displays.
  * \invariant base class invariant holds, _baseSystem > 0u, _minValue <= _maxValue,
  *            _rolloverThreshold > 0.0f,
  *            GlsOdometerBehaviorIsValid( _behavior ), GlsOdometerGeometryTypeIsValid( _geometryType )
  *            GlsFloatIsValid( _degreesPerDigit ), GlsFloatIsValid( _textureScale ),
  *            _magnitude > 0.0, ( _minValue <= _value ) && ( _value <= _maxValue ),
  *            ( ( ( 0u == _objects.GetSize() ) && ( GLS_NULL == _textureOffsetY ) ) ||
  *              ( ( _objects.GetSize() > 0u  ) && ( GLS_NULL != _textureOffsetY ) ) ),
  *            _textureOffsetY array contains valid floating point values
  */
class GlsOdometer : public GlsGroup
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsOdometer )

    /** odometer behvior mode */
    enum Behavior
    {
        BEHAVIOR_ANALOG,        /**< analog odometer */
        BEHAVIOR_DIGITAL,       /**< digital odometer */

        #if defined( GLS_DEBUG )
            BEHAVIOR_INVALID    /**< invalid behavior ( GLS_DEBUG only ) */
        #endif // GLS_DEBUG
    };

    /** odometer geometry types */
    enum GeometryType
    {
        GEOMETRY_TYPE_2D,         /**< two dimensional geometry */
        GEOMETRY_TYPE_3D,         /**< three dimensional geometry */

        #if defined( GLS_DEBUG )
            GEOMETRY_TYPE_INVALID /**< invalid geometry type */
        #endif // GLS_DEBUG
    };

    /** intialization parameters for a GlsOdometer */
    struct InitParameters
    {
        GlsGroup::InitParameters groupInitParameters; /**< base class init parameters */

        const GlsUInt32    baseSystem;        /**< base of number system for display values ( >0 ) */
        const GlsFloat32   minValue;          /**< minimum display value for odometer ( minValue <= maxValue ) */
        const GlsFloat32   maxValue;          /**< maximum display value for odometer ( maxValue >= minValue ) */
        const GlsFloat32   initialValue;      /**< initial display value for odometer
                                                * ( minValue <= initialValue <= maxValue ) */
        const GlsUInt32    orderOfMagnitude;  /**< order of magnitude of odometer digits */
        const GlsFloat32   rolloverThreshold; /**< threshold determining when digit rollover occurs ( >0.0f ) */
        const Behavior     behavior;          /**< odometer behavior */
        const GeometryType geometryType;      /**< odometer geometry type */
        const GlsFloat32   degreesPerDigit;   /**< rotation in degrees for one digit when in 3D geometry mode */
        const GlsFloat32   textureScale;      /**< amount to slide texture when in 2D geometry mode */

        /** 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
      */
    GlsOdometer( InitParameters &initParameters, GlsEventDispatcher* const eventDispatcher );

    /** Set the current display value for the odometer
      * \param value new display value
      * \pre _minValue <= value <= _maxValue
      * \post odometer has new display value
      */
    void SetValue( const GlsFloat32 value );

protected:
    /** Update the odometer digits to display the current value
      * \pre none
      * \post current value is reflected in the odometer digits
      */
    void UpdateDigits( void );

    const GlsUInt32     _baseSystem;        /**< base of number system for display ( >0 ) */
    const GlsFloat32    _minValue;          /**< minimum display value for odometer ( minValue <= maxValue ) */
    const GlsFloat32    _maxValue;          /**< maximum display value for odometer ( maxValue >= minValue ) */
    const GlsFloat32    _rolloverThreshold; /**< threshold determining when digit rollover occurs ( >0.0f ) */
    const Behavior      _behavior;          /**< odometer behavior mode */
    const GeometryType  _geometryType;      /**< odometer geometry type */
    const GlsFloat32    _degreesPerDigit;   /**< rotation in degrees for one digit when in 3D geometry mode */
    const GlsFloat32    _textureScale;      /**< amount to slide texture when in 2D geometry mode */

    const GlsFloat64    _magnitude;         /**< magnitude of most significant digit on odometer */
    const GlsFloat64    _lastMagnitude;     /**< magnitude of last (least significant) digit in odometer */
    GlsFloat32          _value;             /**< current display value for odometer
                                              * ( minValue <= initialValue <= maxValue ) */
    GlsFloat32* const   _textureOffsetY;    /**< array of y texture offsets for each digit in odometer else GLS_NULL
                                              * if no digits */

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

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

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

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given odometer behavior is valid ( GLS_DEBUG only )
  * \param behavior odometer behavior in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsOdometerBehaviorIsValid( const GlsOdometer::Behavior behavior )
{
    return( ( GlsOdometer::BEHAVIOR_ANALOG  == behavior ) ||
            ( GlsOdometer::BEHAVIOR_DIGITAL == behavior ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given odometer geometry type is valid ( GLS_DEBUG only )
  * \param geometryType odometer geometry type in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsOdometerGeometryTypeIsValid( const GlsOdometer::GeometryType geometryType )
{
    return( ( GlsOdometer::GEOMETRY_TYPE_2D == geometryType ) ||
            ( GlsOdometer::GEOMETRY_TYPE_3D == geometryType ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#endif // _GLS_ODOMETER_H