1 /* GStreamer 2 * Copyright (C) 2007 Stefan Kost <ensonic@users.sf.net> 3 * 4 * gstdebugutils.h: debugging and analysis utilities 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Library General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Library General Public License for more details. 15 * 16 * You should have received a copy of the GNU Library General Public 17 * License along with this library; if not, write to the 18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 19 * Boston, MA 02110-1301, USA. 20 */ 21 22 #ifndef __GSTDEBUGUTILS_H__ 23 #define __GSTDEBUGUTILS_H__ 24 25 #include <glib.h> 26 #include <glib-object.h> 27 #include <gst/gstconfig.h> 28 #include <gst/gstbin.h> 29 30 G_BEGIN_DECLS 31 32 /** 33 * GstDebugGraphDetails: 34 * @GST_DEBUG_GRAPH_SHOW_MEDIA_TYPE: show caps-name on edges 35 * @GST_DEBUG_GRAPH_SHOW_CAPS_DETAILS: show caps-details on edges 36 * @GST_DEBUG_GRAPH_SHOW_NON_DEFAULT_PARAMS: show modified parameters on 37 * elements 38 * @GST_DEBUG_GRAPH_SHOW_STATES: show element states 39 * @GST_DEBUG_GRAPH_SHOW_FULL_PARAMS: show full element parameter values even 40 * if they are very long 41 * @GST_DEBUG_GRAPH_SHOW_ALL: show all the typical details that one might want 42 * @GST_DEBUG_GRAPH_SHOW_VERBOSE: show all details regardless of how large or 43 * verbose they make the resulting output 44 * 45 * Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE() 46 * and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS(). 47 */ 48 /* FIXME: For GST_DEBUG_GRAPH_SHOW_VERBOSE ~0 -> 0xffffffff see 49 * https://bugzilla.gnome.org/show_bug.cgi?id=732633 50 */ 51 typedef enum { 52 GST_DEBUG_GRAPH_SHOW_MEDIA_TYPE = (1<<0), 53 GST_DEBUG_GRAPH_SHOW_CAPS_DETAILS = (1<<1), 54 GST_DEBUG_GRAPH_SHOW_NON_DEFAULT_PARAMS = (1<<2), 55 GST_DEBUG_GRAPH_SHOW_STATES = (1<<3), 56 GST_DEBUG_GRAPH_SHOW_FULL_PARAMS = (1<<4), 57 GST_DEBUG_GRAPH_SHOW_ALL = ((1<<4)-1), 58 GST_DEBUG_GRAPH_SHOW_VERBOSE = (gint) (0xffffffff) 59 } GstDebugGraphDetails; 60 61 62 /********** pipeline graphs **********/ 63 64 GST_API 65 gchar * gst_debug_bin_to_dot_data (GstBin *bin, GstDebugGraphDetails details); 66 67 GST_API 68 void gst_debug_bin_to_dot_file (GstBin *bin, GstDebugGraphDetails details, const gchar *file_name); 69 70 GST_API 71 void gst_debug_bin_to_dot_file_with_ts (GstBin *bin, GstDebugGraphDetails details, const gchar *file_name); 72 73 #ifndef GST_DISABLE_GST_DEBUG 74 75 /** 76 * GST_DEBUG_BIN_TO_DOT_FILE: 77 * @bin: the top-level pipeline that should be analyzed 78 * @details: details to show in the graph, e.g. #GST_DEBUG_GRAPH_SHOW_ALL or 79 * one or more other #GstDebugGraphDetails flags. 80 * @file_name: output base filename (e.g. "myplayer") 81 * 82 * To aid debugging applications one can use this method to write out the whole 83 * network of gstreamer elements that form the pipeline into a dot file. 84 * This file can be processed with graphviz to get an image, like this: 85 * 86 * ``` shell 87 * dot -Tpng -oimage.png graph_lowlevel.dot 88 * ``` 89 * 90 * There is also a utility called [xdot] which allows you to view the dot file 91 * directly without converting it first. 92 * 93 * The macro is only active if the environment variable `GST_DEBUG_DUMP_DOT_DIR` 94 * is set to a basepath (e.g. `/tmp`), and the GStreamer debugging subsystem is 95 * enabled (i.e., no use of `./configure --disable-gst-debug`) 96 * 97 * [xdot]: https://pypi.org/project/xdot/ 98 */ 99 #define GST_DEBUG_BIN_TO_DOT_FILE(bin, details, file_name) gst_debug_bin_to_dot_file (bin, details, file_name) 100 101 /** 102 * GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS: 103 * @bin: the top-level pipeline that should be analyzed 104 * @details: details to show in the graph, e.g. #GST_DEBUG_GRAPH_SHOW_ALL or 105 * one or more other #GstDebugGraphDetails flags. 106 * @file_name: output base filename (e.g. "myplayer") 107 * 108 * This works like GST_DEBUG_BIN_TO_DOT_FILE(), but adds the current timestamp 109 * to the filename, so that it can be used to take multiple snapshots. 110 */ 111 #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) 112 113 114 #else /* GST_DISABLE_GST_DEBUG */ 115 116 117 #define GST_DEBUG_BIN_TO_DOT_FILE(bin, details, file_name) 118 #define GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS(bin, details, file_name) 119 120 #endif /* GST_DISABLE_GST_DEBUG */ 121 122 G_END_DECLS 123 124 #endif /* __GSTDEBUGUTILS_H__ */ 125 126