Debugging
GStreamer has an extensive set of debugging tools for
plugin developers.
Command line options
Applications using the GStreamer libraries accept the following set
of command line argruments that help in debugging.
Print available debug categories and exit
Sets the default debug level from 0 (no output) to 5 (everything)
Comma-separated list of category_name:level pairs to set specific
levels for the individual categories.
Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3
Disable color debugging output
Disable debugging
Enable printout of errors while loading GStreamer plugins.
Adding debugging to a plugin
Plugins can define their own categories for the debugging system.
Three things need to happen:
The debugging variable needs to be defined somewhere.
If you only have one source file, you can Use GST_DEBUG_CATEGORY_STATIC to
define a static debug category variable.
If you have multiple source files, you should define the variable using
GST_DEBUG_CATEGORY in the source file where you're initializing the debug
category. The other source files should use GST_DEBUG_CATEGORY_EXTERN to
declare the debug category variable, possibly by including a common header
that has this statement.
The debugging category needs to be initialized. This is done through
GST_DEBUG_CATEGORY_INIT.
If you're using a global debugging category for the complete plugin,
you can call this in the
plugin's plugin_init.
If the debug category is only used for one of the elements, you can call it
from the element's _class_init function.
You should also define a default category to be used for debugging. This is
done by defining GST_CAT_DEFAULT for the source files where you're using
debug macros.
Elements can then log debugging information using the set of macros. There
are five levels of debugging information:
ERROR for fatal errors (for example, internal errors)WARNING for warningsINFO for normal informationDEBUG for debug information (for example, device parameters)LOG for regular operation information (for example, chain handlers)
For each of these levels, there are four macros to log debugging information.
Taking the LOG level as an example, there is
GST_CAT_LOG_OBJECT logs debug information in the given GstCategory
and for the given GstObject
GST_CAT_LOG logs debug information in the given GstCategory
but without a GstObject (this is useful for libraries, for example)
GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT
category (as defined somewhere in the source), for the given GstObject
GST_LOG logs debug information in the default GST_CAT_DEFAULT
category, without a GstObject