nuclear@1: /************************************************************************************
nuclear@1: 
nuclear@1: PublicHeader:   OVR
nuclear@1: Filename    :   OVR_Timer.h
nuclear@1: Content     :   Provides static functions for precise timing
nuclear@1: Created     :   September 19, 2012
nuclear@1: Notes       : 
nuclear@1: 
nuclear@1: Copyright   :   Copyright 2012 Oculus VR, Inc. All Rights reserved.
nuclear@1: 
nuclear@1: Use of this software is subject to the terms of the Oculus license
nuclear@1: agreement provided at the time of installation or download, or which
nuclear@1: otherwise accompanies this software in either electronic or hard copy form.
nuclear@1: 
nuclear@1: ************************************************************************************/
nuclear@1: 
nuclear@1: #ifndef OVR_Timer_h
nuclear@1: #define OVR_Timer_h
nuclear@1: 
nuclear@1: #include "OVR_Types.h"
nuclear@1: 
nuclear@1: namespace OVR {
nuclear@1:     
nuclear@1: //-----------------------------------------------------------------------------------
nuclear@1: // ***** Timer
nuclear@1: 
nuclear@1: // Timer class defines a family of static functions used for application
nuclear@1: // timing and profiling.
nuclear@1: 
nuclear@1: class Timer
nuclear@1: {
nuclear@1: public:
nuclear@1:     enum {
nuclear@1:         MsPerSecond     = 1000, // Milliseconds in one second.
nuclear@1:         MksPerMs        = 1000, // Microseconds in one millisecond.
nuclear@1:         MksPerSecond    = MsPerSecond * MksPerMs
nuclear@1:     };
nuclear@1: 
nuclear@1: 
nuclear@1:     // ***** Timing APIs for Application    
nuclear@1:     // These APIs should be used to guide animation and other program functions
nuclear@1:     // that require precision.
nuclear@1: 
nuclear@1:     // Returns ticks in milliseconds, as a 32-bit number. May wrap around every
nuclear@1:     // 49.2 days. Use either time difference of two values of GetTicks to avoid
nuclear@1:     // wrap-around.  GetTicksMs may perform better then GetTicks.
nuclear@1:     static UInt32  OVR_STDCALL GetTicksMs();
nuclear@1: 
nuclear@1:     // GetTicks returns general-purpose high resolution application timer value,
nuclear@1:     // measured in microseconds (mks, or 1/1000000 of a second). The actual precision
nuclear@1:     // is system-specific and may be much lower, such as 1 ms.
nuclear@1:     static UInt64  OVR_STDCALL GetTicks();
nuclear@1: 
nuclear@1:     
nuclear@1:     // ***** Profiling APIs.
nuclear@1:     // These functions should be used for profiling, but may have system specific
nuclear@1:     // artifacts that make them less appropriate for general system use.
nuclear@1:     // On Win32, for example these rely on QueryPerformanceConter  may have
nuclear@1:     // problems with thread-core switching and power modes.
nuclear@1: 
nuclear@1:     // Return a hi-res timer value in mks (1/1000000 of a sec).
nuclear@1:     // Generally you want to call this at the start and end of an
nuclear@1:     // operation, and pass the difference to
nuclear@1:     // TicksToSeconds() to find out how long the operation took. 
nuclear@1:     static UInt64  OVR_STDCALL GetProfileTicks();
nuclear@1: 
nuclear@1:     // More convenient zero-based profile timer in seconds. First call initializes 
nuclear@1:     // the "zero" value; future calls return the difference. Not thread safe for first call.
nuclear@1:     // Due to low precision of Double, may malfunction after long runtime.
nuclear@1:     static double  OVR_STDCALL GetProfileSeconds();
nuclear@1: 
nuclear@1:     // Get the raw cycle counter value, providing the maximum possible timer resolution.
nuclear@1:     static UInt64  OVR_STDCALL GetRawTicks();
nuclear@1:     static UInt64  OVR_STDCALL GetRawFrequency();
nuclear@1: 
nuclear@1:     
nuclear@1:     // ***** Tick and time unit conversion.
nuclear@1: 
nuclear@1:     // Convert micro-second ticks value into seconds value.
nuclear@1:     static inline double TicksToSeconds(UInt64 ticks)
nuclear@1:     {
nuclear@1:         return static_cast<double>(ticks) * (1.0 / (double)MksPerSecond);
nuclear@1:     }
nuclear@1:     // Convert Raw or frequency-unit ticks to seconds based on specified frequency.
nuclear@1:     static inline double RawTicksToSeconds(UInt64 rawTicks, UInt64 rawFrequency)
nuclear@1:     {
nuclear@1:         return static_cast<double>(rawTicks) * rawFrequency;
nuclear@1:     }
nuclear@1: 
nuclear@1: private:
nuclear@1:     friend class System;
nuclear@1:     // System called during program startup/shutdown.
nuclear@1:     static void initializeTimerSystem();
nuclear@1:     static void shutdownTimerSystem();
nuclear@1: };
nuclear@1: 
nuclear@1: 
nuclear@1: } // Scaleform::Timer
nuclear@1: 
nuclear@1: #endif