ovr_sdk
view LibOVR/Src/Kernel/OVR_Log.h @ 0:1b39a1b46319
initial 0.4.4
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Wed, 14 Jan 2015 06:51:16 +0200 |
| parents | |
| 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 2014 Oculus VR, LLC All Rights reserved.
11 Licensed under the Oculus VR Rift SDK License Version 3.2 (the "License");
12 you may not use the Oculus VR Rift SDK except in compliance with the License,
13 which is provided at the time of installation or download, or which
14 otherwise accompanies this software in either electronic or hard copy form.
16 You may obtain a copy of the License at
18 http://www.oculusvr.com/licenses/LICENSE-3.2
20 Unless required by applicable law or agreed to in writing, the Oculus VR SDK
21 distributed under the License is distributed on an "AS IS" BASIS,
22 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
23 See the License for the specific language governing permissions and
24 limitations under the License.
26 ************************************************************************************/
28 #ifndef OVR_Log_h
29 #define OVR_Log_h
31 #include "OVR_Types.h"
32 #include "../Kernel/OVR_Delegates.h"
33 #include "../Kernel//OVR_Observer.h"
34 #include <stdarg.h>
36 namespace OVR {
38 //-----------------------------------------------------------------------------------
39 // ***** Logging Constants
41 // LogMaskConstants defined bit mask constants that describe what log messages
42 // should be displayed.
43 enum LogMaskConstants
44 {
45 LogMask_Regular = 0x100,
46 LogMask_Debug = 0x200,
47 LogMask_None = 0,
48 LogMask_All = LogMask_Regular|LogMask_Debug
49 };
52 // LogMessageType describes the type of the log message, controls when it is
53 // displayed and what prefix/suffix is given to it. Messages are subdivided into
54 // regular and debug logging types. Debug logging is only generated in debug builds.
55 //
56 // Log_Text - General output text displayed without prefix or new-line.
57 // Used in OVR libraries for general log flow messages
58 // such as "Device Initialized".
59 //
60 // Log_Error - Error message output with "Error: %s\n", intended for
61 // application/sample-level use only, in cases where an expected
62 // operation failed. OVR libraries should not use this internally,
63 // reporting status codes instead.
64 //
65 // Log_DebugText - Message without prefix or new lines; output in Debug build only.
66 //
67 // Log_Debug - Debug-build only message, formatted with "Debug: %s\n".
68 // Intended to comment on incorrect API usage that doesn't lead
69 // to crashes but can be avoided with proper use.
70 // There is no Debug Error on purpose, since real errors should
71 // be handled by API user.
72 //
73 // Log_Assert - Debug-build only message, formatted with "Assert: %s\n".
74 // Intended for severe unrecoverable conditions in library
75 // source code. Generated though OVR_ASSERT_MSG(c, "Text").
77 enum LogMessageType
78 {
79 // General Logging
80 Log_Text = LogMask_Regular | 0,
81 Log_Error = LogMask_Regular | 1, // "Error: %s\n".
83 // Debug-only messages (not generated in release build)
84 Log_DebugText = LogMask_Debug | 0,
85 Log_Debug = LogMask_Debug | 1, // "Debug: %s\n".
86 Log_Assert = LogMask_Debug | 2, // "Assert: %s\n".
87 };
90 // LOG_VAARG_ATTRIBUTE macro, enforces printf-style fromatting for message types
91 #ifdef __GNUC__
92 # define OVR_LOG_VAARG_ATTRIBUTE(a,b) __attribute__((format (printf, a, b)))
93 #else
94 # define OVR_LOG_VAARG_ATTRIBUTE(a,b)
95 #endif
97 //-----------------------------------------------------------------------------------
98 // ***** Log
100 // Log defines a base class interface that can be implemented to catch both
101 // debug and runtime messages.
102 // Debug logging can be overridden by calling Log::SetGlobalLog.
104 class Log
105 {
106 friend class System;
108 #ifdef OVR_OS_WIN32
109 void* hEventSource;
110 #endif
112 public:
113 Log(unsigned logMask = LogMask_Debug);
114 virtual ~Log();
116 typedef Delegate2<void, const char*, LogMessageType> LogHandler;
118 // The following is deprecated, as there is no longer a max log buffer message size.
119 enum { MaxLogBufferMessageSize = 4096 };
121 unsigned GetLoggingMask() const { return LoggingMask; }
122 void SetLoggingMask(unsigned logMask) { LoggingMask = logMask; }
124 // Internal
125 // Invokes observers, then calls LogMessageVarg()
126 static void LogMessageVargInt(LogMessageType messageType, const char* fmt, va_list argList);
128 // This virtual function receives all the messages,
129 // developers should override this function in order to do custom logging
130 virtual void LogMessageVarg(LogMessageType messageType, const char* fmt, va_list argList);
132 static void AddLogObserver(ObserverScope<LogHandler> *logObserver);
134 // Call the logging function with specific message type, with no type filtering.
135 void LogMessage(LogMessageType messageType,
136 const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(3,4);
139 // Helper used by LogMessageVarg to format the log message, writing the resulting
140 // string into buffer. It formats text based on fmt and appends prefix/new line
141 // based on LogMessageType. Return behavior is the same as ISO C vsnprintf: returns the
142 // required strlen of buffer (which will be >= bufferSize if bufferSize is insufficient)
143 // or returns a negative value because the input was bad.
144 static int FormatLog(char* buffer, size_t bufferSize, LogMessageType messageType,
145 const char* fmt, va_list argList);
147 // Default log output implementation used by by LogMessageVarg.
148 // Debug flag may be used to re-direct output on some platforms, but doesn't
149 // necessarily disable it in release builds; that is the job of the called.
150 void DefaultLogOutput(const char* textBuffer, LogMessageType messageType, int bufferSize = -1);
152 // Determines if the specified message type is for debugging only.
153 static bool IsDebugMessage(LogMessageType messageType)
154 {
155 return (messageType & LogMask_Debug) != 0;
156 }
158 // *** Global APIs
160 // Global Log registration APIs.
161 // - Global log is used for OVR_DEBUG messages. Set global log to null (0)
162 // to disable all logging.
163 static void SetGlobalLog(Log *log);
164 static Log* GetGlobalLog();
166 // Returns default log singleton instance.
167 static Log* GetDefaultLog();
169 // Applies logMask to the default log and returns a pointer to it.
170 // By default, only Debug logging is enabled, so to avoid SDK generating console
171 // messages in user app (those are always disabled in release build,
172 // even if the flag is set). This function is useful in System constructor.
173 static Log* ConfigureDefaultLog(unsigned logMask = LogMask_Debug)
174 {
175 Log* log = GetDefaultLog();
176 log->SetLoggingMask(logMask);
177 return log;
178 }
180 private:
181 // Logging mask described by LogMaskConstants.
182 unsigned LoggingMask;
183 };
186 //-----------------------------------------------------------------------------------
187 // ***** Global Logging Functions and Debug Macros
189 // These functions will output text to global log with semantics described by
190 // their LogMessageType.
191 void LogText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
192 void LogError(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
194 #ifdef OVR_BUILD_DEBUG
196 // Debug build only logging.
197 void LogDebugText(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
198 void LogDebug(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
199 void LogAssert(const char* fmt, ...) OVR_LOG_VAARG_ATTRIBUTE(1,2);
201 // Macro to do debug logging, printf-style.
202 // An extra set of set of parenthesis must be used around arguments,
203 // as in: OVR_DEBUG_LOG(("Value %d", 2)).
204 #define OVR_DEBUG_LOG(args) do { OVR::LogDebug args; } while(0)
205 #define OVR_DEBUG_LOG_TEXT(args) do { OVR::LogDebugText args; } while(0)
207 // Conditional logging. It logs when the condition 'c' is true.
208 #define OVR_DEBUG_LOG_COND(c, args) do { if ((c)) { OVR::LogDebug args; } } while(0)
209 #define OVR_DEBUG_LOG_TEXT_COND(c, args) do { if ((c)) { OVR::LogDebugText args; } } while(0)
211 // Conditional logging & asserting. It asserts/logs when the condition 'c' is NOT true.
212 #define OVR_ASSERT_LOG(c, args) do { if (!(c)) { OVR::LogAssert args; OVR_DEBUG_BREAK; } } while(0)
214 #else
216 // If not in debug build, macros do nothing.
217 #define OVR_DEBUG_LOG(args) ((void)0)
218 #define OVR_DEBUG_LOG_TEXT(args) ((void)0)
219 #define OVR_DEBUG_LOG_COND(c, args) ((void)0)
220 #define OVR_DEBUG_LOG_TEXT_COND(args) ((void)0)
221 #define OVR_ASSERT_LOG(c, args) ((void)0)
223 #endif
225 } // OVR
227 #endif