dali/integration-api/debug.h

   1 #ifndef __DALI_INTEGRATION_DEBUG_H__
   2 #define __DALI_INTEGRATION_DEBUG_H__
   3
   4 /*
   5  * Copyright (c) 2018 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <string>
  23 #include <sstream>
  24 #include <iostream>
  25 #include <list>
  26 #include <stdint.h>
  27
  28 #include <dali/public-api/common/vector-wrapper.h>
  29 #include <dali/public-api/object/property-map.h>
  30
  31 // INTERNAL INCLUDES
  32 #include <dali/public-api/common/dali-common.h>
  33
  34 // Using Debug namespace alias shortens the log usage significantly
  35 namespace Dali{namespace Integration{namespace Log{}}}
  36 namespace Debug = Dali::Integration::Log;
  37
  38 namespace Dali
  39 {
  40
  41 struct Vector2;
  42 struct Vector3;
  43 struct Vector4;
  44 class Matrix3;
  45 class Matrix;
  46 class Quaternion;
  47
  48 #if defined(DEBUG_ENABLED)
  49
  50 // Less opaque types for debugger
  51 typedef std::vector<Dali::Property::Value> DebugPropertyValueArray;
  52 typedef std::pair< Property::Index, Property::Value > DebugIndexValuePair;
  53 typedef std::vector<Dali::StringValuePair> DebugStringValueContainer;
  54 typedef std::vector< DebugIndexValuePair > DebugIndexValueContainer;
  55
  56 struct DebugPropertyValueMap
  57 {
  58   DebugStringValueContainer stringValues;
  59   DebugIndexValueContainer  intValues;
  60 };
  61
  62 // Fake globals for gdb typedefs
  63 extern Dali::DebugPropertyValueArray gValueArray;
  64 extern Dali::DebugPropertyValueMap   gValueMap;
  65
  66 #endif
  67
  68 namespace Integration
  69 {
  70 namespace Log
  71 {
  72
  73 enum DebugPriority
  74 {
  75   DebugInfo,
  76   DebugWarning,
  77   DebugError
  78 };
  79
  80 /**
  81  * Used by logging macros to log a message along with function/class name
  82  * @param level debug level
  83  * @param format string format
  84  */
  85 DALI_CORE_API void LogMessage(enum DebugPriority level,const char *format, ...);
  86
  87 /**
  88  * typedef for the logging function.
  89  */
  90 typedef void (*LogFunction)(DebugPriority priority, std::string& message);
  91
  92 /**
  93  * A log function has to be installed for every thread that wants to use logging.
  94  * This should be done by the adaptor.
  95  * The log function can be different for each thread.
  96  * @param logFunction the log function to install
  97  * @param logOpts the log options to save in thread
  98  */
  99 DALI_CORE_API void InstallLogFunction(const LogFunction& logFunction);
 100
 101 /**
 102  * A log function has to be uninstalled for every thread that wants to use logging.
 103  * The log function can be different for each thread.
 104  */
 105 DALI_CORE_API void UninstallLogFunction();
 106
 107 /********************************************************************************
 108  *                            Error/Warning  macros.                            *
 109  ********************************************************************************/
 110
 111 /**
 112  * Provides unfiltered logging for global error level messages
 113  */
 114 #define DALI_LOG_ERROR(format, args...)     Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugError,   "%s " format, __PRETTY_FUNCTION__, ## args)
 115
 116 #define DALI_LOG_ERROR_NOFN(format, args...)     Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugError, format, ## args)
 117
 118 #define DALI_LOG_WARNING_NOFN(format, args...)     Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugWarning, format, ## args)
 119
 120 /**
 121  * Provides unfiltered logging for fps monitor
 122  */
 123 #define DALI_LOG_FPS(format, args...)     Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugInfo, format, ## args)
 124
 125 /**
 126  * Provides unfiltered logging for update status
 127  */
 128 #define DALI_LOG_UPDATE_STATUS(format, args...)     Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugInfo, format, ## args)
 129
 130 /**
 131  * Provides unfiltered logging for render information
 132  */
 133 #define DALI_LOG_RENDER_INFO(format, args...)     Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugInfo, format, ## args)
 134
 135 /**
 136  * Provides unfiltered logging for release
 137  */
 138 #define DALI_LOG_RELEASE_INFO(format, args...)     Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugInfo, format, ## args)
 139
 140 #ifdef DEBUG_ENABLED
 141
 142 /**
 143  * Provides unfiltered logging for global warning level messages
 144  */
 145 #define DALI_LOG_WARNING(format, args...)   Dali::Integration::Log::LogMessage(Dali::Integration::Log::DebugWarning, "%s " format, __PRETTY_FUNCTION__, ## args)
 146
 147
 148 #else // DEBUG_ENABLED
 149
 150 // Don't warn on release build
 151 #define DALI_LOG_WARNING(format, args...)
 152
 153 #endif
 154
 155 /********************************************************************************
 156  *                                    Filter                                    *
 157  ********************************************************************************/
 158
 159 #ifdef DEBUG_ENABLED
 160
 161 /**
 162  * Enumeration of logging levels.
 163  * Used by the filters to provide multiple log levels.
 164  * In general, the higher the value, the more debug is available for that filter.
 165  */
 166 enum LogLevel
 167 {
 168   NoLogging   = 0,
 169   Concise     = 1,
 170   General     = 2,
 171   Verbose     = 3
 172 };
 173
 174
 175 /**
 176  * The Filter object is used by the DALI_LOG_INFO macro and others to determine if the logging
 177  * should take place, and routes the logging via the platform abstraction's LogMessage.
 178  *
 179  * It provides a logging level. If this is set to zero, then DALI_LOG_INFO won't log anything.
 180  * It provides the ability to turn tracing on or off.
 181  *
 182  */
 183 class DALI_CORE_API Filter
 184 {
 185 public:
 186   typedef std::list<Filter*>           FilterList;
 187   typedef std::list<Filter*>::iterator FilterIter;
 188
 189 public:
 190
 191   /**
 192    * Test if the filter is enabled for the given logging level
 193    * @param[in] level - the level to test.
 194    * @return true if this level of logging is enabled.
 195    */
 196   bool IsEnabledFor(LogLevel level) { return level != Debug::NoLogging && level <= mLoggingLevel;}
 197
 198   /**
 199    * Test if trace is enabled for this filter.
 200    * @return true if trace is enabled;
 201    */
 202   bool IsTraceEnabled() { return mTraceEnabled; }
 203
 204   /**
 205    * Enable tracing on this filter.
 206    */
 207   void EnableTrace() { mTraceEnabled = true; }
 208
 209   /**
 210    * Disable tracing on this filter.
 211    */
 212   void DisableTrace() { mTraceEnabled = false; }
 213
 214   /**
 215    * Set the log level for this filter. Setting to a higher value than Debug::General also
 216    * enables General;
 217    */
 218   void SetLogLevel(LogLevel level) { mLoggingLevel = level; }
 219
 220   /**
 221    * Perform the logging for this filter.
 222    */
 223   void Log(LogLevel level, const char* format, ...);
 224
 225   /**
 226    * Create a new filter whose debug level and trace can be modified through the use of an
 227    * environment variable.
 228    *
 229    * @param[in] level The default log level
 230    * @param[in] trace The default trace level. If true, function tracing is on.
 231    * @param[in] environmentVariableName The environment variable name used in order to change the
 232    *                                    log level or trace.
 233    *
 234    * @info To modify logg level/trace at runtime, you can should define your filter as shown below:
 235    *
 236    * @code
 237    * Debug::Filter* filter = Debug::Filter::New( Debug::NoLogging, false, "FILTER_ENV" );
 238    * @endcode
 239    *
 240    * And to use it when running an executable:
 241    * @code
 242    * FILTER_ENV=3 dali-demo        // LogLevel Verbose,   Trace using default
 243    * FILTER_ENV=1,true dali-demo   // LogLevel Concise,   Trace ON
 244    * FILTER_ENV=2,false dali-demo  // LogLevel General,   Trace OFF
 245    * FILTER_ENV=0,true dali-demo   // LogLevel NoLogging, Trace ON
 246    * @endcode
 247    */
 248   static Filter* New(LogLevel level, bool trace, const char * environmentVariableName );
 249
 250   /**
 251    * Enable trace on all filters.
 252    */
 253   void EnableGlobalTrace();
 254
 255   /**
 256    * Disable trace on all filters.
 257    */
 258   void DisableGlobalTrace();
 259
 260 private:
 261
 262   /**
 263    * Constructor.
 264    * @param[in] level - the highest log level.
 265    * @param[in] trace - whether this filter allows tracing.
 266    */
 267   Filter(LogLevel level, bool trace) : mLoggingLevel(level), mTraceEnabled(trace), mNesting(0) {}
 268
 269   static FilterList* GetActiveFilters();
 270
 271 public:
 272   // High level filters. If these filters are too broad for your current requirement, then
 273   // you can add a filter to your own class or source file. If you do, use Filter::New()
 274   // to tell this class about it.
 275
 276   static Filter *gRender;
 277   static Filter *gResource;
 278   static Filter *gGLResource;
 279   static Filter *gObject;
 280   static Filter *gImage;
 281   static Filter *gModel;
 282   static Filter *gNode;
 283   static Filter *gElement;
 284   static Filter *gActor;
 285   static Filter *gShader;
 286
 287 private:
 288   LogLevel mLoggingLevel;
 289   bool     mTraceEnabled;
 290 public:
 291   int      mNesting;
 292
 293 };
 294
 295
 296 #define  DALI_LOG_FILTER_SET_LEVEL(filter, level) filter->SetLogLevel(level)
 297 #define  DALI_LOG_FILTER_ENABLE_TRACE(filter)     filter->EnableTrace()
 298 #define  DALI_LOG_FILTER_DISABLE_TRACE(filter)    filter->DisableTrace()
 299
 300 #else
 301
 302 #define  DALI_LOG_FILTER_SET_LEVEL(filter, level)
 303 #define  DALI_LOG_FILTER_ENABLE_TRACE(filter)
 304 #define  DALI_LOG_FILTER_DISABLE_TRACE(filter)
 305
 306 #endif
 307
 308 /********************************************************************************
 309  *                            General Logging macros                            *
 310  ********************************************************************************/
 311
 312 #ifdef DEBUG_ENABLED
 313
 314 #define DALI_LOG_INFO(filter, level, format, args...)                        \
 315   if(filter && filter->IsEnabledFor(level)) { filter->Log(level, format,  ## args); }
 316
 317 #define DALI_LOG_STREAM( filter, level, stream )  \
 318   if(filter && filter->IsEnabledFor(level))       \
 319   {                                               \
 320     std::ostringstream o;                         \
 321     o << stream << std::endl;                     \
 322     filter->Log(level, "%s", o.str().c_str());    \
 323   }
 324
 325 #else // DEBUG_ENABLED
 326
 327 #define DALI_LOG_INFO(filter, level, format, args...)
 328 #define DALI_LOG_STREAM( filter, level, stream )
 329
 330 #endif // DEBUG_ENABLED
 331
 332
 333 /********************************************************************************
 334  *                                  Trace Macros                                *
 335  ********************************************************************************/
 336
 337 /*
 338  * These macros allow the instrumentation of methods. These translate into calls
 339  * to LogMessage(DebugInfo).
 340  */
 341
 342 #ifdef DEBUG_ENABLED
 343
 344 class DALI_CORE_API TraceObj
 345 {
 346 public:
 347   TraceObj(Filter* filter, const char* fmt, ...);
 348   ~TraceObj();
 349
 350 public:
 351   std::string mMessage;
 352   Filter* mFilter;
 353 };
 354
 355
 356 #define DALI_LOG_TRACE_METHOD_FMT(filter, format, args...)                 \
 357   Dali::Integration::Log::TraceObj debugTraceObj(filter, "%s: " format, __PRETTY_FUNCTION__, ## args)
 358
 359 #define DALI_LOG_TRACE_METHOD(filter)                                      \
 360   Dali::Integration::Log::TraceObj debugTraceObj(filter, __PRETTY_FUNCTION__)
 361
 362
 363 #else // DEBUG_ENABLED
 364
 365 #define DALI_LOG_TRACE_METHOD_FMT(filter, format, args...)
 366 #define DALI_LOG_TRACE_METHOD(filter)
 367
 368
 369 #endif
 370
 371 /********************************************************************************
 372  *                              Extra object debug                              *
 373  ********************************************************************************/
 374
 375 #ifdef DEBUG_ENABLED
 376
 377 /**
 378  * Warning, this macro changes the current scope, so should usually be put at the
 379  * end of the class definition.
 380  *
 381  * Suggest that the value is usually set to the object's name.
 382  * Warning - this will increase the size of the object for a debug build.
 383  */
 384 #define DALI_LOG_OBJECT_STRING_DECLARATION \
 385 public: \
 386   std::string mDebugString;
 387
 388 /**
 389  * Print all the actor tree names
 390  **/
 391 #define DALI_LOG_ACTOR_TREE( node ) { \
 392   std::stringstream branch; \
 393   Node* tempNode = node; \
 394   while( tempNode ) { \
 395     branch << "<" << tempNode->mDebugString << ">::"; \
 396     tempNode = tempNode->GetParent(); \
 397   } \
 398   DALI_LOG_ERROR_NOFN("Actor tree: %s\n", branch.str().c_str()); \
 399 }
 400
 401 /**
 402  * Allows one object to set another object's debug string
 403  */
 404 #define DALI_LOG_SET_OBJECT_STRING(object, string) (object->mDebugString = string)
 405
 406 /**
 407  * Allows one object to set another object's std::string easily
 408  */
 409 #define DALI_LOG_FMT_OBJECT_STRING(object, fmt, args...) (object->mDebugString = FormatToString(fmt, ## args))
 410
 411 /**
 412  * Allows one object to get another object's debug string
 413  */
 414 #define DALI_LOG_GET_OBJECT_STRING(object) (object->mDebugString)
 415
 416 /**
 417  * Get the C string (for use in formatted logging)
 418  */
 419 #define DALI_LOG_GET_OBJECT_C_STR(object) (object->mDebugString.c_str())
 420
 421 /**
 422  * Filtered logging of the object's debug string
 423  */
 424 #define DALI_LOG_OBJECT(filter, object)  DALI_LOG_INFO(filter, Debug::General, object->mDebugString)
 425
 426
 427 #else // DEBUG_ENABLED
 428
 429 #define DALI_LOG_OBJECT_STRING_DECLARATION
 430 #define DALI_LOG_ACTOR_TREE(node)
 431 #define DALI_LOG_SET_OBJECT_STRING(object, string)
 432 #define DALI_LOG_FMT_OBJECT_STRING(object, fmt, args...)
 433 #define DALI_LOG_GET_OBJECT_STRING(object)
 434 #define DALI_LOG_GET_OBJECT_C_STR(object) ""
 435 #define DALI_LOG_OBJECT(filter, object)
 436
 437 #endif
 438
 439 /********************************************************************************
 440  *                            Time instrumentation                              *
 441  ********************************************************************************/
 442
 443 #if defined(DEBUG_ENABLED)
 444
 445 void GetNanoseconds( uint64_t& timeInNanoseconds );
 446
 447 #define DALI_LOG_TIMER_START( timeVariable )      \
 448   uint64_t timeVariable##1; \
 449   Debug::GetNanoseconds( timeVariable##1 );
 450
 451 #define DALI_LOG_TIMER_END( timeVariable, filter, level, preString)  \
 452   uint64_t timeVariable##2; \
 453   Debug::GetNanoseconds( timeVariable##2 );                             \
 454   DALI_LOG_INFO( filter, level, preString " %ld uSec\n", ((timeVariable##2-timeVariable##1)/1000));
 455
 456 #else // DEBUG_ENABLED
 457
 458 #define DALI_LOG_TIMER_START( timeVariable )
 459 #define DALI_LOG_TIMER_END( timeVariable, filter, level, preString)
 460
 461 #endif
 462
 463 } // Debug
 464 } // Integration
 465 } // Dali
 466
 467
 468 #endif // __DALI_INTEGRATION_DEBUG_H__