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.Utils;
26 
27 private import glib.MemorySlice;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Value;
31 private import gobject.ValueArray;
32 private import gstreamer.Plugin;
33 private import gstreamer.c.functions;
34 public  import gstreamer.c.types;
35 public  import gstreamerc.gstreamertypes;
36 
37 
38 /** */
39 public struct Utils
40 {
41 
42 	/**
43 	 * Searches inside @array for @search_data by using the comparison function
44 	 * @search_func. @array must be sorted ascending.
45 	 *
46 	 * As @search_data is always passed as second argument to @search_func it's
47 	 * not required that @search_data has the same type as the array elements.
48 	 *
49 	 * The complexity of this search function is O(log (num_elements)).
50 	 *
51 	 * Params:
52 	 *     array = the sorted input array
53 	 *     numElements = number of elements in the array
54 	 *     elementSize = size of every element in bytes
55 	 *     searchFunc = function to compare two elements, @search_data will always be passed as second argument
56 	 *     mode = search mode that should be used
57 	 *     searchData = element that should be found
58 	 *     userData = data to pass to @search_func
59 	 *
60 	 * Returns: The address of the found
61 	 *     element or %NULL if nothing was found
62 	 */
63 	public static void* arrayBinarySearch(void* array, uint numElements, size_t elementSize, GCompareDataFunc searchFunc, GstSearchMode mode, void* searchData, void* userData)
64 	{
65 		return gst_util_array_binary_search(array, numElements, elementSize, searchFunc, mode, searchData, userData);
66 	}
67 
68 	/**
69 	 * Transforms a #gdouble to a fraction and simplifies
70 	 * the result.
71 	 *
72 	 * Params:
73 	 *     src = #gdouble to transform
74 	 *     destN = pointer to a #gint to hold the result numerator
75 	 *     destD = pointer to a #gint to hold the result denominator
76 	 */
77 	public static void doubleToFraction(double src, out int destN, out int destD)
78 	{
79 		gst_util_double_to_fraction(src, &destN, &destD);
80 	}
81 
82 	/**
83 	 * Dumps the memory block into a hex representation. Useful for debugging.
84 	 *
85 	 * Params:
86 	 *     mem = a pointer to the memory to dump
87 	 *     size = the size of the memory block to dump
88 	 */
89 	public static void dumpMem(char* mem, uint size)
90 	{
91 		gst_util_dump_mem(mem, size);
92 	}
93 
94 	/**
95 	 * Adds the fractions @a_n/@a_d and @b_n/@b_d and stores
96 	 * the result in @res_n and @res_d.
97 	 *
98 	 * Params:
99 	 *     aN = Numerator of first value
100 	 *     aD = Denominator of first value
101 	 *     bN = Numerator of second value
102 	 *     bD = Denominator of second value
103 	 *     resN = Pointer to #gint to hold the result numerator
104 	 *     resD = Pointer to #gint to hold the result denominator
105 	 *
106 	 * Returns: %FALSE on overflow, %TRUE otherwise.
107 	 */
108 	public static bool fractionAdd(int aN, int aD, int bN, int bD, out int resN, out int resD)
109 	{
110 		return gst_util_fraction_add(aN, aD, bN, bD, &resN, &resD) != 0;
111 	}
112 
113 	/**
114 	 * Compares the fractions @a_n/@a_d and @b_n/@b_d and returns
115 	 * -1 if a < b, 0 if a = b and 1 if a > b.
116 	 *
117 	 * Params:
118 	 *     aN = Numerator of first value
119 	 *     aD = Denominator of first value
120 	 *     bN = Numerator of second value
121 	 *     bD = Denominator of second value
122 	 *
123 	 * Returns: -1 if a < b; 0 if a = b; 1 if a > b.
124 	 */
125 	public static int fractionCompare(int aN, int aD, int bN, int bD)
126 	{
127 		return gst_util_fraction_compare(aN, aD, bN, bD);
128 	}
129 
130 	/**
131 	 * Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores
132 	 * the result in @res_n and @res_d.
133 	 *
134 	 * Params:
135 	 *     aN = Numerator of first value
136 	 *     aD = Denominator of first value
137 	 *     bN = Numerator of second value
138 	 *     bD = Denominator of second value
139 	 *     resN = Pointer to #gint to hold the result numerator
140 	 *     resD = Pointer to #gint to hold the result denominator
141 	 *
142 	 * Returns: %FALSE on overflow, %TRUE otherwise.
143 	 */
144 	public static bool fractionMultiply(int aN, int aD, int bN, int bD, out int resN, out int resD)
145 	{
146 		return gst_util_fraction_multiply(aN, aD, bN, bD, &resN, &resD) != 0;
147 	}
148 
149 	/**
150 	 * Transforms a fraction to a #gdouble.
151 	 *
152 	 * Params:
153 	 *     srcN = Fraction numerator as #gint
154 	 *     srcD = Fraction denominator #gint
155 	 *     dest = pointer to a #gdouble for the result
156 	 */
157 	public static void fractionToDouble(int srcN, int srcD, out double dest)
158 	{
159 		gst_util_fraction_to_double(srcN, srcD, &dest);
160 	}
161 
162 	/** */
163 	public static ulong gdoubleToGuint64(double value)
164 	{
165 		return gst_util_gdouble_to_guint64(value);
166 	}
167 
168 	/**
169 	 * Get a timestamp as GstClockTime to be used for interval measurements.
170 	 * The timestamp should not be interpreted in any other way.
171 	 *
172 	 * Returns: the timestamp
173 	 */
174 	public static GstClockTime getTimestamp()
175 	{
176 		return gst_util_get_timestamp();
177 	}
178 
179 	/**
180 	 * Calculates the greatest common divisor of @a
181 	 * and @b.
182 	 *
183 	 * Params:
184 	 *     a = First value as #gint
185 	 *     b = Second value as #gint
186 	 *
187 	 * Returns: Greatest common divisor of @a and @b
188 	 */
189 	public static int greatestCommonDivisor(int a, int b)
190 	{
191 		return gst_util_greatest_common_divisor(a, b);
192 	}
193 
194 	/**
195 	 * Calculates the greatest common divisor of @a
196 	 * and @b.
197 	 *
198 	 * Params:
199 	 *     a = First value as #gint64
200 	 *     b = Second value as #gint64
201 	 *
202 	 * Returns: Greatest common divisor of @a and @b
203 	 */
204 	public static long greatestCommonDivisorInt64(long a, long b)
205 	{
206 		return gst_util_greatest_common_divisor_int64(a, b);
207 	}
208 
209 	/**
210 	 * Return a constantly incrementing group id.
211 	 *
212 	 * This function is used to generate a new group-id for the
213 	 * stream-start event.
214 	 *
215 	 * Returns: A constantly incrementing unsigned integer, which might
216 	 *     overflow back to 0 at some point.
217 	 */
218 	public static uint groupIdNext()
219 	{
220 		return gst_util_group_id_next();
221 	}
222 
223 	/** */
224 	public static double guint64ToGdouble(ulong value)
225 	{
226 		return gst_util_guint64_to_gdouble(value);
227 	}
228 
229 	/**
230 	 * Compare two sequence numbers, handling wraparound.
231 	 *
232 	 * The current implementation just returns (gint32)(@s1 - @s2).
233 	 *
234 	 * Params:
235 	 *     s1 = A sequence number.
236 	 *     s2 = Another sequence number.
237 	 *
238 	 * Returns: A negative number if @s1 is before @s2, 0 if they are equal, or a
239 	 *     positive number if @s1 is after @s2.
240 	 */
241 	public static int seqnumCompare(uint s1, uint s2)
242 	{
243 		return gst_util_seqnum_compare(s1, s2);
244 	}
245 
246 	/**
247 	 * Return a constantly incrementing sequence number.
248 	 *
249 	 * This function is used internally to GStreamer to be able to determine which
250 	 * events and messages are "the same". For example, elements may set the seqnum
251 	 * on a segment-done message to be the same as that of the last seek event, to
252 	 * indicate that event and the message correspond to the same segment.
253 	 *
254 	 * Returns: A constantly incrementing 32-bit unsigned integer, which might
255 	 *     overflow back to 0 at some point. Use gst_util_seqnum_compare() to make sure
256 	 *     you handle wraparound correctly.
257 	 */
258 	public static uint seqnumNext()
259 	{
260 		return gst_util_seqnum_next();
261 	}
262 
263 	/**
264 	 * Converts the string value to the type of the objects argument and
265 	 * sets the argument with it.
266 	 *
267 	 * Note that this function silently returns if @object has no property named
268 	 * @name or when @value cannot be converted to the type of the property.
269 	 *
270 	 * Params:
271 	 *     object = the object to set the argument of
272 	 *     name = the name of the argument to set
273 	 *     value = the string value to set
274 	 */
275 	public static void setObjectArg(ObjectG object, string name, string value)
276 	{
277 		gst_util_set_object_arg((object is null) ? null : object.getObjectGStruct(), Str.toStringz(name), Str.toStringz(value));
278 	}
279 
280 	/**
281 	 * Converts the string to the type of the value and
282 	 * sets the value with it.
283 	 *
284 	 * Note that this function is dangerous as it does not return any indication
285 	 * if the conversion worked or not.
286 	 *
287 	 * Params:
288 	 *     value = the value to set
289 	 *     valueStr = the string to get the value from
290 	 */
291 	public static void setValueFromString(out Value value, string valueStr)
292 	{
293 		GValue* outvalue = sliceNew!GValue();
294 
295 		gst_util_set_value_from_string(outvalue, Str.toStringz(valueStr));
296 
297 		value = ObjectG.getDObject!(Value)(outvalue, true);
298 	}
299 
300 	/**
301 	 * Scale @val by the rational number @num / @denom, avoiding overflows and
302 	 * underflows and without loss of precision.
303 	 *
304 	 * This function can potentially be very slow if val and num are both
305 	 * greater than G_MAXUINT32.
306 	 *
307 	 * Params:
308 	 *     val = the number to scale
309 	 *     num = the numerator of the scale ratio
310 	 *     denom = the denominator of the scale ratio
311 	 *
312 	 * Returns: @val * @num / @denom.  In the case of an overflow, this
313 	 *     function returns G_MAXUINT64.  If the result is not exactly
314 	 *     representable as an integer it is truncated.  See also
315 	 *     gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(),
316 	 *     gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(),
317 	 *     gst_util_uint64_scale_int_ceil().
318 	 */
319 	public static ulong uint64Scale(ulong val, ulong num, ulong denom)
320 	{
321 		return gst_util_uint64_scale(val, num, denom);
322 	}
323 
324 	/**
325 	 * Scale @val by the rational number @num / @denom, avoiding overflows and
326 	 * underflows and without loss of precision.
327 	 *
328 	 * This function can potentially be very slow if val and num are both
329 	 * greater than G_MAXUINT32.
330 	 *
331 	 * Params:
332 	 *     val = the number to scale
333 	 *     num = the numerator of the scale ratio
334 	 *     denom = the denominator of the scale ratio
335 	 *
336 	 * Returns: @val * @num / @denom.  In the case of an overflow, this
337 	 *     function returns G_MAXUINT64.  If the result is not exactly
338 	 *     representable as an integer, it is rounded up.  See also
339 	 *     gst_util_uint64_scale(), gst_util_uint64_scale_round(),
340 	 *     gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(),
341 	 *     gst_util_uint64_scale_int_ceil().
342 	 */
343 	public static ulong uint64ScaleCeil(ulong val, ulong num, ulong denom)
344 	{
345 		return gst_util_uint64_scale_ceil(val, num, denom);
346 	}
347 
348 	/**
349 	 * Scale @val by the rational number @num / @denom, avoiding overflows and
350 	 * underflows and without loss of precision.  @num must be non-negative and
351 	 * @denom must be positive.
352 	 *
353 	 * Params:
354 	 *     val = guint64 (such as a #GstClockTime) to scale.
355 	 *     num = numerator of the scale factor.
356 	 *     denom = denominator of the scale factor.
357 	 *
358 	 * Returns: @val * @num / @denom.  In the case of an overflow, this
359 	 *     function returns G_MAXUINT64.  If the result is not exactly
360 	 *     representable as an integer, it is truncated.  See also
361 	 *     gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(),
362 	 *     gst_util_uint64_scale(), gst_util_uint64_scale_round(),
363 	 *     gst_util_uint64_scale_ceil().
364 	 */
365 	public static ulong uint64ScaleInt(ulong val, int num, int denom)
366 	{
367 		return gst_util_uint64_scale_int(val, num, denom);
368 	}
369 
370 	/**
371 	 * Scale @val by the rational number @num / @denom, avoiding overflows and
372 	 * underflows and without loss of precision.  @num must be non-negative and
373 	 * @denom must be positive.
374 	 *
375 	 * Params:
376 	 *     val = guint64 (such as a #GstClockTime) to scale.
377 	 *     num = numerator of the scale factor.
378 	 *     denom = denominator of the scale factor.
379 	 *
380 	 * Returns: @val * @num / @denom.  In the case of an overflow, this
381 	 *     function returns G_MAXUINT64.  If the result is not exactly
382 	 *     representable as an integer, it is rounded up.  See also
383 	 *     gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(),
384 	 *     gst_util_uint64_scale(), gst_util_uint64_scale_round(),
385 	 *     gst_util_uint64_scale_ceil().
386 	 */
387 	public static ulong uint64ScaleIntCeil(ulong val, int num, int denom)
388 	{
389 		return gst_util_uint64_scale_int_ceil(val, num, denom);
390 	}
391 
392 	/**
393 	 * Scale @val by the rational number @num / @denom, avoiding overflows and
394 	 * underflows and without loss of precision.  @num must be non-negative and
395 	 * @denom must be positive.
396 	 *
397 	 * Params:
398 	 *     val = guint64 (such as a #GstClockTime) to scale.
399 	 *     num = numerator of the scale factor.
400 	 *     denom = denominator of the scale factor.
401 	 *
402 	 * Returns: @val * @num / @denom.  In the case of an overflow, this
403 	 *     function returns G_MAXUINT64.  If the result is not exactly
404 	 *     representable as an integer, it is rounded to the nearest integer
405 	 *     (half-way cases are rounded up).  See also gst_util_uint64_scale_int(),
406 	 *     gst_util_uint64_scale_int_ceil(), gst_util_uint64_scale(),
407 	 *     gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil().
408 	 */
409 	public static ulong uint64ScaleIntRound(ulong val, int num, int denom)
410 	{
411 		return gst_util_uint64_scale_int_round(val, num, denom);
412 	}
413 
414 	/**
415 	 * Scale @val by the rational number @num / @denom, avoiding overflows and
416 	 * underflows and without loss of precision.
417 	 *
418 	 * This function can potentially be very slow if val and num are both
419 	 * greater than G_MAXUINT32.
420 	 *
421 	 * Params:
422 	 *     val = the number to scale
423 	 *     num = the numerator of the scale ratio
424 	 *     denom = the denominator of the scale ratio
425 	 *
426 	 * Returns: @val * @num / @denom.  In the case of an overflow, this
427 	 *     function returns G_MAXUINT64.  If the result is not exactly
428 	 *     representable as an integer, it is rounded to the nearest integer
429 	 *     (half-way cases are rounded up).  See also gst_util_uint64_scale(),
430 	 *     gst_util_uint64_scale_ceil(), gst_util_uint64_scale_int(),
431 	 *     gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil().
432 	 */
433 	public static ulong uint64ScaleRound(ulong val, ulong num, ulong denom)
434 	{
435 		return gst_util_uint64_scale_round(val, num, denom);
436 	}
437 
438 	/**
439 	 * Calculates the linear regression of the values @xy and places the
440 	 * result in @m_num, @m_denom, @b and @xbase, representing the function
441 	 * y(x) = m_num/m_denom * (x - xbase) + b
442 	 * that has the least-square distance from all points @x and @y.
443 	 *
444 	 * @r_squared will contain the remaining error.
445 	 *
446 	 * If @temp is not %NULL, it will be used as temporary space for the function,
447 	 * in which case the function works without any allocation at all. If @temp is
448 	 * %NULL, an allocation will take place. @temp should have at least the same
449 	 * amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime).
450 	 *
451 	 * > This function assumes (x,y) values with reasonable large differences
452 	 * > between them. It will not calculate the exact results if the differences
453 	 * > between neighbouring values are too small due to not being able to
454 	 * > represent sub-integer values during the calculations.
455 	 *
456 	 * Params:
457 	 *     xy = Pairs of (x,y) values
458 	 *     temp = Temporary scratch space used by the function
459 	 *     n = number of (x,y) pairs
460 	 *     mNum = numerator of calculated slope
461 	 *     mDenom = denominator of calculated slope
462 	 *     b = Offset at Y-axis
463 	 *     xbase = Offset at X-axis
464 	 *     rSquared = R-squared
465 	 *
466 	 * Returns: %TRUE if the linear regression was successfully calculated
467 	 *
468 	 * Since: 1.12
469 	 */
470 	public static bool calculateLinearRegression(GstClockTime* xy, GstClockTime* temp, uint n, out GstClockTime mNum, out GstClockTime mDenom, out GstClockTime b, out GstClockTime xbase, out double rSquared)
471 	{
472 		return gst_calculate_linear_regression(xy, temp, n, &mNum, &mDenom, &b, &xbase, &rSquared) != 0;
473 	}
474 
475 	/** */
476 	public static bool dynamicTypeRegister(Plugin plugin, GType type)
477 	{
478 		return gst_dynamic_type_register((plugin is null) ? null : plugin.getPluginStruct(), type) != 0;
479 	}
480 
481 	/**
482 	 * Get a property of type %GST_TYPE_ARRAY and transform it into a
483 	 * #GValueArray. This allow language bindings to get GST_TYPE_ARRAY
484 	 * properties which are otherwise not an accessible type.
485 	 *
486 	 * Params:
487 	 *     object = the object to set the array to
488 	 *     name = the name of the property to set
489 	 *     array = a return #GValueArray
490 	 *
491 	 * Since: 1.12
492 	 */
493 	public static bool getObjectArray(ObjectG object, string name, out ValueArray array)
494 	{
495 		GValueArray* outarray = null;
496 
497 		auto p = gst_util_get_object_array((object is null) ? null : object.getObjectGStruct(), Str.toStringz(name), &outarray) != 0;
498 
499 		array = ObjectG.getDObject!(ValueArray)(outarray);
500 
501 		return p;
502 	}
503 
504 	/**
505 	 * Transfer a #GValueArray to %GST_TYPE_ARRAY and set this value on the
506 	 * specified property name. This allow language bindings to set GST_TYPE_ARRAY
507 	 * properties which are otherwise not an accessible type.
508 	 *
509 	 * Params:
510 	 *     object = the object to set the array to
511 	 *     name = the name of the property to set
512 	 *     array = a #GValueArray containing the values
513 	 *
514 	 * Since: 1.12
515 	 */
516 	public static bool setObjectArray(ObjectG object, string name, ValueArray array)
517 	{
518 		return gst_util_set_object_array((object is null) ? null : object.getObjectGStruct(), Str.toStringz(name), (array is null) ? null : array.getValueArrayStruct()) != 0;
519 	}
520 }