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