mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-22 17:51:16 +00:00
728 lines
15 KiB
Text
728 lines
15 KiB
Text
<!-- ##### SECTION Title ##### -->
|
|
GstInfo
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Debugging and logging
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
This file describes the debugging subsystem. The debugging subsystem works
|
|
only after GStreamer was initilized - for example by calling #gst_init.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
<informalexample>
|
|
<programlisting>
|
|
GST_DEBUG_CATEGORY (my_category); /* define category */
|
|
&hash;define GST_CAT_DEFAULT my_category /* set as default */
|
|
</programlisting>
|
|
</informalexample>
|
|
After that you only need to initialize the category.
|
|
<informalexample>
|
|
<programlisting>
|
|
GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
|
|
</programlisting>
|
|
</informalexample>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
Please note that there are naming conventions for the names of debugging
|
|
categories. These are explained at GST_DEBUG_CATEGORY_INIT().
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
<link linkend="gstreamer-gstconfig">configuration</link>,
|
|
<link linkend="gstreamer-gst">initialization</link> for command line parameters
|
|
and environment variables that affect the debugging output.
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### ENUM GstDebugLevel ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@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.
|
|
|
|
<!-- ##### MACRO GST_LEVEL_DEFAULT ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### ENUM GstDebugColorFlags ##### -->
|
|
<para>
|
|
These are some terminal-oriented flags you can use when creating your debugging
|
|
categories to make them stand out in debugging output.
|
|
</para>
|
|
|
|
@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.
|
|
|
|
<!-- ##### STRUCT GstDebugCategory ##### -->
|
|
<para>
|
|
This is the struct that describes the categories. Once initialized with
|
|
#GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.
|
|
</para>
|
|
|
|
|
|
<!-- ##### MACRO GST_STR_NULL ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@str: The string to check.
|
|
@Returns: A string that is guaranteed to be not NULL.
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_PAD_NAME ##### -->
|
|
<para>
|
|
Evaluates to 2 strings, that describe the pad. Often used in debugging
|
|
statements.
|
|
</para>
|
|
|
|
@pad: The pad to debug.
|
|
|
|
|
|
<!-- ##### MACRO GST_FUNCTION ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### STRUCT GstDebugMessage ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GstLogFunction ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@level:
|
|
@file:
|
|
@function:
|
|
@line:
|
|
@object:
|
|
@message:
|
|
@data:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_log ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@level:
|
|
@file:
|
|
@function:
|
|
@line:
|
|
@object:
|
|
@format:
|
|
@Varargs:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_log_valist ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@level:
|
|
@file:
|
|
@function:
|
|
@line:
|
|
@object:
|
|
@format:
|
|
@args:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_message_get ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@message:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_log_default ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@level:
|
|
@file:
|
|
@function:
|
|
@line:
|
|
@object:
|
|
@message:
|
|
@unused:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_level_get_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@level:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_add_log_function ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@func:
|
|
@data:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_remove_log_function ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@func:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_remove_log_function_by_data ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_set_active ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@active:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_is_active ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_set_colored ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@colored:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_is_colored ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_set_default_threshold ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@level:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_get_default_threshold ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_set_threshold_for_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@name:
|
|
@level:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_unset_threshold_for_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@name:
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_CATEGORY ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@cat:
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_CATEGORY_EXTERN ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@cat:
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_CATEGORY_STATIC ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@cat:
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_CATEGORY_INIT ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@cat:
|
|
@name:
|
|
@color:
|
|
@description:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_category_free ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_category_set_threshold ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@level:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_category_reset_threshold ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_category_get_threshold ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_category_get_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_category_get_color ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_category_get_description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@category:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_get_all_categories ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_construct_term_color ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@colorinfo:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_LEVEL_LOG ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@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
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_ERROR_OBJECT ##### -->
|
|
<para>
|
|
Output an error message belonging to the given object in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_WARNING_OBJECT ##### -->
|
|
<para>
|
|
Output a warning message belonging to the given object in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_INFO_OBJECT ##### -->
|
|
<para>
|
|
Output an informational message belonging to the given object in the given
|
|
category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_DEBUG_OBJECT ##### -->
|
|
<para>
|
|
Output an debugging message belonging to the given object in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_LOG_OBJECT ##### -->
|
|
<para>
|
|
Output an logging message belonging to the given object in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_ERROR ##### -->
|
|
<para>
|
|
Output an error message in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_WARNING ##### -->
|
|
<para>
|
|
Output a warning message in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_INFO ##### -->
|
|
<para>
|
|
Output an informational message in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_DEBUG ##### -->
|
|
<para>
|
|
Output a debuggign message in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_CAT_LOG ##### -->
|
|
<para>
|
|
Output a logging message in the given category.
|
|
</para>
|
|
|
|
@cat: category to use
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_ERROR_OBJECT ##### -->
|
|
<para>
|
|
Output an error message belonging to the given object in the default category.
|
|
</para>
|
|
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_WARNING_OBJECT ##### -->
|
|
<para>
|
|
Output a warning message belonging to the given object in the default category.
|
|
</para>
|
|
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_INFO_OBJECT ##### -->
|
|
<para>
|
|
Output an informational message belonging to the given object in the default
|
|
category.
|
|
</para>
|
|
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_OBJECT ##### -->
|
|
<para>
|
|
Output a debugging message belonging to the given object in the default
|
|
category.
|
|
</para>
|
|
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_LOG_OBJECT ##### -->
|
|
<para>
|
|
Output a logging message belonging to the given object in the default category.
|
|
</para>
|
|
|
|
@obj: the #GObject the message belongs to
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_ERROR ##### -->
|
|
<para>
|
|
Output an error message in the default category.
|
|
</para>
|
|
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_WARNING ##### -->
|
|
<para>
|
|
Output a warning message in the default category.
|
|
</para>
|
|
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_INFO ##### -->
|
|
<para>
|
|
Output an informational message in the default category.
|
|
</para>
|
|
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG ##### -->
|
|
<para>
|
|
Output a debugging message in the default category.
|
|
</para>
|
|
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_LOG ##### -->
|
|
<para>
|
|
Output a logging message in the default category.
|
|
</para>
|
|
|
|
@...: printf-style message to output
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_FUNCPTR ##### -->
|
|
<para>
|
|
Register a pointer to a function with its name, so it can later be used by
|
|
GST_DEBUG_FUNCPTR_NAME().
|
|
</para>
|
|
|
|
@ptr: The function to register
|
|
Returns: The ptr to the function.
|
|
|
|
|
|
<!-- ##### MACRO GST_DEBUG_FUNCPTR_NAME ##### -->
|
|
<para>
|
|
Retrieves the name of the function, if it was previously registered with
|
|
GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer.
|
|
<note>
|
|
<para>
|
|
Make sure you free the string after use.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
|
|
@ptr: pointer to the function
|
|
Returns: The name of the function
|
|
|
|
|
|
<!-- ##### MACRO gst_debug_set_log_function ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@func:
|
|
@data:
|
|
|
|
|
|
<!-- ##### MACRO gst_debug_reset_log_function ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@void:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_debug_print_stack_trace ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GST_TIME_FORMAT ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GST_TIME_ARGS ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@t:
|
|
|
|
|