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