1 /*
2 * This file is part of libplacebo.
3 *
4 * libplacebo is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * libplacebo is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with libplacebo. If not, see <http://www.gnu.org/licenses/>.
16 */
17
18 #ifndef LIBPLACEBO_LOG_H_
19 #define LIBPLACEBO_LOG_H_
20
21 #include <libplacebo/config.h>
22 #include <libplacebo/common.h>
23
24 PL_API_BEGIN
25
26 // The log level associated with a given log message.
27 enum pl_log_level {
28 PL_LOG_NONE = 0,
29 PL_LOG_FATAL, // results in total loss of function of a major component
30 PL_LOG_ERR, // serious error; may result in degraded function
31 PL_LOG_WARN, // warning; potentially bad, probably user-relevant
32 PL_LOG_INFO, // informational message, also potentially harmless errors
33 PL_LOG_DEBUG, // verbose debug message, informational
34 PL_LOG_TRACE, // very noisy trace of activity,, usually benign
35 PL_LOG_ALL = PL_LOG_TRACE,
36 };
37
38 struct pl_log_params {
39 // Logging callback. All messages, informational or otherwise, will get
40 // redirected to this callback. The logged messages do not include trailing
41 // newlines. Optional.
42 void (*log_cb)(void *log_priv, enum pl_log_level level, const char *msg);
43 void *log_priv;
44
45 // The current log level. Controls the level of message that will be
46 // redirected to the log callback. Setting this to PL_LOG_ALL means all
47 // messages will be forwarded, but doing so indiscriminately can result
48 // in increased CPU usage as it may enable extra debug paths based on the
49 // configured log level.
50 enum pl_log_level log_level;
51 };
52
53 // Thread-safety: Safe
54 //
55 // Note: In any context in which `pl_log` is used, users may also pass NULL
56 // to disable logging. In other words, NULL is a valid `pl_log`.
57 typedef const PL_STRUCT(pl_log) {
58 struct pl_log_params params;
59 } *pl_log;
60
61 // Creates a pl_log. For historical reasons, the argument `api_ver` must be
62 // given as PL_API_VER. `params` defaults to `&pl_log_default_params` if left
63 // as NULL.
64 //
65 // Note: As a general rule, any `params` struct used as an argument to a
66 // function need only live until the corresponding function returns.
67 pl_log pl_log_create(int api_ver, const struct pl_log_params *params);
68
69 // Equal to (struct pl_log_params) {0}
70 extern const struct pl_log_params pl_log_default_params;
71
72 // Destroy a `pl_log` object.
73 //
74 // Note: As a general rule, all `_destroy` functions take the pointer to the
75 // object to free as their parameter. This pointer is overwritten by NULL
76 // afterwards. Calling a _destroy function on &{NULL} is valid, but calling it
77 // on NULL itself is invalid.
78 void pl_log_destroy(pl_log *log);
79
80 // Update the parameters of a `pl_log` without destroying it. This can be
81 // used to change the log function, log context or log level retroactively.
82 // `params` defaults to `&pl_log_default_params` if left as NULL.
83 //
84 // Returns the previous params, atomically.
85 struct pl_log_params pl_log_update(pl_log log, const struct pl_log_params *params);
86
87 // Like `pl_log_update` but only updates the log level, leaving the log
88 // callback intact.
89 //
90 // Returns the previous log level, atomically.
91 enum pl_log_level pl_log_level_update(pl_log log, enum pl_log_level level);
92
93 // Two simple, stream-based loggers. You can use these as the log_cb. If you
94 // also set log_priv to a FILE* (e.g. stdout or stderr) it will be printed
95 // there; otherwise, it will be printed to stdout or stderr depending on the
96 // log level.
97 //
98 // The version with colors will use ANSI escape sequences to indicate the log
99 // level. The version without will use explicit prefixes.
100 void pl_log_simple(void *stream, enum pl_log_level level, const char *msg);
101 void pl_log_color(void *stream, enum pl_log_level level, const char *msg);
102
103 // Backwards compatibility with older versions of libplacebo
104
105 #define pl_context pl_log
106 #define pl_context_params pl_log_params
107
PL_STRUCT(pl_context)108 static inline PL_DEPRECATED PL_STRUCT(pl_context) *
109 pl_context_create(int api_ver, const struct pl_context_params *params)
110 {
111 return (PL_STRUCT(pl_context) *) pl_log_create(api_ver, params);
112 }
113
pl_context_destroy(PL_STRUCT (pl_context)** pctx)114 static inline PL_DEPRECATED void pl_context_destroy(PL_STRUCT(pl_context) **pctx)
115 {
116 pl_log_destroy((pl_log *) pctx);
117 }
118
119 static inline PL_DEPRECATED void
pl_context_update(PL_STRUCT (pl_context)* ctx,const struct pl_context_params * params)120 pl_context_update(PL_STRUCT(pl_context) *ctx, const struct pl_context_params *params)
121 {
122 pl_log_update((pl_log) ctx, params);
123 }
124
125 PL_API_END
126
127 #endif // LIBPLACEBO_LOG_H_
128