GstInfo Debugging and logging This file describes the debugging subsystem. The debugging subsystem works only after GStreamer was initilized - for example by calling #gst_init. The debugging subsystem is used to send informational strings to the debugging developer. Each messages has some properties attached to it. These properties are the debugging category, the severity (called "level" here) and an obtional #GObject it belongs to. Each of these messages is sent to all registered debugging handlers, which then handle the messages. GStreamer attaches a default handler on startup, which outputs requested messages to stderr. Messages are output by using shortcut macros like #GST_DEBUG, #GST_CAT_ERROR_OBJECT or similar. These all expand to calling #gst_debug_log with the right parameters. The only thing a developer will probably want to do is define his own categories. This is easily done with 3 lines. At the top of your code, declare the variables and set the default category. GST_DEBUG_CATEGORY (my_category); /* define category */ &hash;define GST_CAT_DEFAULT my_category /* set as default */ After that you only need to initialize the category. GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own"); Initialization must be done before the category is used first. Plugins do this in their plugin_init function, libraries and applications should do that during their initialization. The whole debugging subsystem can be disabled at build time with passing the --disable-gst-debug switch to configure. If this is done, every function, macro and even structs described in this file evaluate to default values or nothing at all. So don't take addresses of these functions or use other tricks. If you must do that for some reason, there is still an option. If the debugging subsystem was compiled out, #GST_DISABLE_GST_DEBUG is defined in <gst/gst.h>, so you can check that before doing your trick. Disabling the debugging subsystem will give you a slight (read: unnoticable) speed increase and will reduce the size of your compiled code. The GStreamer library itself becomes around 10% smaller. Please note that there are naming conventions for the names of debugging categories. These are explained at GST_DEBUG_CATEGORY_INIT(). configuration, initialization for command line parameters and environment variables that affect the debugging output. The level defines the importance of a debugging message. The more important a message is, the greater the probability that the debugging system outputs it. @GST_LEVEL_NONE: No debugging level specified or desired. Used to deactivate debugging output. @GST_LEVEL_ERROR: Error messages are to be used only when an error occured that stops the application from keeping working correctly. An examples is gst_element_error, which outputs a message with this priority. It does not mean that the application is terminating as with g_errror. @GST_LEVEL_WARNING: Warning messages are to inform about abnormal behaviour that could lead to problems or weird behaviour later on. An example of this would be clocking issues ("your computer is pretty slow") or broken input data ("Can't synchronize to stream.") @GST_LEVEL_INFO: Informational messages should be used to keep the developer updated about what is happening. Examples where this should be used are when a typefind function has successfully determined the type of the stream or when an mp3 plugin detects the format to be used. ("This file has mono sound.") @GST_LEVEL_DEBUG: Debugging messages should be used when something common happens that is not the expected default behavior. An example would be notifications about state changes or receiving/sending of events. @GST_LEVEL_LOG: Log messages are messages that are very common but might be useful to know. As a rule of thumb a pipeline that is iterating as expected should never output anzthing else but LOG messages. Examples for this are referencing/dereferencing of objects or cothread switches. @GST_LEVEL_COUNT: The number of defined debugging levels. Defines the default debugging level to be used with GStreamer. It is normally set to #GST_LEVEL_ERROR so only errors are printed. Developer builds may chose to override that though. You can use this as an argument to gst_debug_set_default_threshold() to reset the debugging output to default behaviour. These are some terminal-oriented flags you can use when creating your debugging categories to make them stand out in debugging output. @GST_DEBUG_FG_BLACK: Use black as foreground color. @GST_DEBUG_FG_RED: Use red as foreground color. @GST_DEBUG_FG_GREEN: Use green as foreground color. @GST_DEBUG_FG_YELLOW: Use yellow as foreground color. @GST_DEBUG_FG_BLUE: Use blue as foreground color. @GST_DEBUG_FG_MAGENTA: Use magenta as foreground color. @GST_DEBUG_FG_CYAN: Use cyan as foreground color. @GST_DEBUG_FG_WHITE: Use white as foreground color. @GST_DEBUG_BG_BLACK: Use black as background color. @GST_DEBUG_BG_RED: Use red as background color. @GST_DEBUG_BG_GREEN: Use green as background color. @GST_DEBUG_BG_YELLOW: Use yellow as background color. @GST_DEBUG_BG_BLUE: Use blue as background color. @GST_DEBUG_BG_MAGENTA: Use magenta as background color. @GST_DEBUG_BG_CYAN: Use cyan as background color. @GST_DEBUG_BG_WHITE: Use white as background color. @GST_DEBUG_BOLD: Make the output bold. @GST_DEBUG_UNDERLINE: Underline the output. This is the struct that describes the categories. Once initialized with #GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore. Macro to use when a string must not be NULL, but may be NULL. If the string is NULL, "(NULL)" is printed instead. In GStreamer printf string arguments may not be NULL, because on some platforms (ie Solaris) the libc crashes in that case. This includes debugging strings. @str: The string to check. @Returns: A string that is guaranteed to be not NULL. Evaluates to 2 strings, that describe the pad. Often used in debugging statements. @pad: The pad to debug. This macro should evaluate to the name of the current function and be should be defined when configuring your project, as it is compiler dependant. If it is not defined, some default value is used. It is used to provide debugging output with the function name of the message. @category: @level: @file: @function: @line: @object: @message: @data: @category: @level: @file: @function: @line: @object: @format: @Varargs: @category: @level: @file: @function: @line: @object: @format: @args: @message: @Returns: @category: @level: @file: @function: @line: @object: @message: @unused: @level: @Returns: @func: @data: @func: @Returns: @data: @Returns: @active: @Returns: @colored: @Returns: @level: @Returns: @name: @level: @name: @cat: @cat: @cat: @cat: @name: @color: @description: @category: @category: @level: @category: @category: @Returns: @category: @Returns: @category: @Returns: @category: @Returns: @Returns: @colorinfo: @Returns: The default category that is used when no other category is defined as the default. If you want to define a default category, do it like this: &hash;define GST_CAT_DEFAULT category_to_be_default GST_CAT_LEVEL_LOG: Outputs a debugging message. This is the most general macro for outputting debugging messages. You will probably want to use one of the ones described below. @cat: category to use @level: the severity of the message @object: the #GObject the message belongs to or NULL if none @...: A printf-style message to output Output an error message belonging to the given object in the given category. @cat: category to use @obj: the #GObject the message belongs to @...: printf-style message to output Output a warning message belonging to the given object in the given category. @cat: category to use @obj: the #GObject the message belongs to @...: printf-style message to output Output an informational message belonging to the given object in the given category. @cat: category to use @obj: the #GObject the message belongs to @...: printf-style message to output Output an debugging message belonging to the given object in the given category. @cat: category to use @obj: the #GObject the message belongs to @...: printf-style message to output Output an logging message belonging to the given object in the given category. @cat: category to use @obj: the #GObject the message belongs to @...: printf-style message to output Output an error message in the given category. @cat: category to use @...: printf-style message to output Output a warning message in the given category. @cat: category to use @...: printf-style message to output Output an informational message in the given category. @cat: category to use @...: printf-style message to output Output a debuggign message in the given category. @cat: category to use @...: printf-style message to output Output a logging message in the given category. @cat: category to use @...: printf-style message to output Output an error message belonging to the given object in the default category. @obj: the #GObject the message belongs to @...: printf-style message to output Output a warning message belonging to the given object in the default category. @obj: the #GObject the message belongs to @...: printf-style message to output Output an informational message belonging to the given object in the default category. @obj: the #GObject the message belongs to @...: printf-style message to output Output a debugging message belonging to the given object in the default category. @obj: the #GObject the message belongs to @...: printf-style message to output Output a logging message belonging to the given object in the default category. @obj: the #GObject the message belongs to @...: printf-style message to output Output an error message in the default category. @...: printf-style message to output Output a warning message in the default category. @...: printf-style message to output Output an informational message in the default category. @...: printf-style message to output Output a debugging message in the default category. @...: printf-style message to output Output a logging message in the default category. @...: printf-style message to output @cat: @obj: @...: @cat: @obj: @...: @...: @...: @...: @...: Register a pointer to a function with its name, so it can later be used by GST_DEBUG_FUNCPTR_NAME(). @ptr: The function to register Returns: The ptr to the function. Retrieves the name of the function, if it was previously registered with GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer. Make sure you free the string after use. @ptr: pointer to the function Returns: The name of the function @func: @data: @void: @name: @level: @name: