1.1 --- a/libovr/Src/Kernel/OVR_Log.h	Sat Sep 14 17:51:03 2013 +0300
     1.2 +++ b/libovr/Src/Kernel/OVR_Log.h	Sun Sep 15 04:10:05 2013 +0300
     1.3 @@ -1,1 +1,193 @@
     1.4 -/************************************************************************************
     1.5 
     1.6 PublicHeader:   OVR
     1.7 Filename    :   OVR_Log.h
     1.8 Content     :   Logging support
     1.9 Created     :   September 19, 2012
    1.10 Notes       : 
    1.11 
    1.12 Copyright   :   Copyright 2012 Oculus VR, Inc. All Rights reserved.
    1.13 
    1.14 Use of this software is subject to the terms of the Oculus license
    1.15 agreement provided at the time of installation or download, or which
    1.16 otherwise accompanies this software in either electronic or hard copy form.
    1.17 
    1.18 ************************************************************************************/
    1.19 
    1.20 #ifndef OVR_Log_h
    1.21 #define OVR_Log_h
    1.22 
    1.23 #include "OVR_Types.h"
    1.24 #include <stdarg.h>
    1.25 
    1.26 namespace OVR {
    1.27 
    1.28 //-----------------------------------------------------------------------------------
    1.29 // ***** Logging Constants
    1.30 
    1.31 // LogMaskConstants defined bit mask constants that describe what log messages
    1.32 // should be displayed.
    1.33 enum LogMaskConstants
    1.34 {
    1.35     LogMask_Regular = 0x100,
    1.36     LogMask_Debug   = 0x200,
    1.37     LogMask_None    = 0,
    1.38     LogMask_All     = LogMask_Regular|LogMask_Debug
    1.39 };
    1.40 
    1.41 
    1.42 // LogMessageType describes the type of the log message, controls when it is
    1.43 // displayed and what prefix/suffix is given to it. Messages are subdivided into
    1.44 // regular and debug logging types. Debug logging is only generated in debug builds.
    1.45 //
    1.46 // Log_Text         - General output text displayed without prefix or new-line.
    1.47 //                    Used in OVR libraries for general log flow messages
    1.48 //                    such as "Device Initialized".
    1.49 //
    1.50 // Log_Error        - Error message output with "Error: %s\n", intended for
    1.51 //                    application/sample-level use only, in cases where an expected
    1.52 //                    operation failed. OVR libraries should not use this internally,
    1.53 //                    reporting status codes instead.
    1.54 //
    1.55 // Log_DebugText    - Message without prefix or new lines; output in Debug build only.
    1.56 //
    1.57 // Log_Debug        - Debug-build only message, formatted with "Debug: %s\n".
    1.58 //                    Intended to comment on incorrect API usage that doesn't lead
    1.59 //                    to crashes but can be avoided with proper use.
    1.60 //                    There is no Debug Error on purpose, since real errors should
    1.61 //                    be handled by API user.
    1.62 //
    1.63 // Log_Assert      -  Debug-build only message, formatted with "Assert: %s\n".
    1.64 //                    Intended for severe unrecoverable conditions in library
    1.65 //                    source code. Generated though OVR_ASSERT_MSG(c, "Text").
    1.66 
    1.67 enum LogMessageType
    1.68 {    
    1.69     // General Logging
    1.70     Log_Text        = LogMask_Regular | 0,    
    1.71     Log_Error       = LogMask_Regular | 1, // "Error: %s\n".
    1.72     
    1.73     // Debug-only messages (not generated in release build)
    1.74     Log_DebugText   = LogMask_Debug | 0,
    1.75     Log_Debug       = LogMask_Debug | 1,   // "Debug: %s\n".
    1.76     Log_Assert      = LogMask_Debug | 2,   // "Assert: %s\n".
    1.77 };
    1.78 
    1.79 
    1.80 // LOG_VAARG_ATTRIBUTE macro, enforces printf-style fromatting for message types
    1.81 #ifdef __GNUC__
    1.82 #  define OVR_LOG_VAARG_ATTRIBUTE(a,b) __attribute__((format (printf, a, b)))
    1.83 #else
    1.84 #  define OVR_LOG_VAARG_ATTRIBUTE(a,b)
    1.85 #endif
    1.86 
    1.87 
    1.88 //-----------------------------------------------------------------------------------
    1.89 // ***** Log
    1.90 
    1.91 // Log defines a base class interface that can be implemented to catch both
    1.92 // debug and runtime messages.
    1.93 // Debug logging can be overridden by calling Log::SetGlobalLog.
    1.94 
    1.95 class Log
    1.96 {
    1.97     friend class System;
    1.98 public: 
    1.99     Log(unsigned logMask = LogMask_Debug) : LoggingMask(logMask) { }
   1.100     virtual ~Log();
   1.101 
   1.102     // Log formating buffer size used by default LogMessageVarg. Longer strings are truncated.
   1.103     enum { MaxLogBufferMessageSize = 2048 };
   1.104 
   1.105     unsigned        GetLoggingMask() const            { return LoggingMask; }
   1.106     void            SetLoggingMask(unsigned logMask)  { LoggingMask = logMask; }
   1.107 
   1.108     // This virtual function receives all the messages,
   1.109     // developers should override this function in order to do custom logging
   1.110     virtual void    LogMessageVarg(LogMessageType messageType, const char* fmt, va_list argList);
   1.111 
   1.112     // Call the logging function with specific message type, with no type filtering.
   1.113     void            LogMessage(LogMessageType messageType,
   1.114                                const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(3,4);
   1.115 
   1.116 
   1.117     // Helper used by LogMessageVarg to format the log message, writing the resulting
   1.118     // string into buffer. It formats text based on fmt and appends prefix/new line
   1.119     // based on LogMessageType.
   1.120     static void     FormatLog(char* buffer, unsigned bufferSize, LogMessageType messageType,
   1.121                               const char* fmt, va_list argList);
   1.122 
   1.123     // Default log output implementation used by by LogMessageVarg.
   1.124     // Debug flag may be used to re-direct output on some platforms, but doesn't
   1.125     // necessarily disable it in release builds; that is the job of the called.    
   1.126     static void     DefaultLogOutput(const char* textBuffer, bool debug);
   1.127 
   1.128     // Determines if the specified message type is for debugging only.
   1.129     static bool     IsDebugMessage(LogMessageType messageType)
   1.130     {
   1.131         return (messageType & LogMask_Debug) != 0;
   1.132     }
   1.133 
   1.134     // *** Global APIs
   1.135 
   1.136     // Global Log registration APIs.
   1.137     //  - Global log is used for OVR_DEBUG messages. Set global log to null (0)
   1.138     //    to disable all logging.
   1.139     static void     SetGlobalLog(Log *log);
   1.140     static Log*     GetGlobalLog();
   1.141 
   1.142     // Returns default log singleton instance.
   1.143     static Log*     GetDefaultLog();
   1.144 
   1.145     // Applies logMask to the default log and returns a pointer to it.
   1.146     // By default, only Debug logging is enabled, so to avoid SDK generating console
   1.147     // messages in user app (those are always disabled in release build,
   1.148     // even if the flag is set). This function is useful in System constructor.
   1.149     static Log*     ConfigureDefaultLog(unsigned logMask = LogMask_Debug)
   1.150     {
   1.151         Log* log = GetDefaultLog();
   1.152         log->SetLoggingMask(logMask);
   1.153         return log;
   1.154     }
   1.155 
   1.156 private:
   1.157     // Logging mask described by LogMaskConstants.
   1.158     unsigned    LoggingMask;
   1.159 };
   1.160 
   1.161 
   1.162 //-----------------------------------------------------------------------------------
   1.163 // ***** Global Logging Functions and Debug Macros
   1.164 
   1.165 // These functions will output text to global log with semantics described by
   1.166 // their LogMessageType.
   1.167 void LogText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.168 void LogError(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.169 
   1.170 #ifdef OVR_BUILD_DEBUG
   1.171 
   1.172     // Debug build only logging.
   1.173     void LogDebugText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.174     void LogDebug(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.175     void LogAssert(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.176 
   1.177     // Macro to do debug logging, printf-style.
   1.178     // An extra set of set of parenthesis must be used around arguments,
   1.179     // as in: OVR_LOG_DEBUG(("Value %d", 2)).
   1.180     #define OVR_DEBUG_LOG(args)       do { OVR::LogDebug args; } while(0)
   1.181     #define OVR_DEBUG_LOG_TEXT(args)  do { OVR::LogDebugText args; } while(0)
   1.182 
   1.183     #define OVR_ASSERT_LOG(c, args)   do { if (!(c)) { OVR::LogAssert args; OVR_DEBUG_BREAK; } } while(0)
   1.184 
   1.185 #else
   1.186 
   1.187     // If not in debug build, macros do nothing.
   1.188     #define OVR_DEBUG_LOG(args)         ((void)0)
   1.189     #define OVR_DEBUG_LOG_TEXT(args)    ((void)0)
   1.190     #define OVR_ASSERT_LOG(c, args)     ((void)0)
   1.191 
   1.192 #endif
   1.193 
   1.194 } // OVR 
   1.195 
   1.196 #endif
   1.197 \ No newline at end of file
   1.198 +/************************************************************************************
   1.199 +
   1.200 +PublicHeader:   OVR
   1.201 +Filename    :   OVR_Log.h
   1.202 +Content     :   Logging support
   1.203 +Created     :   September 19, 2012
   1.204 +Notes       : 
   1.205 +
   1.206 +Copyright   :   Copyright 2012 Oculus VR, Inc. All Rights reserved.
   1.207 +
   1.208 +Use of this software is subject to the terms of the Oculus license
   1.209 +agreement provided at the time of installation or download, or which
   1.210 +otherwise accompanies this software in either electronic or hard copy form.
   1.211 +
   1.212 +************************************************************************************/
   1.213 +
   1.214 +#ifndef OVR_Log_h
   1.215 +#define OVR_Log_h
   1.216 +
   1.217 +#include "OVR_Types.h"
   1.218 +#include <stdarg.h>
   1.219 +
   1.220 +namespace OVR {
   1.221 +
   1.222 +//-----------------------------------------------------------------------------------
   1.223 +// ***** Logging Constants
   1.224 +
   1.225 +// LogMaskConstants defined bit mask constants that describe what log messages
   1.226 +// should be displayed.
   1.227 +enum LogMaskConstants
   1.228 +{
   1.229 +    LogMask_Regular = 0x100,
   1.230 +    LogMask_Debug   = 0x200,
   1.231 +    LogMask_None    = 0,
   1.232 +    LogMask_All     = LogMask_Regular|LogMask_Debug
   1.233 +};
   1.234 +
   1.235 +
   1.236 +// LogMessageType describes the type of the log message, controls when it is
   1.237 +// displayed and what prefix/suffix is given to it. Messages are subdivided into
   1.238 +// regular and debug logging types. Debug logging is only generated in debug builds.
   1.239 +//
   1.240 +// Log_Text         - General output text displayed without prefix or new-line.
   1.241 +//                    Used in OVR libraries for general log flow messages
   1.242 +//                    such as "Device Initialized".
   1.243 +//
   1.244 +// Log_Error        - Error message output with "Error: %s\n", intended for
   1.245 +//                    application/sample-level use only, in cases where an expected
   1.246 +//                    operation failed. OVR libraries should not use this internally,
   1.247 +//                    reporting status codes instead.
   1.248 +//
   1.249 +// Log_DebugText    - Message without prefix or new lines; output in Debug build only.
   1.250 +//
   1.251 +// Log_Debug        - Debug-build only message, formatted with "Debug: %s\n".
   1.252 +//                    Intended to comment on incorrect API usage that doesn't lead
   1.253 +//                    to crashes but can be avoided with proper use.
   1.254 +//                    There is no Debug Error on purpose, since real errors should
   1.255 +//                    be handled by API user.
   1.256 +//
   1.257 +// Log_Assert      -  Debug-build only message, formatted with "Assert: %s\n".
   1.258 +//                    Intended for severe unrecoverable conditions in library
   1.259 +//                    source code. Generated though OVR_ASSERT_MSG(c, "Text").
   1.260 +
   1.261 +enum LogMessageType
   1.262 +{    
   1.263 +    // General Logging
   1.264 +    Log_Text        = LogMask_Regular | 0,    
   1.265 +    Log_Error       = LogMask_Regular | 1, // "Error: %s\n".
   1.266 +    
   1.267 +    // Debug-only messages (not generated in release build)
   1.268 +    Log_DebugText   = LogMask_Debug | 0,
   1.269 +    Log_Debug       = LogMask_Debug | 1,   // "Debug: %s\n".
   1.270 +    Log_Assert      = LogMask_Debug | 2,   // "Assert: %s\n".
   1.271 +};
   1.272 +
   1.273 +
   1.274 +// LOG_VAARG_ATTRIBUTE macro, enforces printf-style fromatting for message types
   1.275 +#ifdef __GNUC__
   1.276 +#  define OVR_LOG_VAARG_ATTRIBUTE(a,b) __attribute__((format (printf, a, b)))
   1.277 +#else
   1.278 +#  define OVR_LOG_VAARG_ATTRIBUTE(a,b)
   1.279 +#endif
   1.280 +
   1.281 +
   1.282 +//-----------------------------------------------------------------------------------
   1.283 +// ***** Log
   1.284 +
   1.285 +// Log defines a base class interface that can be implemented to catch both
   1.286 +// debug and runtime messages.
   1.287 +// Debug logging can be overridden by calling Log::SetGlobalLog.
   1.288 +
   1.289 +class Log
   1.290 +{
   1.291 +    friend class System;
   1.292 +public: 
   1.293 +    Log(unsigned logMask = LogMask_Debug) : LoggingMask(logMask) { }
   1.294 +    virtual ~Log();
   1.295 +
   1.296 +    // Log formating buffer size used by default LogMessageVarg. Longer strings are truncated.
   1.297 +    enum { MaxLogBufferMessageSize = 2048 };
   1.298 +
   1.299 +    unsigned        GetLoggingMask() const            { return LoggingMask; }
   1.300 +    void            SetLoggingMask(unsigned logMask)  { LoggingMask = logMask; }
   1.301 +
   1.302 +    // This virtual function receives all the messages,
   1.303 +    // developers should override this function in order to do custom logging
   1.304 +    virtual void    LogMessageVarg(LogMessageType messageType, const char* fmt, va_list argList);
   1.305 +
   1.306 +    // Call the logging function with specific message type, with no type filtering.
   1.307 +    void            LogMessage(LogMessageType messageType,
   1.308 +                               const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(3,4);
   1.309 +
   1.310 +
   1.311 +    // Helper used by LogMessageVarg to format the log message, writing the resulting
   1.312 +    // string into buffer. It formats text based on fmt and appends prefix/new line
   1.313 +    // based on LogMessageType.
   1.314 +    static void     FormatLog(char* buffer, unsigned bufferSize, LogMessageType messageType,
   1.315 +                              const char* fmt, va_list argList);
   1.316 +
   1.317 +    // Default log output implementation used by by LogMessageVarg.
   1.318 +    // Debug flag may be used to re-direct output on some platforms, but doesn't
   1.319 +    // necessarily disable it in release builds; that is the job of the called.    
   1.320 +    static void     DefaultLogOutput(const char* textBuffer, bool debug);
   1.321 +
   1.322 +    // Determines if the specified message type is for debugging only.
   1.323 +    static bool     IsDebugMessage(LogMessageType messageType)
   1.324 +    {
   1.325 +        return (messageType & LogMask_Debug) != 0;
   1.326 +    }
   1.327 +
   1.328 +    // *** Global APIs
   1.329 +
   1.330 +    // Global Log registration APIs.
   1.331 +    //  - Global log is used for OVR_DEBUG messages. Set global log to null (0)
   1.332 +    //    to disable all logging.
   1.333 +    static void     SetGlobalLog(Log *log);
   1.334 +    static Log*     GetGlobalLog();
   1.335 +
   1.336 +    // Returns default log singleton instance.
   1.337 +    static Log*     GetDefaultLog();
   1.338 +
   1.339 +    // Applies logMask to the default log and returns a pointer to it.
   1.340 +    // By default, only Debug logging is enabled, so to avoid SDK generating console
   1.341 +    // messages in user app (those are always disabled in release build,
   1.342 +    // even if the flag is set). This function is useful in System constructor.
   1.343 +    static Log*     ConfigureDefaultLog(unsigned logMask = LogMask_Debug)
   1.344 +    {
   1.345 +        Log* log = GetDefaultLog();
   1.346 +        log->SetLoggingMask(logMask);
   1.347 +        return log;
   1.348 +    }
   1.349 +
   1.350 +private:
   1.351 +    // Logging mask described by LogMaskConstants.
   1.352 +    unsigned    LoggingMask;
   1.353 +};
   1.354 +
   1.355 +
   1.356 +//-----------------------------------------------------------------------------------
   1.357 +// ***** Global Logging Functions and Debug Macros
   1.358 +
   1.359 +// These functions will output text to global log with semantics described by
   1.360 +// their LogMessageType.
   1.361 +void LogText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.362 +void LogError(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.363 +
   1.364 +#ifdef OVR_BUILD_DEBUG
   1.365 +
   1.366 +    // Debug build only logging.
   1.367 +    void LogDebugText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.368 +    void LogDebug(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.369 +    void LogAssert(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.370 +
   1.371 +    // Macro to do debug logging, printf-style.
   1.372 +    // An extra set of set of parenthesis must be used around arguments,
   1.373 +    // as in: OVR_LOG_DEBUG(("Value %d", 2)).
   1.374 +    #define OVR_DEBUG_LOG(args)       do { OVR::LogDebug args; } while(0)
   1.375 +    #define OVR_DEBUG_LOG_TEXT(args)  do { OVR::LogDebugText args; } while(0)
   1.376 +
   1.377 +    #define OVR_ASSERT_LOG(c, args)   do { if (!(c)) { OVR::LogAssert args; OVR_DEBUG_BREAK; } } while(0)
   1.378 +
   1.379 +#else
   1.380 +
   1.381 +    // If not in debug build, macros do nothing.
   1.382 +    #define OVR_DEBUG_LOG(args)         ((void)0)
   1.383 +    #define OVR_DEBUG_LOG_TEXT(args)    ((void)0)
   1.384 +    #define OVR_ASSERT_LOG(c, args)     ((void)0)
   1.385 +
   1.386 +#endif
   1.387 +
   1.388 +} // OVR 
   1.389 +
   1.390 +#endif