log.h 11.4 KB
Newer Older
1 2 3
/*
 * copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at>
 *
4 5 6
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
7 8
 * modify it under the terms of the GNU Lesser General Public
 * 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 13 14 15 16
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * 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 19 20
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

21 22
#ifndef AVUTIL_LOG_H
#define AVUTIL_LOG_H
23 24

#include <stdarg.h>
25
#include "avutil.h"
26
#include "attributes.h"
27
#include "version.h"
28

29 30 31 32 33 34 35 36 37 38
typedef enum {
    AV_CLASS_CATEGORY_NA = 0,
    AV_CLASS_CATEGORY_INPUT,
    AV_CLASS_CATEGORY_OUTPUT,
    AV_CLASS_CATEGORY_MUXER,
    AV_CLASS_CATEGORY_DEMUXER,
    AV_CLASS_CATEGORY_ENCODER,
    AV_CLASS_CATEGORY_DECODER,
    AV_CLASS_CATEGORY_FILTER,
    AV_CLASS_CATEGORY_BITSTREAM_FILTER,
Paul B Mahol's avatar
Paul B Mahol committed
39 40
    AV_CLASS_CATEGORY_SWSCALER,
    AV_CLASS_CATEGORY_SWRESAMPLER,
41 42 43 44 45 46
    AV_CLASS_CATEGORY_DEVICE_VIDEO_OUTPUT = 40,
    AV_CLASS_CATEGORY_DEVICE_VIDEO_INPUT,
    AV_CLASS_CATEGORY_DEVICE_AUDIO_OUTPUT,
    AV_CLASS_CATEGORY_DEVICE_AUDIO_INPUT,
    AV_CLASS_CATEGORY_DEVICE_OUTPUT,
    AV_CLASS_CATEGORY_DEVICE_INPUT,
47
    AV_CLASS_CATEGORY_NB, ///< not part of ABI/API
48 49
}AVClassCategory;

50 51 52 53 54 55 56 57 58 59
#define AV_IS_INPUT_DEVICE(category) \
    (((category) == AV_CLASS_CATEGORY_DEVICE_VIDEO_INPUT) || \
     ((category) == AV_CLASS_CATEGORY_DEVICE_AUDIO_INPUT) || \
     ((category) == AV_CLASS_CATEGORY_DEVICE_INPUT))

#define AV_IS_OUTPUT_DEVICE(category) \
    (((category) == AV_CLASS_CATEGORY_DEVICE_VIDEO_OUTPUT) || \
     ((category) == AV_CLASS_CATEGORY_DEVICE_AUDIO_OUTPUT) || \
     ((category) == AV_CLASS_CATEGORY_DEVICE_OUTPUT))

60 61
struct AVOptionRanges;

62
/**
63
 * Describe the class of an AVClass context structure. That is an
64 65
 * arbitrary struct of which the first field is a pointer to an
 * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.).
66
 */
67
typedef struct AVClass {
68
    /**
Diego Biurrun's avatar
Diego Biurrun committed
69
     * The name of the class; usually it is the same name as the
Diego Biurrun's avatar
Diego Biurrun committed
70
     * context structure type to which the AVClass is associated.
71
     */
72
    const char* class_name;
73 74

    /**
75
     * A pointer to a function which returns the name of a context
76
     * instance ctx associated with the class.
77 78 79 80 81 82 83 84
     */
    const char* (*item_name)(void* ctx);

    /**
     * a pointer to the first option specified in the class if any or NULL
     *
     * @see av_set_default_options()
     */
85
    const struct AVOption *option;
86 87 88

    /**
     * LIBAVUTIL_VERSION with which this structure was created.
Jai Menon's avatar
Jai Menon committed
89
     * This is used to allow fields to be added without requiring major
90 91 92 93
     * version bumps everywhere.
     */

    int version;
94 95 96 97 98 99

    /**
     * Offset in the structure where log_level_offset is stored.
     * 0 means there is no such variable
     */
    int log_level_offset_offset;
100 101

    /**
102 103 104 105 106
     * Offset in the structure where a pointer to the parent context for
     * logging is stored. For example a decoder could pass its AVCodecContext
     * to eval as such a parent context, which an av_log() implementation
     * could then leverage to display the parent context.
     * The offset can be NULL.
107 108
     */
    int parent_log_context_offset;
109 110

    /**
111
     * Return next AVOptions-enabled child or NULL
112
     */
113 114 115
    void* (*child_next)(void *obj, void *prev);

    /**
116
     * Return an AVClass corresponding to the next potential
117 118 119 120 121 122 123
     * AVOptions-enabled child.
     *
     * The difference between child_next and this is that
     * child_next iterates over _already existing_ objects, while
     * child_class_next iterates over _all possible_ children.
     */
    const struct AVClass* (*child_class_next)(const struct AVClass *prev);
124 125 126

    /**
     * Category used for visualization (like color)
127
     * This is only set if the category is equal for all objects using this class.
128 129 130
     * available since version (51 << 16 | 56 << 8 | 100)
     */
    AVClassCategory category;
131 132 133 134 135 136

    /**
     * Callback to return the category.
     * available since version (51 << 16 | 59 << 8 | 100)
     */
    AVClassCategory (*get_category)(void* ctx);
137 138 139 140 141 142

    /**
     * Callback to return the supported/allowed ranges.
     * available since version (52.12)
     */
    int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags);
143
} AVClass;
144

Luca Barbato's avatar
Luca Barbato committed
145 146 147 148 149 150 151 152 153
/**
 * @addtogroup lavu_log
 *
 * @{
 *
 * @defgroup lavu_log_constants Logging Constants
 *
 * @{
 */
154

Luca Barbato's avatar
Luca Barbato committed
155 156 157
/**
 * Print no output.
 */
158 159 160
#define AV_LOG_QUIET    -8

/**
161
 * Something went really wrong and we will crash now.
162 163 164 165
 */
#define AV_LOG_PANIC     0

/**
166 167 168
 * Something went wrong and recovery is not possible.
 * For example, no header was found for a format which depends
 * on headers or an illegal combination of parameters is used.
169 170 171 172
 */
#define AV_LOG_FATAL     8

/**
173 174
 * Something went wrong and cannot losslessly be recovered.
 * However, not all future data is affected.
175 176 177 178
 */
#define AV_LOG_ERROR    16

/**
179 180
 * Something somehow does not look correct. This may or may not
 * lead to problems. An example would be the use of '-vstrict -2'.
181 182 183
 */
#define AV_LOG_WARNING  24

Luca Barbato's avatar
Luca Barbato committed
184 185 186
/**
 * Standard information.
 */
187
#define AV_LOG_INFO     32
Luca Barbato's avatar
Luca Barbato committed
188 189 190 191

/**
 * Detailed information.
 */
192 193 194
#define AV_LOG_VERBOSE  40

/**
195
 * Stuff which is only useful for libav* developers.
196 197
 */
#define AV_LOG_DEBUG    48
198

199 200 201 202 203
/**
 * Extremely verbose debugging, useful for libav* development.
 */
#define AV_LOG_TRACE    56

204 205
#define AV_LOG_MAX_OFFSET (AV_LOG_TRACE - AV_LOG_QUIET)

206
/**
207
 * @}
208 209
 */

Luca Barbato's avatar
Luca Barbato committed
210
/**
211 212 213 214 215 216
 * Sets additional colors for extended debugging sessions.
 * @code
   av_log(ctx, AV_LOG_DEBUG|AV_LOG_C(134), "Message in purple\n");
   @endcode
 * Requires 256color terminal support. Uses outside debugging is not
 * recommended.
Luca Barbato's avatar
Luca Barbato committed
217
 */
218
#define AV_LOG_C(x) ((x) << 8)
Luca Barbato's avatar
Luca Barbato committed
219

220
/**
221
 * Send the specified message to the log if the level is less than or equal
222
 * to the current av_log_level. By default, all logging messages are sent to
Luca Barbato's avatar
Luca Barbato committed
223
 * stderr. This behavior can be altered by setting a different logging callback
224
 * function.
Luca Barbato's avatar
Luca Barbato committed
225
 * @see av_log_set_callback
226 227
 *
 * @param avcl A pointer to an arbitrary struct of which the first field is a
228
 *        pointer to an AVClass struct or NULL if general log.
Luca Barbato's avatar
Luca Barbato committed
229 230
 * @param level The importance level of the message expressed using a @ref
 *        lavu_log_constants "Logging Constant".
231
 * @param fmt The format string (printf-compatible) that specifies how
Luca Barbato's avatar
Luca Barbato committed
232
 *        subsequent arguments are converted to output.
233
 */
234
void av_log(void *avcl, int level, const char *fmt, ...) av_printf_format(3, 4);
235

Luca Barbato's avatar
Luca Barbato committed
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260

/**
 * Send the specified message to the log if the level is less than or equal
 * to the current av_log_level. By default, all logging messages are sent to
 * stderr. This behavior can be altered by setting a different logging callback
 * function.
 * @see av_log_set_callback
 *
 * @param avcl A pointer to an arbitrary struct of which the first field is a
 *        pointer to an AVClass struct.
 * @param level The importance level of the message expressed using a @ref
 *        lavu_log_constants "Logging Constant".
 * @param fmt The format string (printf-compatible) that specifies how
 *        subsequent arguments are converted to output.
 * @param vl The arguments referenced by the format string.
 */
void av_vlog(void *avcl, int level, const char *fmt, va_list vl);

/**
 * Get the current log level
 *
 * @see lavu_log_constants
 *
 * @return Current log level
 */
261
int av_log_get_level(void);
Luca Barbato's avatar
Luca Barbato committed
262 263 264 265 266 267 268 269 270 271 272 273 274

/**
 * Set the log level
 *
 * @see lavu_log_constants
 *
 * @param level Logging level
 */
void av_log_set_level(int level);

/**
 * Set the logging callback
 *
275 276 277
 * @note The callback must be thread safe, even if the application does not use
 *       threads itself as some codecs are multithreaded.
 *
Luca Barbato's avatar
Luca Barbato committed
278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294
 * @see av_log_default_callback
 *
 * @param callback A logging function with a compatible signature.
 */
void av_log_set_callback(void (*callback)(void*, int, const char*, va_list));

/**
 * Default logging callback
 *
 * It prints the message to stderr, optionally colorizing it.
 *
 * @param avcl A pointer to an arbitrary struct of which the first field is a
 *        pointer to an AVClass struct.
 * @param level The importance level of the message expressed using a @ref
 *        lavu_log_constants "Logging Constant".
 * @param fmt The format string (printf-compatible) that specifies how
 *        subsequent arguments are converted to output.
295
 * @param vl The arguments referenced by the format string.
Luca Barbato's avatar
Luca Barbato committed
296
 */
297 298
void av_log_default_callback(void *avcl, int level, const char *fmt,
                             va_list vl);
Luca Barbato's avatar
Luca Barbato committed
299 300 301 302 303 304 305 306

/**
 * Return the context name
 *
 * @param  ctx The AVClass context
 *
 * @return The AVClass class_name
 */
307
const char* av_default_item_name(void* ctx);
308
AVClassCategory av_default_get_category(void *ptr);
309

310 311
/**
 * Format a line of log the same way as the default callback.
312
 * @param line          buffer to receive the formatted line
313 314 315 316 317 318 319
 * @param line_size     size of the buffer
 * @param print_prefix  used to store whether the prefix must be printed;
 *                      must point to a persistent integer initially set to 1
 */
void av_log_format_line(void *ptr, int level, const char *fmt, va_list vl,
                        char *line, int line_size, int *print_prefix);

320 321 322 323 324 325 326 327
/**
 * Format a line of log the same way as the default callback.
 * @param line          buffer to receive the formatted line;
 *                      may be NULL if line_size is 0
 * @param line_size     size of the buffer; at most line_size-1 characters will
 *                      be written to the buffer, plus one null terminator
 * @param print_prefix  used to store whether the prefix must be printed;
 *                      must point to a persistent integer initially set to 1
328
 * @return Returns a negative value if an error occurred, otherwise returns
329 330 331 332 333 334 335 336
 *         the number of characters that would have been written for a
 *         sufficiently large buffer, not including the terminating null
 *         character. If the return value is not less than line_size, it means
 *         that the log message was truncated to fit the buffer.
 */
int av_log_format_line2(void *ptr, int level, const char *fmt, va_list vl,
                        char *line, int line_size, int *print_prefix);

337
#if FF_API_DLOG
338 339
/**
 * av_dlog macros
340
 * @deprecated unused
341 342 343 344 345 346
 * Useful to print debug messages that shouldn't get compiled in normally.
 */

#ifdef DEBUG
#    define av_dlog(pctx, ...) av_log(pctx, AV_LOG_DEBUG, __VA_ARGS__)
#else
347
#    define av_dlog(pctx, ...) do { if (0) av_log(pctx, AV_LOG_DEBUG, __VA_ARGS__); } while (0)
348
#endif
349
#endif /* FF_API_DLOG */
350

351 352 353 354 355 356
/**
 * Skip repeated messages, this requires the user app to use av_log() instead of
 * (f)printf as the 2 would otherwise interfere and lead to
 * "Last message repeated x times" messages below (f)printf messages with some
 * bad luck.
 * Also to receive the last, "last repeated" line if any, the user app must
357
 * call av_log(NULL, AV_LOG_QUIET, "%s", ""); at the end
358 359
 */
#define AV_LOG_SKIP_REPEATED 1
360 361 362 363 364 365 366 367 368

/**
 * Include the log severity in messages originating from codecs.
 *
 * Results in messages such as:
 * [rawvideo @ 0xDEADBEEF] [error] encode did not produce valid pts
 */
#define AV_LOG_PRINT_LEVEL 2

369
void av_log_set_flags(int arg);
370
int av_log_get_flags(void);
371

Luca Barbato's avatar
Luca Barbato committed
372 373 374 375
/**
 * @}
 */

376
#endif /* AVUTIL_LOG_H */