openscenegraph
Notify
Go to the documentation of this file.
1/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2006 Robert Osfield
2 *
3 * This library is open source and may be redistributed and/or modified under
4 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or
5 * (at your option) any later version. The full license is in LICENSE file
6 * included with this distribution, and on the openscenegraph.org website.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * OpenSceneGraph Public License for more details.
12*/
13
14#ifndef OSG_NOTIFY_H
15#define OSG_NOTIFY_H 1
16
17#include <osg/Export>
18#include <osg/Referenced> // for NotifyHandler
19
20#include <ostream>
21
22namespace osg {
23
24/** Range of notify levels from DEBUG_FP through to FATAL, ALWAYS
25 * is reserved for forcing the absorption of all messages. The
26 * keywords are also used verbatim when specified by the environmental
27 * variable OSGNOTIFYLEVEL or OSG_NOTIFY_LEVEL.
28 * See documentation on osg::notify() for further details.
29 */
30enum NotifySeverity {
31 ALWAYS=0,
32 FATAL=1,
33 WARN=2,
34 NOTICE=3,
35 INFO=4,
36 DEBUG_INFO=5,
37 DEBUG_FP=6
38};
39
40/** set the notify level, overriding the default or the value set by
41 * the environmental variable OSGNOTIFYLEVEL or OSG_NOTIFY_LEVEL.
42 */
43extern OSG_EXPORT void setNotifyLevel(NotifySeverity severity);
44
45/** get the notify level. */
46extern OSG_EXPORT NotifySeverity getNotifyLevel();
47
48/** initialize notify level. */
49extern OSG_EXPORT bool initNotifyLevel();
50
51#ifdef OSG_NOTIFY_DISABLED
52 inline bool isNotifyEnabled(NotifySeverity) { return false; }
53#else
54 /** is notification enabled, given the current setNotifyLevel() setting? */
55 extern OSG_EXPORT bool isNotifyEnabled(NotifySeverity severity);
56#endif
57
58/** notify messaging function for providing fatal through to verbose
59 * debugging messages. Level of messages sent to the console can
60 * be controlled by setting the NotifyLevel either within your
61 * application or via the an environmental variable i.e.
62 * - setenv OSGNOTIFYLEVEL DEBUG (for tsh)
63 * - export OSGNOTIFYLEVEL=DEBUG (for bourne shell)
64 * - set OSGNOTIFYLEVEL=DEBUG (for Windows)
65 *
66 * All tell the osg to redirect all debugging and more important messages
67 * to the notification stream (useful for debugging) setting ALWAYS will force
68 * all messages to be absorbed, which might be appropriate for final
69 * applications. Default NotifyLevel is NOTICE. Check the enum
70 * #NotifySeverity for full range of possibilities. To use the notify
71 * with your code simply use the notify function as a normal file
72 * stream (like std::cout) i.e
73 * @code
74 * osg::notify(osg::DEBUG) << "Hello Bugs!" << std::endl;
75 * @endcode
76 * @see setNotifyLevel, setNotifyHandler
77 */
78extern OSG_EXPORT std::ostream& notify(const NotifySeverity severity);
79
80inline std::ostream& notify(void) { return notify(osg::INFO); }
81
82#define OSG_NOTIFY(level) if (osg::isNotifyEnabled(level)) osg::notify(level)
83#define OSG_ALWAYS OSG_NOTIFY(osg::ALWAYS)
84#define OSG_FATAL OSG_NOTIFY(osg::FATAL)
85#define OSG_WARN OSG_NOTIFY(osg::WARN)
86#define OSG_NOTICE OSG_NOTIFY(osg::NOTICE)
87#define OSG_INFO OSG_NOTIFY(osg::INFO)
88#define OSG_DEBUG OSG_NOTIFY(osg::DEBUG_INFO)
89#define OSG_DEBUG_FP OSG_NOTIFY(osg::DEBUG_FP)
90
91/** Handler processing output of notification stream. It acts as a sink to
92 * notification messages. It is called when notification stream needs to be
93 * synchronized (i.e. after osg::notify() << std::endl).
94 * StandardNotifyHandler is used by default, it writes notifications to stderr
95 * (severity <= WARN) or stdout (severity > WARN).
96 * Notifications can be redirected to other sinks such as GUI widgets or
97 * windows debugger (WinDebugNotifyHandler) with custom handlers.
98 * Use setNotifyHandler to set custom handler.
99 * Note that osg notification API is not thread safe although notification
100 * handler is called from many threads. When incorporating handlers into GUI
101 * widgets you must take care of thread safety on your own.
102 * @see setNotifyHandler
103 */
104class OSG_EXPORT NotifyHandler : public osg::Referenced
105{
106public:
107 virtual void notify(osg::NotifySeverity severity, const char *message) = 0;
108};
109
110/** Set notification handler, by default StandardNotifyHandler is used.
111 * @see NotifyHandler
112 */
113extern OSG_EXPORT void setNotifyHandler(NotifyHandler *handler);
114
115/** Get currrent notification handler. */
116extern OSG_EXPORT NotifyHandler *getNotifyHandler();
117
118/** Redirects notification stream to stderr (severity <= WARN) or stdout (severity > WARN).
119 * The fputs() function is used to write messages to standard files. Note that
120 * std::out and std::cerr streams are not used.
121 * @see setNotifyHandler
122 */
123class OSG_EXPORT StandardNotifyHandler : public NotifyHandler
124{
125public:
126 void notify(osg::NotifySeverity severity, const char *message);
127};
128
129#if defined(WIN32) && !defined(__CYGWIN__)
130
131/** Redirects notification stream to windows debugger with use of
132 * OuputDebugString functions.
133 * @see setNotifyHandler
134 */
135class OSG_EXPORT WinDebugNotifyHandler : public NotifyHandler
136{
137public:
138 void notify(osg::NotifySeverity severity, const char *message);
139};
140
141#endif
142
143}
144
145#endif