GstInfo

GstInfo — Debugging and logging facilities

Functions

#define GST_STR_NULL()
#define GST_DEBUG_PAD_NAME()
#define GST_FUNCTION
void (*GstLogFunction) ()
void gst_debug_log ()
void gst_debug_log_valist ()
const gchar * gst_debug_message_get ()
void gst_debug_log_default ()
const gchar * gst_debug_level_get_name ()
void gst_debug_add_log_function ()
guint gst_debug_remove_log_function ()
guint gst_debug_remove_log_function_by_data ()
void gst_debug_set_active ()
gboolean gst_debug_is_active ()
void gst_debug_set_colored ()
void gst_debug_set_color_mode ()
void gst_debug_set_color_mode_from_string ()
gboolean gst_debug_is_colored ()
GstDebugColorMode gst_debug_get_color_mode ()
void gst_debug_set_default_threshold ()
void gst_debug_set_threshold_from_string ()
GstDebugLevel gst_debug_get_default_threshold ()
void gst_debug_set_threshold_for_name ()
void gst_debug_unset_threshold_for_name ()
#define GST_DEBUG_CATEGORY()
#define GST_DEBUG_CATEGORY_EXTERN()
#define GST_DEBUG_CATEGORY_STATIC()
#define GST_DEBUG_CATEGORY_INIT()
#define GST_DEBUG_CATEGORY_GET()
void gst_debug_category_free ()
void gst_debug_category_set_threshold ()
void gst_debug_category_reset_threshold ()
GstDebugLevel gst_debug_category_get_threshold ()
const gchar * gst_debug_category_get_name ()
guint gst_debug_category_get_color ()
const gchar * gst_debug_category_get_description ()
GSList * gst_debug_get_all_categories ()
gchar * gst_debug_construct_term_color ()
gint gst_debug_construct_win_color ()
#define GST_CAT_LEVEL_LOG()
#define GST_CAT_ERROR_OBJECT()
#define GST_CAT_WARNING_OBJECT()
#define GST_CAT_INFO_OBJECT()
#define GST_CAT_DEBUG_OBJECT()
#define GST_CAT_LOG_OBJECT()
#define GST_CAT_FIXME_OBJECT()
#define GST_CAT_TRACE_OBJECT()
#define GST_CAT_MEMDUMP_OBJECT()
#define GST_CAT_ERROR()
#define GST_CAT_WARNING()
#define GST_CAT_INFO()
#define GST_CAT_DEBUG()
#define GST_CAT_LOG()
#define GST_CAT_FIXME()
#define GST_CAT_TRACE()
#define GST_CAT_MEMDUMP()
#define GST_ERROR_OBJECT()
#define GST_WARNING_OBJECT()
#define GST_INFO_OBJECT()
#define GST_DEBUG_OBJECT()
#define GST_LOG_OBJECT()
#define GST_FIXME_OBJECT()
#define GST_TRACE_OBJECT()
#define GST_MEMDUMP_OBJECT()
#define GST_ERROR()
#define GST_WARNING()
#define GST_INFO()
#define GST_DEBUG()
#define GST_LOG()
#define GST_FIXME()
#define GST_TRACE()
#define GST_MEMDUMP()
#define GST_DEBUG_REGISTER_FUNCPTR()
#define GST_DEBUG_FUNCPTR()
#define GST_DEBUG_FUNCPTR_NAME()
#define GST_DEBUG_BIN_TO_DOT_FILE()
#define GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS()
void gst_debug_print_stack_trace ()
#define GST_TIME_ARGS()
void gst_debug_bin_to_dot_file ()
void gst_debug_bin_to_dot_file_with_ts ()

Types and Values

Includes

#include <gst/gst.h>

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

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.

Parameters

str

The string to check.

[allow-none]

GST_DEBUG_PAD_NAME()

#define             GST_DEBUG_PAD_NAME(pad)

Evaluates to 2 strings, that describe the pad. Often used in debugging statements.

Parameters

pad

The pad to debug.

 

GST_FUNCTION

#  define GST_FUNCTION     ((const char*) (__FUNCTION__))

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.


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

a GstDebugCategory

 

level

a GstDebugLevel

 

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 NULL if none.

[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 NULL if none.

[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.

Parameters

message

a debug message

 

Returns

the string representation of a GstDebugMessage.


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 unused);

The default logging handler used by GStreamer. Logging functions get called whenever a macro like GST_DEBUG or similar is used. This function outputs the message and additional info to stderr (or the log file specified via the GST_DEBUG_FILE environment variable).

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 NULL if none.

[transfer none][allow-none]

unused

an unused variable, reserved for some user_data.

 

gst_debug_level_get_name ()

const gchar *
gst_debug_level_get_name (GstDebugLevel level);

Get the string representation of a debugging level

Parameters

level

the level to get the name for

 

Returns

the name


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.

Parameters

func

the function to use

 

user_data

user data

 

notify

called when user_data is not used anymore

 

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.

[scope call]

Returns

How many instances of the function were removed


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.

Parameters

data

user data of the log function to remove

 

Returns

How many instances of the function were removed


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.

Parameters

active

Whether to use debugging output or not

 

gst_debug_is_active ()

gboolean
gst_debug_is_active (void);

Checks if debugging output is activated.

Returns

TRUE, if debugging 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().

Parameters

colored

Whether to use colored output or not

 

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().

Parameters

mode

The coloring mode for debug output. See GstDebugColorMode .

 

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.

Returns

TRUE, if the debug output should be colored.


gst_debug_get_color_mode ()

GstDebugColorMode
gst_debug_get_color_mode (void);

Changes the coloring mode for debug output.

Returns

see GstDebugColorMode for possible values.

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().

Parameters

level

level to set

 

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.

Parameters

list

comma-separated list of "category:level" pairs to be used as debug logging levels

 

reset

TRUE to clear all previously-set debug levels before setting new thresholds FALSE if adding the threshold described by list to the one already set.

 

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.

Returns

the default threshold level


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.

Parameters

name

name of the categories to set

 

level

level to set them to

 

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.

Parameters

name

name of the categories to set

 

GST_DEBUG_CATEGORY()

#define GST_DEBUG_CATEGORY(cat) GstDebugCategory *cat = NULL

Defines a GstDebugCategory variable. This macro expands to nothing if debugging is disabled.

Parameters

cat

the category

 

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.

Parameters

cat

the category

 

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.

Parameters

cat

the category

 

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.

Parameters

cat

the category to initialize.

 

name

the name of the category.

 

color

the colors to use for a color representation or 0 for no color.

 

description

optional description of the category.

 

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");

Parameters

cat

the category to initialize.

 

name

log category name

 

gst_debug_category_free ()

void
gst_debug_category_free (GstDebugCategory *category);

Removes and frees the category and all associated resources.

Parameters

category

GstDebugCategory to free.

 

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().

Parameters

category

a GstDebugCategory to reset threshold of.

 

gst_debug_category_get_threshold ()

GstDebugLevel
gst_debug_category_get_threshold (GstDebugCategory *category);

Returns the threshold of a GstDebugCategory.

Parameters

category

a GstDebugCategory to get threshold of.

 

Returns

the GstDebugLevel that is used as threshold.


gst_debug_category_get_name ()

const gchar *
gst_debug_category_get_name (GstDebugCategory *category);

Returns the name of a debug category.

Parameters

category

a GstDebugCategory to get name of.

 

Returns

the name of the 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.

Parameters

category

a GstDebugCategory to get the color of.

 

Returns

the color of the category.


gst_debug_category_get_description ()

const gchar *
gst_debug_category_get_description (GstDebugCategory *category);

Returns the description of a debug category.

Parameters

category

a GstDebugCategory to get the description of.

 

Returns

the description of the 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.

Returns

the list of debug categories.

[transfer container][element-type Gst.DebugCategory]


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.

Parameters

colorinfo

the color info

 

Returns

a string containing the color definition.

[transfer full][type gchar*]


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.

Parameters

colorinfo

the color info

 

Returns

an integer containing the color definition


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.

Parameters

cat

category to use

 

level

the severity of the message

 

object

the GObject the message belongs to or NULL if none.

[allow-none]

...

A printf-style message to output

 

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.

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.

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.

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.

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.

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.

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.

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.

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.

Parameters

cat

category to use

 

...

printf-style message to output

 

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.

Parameters

cat

category to use

 

...

printf-style message to output

 

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.

Parameters

cat

category to use

 

...

printf-style message to output

 

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.

Parameters

cat

category to use

 

...

printf-style message to output

 

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.

Parameters

cat

category to use

 

...

printf-style message to output

 

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.

Parameters

cat

category to use

 

...

printf-style message to output

 

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.

Parameters

cat

category to use

 

...

printf-style message to output

 

GST_CAT_MEMDUMP()

#define             GST_CAT_MEMDUMP(cat,msg,data,length)

Output a hexdump of data in the given category.

Parameters

cat

category to use

 

msg

message string to log with the data

 

data

pointer to the data to output

 

length

length of the data to output

 

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.

Parameters

obj

the GObject the message belongs to

 

...

printf-style message to output

 

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.

Parameters

obj

the GObject the message belongs to

 

...

printf-style message to output

 

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.

Parameters

obj

the GObject the message belongs to

 

...

printf-style message to output

 

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.

Parameters

obj

the GObject the message belongs to

 

...

printf-style message to output

 

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.

Parameters

obj

the GObject the message belongs to

 

...

printf-style message to output

 

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.

Parameters

obj

the GObject the message belongs to

 

...

printf-style message to output

 

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.

Parameters

obj

the GObject the message belongs to

 

...

printf-style message to output

 

GST_MEMDUMP_OBJECT()

#define             GST_MEMDUMP_OBJECT(obj,msg,data,length)

Output a logging message belonging to the given object in the default category.

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.

Parameters

...

printf-style message to output

 

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.

Parameters

...

printf-style message to output

 

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.

Parameters

...

printf-style message to output

 

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.

Parameters

...

printf-style message to output

 

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.

Parameters

...

printf-style message to output

 

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.

Parameters

...

printf-style message to output

 

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.

Parameters

...

printf-style message to output

 

GST_MEMDUMP()

#define             GST_MEMDUMP(msg,data,length)

Output a hexdump of data .

Parameters

msg

message string to log with the data

 

data

pointer to the data to output

 

length

length of the data to output

 

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 .

Parameters

ptr

pointer to the function to register

 

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().

Parameters

ptr

pointer to the function to register

 

Returns

the value passed to ptr .


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.

Parameters

ptr

address of the function of which to look up the name

 

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.

1
dot -Tpng -oimage.png graph_lowlevel.dot

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 GST_ENABLE_FUNC_INSTRUMENTATION is defined a stacktrace is available for gstreamer code, which can be printed with this function.


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.

Parameters

t

a GstClockTime

 

gst_debug_bin_to_dot_file ()

void
gst_debug_bin_to_dot_file (GstBin *bin,
                           GstDebugGraphDetails details,
                           const gchar *file_name);

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);

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

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 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.

 

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_FIXME

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.

 

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, 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.

 

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 anything else but LOG messages. Use this log level to log recurring information in chain functions and loop functions, for example.

 

GST_LEVEL_TRACE

Tracing-related messages. Examples for this are referencing/dereferencing of objects.

 

GST_LEVEL_MEMDUMP

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.

 

GST_LEVEL_COUNT

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.


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

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.

 

enum GstDebugColorMode

Members

GST_DEBUG_COLOR_MODE_OFF

Do not use colors in logs.

 

GST_DEBUG_COLOR_MODE_ON

Paint logs in a platform-specific way.

 

GST_DEBUG_COLOR_MODE_UNIX

Paint logs with UNIX terminal color codes no matter what platform GStreamer is running on.

 

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

GST_DEBUG_GRAPH_SHOW_MEDIA_TYPE

show caps-name on edges

 

GST_DEBUG_GRAPH_SHOW_CAPS_DETAILS

show caps-details on edges

 

GST_DEBUG_GRAPH_SHOW_NON_DEFAULT_PARAMS

show modified parameters on elements

 

GST_DEBUG_GRAPH_SHOW_STATES

show element states

 

GST_DEBUG_GRAPH_SHOW_ALL

show all details

 

GST_CAT_DEFAULT

GST_EXPORT 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));

See Also

gstreamer-gstconfig, gstreamer-Gst for command line parameters and environment variables that affect the debugging output.