1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Debug;
26 
27 private import glib.ListSG;
28 private import glib.Str;
29 private import glib.c.functions;
30 private import gobject.ObjectG;
31 private import gstreamer.Bin;
32 private import gstreamer.DebugCategory;
33 private import gstreamer.c.functions;
34 public  import gstreamer.c.types;
35 
36 
37 /** */
38 public struct Debug
39 {
40 
41 	/**
42 	 * Adds the logging function to the list of logging functions.
43 	 * Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed.
44 	 *
45 	 * Params:
46 	 *     func = the function to use
47 	 *     userData = user data
48 	 *     notify = called when @user_data is not used anymore
49 	 */
50 	public static void addLogFunction(GstLogFunction func, void* userData, GDestroyNotify notify)
51 	{
52 		gst_debug_add_log_function(func, userData, notify);
53 	}
54 
55 	/**
56 	 * To aid debugging applications one can use this method to obtain the whole
57 	 * network of gstreamer elements that form the pipeline into an dot file.
58 	 * This data can be processed with graphviz to get an image.
59 	 *
60 	 * Params:
61 	 *     bin = the top-level pipeline that should be analyzed
62 	 *     details = type of #GstDebugGraphDetails to use
63 	 *
64 	 * Returns: a string containing the pipeline in graphviz
65 	 *     dot format.
66 	 */
67 	public static string binToDotData(Bin bin, GstDebugGraphDetails details)
68 	{
69 		auto retStr = gst_debug_bin_to_dot_data((bin is null) ? null : bin.getBinStruct(), details);
70 
71 		scope(exit) Str.freeString(retStr);
72 		return Str.toString(retStr);
73 	}
74 
75 	/**
76 	 * To aid debugging applications one can use this method to write out the whole
77 	 * network of gstreamer elements that form the pipeline into an dot file.
78 	 * This file can be processed with graphviz to get an image.
79 	 *
80 	 * ``` shell
81 	 * dot -Tpng -oimage.png graph_lowlevel.dot
82 	 * ```
83 	 *
84 	 * Params:
85 	 *     bin = the top-level pipeline that should be analyzed
86 	 *     details = type of #GstDebugGraphDetails to use
87 	 *     fileName = output base filename (e.g. "myplayer")
88 	 */
89 	public static void binToDotFile(Bin bin, GstDebugGraphDetails details, string fileName)
90 	{
91 		gst_debug_bin_to_dot_file((bin is null) ? null : bin.getBinStruct(), details, Str.toStringz(fileName));
92 	}
93 
94 	/**
95 	 * This works like gst_debug_bin_to_dot_file(), but adds the current timestamp
96 	 * to the filename, so that it can be used to take multiple snapshots.
97 	 *
98 	 * Params:
99 	 *     bin = the top-level pipeline that should be analyzed
100 	 *     details = type of #GstDebugGraphDetails to use
101 	 *     fileName = output base filename (e.g. "myplayer")
102 	 */
103 	public static void binToDotFileWithTs(Bin bin, GstDebugGraphDetails details, string fileName)
104 	{
105 		gst_debug_bin_to_dot_file_with_ts((bin is null) ? null : bin.getBinStruct(), details, Str.toStringz(fileName));
106 	}
107 
108 	/**
109 	 * Constructs a string that can be used for getting the desired color in color
110 	 * terminals.
111 	 * You need to free the string after use.
112 	 *
113 	 * Params:
114 	 *     colorinfo = the color info
115 	 *
116 	 * Returns: a string containing the color
117 	 *     definition
118 	 */
119 	public static string constructTermColor(uint colorinfo)
120 	{
121 		auto retStr = gst_debug_construct_term_color(colorinfo);
122 
123 		scope(exit) Str.freeString(retStr);
124 		return Str.toString(retStr);
125 	}
126 
127 	/**
128 	 * Constructs an integer that can be used for getting the desired color in
129 	 * windows' terminals (cmd.exe). As there is no mean to underline, we simply
130 	 * ignore this attribute.
131 	 *
132 	 * This function returns 0 on non-windows machines.
133 	 *
134 	 * Params:
135 	 *     colorinfo = the color info
136 	 *
137 	 * Returns: an integer containing the color definition
138 	 */
139 	public static int constructWinColor(uint colorinfo)
140 	{
141 		return gst_debug_construct_win_color(colorinfo);
142 	}
143 
144 	/**
145 	 * Returns a snapshot of a all categories that are currently in use . This list
146 	 * may change anytime.
147 	 * The caller has to free the list after use.
148 	 *
149 	 * Returns: the list of
150 	 *     debug categories
151 	 */
152 	public static ListSG getAllCategories()
153 	{
154 		auto __p = gst_debug_get_all_categories();
155 
156 		if(__p is null)
157 		{
158 			return null;
159 		}
160 
161 		return new ListSG(cast(GSList*) __p);
162 	}
163 
164 	/**
165 	 * Changes the coloring mode for debug output.
166 	 *
167 	 * Returns: see @GstDebugColorMode for possible values.
168 	 *
169 	 * Since: 1.2
170 	 */
171 	public static GstDebugColorMode getColorMode()
172 	{
173 		return gst_debug_get_color_mode();
174 	}
175 
176 	/**
177 	 * Returns the default threshold that is used for new categories.
178 	 *
179 	 * Returns: the default threshold level
180 	 */
181 	public static GstDebugLevel getDefaultThreshold()
182 	{
183 		return gst_debug_get_default_threshold();
184 	}
185 
186 	/**
187 	 * Checks if debugging output is activated.
188 	 *
189 	 * Returns: %TRUE, if debugging is activated
190 	 */
191 	public static bool isActive()
192 	{
193 		return gst_debug_is_active() != 0;
194 	}
195 
196 	/**
197 	 * Checks if the debugging output should be colored.
198 	 *
199 	 * Returns: %TRUE, if the debug output should be colored.
200 	 */
201 	public static bool isColored()
202 	{
203 		return gst_debug_is_colored() != 0;
204 	}
205 
206 	/**
207 	 * Get the string representation of a debugging level
208 	 *
209 	 * Params:
210 	 *     level = the level to get the name for
211 	 *
212 	 * Returns: the name
213 	 */
214 	public static string levelGetName(GstDebugLevel level)
215 	{
216 		return Str.toString(gst_debug_level_get_name(level));
217 	}
218 
219 	/**
220 	 * The default logging handler used by GStreamer. Logging functions get called
221 	 * whenever a macro like GST_DEBUG or similar is used. By default this function
222 	 * is setup to output the message and additional info to stderr (or the log file
223 	 * specified via the GST_DEBUG_FILE environment variable) as received via
224 	 * @user_data.
225 	 *
226 	 * You can add other handlers by using gst_debug_add_log_function().
227 	 * And you can remove this handler by calling
228 	 * gst_debug_remove_log_function(gst_debug_log_default);
229 	 *
230 	 * Params:
231 	 *     category = category to log
232 	 *     level = level of the message
233 	 *     file = the file that emitted the message, usually the __FILE__ identifier
234 	 *     function_ = the function that emitted the message
235 	 *     line = the line from that the message was emitted, usually __LINE__
236 	 *     object = the object this message relates to,
237 	 *         or %NULL if none
238 	 *     message = the actual message
239 	 *     userData = the FILE* to log to
240 	 */
241 	public static void logDefault(DebugCategory category, GstDebugLevel level, string file, string function_, int line, ObjectG object, GstDebugMessage* message, void* userData)
242 	{
243 		gst_debug_log_default((category is null) ? null : category.getDebugCategoryStruct(), level, Str.toStringz(file), Str.toStringz(function_), line, (object is null) ? null : object.getObjectGStruct(), message, userData);
244 	}
245 
246 	/**
247 	 * Logs the given message using the currently registered debugging handlers.
248 	 *
249 	 * Params:
250 	 *     category = category to log
251 	 *     level = level of the message is in
252 	 *     file = the file that emitted the message, usually the __FILE__ identifier
253 	 *     function_ = the function that emitted the message
254 	 *     line = the line from that the message was emitted, usually __LINE__
255 	 *     object = the object this message relates to,
256 	 *         or %NULL if none
257 	 *     format = a printf style format string
258 	 *     args = optional arguments for the format
259 	 */
260 	public static void logValist(DebugCategory category, GstDebugLevel level, string file, string function_, int line, ObjectG object, string format, void* args)
261 	{
262 		gst_debug_log_valist((category is null) ? null : category.getDebugCategoryStruct(), level, Str.toStringz(file), Str.toStringz(function_), line, (object is null) ? null : object.getObjectGStruct(), Str.toStringz(format), args);
263 	}
264 
265 	/**
266 	 * If libunwind, glibc backtrace or DbgHelp are present
267 	 * a stack trace is printed.
268 	 */
269 	public static void printStackTrace()
270 	{
271 		gst_debug_print_stack_trace();
272 	}
273 
274 	/**
275 	 * Removes all registered instances of the given logging functions.
276 	 *
277 	 * Params:
278 	 *     func = the log function to remove, or %NULL to
279 	 *         remove the default log function
280 	 *
281 	 * Returns: How many instances of the function were removed
282 	 */
283 	public static uint removeLogFunction(GstLogFunction func)
284 	{
285 		return gst_debug_remove_log_function(func);
286 	}
287 
288 	/**
289 	 * Removes all registered instances of log functions with the given user data.
290 	 *
291 	 * Params:
292 	 *     data = user data of the log function to remove
293 	 *
294 	 * Returns: How many instances of the function were removed
295 	 */
296 	public static uint removeLogFunctionByData(void* data)
297 	{
298 		return gst_debug_remove_log_function_by_data(data);
299 	}
300 
301 	/**
302 	 * If activated, debugging messages are sent to the debugging
303 	 * handlers.
304 	 * It makes sense to deactivate it for speed issues.
305 	 * > This function is not threadsafe. It makes sense to only call it
306 	 * during initialization.
307 	 *
308 	 * Params:
309 	 *     active = Whether to use debugging output or not
310 	 */
311 	public static void setActive(bool active)
312 	{
313 		gst_debug_set_active(active);
314 	}
315 
316 	/**
317 	 * Changes the coloring mode for debug output.
318 	 *
319 	 * This function may be called before gst_init().
320 	 *
321 	 * Params:
322 	 *     mode = The coloring mode for debug output. See @GstDebugColorMode.
323 	 *
324 	 * Since: 1.2
325 	 */
326 	public static void setColorMode(GstDebugColorMode mode)
327 	{
328 		gst_debug_set_color_mode(mode);
329 	}
330 
331 	/**
332 	 * Changes the coloring mode for debug output.
333 	 *
334 	 * This function may be called before gst_init().
335 	 *
336 	 * Params:
337 	 *     mode = The coloring mode for debug output. One of the following:
338 	 *         "on", "auto", "off", "disable", "unix".
339 	 *
340 	 * Since: 1.2
341 	 */
342 	public static void setColorModeFromString(string mode)
343 	{
344 		gst_debug_set_color_mode_from_string(Str.toStringz(mode));
345 	}
346 
347 	/**
348 	 * Sets or unsets the use of coloured debugging output.
349 	 * Same as gst_debug_set_color_mode () with the argument being
350 	 * being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF.
351 	 *
352 	 * This function may be called before gst_init().
353 	 *
354 	 * Params:
355 	 *     colored = Whether to use colored output or not
356 	 */
357 	public static void setColored(bool colored)
358 	{
359 		gst_debug_set_colored(colored);
360 	}
361 
362 	/**
363 	 * Sets the default threshold to the given level and updates all categories to
364 	 * use this threshold.
365 	 *
366 	 * This function may be called before gst_init().
367 	 *
368 	 * Params:
369 	 *     level = level to set
370 	 */
371 	public static void setDefaultThreshold(GstDebugLevel level)
372 	{
373 		gst_debug_set_default_threshold(level);
374 	}
375 
376 	/**
377 	 * Sets all categories which match the given glob style pattern to the given
378 	 * level.
379 	 *
380 	 * Params:
381 	 *     name = name of the categories to set
382 	 *     level = level to set them to
383 	 */
384 	public static void setThresholdForName(string name, GstDebugLevel level)
385 	{
386 		gst_debug_set_threshold_for_name(Str.toStringz(name), level);
387 	}
388 
389 	/**
390 	 * Sets the debug logging wanted in the same form as with the GST_DEBUG
391 	 * environment variable. You can use wildcards such as '*', but note that
392 	 * the order matters when you use wild cards, e.g. "foosrc:6,*src:3,*:2" sets
393 	 * everything to log level 2.
394 	 *
395 	 * Params:
396 	 *     list = comma-separated list of "category:level" pairs to be used
397 	 *         as debug logging levels
398 	 *     reset = %TRUE to clear all previously-set debug levels before setting
399 	 *         new thresholds
400 	 *         %FALSE if adding the threshold described by @list to the one already set.
401 	 *
402 	 * Since: 1.2
403 	 */
404 	public static void setThresholdFromString(string list, bool reset)
405 	{
406 		gst_debug_set_threshold_from_string(Str.toStringz(list), reset);
407 	}
408 
409 	/**
410 	 * Resets all categories with the given name back to the default level.
411 	 *
412 	 * Params:
413 	 *     name = name of the categories to set
414 	 */
415 	public static void unsetThresholdForName(string name)
416 	{
417 		gst_debug_unset_threshold_for_name(Str.toStringz(name));
418 	}
419 }