From bacf783293aee06e9475f6a443b143168e9e8451 Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Wed, 25 Feb 2004 17:38:53 +0000 Subject: [PATCH] fix debugging info in manual Original commit message from CVS: fix debugging info in manual --- ChangeLog | 5 + docs/manual/appendix-checklist.xml | 167 +++++++++++++++++++---------- docs/manual/appendix-debugging.xml | 167 +++++++++++++++++++---------- docs/manual/debugging.xml | 167 +++++++++++++++++++---------- 4 files changed, 329 insertions(+), 177 deletions(-) diff --git a/ChangeLog b/ChangeLog index 814e1b798c..11e720b91a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2004-02-25 Thomas Vander Stichele + + * docs/manual/debugging.xml: + fix manual for new debugging system + 2004-02-25 Andy Wingo * gst/gstpad.c (gst_pad_link_prepare): Re-add diff --git a/docs/manual/appendix-checklist.xml b/docs/manual/appendix-checklist.xml index 698d8da41b..2224241c4e 100644 --- a/docs/manual/appendix-checklist.xml +++ b/docs/manual/appendix-checklist.xml @@ -9,94 +9,143 @@ Command line options Applications using the GStreamer libraries accept the following set - of command line argruments to enable the debugging system. + of command line argruments that help in debugging. - - Sets the mask for the debugging output. + + Print available debug categories and exit - - Sets the mask for the info output. + + Sets the default debug level from 0 (no output) to 5 (everything) - - Sets the mask for the info *and* the debug output. + + Comma-separated list of category_name:level pairs to set specific + levels for the individual categories. + Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3 - - Print out the meaning of gst-mask-* values. + + Disable color debugging output + + + + + + Disable debugging - Enable printout of errors while loading GST plugins. - - - - - - Add a directory to the plugin search path. - - - - - Print the a short desciption of the - options + Enable printout of errors while loading GStreamer plugins. - - The following table gives an overview of the mask values and their meaning. (enabled) means - that the corresponding flag is set by default. This table is available to any GStreamer - application by the --gst-mask-help option. - - -Mask (to be OR'ed) info/debug FLAGS --------------------------------------------------------- -0x00000001 (enabled)/ GST_INIT -0x00000002 / COTHREADS -0x00000004 / COTHREAD_SWITCH -0x00000008 / AUTOPLUG -0x00000010 / AUTOPLUG_ATTEMPT -0x00000020 / PARENTAGE -0x00000040 / STATES -0x00000080 / PLANING -0x00000100 / SCHEDULING -0x00000200 / OPERATION -0x00000400 / BUFFER -0x00000800 / CAPS -0x00001000 / CLOCK -0x00002000 / ELEMENT_PADS -0x00004000 / ELEMENT_FACTORY -0x00008000 / PADS -0x00010000 / PIPELINE -0x00020000 / PLUGIN_LOADING -0x00040000 / PLUGIN_ERRORS -0x00080000 / PLUGIN_INFO -0x00100000 / PROPERTIES -0x00200000 / THREAD -0x00400000 / TYPES -0x00800000 / XML -0x01000000 / NEGOTIATION -0x02000000 / REFCOUNTING - - - Adding a custom debug handler + + + 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 warnings + + +INFO for normal information + + +DEBUG 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 + + + diff --git a/docs/manual/appendix-debugging.xml b/docs/manual/appendix-debugging.xml index 698d8da41b..2224241c4e 100644 --- a/docs/manual/appendix-debugging.xml +++ b/docs/manual/appendix-debugging.xml @@ -9,94 +9,143 @@ Command line options Applications using the GStreamer libraries accept the following set - of command line argruments to enable the debugging system. + of command line argruments that help in debugging. - - Sets the mask for the debugging output. + + Print available debug categories and exit - - Sets the mask for the info output. + + Sets the default debug level from 0 (no output) to 5 (everything) - - Sets the mask for the info *and* the debug output. + + Comma-separated list of category_name:level pairs to set specific + levels for the individual categories. + Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3 - - Print out the meaning of gst-mask-* values. + + Disable color debugging output + + + + + + Disable debugging - Enable printout of errors while loading GST plugins. - - - - - - Add a directory to the plugin search path. - - - - - Print the a short desciption of the - options + Enable printout of errors while loading GStreamer plugins. - - The following table gives an overview of the mask values and their meaning. (enabled) means - that the corresponding flag is set by default. This table is available to any GStreamer - application by the --gst-mask-help option. - - -Mask (to be OR'ed) info/debug FLAGS --------------------------------------------------------- -0x00000001 (enabled)/ GST_INIT -0x00000002 / COTHREADS -0x00000004 / COTHREAD_SWITCH -0x00000008 / AUTOPLUG -0x00000010 / AUTOPLUG_ATTEMPT -0x00000020 / PARENTAGE -0x00000040 / STATES -0x00000080 / PLANING -0x00000100 / SCHEDULING -0x00000200 / OPERATION -0x00000400 / BUFFER -0x00000800 / CAPS -0x00001000 / CLOCK -0x00002000 / ELEMENT_PADS -0x00004000 / ELEMENT_FACTORY -0x00008000 / PADS -0x00010000 / PIPELINE -0x00020000 / PLUGIN_LOADING -0x00040000 / PLUGIN_ERRORS -0x00080000 / PLUGIN_INFO -0x00100000 / PROPERTIES -0x00200000 / THREAD -0x00400000 / TYPES -0x00800000 / XML -0x01000000 / NEGOTIATION -0x02000000 / REFCOUNTING - - - Adding a custom debug handler + + + 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 warnings + + +INFO for normal information + + +DEBUG 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 + + + diff --git a/docs/manual/debugging.xml b/docs/manual/debugging.xml index 698d8da41b..2224241c4e 100644 --- a/docs/manual/debugging.xml +++ b/docs/manual/debugging.xml @@ -9,94 +9,143 @@ Command line options Applications using the GStreamer libraries accept the following set - of command line argruments to enable the debugging system. + of command line argruments that help in debugging. - - Sets the mask for the debugging output. + + Print available debug categories and exit - - Sets the mask for the info output. + + Sets the default debug level from 0 (no output) to 5 (everything) - - Sets the mask for the info *and* the debug output. + + Comma-separated list of category_name:level pairs to set specific + levels for the individual categories. + Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3 - - Print out the meaning of gst-mask-* values. + + Disable color debugging output + + + + + + Disable debugging - Enable printout of errors while loading GST plugins. - - - - - - Add a directory to the plugin search path. - - - - - Print the a short desciption of the - options + Enable printout of errors while loading GStreamer plugins. - - The following table gives an overview of the mask values and their meaning. (enabled) means - that the corresponding flag is set by default. This table is available to any GStreamer - application by the --gst-mask-help option. - - -Mask (to be OR'ed) info/debug FLAGS --------------------------------------------------------- -0x00000001 (enabled)/ GST_INIT -0x00000002 / COTHREADS -0x00000004 / COTHREAD_SWITCH -0x00000008 / AUTOPLUG -0x00000010 / AUTOPLUG_ATTEMPT -0x00000020 / PARENTAGE -0x00000040 / STATES -0x00000080 / PLANING -0x00000100 / SCHEDULING -0x00000200 / OPERATION -0x00000400 / BUFFER -0x00000800 / CAPS -0x00001000 / CLOCK -0x00002000 / ELEMENT_PADS -0x00004000 / ELEMENT_FACTORY -0x00008000 / PADS -0x00010000 / PIPELINE -0x00020000 / PLUGIN_LOADING -0x00040000 / PLUGIN_ERRORS -0x00080000 / PLUGIN_INFO -0x00100000 / PROPERTIES -0x00200000 / THREAD -0x00400000 / TYPES -0x00800000 / XML -0x01000000 / NEGOTIATION -0x02000000 / REFCOUNTING - - - Adding a custom debug handler + + + 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 warnings + + +INFO for normal information + + +DEBUG 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 + + +