oculus1

annotate libovr/Src/Kernel/OVR_Log.h @ 1:e2f9e4603129

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