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