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