log.h (12766B)
1 /* 2 * copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at> 3 * 4 * This file is part of FFmpeg. 5 * 6 * FFmpeg is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * FFmpeg is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with FFmpeg; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 #ifndef AVUTIL_LOG_H 22 #define AVUTIL_LOG_H 23 24 #include <stdarg.h> 25 #include "attributes.h" 26 #include "version.h" 27 28 typedef enum { 29 AV_CLASS_CATEGORY_NA = 0, 30 AV_CLASS_CATEGORY_INPUT, 31 AV_CLASS_CATEGORY_OUTPUT, 32 AV_CLASS_CATEGORY_MUXER, 33 AV_CLASS_CATEGORY_DEMUXER, 34 AV_CLASS_CATEGORY_ENCODER, 35 AV_CLASS_CATEGORY_DECODER, 36 AV_CLASS_CATEGORY_FILTER, 37 AV_CLASS_CATEGORY_BITSTREAM_FILTER, 38 AV_CLASS_CATEGORY_SWSCALER, 39 AV_CLASS_CATEGORY_SWRESAMPLER, 40 AV_CLASS_CATEGORY_DEVICE_VIDEO_OUTPUT = 40, 41 AV_CLASS_CATEGORY_DEVICE_VIDEO_INPUT, 42 AV_CLASS_CATEGORY_DEVICE_AUDIO_OUTPUT, 43 AV_CLASS_CATEGORY_DEVICE_AUDIO_INPUT, 44 AV_CLASS_CATEGORY_DEVICE_OUTPUT, 45 AV_CLASS_CATEGORY_DEVICE_INPUT, 46 AV_CLASS_CATEGORY_NB ///< not part of ABI/API 47 }AVClassCategory; 48 49 #define AV_IS_INPUT_DEVICE(category) \ 50 (((category) == AV_CLASS_CATEGORY_DEVICE_VIDEO_INPUT) || \ 51 ((category) == AV_CLASS_CATEGORY_DEVICE_AUDIO_INPUT) || \ 52 ((category) == AV_CLASS_CATEGORY_DEVICE_INPUT)) 53 54 #define AV_IS_OUTPUT_DEVICE(category) \ 55 (((category) == AV_CLASS_CATEGORY_DEVICE_VIDEO_OUTPUT) || \ 56 ((category) == AV_CLASS_CATEGORY_DEVICE_AUDIO_OUTPUT) || \ 57 ((category) == AV_CLASS_CATEGORY_DEVICE_OUTPUT)) 58 59 struct AVOptionRanges; 60 61 /** 62 * Describe the class of an AVClass context structure. That is an 63 * arbitrary struct of which the first field is a pointer to an 64 * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.). 65 */ 66 typedef struct AVClass { 67 /** 68 * The name of the class; usually it is the same name as the 69 * context structure type to which the AVClass is associated. 70 */ 71 const char* class_name; 72 73 /** 74 * A pointer to a function which returns the name of a context 75 * instance ctx associated with the class. 76 */ 77 const char* (*item_name)(void* ctx); 78 79 /** 80 * a pointer to the first option specified in the class if any or NULL 81 * 82 * @see av_set_default_options() 83 */ 84 const struct AVOption *option; 85 86 /** 87 * LIBAVUTIL_VERSION with which this structure was created. 88 * This is used to allow fields to be added without requiring major 89 * version bumps everywhere. 90 */ 91 92 int version; 93 94 /** 95 * Offset in the structure where log_level_offset is stored. 96 * 0 means there is no such variable 97 */ 98 int log_level_offset_offset; 99 100 /** 101 * Offset in the structure where a pointer to the parent context for 102 * logging is stored. For example a decoder could pass its AVCodecContext 103 * to eval as such a parent context, which an av_log() implementation 104 * could then leverage to display the parent context. 105 * The offset can be NULL. 106 */ 107 int parent_log_context_offset; 108 109 /** 110 * Category used for visualization (like color) 111 * This is only set if the category is equal for all objects using this class. 112 * available since version (51 << 16 | 56 << 8 | 100) 113 */ 114 AVClassCategory category; 115 116 /** 117 * Callback to return the category. 118 * available since version (51 << 16 | 59 << 8 | 100) 119 */ 120 AVClassCategory (*get_category)(void* ctx); 121 122 /** 123 * Callback to return the supported/allowed ranges. 124 * available since version (52.12) 125 */ 126 int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags); 127 128 /** 129 * Return next AVOptions-enabled child or NULL 130 */ 131 void* (*child_next)(void *obj, void *prev); 132 133 /** 134 * Iterate over the AVClasses corresponding to potential AVOptions-enabled 135 * children. 136 * 137 * @param iter pointer to opaque iteration state. The caller must initialize 138 * *iter to NULL before the first call. 139 * @return AVClass for the next AVOptions-enabled child or NULL if there are 140 * no more such children. 141 * 142 * @note The difference between child_next and this is that child_next 143 * iterates over _already existing_ objects, while child_class_iterate 144 * iterates over _all possible_ children. 145 */ 146 const struct AVClass* (*child_class_iterate)(void **iter); 147 } AVClass; 148 149 /** 150 * @addtogroup lavu_log 151 * 152 * @{ 153 * 154 * @defgroup lavu_log_constants Logging Constants 155 * 156 * @{ 157 */ 158 159 /** 160 * Print no output. 161 */ 162 #define AV_LOG_QUIET -8 163 164 /** 165 * Something went really wrong and we will crash now. 166 */ 167 #define AV_LOG_PANIC 0 168 169 /** 170 * Something went wrong and recovery is not possible. 171 * For example, no header was found for a format which depends 172 * on headers or an illegal combination of parameters is used. 173 */ 174 #define AV_LOG_FATAL 8 175 176 /** 177 * Something went wrong and cannot losslessly be recovered. 178 * However, not all future data is affected. 179 */ 180 #define AV_LOG_ERROR 16 181 182 /** 183 * Something somehow does not look correct. This may or may not 184 * lead to problems. An example would be the use of '-vstrict -2'. 185 */ 186 #define AV_LOG_WARNING 24 187 188 /** 189 * Standard information. 190 */ 191 #define AV_LOG_INFO 32 192 193 /** 194 * Detailed information. 195 */ 196 #define AV_LOG_VERBOSE 40 197 198 /** 199 * Stuff which is only useful for libav* developers. 200 */ 201 #define AV_LOG_DEBUG 48 202 203 /** 204 * Extremely verbose debugging, useful for libav* development. 205 */ 206 #define AV_LOG_TRACE 56 207 208 #define AV_LOG_MAX_OFFSET (AV_LOG_TRACE - AV_LOG_QUIET) 209 210 /** 211 * @} 212 */ 213 214 /** 215 * Sets additional colors for extended debugging sessions. 216 * @code 217 av_log(ctx, AV_LOG_DEBUG|AV_LOG_C(134), "Message in purple\n"); 218 @endcode 219 * Requires 256color terminal support. Uses outside debugging is not 220 * recommended. 221 */ 222 #define AV_LOG_C(x) ((x) << 8) 223 224 /** 225 * Send the specified message to the log if the level is less than or equal 226 * to the current av_log_level. By default, all logging messages are sent to 227 * stderr. This behavior can be altered by setting a different logging callback 228 * function. 229 * @see av_log_set_callback 230 * 231 * @param avcl A pointer to an arbitrary struct of which the first field is a 232 * pointer to an AVClass struct or NULL if general log. 233 * @param level The importance level of the message expressed using a @ref 234 * lavu_log_constants "Logging Constant". 235 * @param fmt The format string (printf-compatible) that specifies how 236 * subsequent arguments are converted to output. 237 */ 238 void av_log(void *avcl, int level, const char *fmt, ...) av_printf_format(3, 4); 239 240 /** 241 * Send the specified message to the log once with the initial_level and then with 242 * the subsequent_level. By default, all logging messages are sent to 243 * stderr. This behavior can be altered by setting a different logging callback 244 * function. 245 * @see av_log 246 * 247 * @param avcl A pointer to an arbitrary struct of which the first field is a 248 * pointer to an AVClass struct or NULL if general log. 249 * @param initial_level importance level of the message expressed using a @ref 250 * lavu_log_constants "Logging Constant" for the first occurance. 251 * @param subsequent_level importance level of the message expressed using a @ref 252 * lavu_log_constants "Logging Constant" after the first occurance. 253 * @param fmt The format string (printf-compatible) that specifies how 254 * subsequent arguments are converted to output. 255 * @param state a variable to keep trak of if a message has already been printed 256 * this must be initialized to 0 before the first use. The same state 257 * must not be accessed by 2 Threads simultaneously. 258 */ 259 void av_log_once(void* avcl, int initial_level, int subsequent_level, int *state, const char *fmt, ...) av_printf_format(5, 6); 260 261 262 /** 263 * Send the specified message to the log if the level is less than or equal 264 * to the current av_log_level. By default, all logging messages are sent to 265 * stderr. This behavior can be altered by setting a different logging callback 266 * function. 267 * @see av_log_set_callback 268 * 269 * @param avcl A pointer to an arbitrary struct of which the first field is a 270 * pointer to an AVClass struct. 271 * @param level The importance level of the message expressed using a @ref 272 * lavu_log_constants "Logging Constant". 273 * @param fmt The format string (printf-compatible) that specifies how 274 * subsequent arguments are converted to output. 275 * @param vl The arguments referenced by the format string. 276 */ 277 void av_vlog(void *avcl, int level, const char *fmt, va_list vl); 278 279 /** 280 * Get the current log level 281 * 282 * @see lavu_log_constants 283 * 284 * @return Current log level 285 */ 286 int av_log_get_level(void); 287 288 /** 289 * Set the log level 290 * 291 * @see lavu_log_constants 292 * 293 * @param level Logging level 294 */ 295 void av_log_set_level(int level); 296 297 /** 298 * Set the logging callback 299 * 300 * @note The callback must be thread safe, even if the application does not use 301 * threads itself as some codecs are multithreaded. 302 * 303 * @see av_log_default_callback 304 * 305 * @param callback A logging function with a compatible signature. 306 */ 307 void av_log_set_callback(void (*callback)(void*, int, const char*, va_list)); 308 309 /** 310 * Default logging callback 311 * 312 * It prints the message to stderr, optionally colorizing it. 313 * 314 * @param avcl A pointer to an arbitrary struct of which the first field is a 315 * pointer to an AVClass struct. 316 * @param level The importance level of the message expressed using a @ref 317 * lavu_log_constants "Logging Constant". 318 * @param fmt The format string (printf-compatible) that specifies how 319 * subsequent arguments are converted to output. 320 * @param vl The arguments referenced by the format string. 321 */ 322 void av_log_default_callback(void *avcl, int level, const char *fmt, 323 va_list vl); 324 325 /** 326 * Return the context name 327 * 328 * @param ctx The AVClass context 329 * 330 * @return The AVClass class_name 331 */ 332 const char* av_default_item_name(void* ctx); 333 AVClassCategory av_default_get_category(void *ptr); 334 335 /** 336 * Format a line of log the same way as the default callback. 337 * @param line buffer to receive the formatted line 338 * @param line_size size of the buffer 339 * @param print_prefix used to store whether the prefix must be printed; 340 * must point to a persistent integer initially set to 1 341 */ 342 void av_log_format_line(void *ptr, int level, const char *fmt, va_list vl, 343 char *line, int line_size, int *print_prefix); 344 345 /** 346 * Format a line of log the same way as the default callback. 347 * @param line buffer to receive the formatted line; 348 * may be NULL if line_size is 0 349 * @param line_size size of the buffer; at most line_size-1 characters will 350 * be written to the buffer, plus one null terminator 351 * @param print_prefix used to store whether the prefix must be printed; 352 * must point to a persistent integer initially set to 1 353 * @return Returns a negative value if an error occurred, otherwise returns 354 * the number of characters that would have been written for a 355 * sufficiently large buffer, not including the terminating null 356 * character. If the return value is not less than line_size, it means 357 * that the log message was truncated to fit the buffer. 358 */ 359 int av_log_format_line2(void *ptr, int level, const char *fmt, va_list vl, 360 char *line, int line_size, int *print_prefix); 361 362 /** 363 * Skip repeated messages, this requires the user app to use av_log() instead of 364 * (f)printf as the 2 would otherwise interfere and lead to 365 * "Last message repeated x times" messages below (f)printf messages with some 366 * bad luck. 367 * Also to receive the last, "last repeated" line if any, the user app must 368 * call av_log(NULL, AV_LOG_QUIET, "%s", ""); at the end 369 */ 370 #define AV_LOG_SKIP_REPEATED 1 371 372 /** 373 * Include the log severity in messages originating from codecs. 374 * 375 * Results in messages such as: 376 * [rawvideo @ 0xDEADBEEF] [error] encode did not produce valid pts 377 */ 378 #define AV_LOG_PRINT_LEVEL 2 379 380 void av_log_set_flags(int arg); 381 int av_log_get_flags(void); 382 383 /** 384 * @} 385 */ 386 387 #endif /* AVUTIL_LOG_H */