KDIS/KDIS/DataTypes/TimeStamp.h

   1 /*********************************************************************
   2 Copyright 2013 Karl Jones
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7
   8 1. Redistributions of source code must retain the above copyright notice, this
   9    list of conditions and the following disclaimer.
  10 2. Redistributions in binary form must reproduce the above copyright notice,
  11    this list of conditions and the following disclaimer in the documentation
  12    and/or other materials provided with the distribution.
  13
  14 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  15 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  16 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  17 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
  18 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  19 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  20 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  21 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  23 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24
  25 For Further Information Please Contact me at
  26 Karljj1@yahoo.com
  27 http://p.sf.net/kdis/UserGuide
  28 *********************************************************************/
  29
  30 /********************************************************************
  31     class:      TimeStamp
  32     created:    16/10/2008
  33     author:     Karl Jones
  34
  35     purpose:    Stores absolute/ relative timestamps.
  36                 Timestamps are used to reduce the error in a simulation.
  37
  38                 A lot of DIS simulators simply ignore timestamps however if error(I.E inaccuracy
  39                 between a entities position and its actual position) is an issue then the timestamp
  40                 can be used to reduce this error.
  41
  42                 Absolute timestamps tend to require the use of very accurate and expesnive clocks which are synchronized.
  43                 Relative timestamps are less accurate and tend to use the computers internal clock.
  44
  45                 The following is taken straight from the DIS standard:
  46                 "To make sure that relative timestamps are synchronized, you need to compare information about a received
  47                 PDU that contains a relative timestamp with the time you are maintaining in your simulation application.
  48                 This is done using software and without any special hardware. It does require that a few packets be observed
  49                 before time is well synchronized. As packets are received, the difference between their relative timestamps
  50                 and the receiver's clock is averaged. This average will correspond to the average latency, and the difference
  51                 represents clock skew. After a few dozen packets, the difference between the observed average and the real
  52                 average latency is around 5ms. After several hundred, the difference is in the 1ms neighborhood. This is not
  53                 as long a time to wait as might be imagined. A dozen ES PDU's per minute are emitted by simulators for
  54                 entities which are stopped. Thus, a few minutes of idle time before the exercise starts provides data for 5ms
  55                 accuracy, and at 1-2 PDU's per second while moving, 1ms accuracy can be had in a matter of minutes.
  56                 Exercises with stricter needs really should use absolute based time."
  57
  58     size:       32 bits / 4 octets
  59 *********************************************************************/
  60
  61 #pragma once
  62
  63 #include "./DataTypeBase.h"
  64
  65 namespace KDIS {
  66 namespace DATA_TYPE {
  67
  68 class KDIS_EXPORT TimeStamp : public DataTypeBase
  69 {
  70 protected:
  71
  72     union
  73     {
  74         struct
  75         {
  76             KUINT32 m_ui32TimeStampType : 1;
  77             KUINT32 m_ui32Time          : 31;
  78         };
  79         KUINT32 m_ui32TimeStamp;
  80     } m_TimeStampUnion;
  81
  82     KBOOL m_bAutoCalcRel;
  83
  84 public:
  85
  86     static const KUINT16 TIME_STAMP_SIZE = 4;
  87
  88     static const KFLOAT64 SEC_PER_UNIT_TIME;
  89
  90     static const KFLOAT64 UNIT_TIME_PER_SEC;
  91
  92     static const KFLOAT64 NANOSEC_PER_UNIT_TIME;
  93
  94     static const KFLOAT64 UNIT_TIME_PER_NANOSEC;
  95
  96     TimeStamp();
  97
  98     TimeStamp( KDataStream & stream );
  99
 100     TimeStamp( KDIS::DATA_TYPE::ENUMS::TimeStampType T, KUINT32 Time, KBOOL AutoCalcRelative = false);
 101
 102     virtual ~TimeStamp();
 103
 104     //************************************
 105     // FullName:    KDIS::DATA_TYPE::TimeStamp::SetTimeStampType
 106     //              KDIS::DATA_TYPE::TimeStamp::GetTimeStampType
 107     // Description: Set the time stamp type, Absolute or Relative.
 108     // Parameter:   TimeStampType T
 109     //************************************
 110     void SetTimeStampType( KDIS::DATA_TYPE::ENUMS::TimeStampType T );
 111     KDIS::DATA_TYPE::ENUMS::TimeStampType GetTimeStampType() const;
 112
 113     //************************************
 114     // FullName:    KDIS::DATA_TYPE::TimeStamp::SetTime
 115     //              KDIS::DATA_TYPE::TimeStamp::GetTime
 116     // Description: Time value. Scale of the time is determined
 117     //              by setting one hour equal to (2^31 - 1), thereby resulting
 118     //              in each time unit representing 3600 s/( 2^31 - 1 ) = 1.676 micro secs
 119     //              or 0.000001676 seconds. See EnumHeader.h for further details.
 120     //              Note: SetTimeStampAutoCalculate to true to allow KDIS to handle the time stamp.
 121     // Parameter:   TimeStampType T
 122     //************************************
 123     void SetTime( KUINT32 T );
 124     KUINT32 GetTime() const;
 125
 126     //************************************
 127     // FullName:    KDIS::DATA_TYPE::TimeStamp::SetTimeStampAutoCalculate
 128     //              KDIS::DATA_TYPE::TimeStamp::IsTimeStampAutoCalculated
 129     // Description: Do you want the time stamp to be automatically calculated?
 130     //              Setting this to true will cause CalculateTimeStamp to be called every time
 131     //              the PDU is encoded.
 132     // Parameter:   KBOOL A
 133     //************************************
 134     void SetTimeStampAutoCalculate( KBOOL A );
 135     KBOOL IsTimeStampAutoCalculated() const;
 136
 137     //************************************
 138     // FullName:    KDIS::DATA_TYPE::TimeStamp::CalculateRelativeTimeStamp
 139     // Description: Automatically calculates the timestamp for this moment in time.
 140     //************************************
 141     void CalculateTimeStamp();
 142
 143     //************************************
 144     // FullName:    KDIS::DATA_TYPE::TimeStamp::GetAsString
 145     // Description: Returns a string representation.
 146     //************************************
 147     virtual KString GetAsString() const;
 148
 149     //************************************
 150     // FullName:    KDIS::DATA_TYPE::TimeStamp::Decode
 151     // Description: Convert From Network Data.
 152     // Parameter:   KDataStream & stream
 153     //************************************
 154     virtual void Decode( KDataStream & stream ) ;
 155
 156     //************************************
 157     // FullName:    KDIS::DATA_TYPE::TimeStamp::Encode
 158     // Description: Convert To Network Data.
 159     // Parameter:   KDataStream & stream
 160     //************************************
 161     virtual KDataStream Encode() const;
 162     virtual void Encode( KDataStream & stream ) const;
 163
 164     KBOOL operator == ( const TimeStamp & Value ) const;
 165     KBOOL operator != ( const TimeStamp & Value ) const;
 166
 167     // Note: No check is made if the time stamps are of the same type.
 168     KBOOL operator < ( const TimeStamp & Value ) const;
 169 };
 170
 171 } // END namespace DATA_TYPES
 172 } // END namespace KDIS