1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/LibOVR/Src/Kernel/OVR_Log.h	Wed Jan 14 06:51:16 2015 +0200
     1.3 @@ -0,0 +1,227 @@
     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 2014 Oculus VR, LLC All Rights reserved.
    1.13 +
    1.14 +Licensed under the Oculus VR Rift SDK License Version 3.2 (the "License"); 
    1.15 +you may not use the Oculus VR Rift SDK except in compliance with the License, 
    1.16 +which is provided at the time of installation or download, or which 
    1.17 +otherwise accompanies this software in either electronic or hard copy form.
    1.18 +
    1.19 +You may obtain a copy of the License at
    1.20 +
    1.21 +http://www.oculusvr.com/licenses/LICENSE-3.2 
    1.22 +
    1.23 +Unless required by applicable law or agreed to in writing, the Oculus VR SDK 
    1.24 +distributed under the License is distributed on an "AS IS" BASIS,
    1.25 +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    1.26 +See the License for the specific language governing permissions and
    1.27 +limitations under the License.
    1.28 +
    1.29 +************************************************************************************/
    1.30 +
    1.31 +#ifndef OVR_Log_h
    1.32 +#define OVR_Log_h
    1.33 +
    1.34 +#include "OVR_Types.h"
    1.35 +#include "../Kernel/OVR_Delegates.h"
    1.36 +#include "../Kernel//OVR_Observer.h"
    1.37 +#include <stdarg.h>
    1.38 +
    1.39 +namespace OVR {
    1.40 +
    1.41 +//-----------------------------------------------------------------------------------
    1.42 +// ***** Logging Constants
    1.43 +
    1.44 +// LogMaskConstants defined bit mask constants that describe what log messages
    1.45 +// should be displayed.
    1.46 +enum LogMaskConstants
    1.47 +{
    1.48 +    LogMask_Regular = 0x100,
    1.49 +    LogMask_Debug   = 0x200,
    1.50 +    LogMask_None    = 0,
    1.51 +    LogMask_All     = LogMask_Regular|LogMask_Debug
    1.52 +};
    1.53 +
    1.54 +
    1.55 +// LogMessageType describes the type of the log message, controls when it is
    1.56 +// displayed and what prefix/suffix is given to it. Messages are subdivided into
    1.57 +// regular and debug logging types. Debug logging is only generated in debug builds.
    1.58 +//
    1.59 +// Log_Text         - General output text displayed without prefix or new-line.
    1.60 +//                    Used in OVR libraries for general log flow messages
    1.61 +//                    such as "Device Initialized".
    1.62 +//
    1.63 +// Log_Error        - Error message output with "Error: %s\n", intended for
    1.64 +//                    application/sample-level use only, in cases where an expected
    1.65 +//                    operation failed. OVR libraries should not use this internally,
    1.66 +//                    reporting status codes instead.
    1.67 +//
    1.68 +// Log_DebugText    - Message without prefix or new lines; output in Debug build only.
    1.69 +//
    1.70 +// Log_Debug        - Debug-build only message, formatted with "Debug: %s\n".
    1.71 +//                    Intended to comment on incorrect API usage that doesn't lead
    1.72 +//                    to crashes but can be avoided with proper use.
    1.73 +//                    There is no Debug Error on purpose, since real errors should
    1.74 +//                    be handled by API user.
    1.75 +//
    1.76 +// Log_Assert      -  Debug-build only message, formatted with "Assert: %s\n".
    1.77 +//                    Intended for severe unrecoverable conditions in library
    1.78 +//                    source code. Generated though OVR_ASSERT_MSG(c, "Text").
    1.79 +
    1.80 +enum LogMessageType
    1.81 +{    
    1.82 +    // General Logging
    1.83 +    Log_Text        = LogMask_Regular | 0,    
    1.84 +    Log_Error       = LogMask_Regular | 1, // "Error: %s\n".
    1.85 +    
    1.86 +    // Debug-only messages (not generated in release build)
    1.87 +    Log_DebugText   = LogMask_Debug | 0,
    1.88 +    Log_Debug       = LogMask_Debug | 1,   // "Debug: %s\n".
    1.89 +    Log_Assert      = LogMask_Debug | 2,   // "Assert: %s\n".
    1.90 +};
    1.91 +
    1.92 +
    1.93 +// LOG_VAARG_ATTRIBUTE macro, enforces printf-style fromatting for message types
    1.94 +#ifdef __GNUC__
    1.95 +#  define OVR_LOG_VAARG_ATTRIBUTE(a,b) __attribute__((format (printf, a, b)))
    1.96 +#else
    1.97 +#  define OVR_LOG_VAARG_ATTRIBUTE(a,b)
    1.98 +#endif
    1.99 +
   1.100 +//-----------------------------------------------------------------------------------
   1.101 +// ***** Log
   1.102 +
   1.103 +// Log defines a base class interface that can be implemented to catch both
   1.104 +// debug and runtime messages.
   1.105 +// Debug logging can be overridden by calling Log::SetGlobalLog.
   1.106 +
   1.107 +class Log
   1.108 +{
   1.109 +	friend class System;
   1.110 +
   1.111 +#ifdef OVR_OS_WIN32
   1.112 +    void* hEventSource;
   1.113 +#endif
   1.114 +
   1.115 +public: 
   1.116 +    Log(unsigned logMask = LogMask_Debug);
   1.117 +    virtual ~Log();
   1.118 +
   1.119 +	typedef Delegate2<void, const char*, LogMessageType> LogHandler;
   1.120 +
   1.121 +    // The following is deprecated, as there is no longer a max log buffer message size.
   1.122 +    enum { MaxLogBufferMessageSize = 4096 };
   1.123 +
   1.124 +    unsigned        GetLoggingMask() const            { return LoggingMask; }
   1.125 +    void            SetLoggingMask(unsigned logMask)  { LoggingMask = logMask; }
   1.126 +
   1.127 +	// Internal
   1.128 +	// Invokes observers, then calls LogMessageVarg()
   1.129 +	static void    LogMessageVargInt(LogMessageType messageType, const char* fmt, va_list argList);
   1.130 +
   1.131 +    // This virtual function receives all the messages,
   1.132 +    // developers should override this function in order to do custom logging
   1.133 +    virtual void    LogMessageVarg(LogMessageType messageType, const char* fmt, va_list argList);
   1.134 +
   1.135 +	static void		AddLogObserver(ObserverScope<LogHandler> *logObserver);
   1.136 +
   1.137 +    // Call the logging function with specific message type, with no type filtering.
   1.138 +    void            LogMessage(LogMessageType messageType,
   1.139 +                               const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(3,4);
   1.140 +
   1.141 +
   1.142 +    // Helper used by LogMessageVarg to format the log message, writing the resulting
   1.143 +    // string into buffer. It formats text based on fmt and appends prefix/new line
   1.144 +    // based on LogMessageType. Return behavior is the same as ISO C vsnprintf: returns the 
   1.145 +    // required strlen of buffer (which will be >= bufferSize if bufferSize is insufficient)
   1.146 +    // or returns a negative value because the input was bad.
   1.147 +    static int     FormatLog(char* buffer, size_t bufferSize, LogMessageType messageType,
   1.148 +                              const char* fmt, va_list argList);
   1.149 +
   1.150 +    // Default log output implementation used by by LogMessageVarg.
   1.151 +    // Debug flag may be used to re-direct output on some platforms, but doesn't
   1.152 +    // necessarily disable it in release builds; that is the job of the called.    
   1.153 +    void            DefaultLogOutput(const char* textBuffer, LogMessageType messageType, int bufferSize = -1);
   1.154 +
   1.155 +    // Determines if the specified message type is for debugging only.
   1.156 +    static bool     IsDebugMessage(LogMessageType messageType)
   1.157 +    {
   1.158 +        return (messageType & LogMask_Debug) != 0;
   1.159 +    }
   1.160 +
   1.161 +    // *** Global APIs
   1.162 +
   1.163 +    // Global Log registration APIs.
   1.164 +    //  - Global log is used for OVR_DEBUG messages. Set global log to null (0)
   1.165 +    //    to disable all logging.
   1.166 +    static void     SetGlobalLog(Log *log);
   1.167 +    static Log*     GetGlobalLog();
   1.168 +
   1.169 +    // Returns default log singleton instance.
   1.170 +    static Log*     GetDefaultLog();
   1.171 +
   1.172 +    // Applies logMask to the default log and returns a pointer to it.
   1.173 +    // By default, only Debug logging is enabled, so to avoid SDK generating console
   1.174 +    // messages in user app (those are always disabled in release build,
   1.175 +    // even if the flag is set). This function is useful in System constructor.
   1.176 +    static Log*     ConfigureDefaultLog(unsigned logMask = LogMask_Debug)
   1.177 +    {
   1.178 +        Log* log = GetDefaultLog();
   1.179 +        log->SetLoggingMask(logMask);
   1.180 +        return log;
   1.181 +    }
   1.182 +
   1.183 +private:
   1.184 +    // Logging mask described by LogMaskConstants.
   1.185 +    unsigned    LoggingMask;
   1.186 +};
   1.187 +
   1.188 +
   1.189 +//-----------------------------------------------------------------------------------
   1.190 +// ***** Global Logging Functions and Debug Macros
   1.191 +
   1.192 +// These functions will output text to global log with semantics described by
   1.193 +// their LogMessageType.
   1.194 +void LogText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.195 +void LogError(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.196 +
   1.197 +#ifdef OVR_BUILD_DEBUG
   1.198 +
   1.199 +    // Debug build only logging.
   1.200 +    void LogDebugText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.201 +    void LogDebug(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.202 +    void LogAssert(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
   1.203 +
   1.204 +    // Macro to do debug logging, printf-style.
   1.205 +    // An extra set of set of parenthesis must be used around arguments,
   1.206 +    // as in: OVR_DEBUG_LOG(("Value %d", 2)).
   1.207 +    #define OVR_DEBUG_LOG(args)       do { OVR::LogDebug args; } while(0)
   1.208 +    #define OVR_DEBUG_LOG_TEXT(args)  do { OVR::LogDebugText args; } while(0)
   1.209 +
   1.210 +	// Conditional logging. It logs when the condition 'c' is true.
   1.211 +	#define OVR_DEBUG_LOG_COND(c, args)			do { if ((c)) { OVR::LogDebug args; } } while(0)
   1.212 +	#define OVR_DEBUG_LOG_TEXT_COND(c, args)	do { if ((c)) { OVR::LogDebugText args; } } while(0)
   1.213 +
   1.214 +	// Conditional logging & asserting. It asserts/logs when the condition 'c' is NOT true.
   1.215 +    #define OVR_ASSERT_LOG(c, args)	  do { if (!(c)) { OVR::LogAssert args; OVR_DEBUG_BREAK; } } while(0)
   1.216 +
   1.217 +#else
   1.218 +
   1.219 +    // If not in debug build, macros do nothing.
   1.220 +    #define OVR_DEBUG_LOG(args)				((void)0)
   1.221 +    #define OVR_DEBUG_LOG_TEXT(args)		((void)0)
   1.222 +	#define OVR_DEBUG_LOG_COND(c, args)		((void)0)
   1.223 +	#define OVR_DEBUG_LOG_TEXT_COND(args)	((void)0)
   1.224 +    #define OVR_ASSERT_LOG(c, args)			((void)0)
   1.225 +
   1.226 +#endif
   1.227 +
   1.228 +} // OVR 
   1.229 +
   1.230 +#endif