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
146