Top |
Functions
Types and Values
enum | GstDebugLevel |
#define | GST_LEVEL_DEFAULT |
#define | GST_LEVEL_MAX |
enum | GstDebugColorFlags |
enum | GstDebugColorMode |
struct | GstDebugCategory |
enum | GstDebugGraphDetails |
#define | GST_FUNCTION |
enum | GstStackTraceFlags |
extern | GST_CAT_DEFAULT |
#define | GST_TIME_FORMAT |
#define | GST_STIME_FORMAT |
#define | GST_PTR_FORMAT |
#define | GST_SEGMENT_FORMAT |
Description
GStreamer's debugging subsystem is an easy way to get information about what the application is doing. It is not meant for programming errors. Use GLib methods (g_warning and friends) for that.
The debugging subsystem works only after GStreamer has been initialized
for example by calling
gst_init()
.
The debugging subsystem is used to log informational messages while the application runs. Each messages has some properties attached to it. Among these properties are the debugging category, the severity (called "level" here) and an optional 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.
1 2 |
GST_DEBUG_CATEGORY_STATIC (my_category); // define category (statically) #define GST_CAT_DEFAULT my_category // set as default |
After that you only need to initialize the category.
1 2 |
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: unnoticeable) 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()
.
Functions
GST_STR_NULL()
#define GST_STR_NULL(str) ((str) ? (str) : "(NULL)")
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.
GST_DEBUG_PAD_NAME()
#define GST_DEBUG_PAD_NAME(pad)
Evaluates to 2 strings, that describe the pad. Often used in debugging statements.
GstLogFunction ()
void (*GstLogFunction) (GstDebugCategory *category
,GstDebugLevel level
,const gchar *file
,const gchar *function
,gint line
,GObject *object
,GstDebugMessage *message
,gpointer user_data
);
Function prototype for a logging function that can be registered with
gst_debug_add_log_function()
.
Use G_GNUC_NO_INSTRUMENT on that function.
Parameters
category |
||
level |
||
file |
file name |
|
function |
function name |
|
line |
line number |
|
object |
a GObject |
|
message |
the message |
|
user_data |
user data for the log function |
gst_debug_log ()
void gst_debug_log (GstDebugCategory *category
,GstDebugLevel level
,const gchar *file
,const gchar *function
,gint line
,GObject *object
,const gchar *format
,...
);
Logs the given message using the currently registered debugging handlers.
Parameters
category |
category to log |
|
level |
level of the message is in |
|
file |
the file that emitted the message, usually the __FILE__ identifier |
|
function |
the function that emitted the message |
|
line |
the line from that the message was emitted, usually __LINE__ |
|
object |
the object this message relates to,
or |
[transfer none][allow-none] |
format |
a printf style format string |
|
... |
optional arguments for the format |
gst_debug_log_valist ()
void gst_debug_log_valist (GstDebugCategory *category
,GstDebugLevel level
,const gchar *file
,const gchar *function
,gint line
,GObject *object
,const gchar *format
,va_list args
);
Logs the given message using the currently registered debugging handlers.
Parameters
category |
category to log |
|
level |
level of the message is in |
|
file |
the file that emitted the message, usually the __FILE__ identifier |
|
function |
the function that emitted the message |
|
line |
the line from that the message was emitted, usually __LINE__ |
|
object |
the object this message relates to,
or |
[transfer none][allow-none] |
format |
a printf style format string |
|
args |
optional arguments for the format |
gst_debug_message_get ()
const gchar *
gst_debug_message_get (GstDebugMessage *message
);
Gets the string representation of a GstDebugMessage. This function is used in debug handlers to extract the message.
gst_debug_log_default ()
void gst_debug_log_default (GstDebugCategory *category
,GstDebugLevel level
,const gchar *file
,const gchar *function
,gint line
,GObject *object
,GstDebugMessage *message
,gpointer user_data
);
The default logging handler used by GStreamer. Logging functions get called
whenever a macro like GST_DEBUG or similar is used. By default this function
is setup to output the message and additional info to stderr (or the log file
specified via the GST_DEBUG_FILE environment variable) as received via
user_data
.
You can add other handlers by using gst_debug_add_log_function()
.
And you can remove this handler by calling
gst_debug_remove_log_function(gst_debug_log_default);
Parameters
category |
category to log |
|
level |
level of the message |
|
file |
the file that emitted the message, usually the __FILE__ identifier |
|
function |
the function that emitted the message |
|
line |
the line from that the message was emitted, usually __LINE__ |
|
message |
the actual message |
|
object |
the object this message relates to,
or |
[transfer none][allow-none] |
user_data |
the FILE* to log to |
gst_debug_level_get_name ()
const gchar *
gst_debug_level_get_name (GstDebugLevel level
);
Get the string representation of a debugging level
gst_debug_add_log_function ()
void gst_debug_add_log_function (GstLogFunction func
,gpointer user_data
,GDestroyNotify notify
);
Adds the logging function to the list of logging functions. Be sure to use G_GNUC_NO_INSTRUMENT on that function, it is needed.
gst_debug_remove_log_function ()
guint
gst_debug_remove_log_function (GstLogFunction func
);
Removes all registered instances of the given logging functions.
Parameters
func |
the log function to remove, or |
[scope call][allow-none] |
gst_debug_remove_log_function_by_data ()
guint
gst_debug_remove_log_function_by_data (gpointer data
);
Removes all registered instances of log functions with the given user data.
gst_debug_add_ring_buffer_logger ()
void gst_debug_add_ring_buffer_logger (guint max_size_per_thread
,guint thread_timeout
);
Adds a memory ringbuffer based debug logger that stores up to
max_size_per_thread
bytes of logs per thread and times out threads after
thread_timeout
seconds of inactivity.
Logs can be fetched with gst_debug_ring_buffer_logger_get_logs()
and the
logger can be removed again with gst_debug_remove_ring_buffer_logger()
.
Only one logger at a time is possible.
Parameters
max_size_per_thread |
Maximum size of log per thread in bytes |
|
thread_timeout |
Timeout for threads in seconds |
Since: 1.14
gst_debug_remove_ring_buffer_logger ()
void
gst_debug_remove_ring_buffer_logger (void
);
Removes any previously added ring buffer logger with
gst_debug_add_ring_buffer_logger()
.
Since: 1.14
gst_debug_ring_buffer_logger_get_logs ()
gchar **
gst_debug_ring_buffer_logger_get_logs (void
);
Fetches the current logs per thread from the ring buffer logger. See
gst_debug_add_ring_buffer_logger()
for details.
Returns
NULL-terminated array of strings with the debug output per thread.
[transfer full][array zero-terminated]
Since: 1.14
gst_debug_set_active ()
void
gst_debug_set_active (gboolean active
);
If activated, debugging messages are sent to the debugging handlers. It makes sense to deactivate it for speed issues.
This function is not threadsafe. It makes sense to only call it during initialization.
gst_debug_is_active ()
gboolean
gst_debug_is_active (void
);
Checks if debugging output is activated.
gst_debug_set_colored ()
void
gst_debug_set_colored (gboolean colored
);
Sets or unsets the use of coloured debugging output.
Same as gst_debug_set_color_mode()
with the argument being
being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF.
This function may be called before gst_init()
.
gst_debug_set_color_mode ()
void
gst_debug_set_color_mode (GstDebugColorMode mode
);
Changes the coloring mode for debug output.
This function may be called before gst_init()
.
Since: 1.2
gst_debug_set_color_mode_from_string ()
void
gst_debug_set_color_mode_from_string (const gchar *mode
);
Changes the coloring mode for debug output.
This function may be called before gst_init()
.
Parameters
mode |
The coloring mode for debug output. One of the following: "on", "auto", "off", "disable", "unix". |
Since: 1.2
gst_debug_is_colored ()
gboolean
gst_debug_is_colored (void
);
Checks if the debugging output should be colored.
gst_debug_get_color_mode ()
GstDebugColorMode
gst_debug_get_color_mode (void
);
Changes the coloring mode for debug output.
Since: 1.2
gst_debug_set_default_threshold ()
void
gst_debug_set_default_threshold (GstDebugLevel level
);
Sets the default threshold to the given level and updates all categories to use this threshold.
This function may be called before gst_init()
.
gst_debug_set_threshold_from_string ()
void gst_debug_set_threshold_from_string (const gchar *list
,gboolean reset
);
Sets the debug logging wanted in the same form as with the GST_DEBUG environment variable. You can use wildcards such as '*', but note that the order matters when you use wild cards, e.g. "foosrc:6,*src:3,*:2" sets everything to log level 2.
Since: 1.2
gst_debug_get_default_threshold ()
GstDebugLevel
gst_debug_get_default_threshold (void
);
Returns the default threshold that is used for new categories.
gst_debug_set_threshold_for_name ()
void gst_debug_set_threshold_for_name (const gchar *name
,GstDebugLevel level
);
Sets all categories which match the given glob style pattern to the given level.
gst_debug_unset_threshold_for_name ()
void
gst_debug_unset_threshold_for_name (const gchar *name
);
Resets all categories with the given name back to the default level.
GST_DEBUG_CATEGORY()
#define GST_DEBUG_CATEGORY(cat) GstDebugCategory *cat = NULL
Defines a GstDebugCategory variable. This macro expands to nothing if debugging is disabled.
GST_DEBUG_CATEGORY_EXTERN()
#define GST_DEBUG_CATEGORY_EXTERN(cat) extern GstDebugCategory *cat
Declares a GstDebugCategory variable as extern. Use in header files. This macro expands to nothing if debugging is disabled.
GST_DEBUG_CATEGORY_STATIC()
#define GST_DEBUG_CATEGORY_STATIC(cat) static GstDebugCategory *cat = NULL
Defines a static GstDebugCategory variable. This macro expands to nothing if debugging is disabled.
GST_DEBUG_CATEGORY_INIT()
#define GST_DEBUG_CATEGORY_INIT(cat,name,color,description)
Initializes a new GstDebugCategory with the given properties and set to the default threshold.
This macro expands to nothing if debugging is disabled.
When naming your category, please follow the following conventions to ensure that the pattern matching for categories works as expected. It is not earth-shattering if you don't follow these conventions, but it would be nice for everyone.
If you define a category for a plugin or a feature of it, name the category like the feature. So if you wanted to write a "filesrc" element, you would name the category "filesrc". Use lowercase letters only. If you define more than one category for the same element, append an underscore and an identifier to your categories, like this: "filesrc_cache"
If you create a library or an application using debugging categories, use a common prefix followed by an underscore for all your categories. GStreamer uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure to include uppercase letters.
GST_DEBUG_CATEGORY_GET()
#define GST_DEBUG_CATEGORY_GET(cat,name)
Looks up an existing GstDebugCategory by its name
and sets cat
. If the
category is not found, but GST_CAT_DEFAULT is defined, that is assigned to
cat
. Otherwise cat
will be NULL
.
1 2 3 4 5 6 |
GST_DEBUG_CATEGORY_STATIC (gst_myplugin_debug); #define GST_CAT_DEFAULT gst_myplugin_debug GST_DEBUG_CATEGORY_STATIC (GST_CAT_PERFORMANCE); ... GST_DEBUG_CATEGORY_INIT (gst_myplugin_debug, "myplugin", 0, "nice element"); GST_DEBUG_CATEGORY_GET (GST_CAT_PERFORMANCE, "GST_PERFORMANCE"); |
gst_debug_category_free ()
void
gst_debug_category_free (GstDebugCategory *category
);
Removes and frees the category and all associated resources.
gst_debug_category_set_threshold ()
void gst_debug_category_set_threshold (GstDebugCategory *category
,GstDebugLevel level
);
Sets the threshold of the category to the given level. Debug information will only be output if the threshold is lower or equal to the level of the debugging message.
Do not use this function in production code, because other functions may change the threshold of categories as side effect. It is however a nice function to use when debugging (even from gdb).
Parameters
category |
a GstDebugCategory to set threshold of. |
|
level |
the GstDebugLevel threshold to set. |
gst_debug_category_reset_threshold ()
void
gst_debug_category_reset_threshold (GstDebugCategory *category
);
Resets the threshold of the category to the default level. Debug information
will only be output if the threshold is lower or equal to the level of the
debugging message.
Use this function to set the threshold back to where it was after using
gst_debug_category_set_threshold()
.
gst_debug_category_get_threshold ()
GstDebugLevel
gst_debug_category_get_threshold (GstDebugCategory *category
);
Returns the threshold of a GstDebugCategory.
gst_debug_category_get_name ()
const gchar *
gst_debug_category_get_name (GstDebugCategory *category
);
Returns the name of a debug category.
gst_debug_category_get_color ()
guint
gst_debug_category_get_color (GstDebugCategory *category
);
Returns the color of a debug category used when printing output in this category.
gst_debug_category_get_description ()
const gchar *
gst_debug_category_get_description (GstDebugCategory *category
);
Returns the description of a debug category.
gst_debug_get_all_categories ()
GSList *
gst_debug_get_all_categories (void
);
Returns a snapshot of a all categories that are currently in use . This list may change anytime. The caller has to free the list after use.
gst_debug_construct_term_color ()
gchar *
gst_debug_construct_term_color (guint colorinfo
);
Constructs a string that can be used for getting the desired color in color terminals. You need to free the string after use.
gst_debug_construct_win_color ()
gint
gst_debug_construct_win_color (guint colorinfo
);
Constructs an integer that can be used for getting the desired color in windows' terminals (cmd.exe). As there is no mean to underline, we simply ignore this attribute.
This function returns 0 on non-windows machines.
GST_CAT_LEVEL_LOG()
#define GST_CAT_LEVEL_LOG(cat,level,object,...)
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.
There is no need to finish the end of the debug message with a newline character, a newline character will be added automatically.
GST_CAT_ERROR_OBJECT()
#define GST_CAT_ERROR_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_ERROR, obj, __VA_ARGS__)
Output an error message belonging to the given object in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
... |
printf-style message to output |
GST_CAT_WARNING_OBJECT()
#define GST_CAT_WARNING_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_WARNING, obj, __VA_ARGS__)
Output a warning message belonging to the given object in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
... |
printf-style message to output |
GST_CAT_INFO_OBJECT()
#define GST_CAT_INFO_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_INFO, obj, __VA_ARGS__)
Output an informational message belonging to the given object in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
... |
printf-style message to output |
GST_CAT_DEBUG_OBJECT()
#define GST_CAT_DEBUG_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_DEBUG, obj, __VA_ARGS__)
Output an debugging message belonging to the given object in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
... |
printf-style message to output |
GST_CAT_LOG_OBJECT()
#define GST_CAT_LOG_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_LOG, obj, __VA_ARGS__)
Output an logging message belonging to the given object in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
... |
printf-style message to output |
GST_CAT_FIXME_OBJECT()
#define GST_CAT_FIXME_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_FIXME, obj, __VA_ARGS__)
Output a fixme message belonging to the given object in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
... |
printf-style message to output |
GST_CAT_TRACE_OBJECT()
#define GST_CAT_TRACE_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_TRACE, obj, __VA_ARGS__)
Output a tracing message belonging to the given object in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
... |
printf-style message to output |
GST_CAT_MEMDUMP_OBJECT()
#define GST_CAT_MEMDUMP_OBJECT(cat,obj,msg,data,length)
Output a hexdump of data
relating to the given object in the given
category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
cat |
category to use |
|
obj |
the GObject the message belongs to |
|
msg |
message string to log with the data |
|
data |
pointer to the data to output |
|
length |
length of the data to output |
GST_CAT_ERROR()
#define GST_CAT_ERROR(cat,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_ERROR, NULL, __VA_ARGS__)
Output an error message in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_CAT_WARNING()
#define GST_CAT_WARNING(cat,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_WARNING, NULL, __VA_ARGS__)
Output an warning message in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_CAT_INFO()
#define GST_CAT_INFO(cat,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_INFO, NULL, __VA_ARGS__)
Output an informational message in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_CAT_DEBUG()
#define GST_CAT_DEBUG(cat,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_DEBUG, NULL, __VA_ARGS__)
Output an debugging message in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_CAT_LOG()
#define GST_CAT_LOG(cat,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_LOG, NULL, __VA_ARGS__)
Output an logging message in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_CAT_FIXME()
#define GST_CAT_FIXME(cat,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_FIXME, NULL, __VA_ARGS__)
Output an fixme message in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_CAT_TRACE()
#define GST_CAT_TRACE(cat,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_TRACE, NULL, __VA_ARGS__)
Output a tracing message in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_CAT_MEMDUMP()
#define GST_CAT_MEMDUMP(cat,msg,data,length)
Output a hexdump of data
in the given category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_ERROR_OBJECT()
#define GST_ERROR_OBJECT(obj,...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_ERROR, obj, __VA_ARGS__)
Output an error message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_WARNING_OBJECT()
#define GST_WARNING_OBJECT(obj,...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_WARNING, obj, __VA_ARGS__)
Output a warning message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_INFO_OBJECT()
#define GST_INFO_OBJECT(obj,...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_INFO, obj, __VA_ARGS__)
Output an informational message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_DEBUG_OBJECT()
#define GST_DEBUG_OBJECT(obj,...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_DEBUG, obj, __VA_ARGS__)
Output a debugging message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_LOG_OBJECT()
#define GST_LOG_OBJECT(obj,...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_LOG, obj, __VA_ARGS__)
Output a logging message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_FIXME_OBJECT()
#define GST_FIXME_OBJECT(obj,...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_FIXME, obj, __VA_ARGS__)
Output a fixme message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_TRACE_OBJECT()
#define GST_TRACE_OBJECT(obj,...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_TRACE, obj, __VA_ARGS__)
Output a tracing message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_MEMDUMP_OBJECT()
#define GST_MEMDUMP_OBJECT(obj,msg,data,length)
Output a logging message belonging to the given object in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
Parameters
obj |
the GObject the message belongs to |
|
msg |
message string to log with the data |
|
data |
pointer to the data to output |
|
length |
length of the data to output |
GST_ERROR()
#define GST_ERROR(...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_ERROR, NULL, __VA_ARGS__)
Output an error message in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_WARNING()
#define GST_WARNING(...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_WARNING, NULL, __VA_ARGS__)
Output a warning message in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_INFO()
#define GST_INFO(...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_INFO, NULL, __VA_ARGS__)
Output an informational message in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_DEBUG()
#define GST_DEBUG(...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_DEBUG, NULL, __VA_ARGS__)
Output a debugging message in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_LOG()
#define GST_LOG(...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_LOG, NULL, __VA_ARGS__)
Output a logging message in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_FIXME()
#define GST_FIXME(...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_FIXME, NULL, __VA_ARGS__)
Output a fixme message in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_TRACE()
#define GST_TRACE(...) GST_CAT_LEVEL_LOG (GST_CAT_DEFAULT, GST_LEVEL_TRACE, NULL, __VA_ARGS__)
Output a tracing message in the default category.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_MEMDUMP()
#define GST_MEMDUMP(msg,data,length)
Output a hexdump of data
.
There is no need to finish the end of the message string with a newline character, a newline character will be added automatically.
GST_DEBUG_REGISTER_FUNCPTR()
#define GST_DEBUG_REGISTER_FUNCPTR(ptr)
Register a pointer to a function with its name, so it can later be used by
GST_DEBUG_FUNCPTR_NAME()
.
Use this variant of GST_DEBUG_FUNCPTR if you do not need to use ptr
.
GST_DEBUG_FUNCPTR()
#define GST_DEBUG_FUNCPTR(ptr)
Register a pointer to a function with its name, so it can later be used by
GST_DEBUG_FUNCPTR_NAME()
.
GST_DEBUG_FUNCPTR_NAME()
#define GST_DEBUG_FUNCPTR_NAME(ptr)
Retrieves the name of the function, if it was previously registered with
GST_DEBUG_FUNCPTR()
. If not, it returns a description of the pointer.
This macro returns a constant string which must not be modified or freed by the caller.
GST_DEBUG_BIN_TO_DOT_FILE()
#define GST_DEBUG_BIN_TO_DOT_FILE(bin, details, file_name) gst_debug_bin_to_dot_file (bin, details, file_name)
To aid debugging applications one can use this method to write out the whole network of gstreamer elements that form the pipeline into an dot file. This file can be processed with graphviz to get an image, like this:
1 |
dot -Tpng -oimage.png graph_lowlevel.dot |
There is also a utility called xdot which allows you to view the dot file directly without converting it first.
The macro is only active if gstreamer is configured with "--gst-enable-gst-debug" and the environment variable GST_DEBUG_DUMP_DOT_DIR is set to a basepath (e.g. /tmp).
Parameters
bin |
the top-level pipeline that should be analyzed |
|
details |
details to show in the graph, e.g. GST_DEBUG_GRAPH_SHOW_ALL or one or more other GstDebugGraphDetails flags. |
|
file_name |
output base filename (e.g. "myplayer") |
GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS()
#define GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS(bin, details, file_name) gst_debug_bin_to_dot_file_with_ts (bin, details, file_name)
This works like GST_DEBUG_BIN_TO_DOT_FILE()
, but adds the current timestamp
to the filename, so that it can be used to take multiple snapshots.
Parameters
bin |
the top-level pipeline that should be analyzed |
|
details |
details to show in the graph, e.g. GST_DEBUG_GRAPH_SHOW_ALL or one or more other GstDebugGraphDetails flags. |
|
file_name |
output base filename (e.g. "myplayer") |
gst_debug_print_stack_trace ()
void
gst_debug_print_stack_trace (void
);
If libunwind or glibc backtrace are present a stack trace is printed.
gst_debug_get_stack_trace ()
gchar *
gst_debug_get_stack_trace (GstStackTraceFlags flags
);
Parameters
flags |
A set of GstStackTraceFlags to determine how the stack trace should look like. Pass 0 to retrieve a minimal backtrace. |
Since: 1.12
GST_TIME_ARGS()
#define GST_TIME_ARGS(t)
Format t
for the GST_TIME_FORMAT format string. Note: t
will be
evaluated more than once.
GST_STIME_ARGS()
#define GST_STIME_ARGS(t)
Format t
for the GST_STIME_FORMAT format string. Note: t
will be
evaluated more than once.
Since: 1.6
gst_debug_bin_to_dot_data ()
gchar * gst_debug_bin_to_dot_data (GstBin *bin
,GstDebugGraphDetails details
);
To aid debugging applications one can use this method to obtain the whole network of gstreamer elements that form the pipeline into an dot file. This data can be processed with graphviz to get an image.
gst_debug_bin_to_dot_file ()
void gst_debug_bin_to_dot_file (GstBin *bin
,GstDebugGraphDetails details
,const gchar *file_name
);
To aid debugging applications one can use this method to write out the whole network of gstreamer elements that form the pipeline into an dot file. This file can be processed with graphviz to get an image.
1 |
dot -Tpng -oimage.png graph_lowlevel.dot |
gst_debug_bin_to_dot_file_with_ts ()
void gst_debug_bin_to_dot_file_with_ts (GstBin *bin
,GstDebugGraphDetails details
,const gchar *file_name
);
This works like gst_debug_bin_to_dot_file()
, but adds the current timestamp
to the filename, so that it can be used to take multiple snapshots.
gst_info_vasprintf ()
gint gst_info_vasprintf (gchar **result
,const gchar *format
,va_list args
);
Allocates and fills a string large enough (including the terminating null
byte) to hold the specified printf style format
and args
.
This function deals with the GStreamer specific printf specifiers
GST_PTR_FORMAT and GST_SEGMENT_FORMAT. If you do not have these specifiers
in your format
string, you do not need to use this function and can use
alternatives such as g_vasprintf()
.
Free result
with g_free()
.
Parameters
result |
the resulting string. |
[out] |
format |
a printf style format string |
|
args |
the va_list of printf arguments for |
Since: 1.8
gst_info_strdup_vprintf ()
gchar * gst_info_strdup_vprintf (const gchar *format
,va_list args
);
Allocates, fills and returns a null terminated string from the printf style
format
string and args
.
See gst_info_vasprintf()
for when this function is required.
Free with g_free()
.
Since: 1.8
gst_info_strdup_printf ()
gchar * gst_info_strdup_printf (const gchar *format
,...
);
Allocates, fills and returns a 0-terminated string from the printf style
format
string and corresponding arguments.
See gst_info_vasprintf()
for when this function is required.
Free with g_free()
.
Since: 1.8
gst_print ()
void gst_print (const gchar *format
,...
);
Outputs a formatted message via the GLib print handler. The default print handler simply outputs the message to stdout.
This function will not append a new-line character at the end, unlike
gst_println()
which will.
All strings must be in ASCII or UTF-8 encoding.
This function differs from g_print()
in that it supports all the additional
printf specifiers that are supported by GStreamer's debug logging system,
such as GST_PTR_FORMAT and GST_SEGMENT_FORMAT.
This function is primarily for printing debug output.
Since: 1.12
gst_println ()
void gst_println (const gchar *format
,...
);
Outputs a formatted message via the GLib print handler. The default print handler simply outputs the message to stdout.
This function will append a new-line character at the end, unlike
gst_print()
which will not.
All strings must be in ASCII or UTF-8 encoding.
This function differs from g_print()
in that it supports all the additional
printf specifiers that are supported by GStreamer's debug logging system,
such as GST_PTR_FORMAT and GST_SEGMENT_FORMAT.
This function is primarily for printing debug output.
Since: 1.12
gst_printerr ()
void gst_printerr (const gchar *format
,...
);
Outputs a formatted message via the GLib error message handler. The default handler simply outputs the message to stderr.
This function will not append a new-line character at the end, unlike
gst_printerrln()
which will.
All strings must be in ASCII or UTF-8 encoding.
This function differs from g_printerr()
in that it supports the additional
printf specifiers that are supported by GStreamer's debug logging system,
such as GST_PTR_FORMAT and GST_SEGMENT_FORMAT.
This function is primarily for printing debug output.
Since: 1.12
gst_printerrln ()
void gst_printerrln (const gchar *format
,...
);
Outputs a formatted message via the GLib error message handler. The default handler simply outputs the message to stderr.
This function will append a new-line character at the end, unlike
gst_printerr()
which will not.
All strings must be in ASCII or UTF-8 encoding.
This function differs from g_printerr()
in that it supports the additional
printf specifiers that are supported by GStreamer's debug logging system,
such as GST_PTR_FORMAT and GST_SEGMENT_FORMAT.
This function is primarily for printing debug output.
Since: 1.12
Types and Values
enum GstDebugLevel
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.
Members
No debugging level specified or desired. Used to deactivate debugging output. |
||
Error messages are to be used only when an error occurred 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_error. |
||
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.") |
||
Fixme messages are messages that indicate that something in the executed code path is not fully implemented or handled yet. Note that this does not replace proper error handling in any way, the purpose of this message is to make it easier to spot incomplete/unfinished pieces of code when reading the debug log. |
||
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.") |
||
Debugging messages should be used when something common happens that is not the expected default behavior, or something that's useful to know but doesn't happen all the time (ie. per loop iteration or buffer processed or event handled). An example would be notifications about state changes or receiving/sending of events. |
||
Log messages are messages that are very common but might be useful to know. As a rule of thumb a pipeline that is running as expected should never output anything else but LOG messages whilst processing data. Use this log level to log recurring information in chain functions and loop functions, for example. |
||
Tracing-related messages. Examples for this are referencing/dereferencing of objects. |
||
memory dump messages are used to log (small) chunks of data as memory dumps in the log. They will be displayed as hexdump with ASCII characters. |
||
The number of defined debugging levels. |
GST_LEVEL_DEFAULT
#define GST_LEVEL_DEFAULT GST_LEVEL_NONE
Defines the default debugging level to be used with GStreamer. It is normally
set to GST_LEVEL_NONE so nothing get printed.
As it can be configured at compile time, 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.
GST_LEVEL_MAX
#define GST_LEVEL_MAX GST_LEVEL_COUNT
Defines the maximum debugging level to be enabled at compilation time. By default it is set such that all debugging statements will be enabled.
If you wish to compile GStreamer and plugins with only some debugging statements (Such as just warnings and errors), you can define it at compile time to the maximum debug level. Any debug statements above that level will be compiled out.
Since: 1.6
enum GstDebugColorFlags
These are some terminal style flags you can use when creating your debugging categories to make them stand out in debugging output.
Members
Use black as foreground color. |
||
Use red as foreground color. |
||
Use green as foreground color. |
||
Use yellow as foreground color. |
||
Use blue as foreground color. |
||
Use magenta as foreground color. |
||
Use cyan as foreground color. |
||
Use white as foreground color. |
||
Use black as background color. |
||
Use red as background color. |
||
Use green as background color. |
||
Use yellow as background color. |
||
Use blue as background color. |
||
Use magenta as background color. |
||
Use cyan as background color. |
||
Use white as background color. |
||
Make the output bold. |
||
Underline the output. |
struct GstDebugCategory
struct GstDebugCategory { };
This is the struct that describes the categories. Once initialized with GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.
enum GstDebugGraphDetails
Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE()
and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS()
.
Members
show caps-name on edges |
||
show caps-details on edges |
||
show modified parameters on elements |
||
show element states |
||
show full element parameter values even if they are very long |
||
show all the typical details that one might want |
||
show all details regardless of how large or verbose they make the resulting output |
GST_FUNCTION
# define GST_FUNCTION ((const char*) (__func__))
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.
Note that this is different from G_STRFUNC as we do not want the full function signature in C++ code.
GST_CAT_DEFAULT
GST_API GstDebugCategory * GST_CAT_DEFAULT;
Default gstreamer core debug log category. Please define your own.
GST_TIME_FORMAT
#define GST_TIME_FORMAT "u:%02u:%02u.%09u"
A string that can be used in printf-like format strings to display a
GstClockTime value in h:m:s format. Use GST_TIME_ARGS()
to construct
the matching arguments.
Example:
1 |
printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts)); |
GST_STIME_FORMAT
#define GST_STIME_FORMAT "c%" GST_TIME_FORMAT
A string that can be used in printf-like format strings to display a signed
GstClockTimeDiff or gint64 value in h:m:s format. Use GST_TIME_ARGS()
to
construct the matching arguments.
Example:
1 |
printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts)); |
Since: 1.6
GST_PTR_FORMAT
#define GST_PTR_FORMAT "p\aA"
printf format type used to debug GStreamer types. You can use this in
combination with GStreamer's debug logging system as well as the functions
gst_info_vasprintf()
, gst_info_strdup_vprintf()
and gst_info_strdup_printf()
to pretty-print the following types: GstCaps, GstStructure,
GstCapsFeatures, GstTagList, GstDateTime, GstBuffer, GstBufferList,
GstMessage, GstEvent, GstQuery, GstContext, GstPad, GstObject. All
GObject types will be printed as typename plus pointer, and everything
else will simply be printed as pointer address.
This can only be used on types whose size is >= sizeof(gpointer).
GST_SEGMENT_FORMAT
#define GST_SEGMENT_FORMAT "p\aB"
printf format type used to debug GStreamer segments. You can use this in
combination with GStreamer's debug logging system as well as the functions
gst_info_vasprintf()
, gst_info_strdup_vprintf()
and gst_info_strdup_printf()
to pretty-print GstSegment structures.
This can only be used on pointers to GstSegment structures.
See Also
gst-running for command line parameters and environment variables that affect the debugging output.