oculus1

annotate libovr/Src/Kernel/OVR_Log.h @ 17:cfe4979ab3eb

find changesets by author, revision, files, or words in the commit message
ops, minor error in the last commit
author John Tsiombikas <nuclear@member.fsf.org>
date Sat, 21 Sep 2013 07:09:48 +0300
parents e2f9e4603129
children
rev   line source
nuclear@3 1 /************************************************************************************
nuclear@3 2
nuclear@3 3 PublicHeader: OVR
nuclear@3 4 Filename : OVR_Log.h
nuclear@3 5 Content : Logging support
nuclear@3 6 Created : September 19, 2012
nuclear@3 7 Notes :
nuclear@3 8
nuclear@3 9 Copyright : Copyright 2012 Oculus VR, Inc. All Rights reserved.
nuclear@3 10
nuclear@3 11 Use of this software is subject to the terms of the Oculus license
nuclear@3 12 agreement provided at the time of installation or download, or which
nuclear@3 13 otherwise accompanies this software in either electronic or hard copy form.
nuclear@3 14
nuclear@3 15 ************************************************************************************/
nuclear@3 16
nuclear@3 17 #ifndef OVR_Log_h
nuclear@3 18 #define OVR_Log_h
nuclear@3 19
nuclear@3 20 #include "OVR_Types.h"
nuclear@3 21 #include <stdarg.h>
nuclear@3 22
nuclear@3 23 namespace OVR {
nuclear@3 24
nuclear@3 25 //-----------------------------------------------------------------------------------
nuclear@3 26 // ***** Logging Constants
nuclear@3 27
nuclear@3 28 // LogMaskConstants defined bit mask constants that describe what log messages
nuclear@3 29 // should be displayed.
nuclear@3 30 enum LogMaskConstants
nuclear@3 31 {
nuclear@3 32 LogMask_Regular = 0x100,
nuclear@3 33 LogMask_Debug = 0x200,
nuclear@3 34 LogMask_None = 0,
nuclear@3 35 LogMask_All = LogMask_Regular|LogMask_Debug
nuclear@3 36 };
nuclear@3 37
nuclear@3 38
nuclear@3 39 // LogMessageType describes the type of the log message, controls when it is
nuclear@3 40 // displayed and what prefix/suffix is given to it. Messages are subdivided into
nuclear@3 41 // regular and debug logging types. Debug logging is only generated in debug builds.
nuclear@3 42 //
nuclear@3 43 // Log_Text - General output text displayed without prefix or new-line.
nuclear@3 44 // Used in OVR libraries for general log flow messages
nuclear@3 45 // such as "Device Initialized".
nuclear@3 46 //
nuclear@3 47 // Log_Error - Error message output with "Error: %s\n", intended for
nuclear@3 48 // application/sample-level use only, in cases where an expected
nuclear@3 49 // operation failed. OVR libraries should not use this internally,
nuclear@3 50 // reporting status codes instead.
nuclear@3 51 //
nuclear@3 52 // Log_DebugText - Message without prefix or new lines; output in Debug build only.
nuclear@3 53 //
nuclear@3 54 // Log_Debug - Debug-build only message, formatted with "Debug: %s\n".
nuclear@3 55 // Intended to comment on incorrect API usage that doesn't lead
nuclear@3 56 // to crashes but can be avoided with proper use.
nuclear@3 57 // There is no Debug Error on purpose, since real errors should
nuclear@3 58 // be handled by API user.
nuclear@3 59 //
nuclear@3 60 // Log_Assert - Debug-build only message, formatted with "Assert: %s\n".
nuclear@3 61 // Intended for severe unrecoverable conditions in library
nuclear@3 62 // source code. Generated though OVR_ASSERT_MSG(c, "Text").
nuclear@3 63
nuclear@3 64 enum LogMessageType
nuclear@3 65 {
nuclear@3 66 // General Logging
nuclear@3 67 Log_Text = LogMask_Regular | 0,
nuclear@3 68 Log_Error = LogMask_Regular | 1, // "Error: %s\n".
nuclear@3 69
nuclear@3 70 // Debug-only messages (not generated in release build)
nuclear@3 71 Log_DebugText = LogMask_Debug | 0,
nuclear@3 72 Log_Debug = LogMask_Debug | 1, // "Debug: %s\n".
nuclear@3 73 Log_Assert = LogMask_Debug | 2, // "Assert: %s\n".
nuclear@3 74 };
nuclear@3 75
nuclear@3 76
nuclear@3 77 // LOG_VAARG_ATTRIBUTE macro, enforces printf-style fromatting for message types
nuclear@3 78 #ifdef __GNUC__
nuclear@3 79 # define OVR_LOG_VAARG_ATTRIBUTE(a,b) __attribute__((format (printf, a, b)))
nuclear@3 80 #else
nuclear@3 81 # define OVR_LOG_VAARG_ATTRIBUTE(a,b)
nuclear@3 82 #endif
nuclear@3 83
nuclear@3 84
nuclear@3 85 //-----------------------------------------------------------------------------------
nuclear@3 86 // ***** Log
nuclear@3 87
nuclear@3 88 // Log defines a base class interface that can be implemented to catch both
nuclear@3 89 // debug and runtime messages.
nuclear@3 90 // Debug logging can be overridden by calling Log::SetGlobalLog.
nuclear@3 91
nuclear@3 92 class Log
nuclear@3 93 {
nuclear@3 94 friend class System;
nuclear@3 95 public:
nuclear@3 96 Log(unsigned logMask = LogMask_Debug) : LoggingMask(logMask) { }
nuclear@3 97 virtual ~Log();
nuclear@3 98
nuclear@3 99 // Log formating buffer size used by default LogMessageVarg. Longer strings are truncated.
nuclear@3 100 enum { MaxLogBufferMessageSize = 2048 };
nuclear@3 101
nuclear@3 102 unsigned GetLoggingMask() const { return LoggingMask; }
nuclear@3 103 void SetLoggingMask(unsigned logMask) { LoggingMask = logMask; }
nuclear@3 104
nuclear@3 105 // This virtual function receives all the messages,
nuclear@3 106 // developers should override this function in order to do custom logging
nuclear@3 107 virtual void LogMessageVarg(LogMessageType messageType, const char* fmt, va_list argList);
nuclear@3 108
nuclear@3 109 // Call the logging function with specific message type, with no type filtering.
nuclear@3 110 void LogMessage(LogMessageType messageType,
nuclear@3 111 const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(3,4);
nuclear@3 112
nuclear@3 113
nuclear@3 114 // Helper used by LogMessageVarg to format the log message, writing the resulting
nuclear@3 115 // string into buffer. It formats text based on fmt and appends prefix/new line
nuclear@3 116 // based on LogMessageType.
nuclear@3 117 static void FormatLog(char* buffer, unsigned bufferSize, LogMessageType messageType,
nuclear@3 118 const char* fmt, va_list argList);
nuclear@3 119
nuclear@3 120 // Default log output implementation used by by LogMessageVarg.
nuclear@3 121 // Debug flag may be used to re-direct output on some platforms, but doesn't
nuclear@3 122 // necessarily disable it in release builds; that is the job of the called.
nuclear@3 123 static void DefaultLogOutput(const char* textBuffer, bool debug);
nuclear@3 124
nuclear@3 125 // Determines if the specified message type is for debugging only.
nuclear@3 126 static bool IsDebugMessage(LogMessageType messageType)
nuclear@3 127 {
nuclear@3 128 return (messageType & LogMask_Debug) != 0;
nuclear@3 129 }
nuclear@3 130
nuclear@3 131 // *** Global APIs
nuclear@3 132
nuclear@3 133 // Global Log registration APIs.
nuclear@3 134 // - Global log is used for OVR_DEBUG messages. Set global log to null (0)
nuclear@3 135 // to disable all logging.
nuclear@3 136 static void SetGlobalLog(Log *log);
nuclear@3 137 static Log* GetGlobalLog();
nuclear@3 138
nuclear@3 139 // Returns default log singleton instance.
nuclear@3 140 static Log* GetDefaultLog();
nuclear@3 141
nuclear@3 142 // Applies logMask to the default log and returns a pointer to it.
nuclear@3 143 // By default, only Debug logging is enabled, so to avoid SDK generating console
nuclear@3 144 // messages in user app (those are always disabled in release build,
nuclear@3 145 // even if the flag is set). This function is useful in System constructor.
nuclear@3 146 static Log* ConfigureDefaultLog(unsigned logMask = LogMask_Debug)
nuclear@3 147 {
nuclear@3 148 Log* log = GetDefaultLog();
nuclear@3 149 log->SetLoggingMask(logMask);
nuclear@3 150 return log;
nuclear@3 151 }
nuclear@3 152
nuclear@3 153 private:
nuclear@3 154 // Logging mask described by LogMaskConstants.
nuclear@3 155 unsigned LoggingMask;
nuclear@3 156 };
nuclear@3 157
nuclear@3 158
nuclear@3 159 //-----------------------------------------------------------------------------------
nuclear@3 160 // ***** Global Logging Functions and Debug Macros
nuclear@3 161
nuclear@3 162 // These functions will output text to global log with semantics described by
nuclear@3 163 // their LogMessageType.
nuclear@3 164 void LogText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
nuclear@3 165 void LogError(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
nuclear@3 166
nuclear@3 167 #ifdef OVR_BUILD_DEBUG
nuclear@3 168
nuclear@3 169 // Debug build only logging.
nuclear@3 170 void LogDebugText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
nuclear@3 171 void LogDebug(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
nuclear@3 172 void LogAssert(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
nuclear@3 173
nuclear@3 174 // Macro to do debug logging, printf-style.
nuclear@3 175 // An extra set of set of parenthesis must be used around arguments,
nuclear@3 176 // as in: OVR_LOG_DEBUG(("Value %d", 2)).
nuclear@3 177 #define OVR_DEBUG_LOG(args) do { OVR::LogDebug args; } while(0)
nuclear@3 178 #define OVR_DEBUG_LOG_TEXT(args) do { OVR::LogDebugText args; } while(0)
nuclear@3 179
nuclear@3 180 #define OVR_ASSERT_LOG(c, args) do { if (!(c)) { OVR::LogAssert args; OVR_DEBUG_BREAK; } } while(0)
nuclear@3 181
nuclear@3 182 #else
nuclear@3 183
nuclear@3 184 // If not in debug build, macros do nothing.
nuclear@3 185 #define OVR_DEBUG_LOG(args) ((void)0)
nuclear@3 186 #define OVR_DEBUG_LOG_TEXT(args) ((void)0)
nuclear@3 187 #define OVR_ASSERT_LOG(c, args) ((void)0)
nuclear@3 188
nuclear@3 189 #endif
nuclear@3 190
nuclear@3 191 } // OVR
nuclear@3 192
nuclear@3 193 #endif