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.Bin;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Signals;
31 private import gstreamer.ChildProxyIF;
32 private import gstreamer.ChildProxyT;
33 private import gstreamer.Element;
34 private import gstreamer.Iterator;
35 private import gstreamer.Pad;
36 private import gstreamer.c.functions;
37 public  import gstreamer.c.types;
38 public  import gstreamerc.gstreamertypes;
39 private import std.algorithm;
40 
41 
42 /**
43  * #GstBin is an element that can contain other #GstElement, allowing them to be
44  * managed as a group.
45  * Pads from the child elements can be ghosted to the bin, see #GstGhostPad.
46  * This makes the bin look like any other elements and enables creation of
47  * higher-level abstraction elements.
48  * 
49  * A new #GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you
50  * want to create a toplevel bin because a normal bin doesn't have a bus or
51  * handle clock distribution of its own.
52  * 
53  * After the bin has been created you will typically add elements to it with
54  * gst_bin_add(). You can remove elements with gst_bin_remove().
55  * 
56  * An element can be retrieved from a bin with gst_bin_get_by_name(), using the
57  * elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal
58  * purposes and will query the parent bins when the element is not found in the
59  * current bin.
60  * 
61  * An iterator of elements in a bin can be retrieved with
62  * gst_bin_iterate_elements(). Various other iterators exist to retrieve the
63  * elements in a bin.
64  * 
65  * gst_object_unref() is used to drop your reference to the bin.
66  * 
67  * The #GstBin::element-added signal is fired whenever a new element is added to
68  * the bin. Likewise the #GstBin::element-removed signal is fired whenever an
69  * element is removed from the bin.
70  * 
71  * ## Notes
72  * 
73  * A #GstBin internally intercepts every #GstMessage posted by its children and
74  * implements the following default behaviour for each of them:
75  * 
76  * * GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING
77  * state. If all sinks posted the EOS message, this bin will post and EOS
78  * message upwards.
79  * 
80  * * GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards.
81  * The messages are used to decide when all elements have completed playback
82  * of their segment.
83  * 
84  * * GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted
85  * a SEGMENT_START have posted a SEGMENT_DONE.
86  * 
87  * * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change
88  * in the stream duration. The default bin behaviour is to clear any
89  * cached duration values so that the next duration query will perform
90  * a full duration recalculation. The duration change is posted to the
91  * application so that it can refetch the new duration with a duration
92  * query. Note that these messages can be posted before the bin is
93  * prerolled, in which case the duration query might fail.
94  * 
95  * * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
96  * can no longer provide a clock. The default bin behaviour is to
97  * check if the lost clock was the one provided by the bin. If so and
98  * the bin is currently in the PLAYING state, the message is forwarded to
99  * the bin parent.
100  * This message is also generated when a clock provider is removed from
101  * the bin. If this message is received by the application, it should
102  * PAUSE the pipeline and set it back to PLAYING to force a new clock
103  * distribution.
104  * 
105  * * GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element
106  * can provide a clock. This mostly happens when a new clock
107  * provider is added to the bin. The default behaviour of the bin is to
108  * mark the currently selected clock as dirty, which will perform a clock
109  * recalculation the next time the bin is asked to provide a clock.
110  * This message is never sent tot the application but is forwarded to
111  * the parent of the bin.
112  * 
113  * * OTHERS: posted upwards.
114  * 
115  * A #GstBin implements the following default behaviour for answering to a
116  * #GstQuery:
117  * 
118  * * GST_QUERY_DURATION:If the query has been asked before with the same format
119  * and the bin is a toplevel bin (ie. has no parent),
120  * use the cached previous value. If no previous value was cached, the
121  * query is sent to all sink elements in the bin and the MAXIMUM of all
122  * values is returned. If the bin is a toplevel bin the value is cached.
123  * If no sinks are available in the bin, the query fails.
124  * 
125  * * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the
126  * MAXIMUM of all values is returned. If no sinks are available in the bin,
127  * the query fails.
128  * 
129  * * OTHERS:the query is forwarded to all sink elements, the result
130  * of the first sink that answers the query successfully is returned. If no
131  * sink is in the bin, the query fails.
132  * 
133  * A #GstBin will by default forward any event sent to it to all sink
134  * (#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements
135  * depending on the event type.
136  * If all the elements return %TRUE, the bin will also return %TRUE, else %FALSE
137  * is returned. If no elements of the required type are in the bin, the event
138  * handler will return %TRUE.
139  */
140 public class Bin : Element, ChildProxyIF
141 {
142 	/** the main Gtk struct */
143 	protected GstBin* gstBin;
144 
145 	/** Get the main Gtk struct */
146 	public GstBin* getBinStruct(bool transferOwnership = false)
147 	{
148 		if (transferOwnership)
149 			ownedRef = false;
150 		return gstBin;
151 	}
152 
153 	/** the main Gtk struct as a void* */
154 	protected override void* getStruct()
155 	{
156 		return cast(void*)gstBin;
157 	}
158 
159 	/**
160 	 * Sets our main struct and passes it to the parent class.
161 	 */
162 	public this (GstBin* gstBin, bool ownedRef = false)
163 	{
164 		this.gstBin = gstBin;
165 		super(cast(GstElement*)gstBin, ownedRef);
166 	}
167 
168 	// add the ChildProxy capabilities
169 	mixin ChildProxyT!(GstBin);
170 
171 	/** */
172 	public this(Element elem)
173 	{
174 		super( elem.getElementStruct(), true );
175 		this.gstBin = cast(GstBin*)elem.getElementStruct();
176 	}
177 
178 	/**
179 	 * Adds a list of elements to a bin.
180 	 * This function is equivalent to calling add() for each member of the list.
181 	 * The return value of each add() is ignored.
182 	 */
183 	public void addMany( Element[] elems... )
184 	{
185 		foreach( e; elems ) add( e );
186 	}
187 
188 	/**
189 	 * Remove a list of elements from a bin.
190 	 * This function is equivalent to calling remove() with each member of the list.
191 	 */
192 	public void removeMany( Element[] elems... )
193 	{
194 		foreach( e; elems ) remove( e );
195 	}
196 
197 	/**
198 	 */
199 
200 	/** */
201 	public static GType getType()
202 	{
203 		return gst_bin_get_type();
204 	}
205 
206 	/**
207 	 * Creates a new bin with the given name.
208 	 *
209 	 * Params:
210 	 *     name = the name of the new bin
211 	 *
212 	 * Returns: a new #GstBin
213 	 *
214 	 * Throws: ConstructionException GTK+ fails to create the object.
215 	 */
216 	public this(string name)
217 	{
218 		auto p = gst_bin_new(Str.toStringz(name));
219 
220 		if(p is null)
221 		{
222 			throw new ConstructionException("null returned by new");
223 		}
224 
225 		this(cast(GstBin*) p);
226 	}
227 
228 	/**
229 	 * Adds the given element to the bin.  Sets the element's parent, and thus
230 	 * takes ownership of the element. An element can only be added to one bin.
231 	 *
232 	 * If the element's pads are linked to other pads, the pads will be unlinked
233 	 * before the element is added to the bin.
234 	 *
235 	 * > When you add an element to an already-running pipeline, you will have to
236 	 * > take care to set the state of the newly-added element to the desired
237 	 * > state (usually PLAYING or PAUSED, same you set the pipeline to originally)
238 	 * > with gst_element_set_state(), or use gst_element_sync_state_with_parent().
239 	 * > The bin or pipeline will not take care of this for you.
240 	 *
241 	 * MT safe.
242 	 *
243 	 * Params:
244 	 *     element = the #GstElement to add
245 	 *
246 	 * Returns: %TRUE if the element could be added, %FALSE if
247 	 *     the bin does not want to accept the element.
248 	 */
249 	public bool add(Element element)
250 	{
251 		return gst_bin_add(gstBin, (element is null) ? null : element.getElementStruct()) != 0;
252 	}
253 
254 	/**
255 	 * Recursively looks for elements with an unlinked pad of the given
256 	 * direction within the specified bin and returns an unlinked pad
257 	 * if one is found, or %NULL otherwise. If a pad is found, the caller
258 	 * owns a reference to it and should use gst_object_unref() on the
259 	 * pad when it is not needed any longer.
260 	 *
261 	 * Params:
262 	 *     direction = whether to look for an unlinked source or sink pad
263 	 *
264 	 * Returns: unlinked pad of the given
265 	 *     direction, %NULL.
266 	 */
267 	public Pad findUnlinkedPad(GstPadDirection direction)
268 	{
269 		auto p = gst_bin_find_unlinked_pad(gstBin, direction);
270 
271 		if(p is null)
272 		{
273 			return null;
274 		}
275 
276 		return ObjectG.getDObject!(Pad)(cast(GstPad*) p, true);
277 	}
278 
279 	/**
280 	 * Looks for an element inside the bin that implements the given
281 	 * interface. If such an element is found, it returns the element.
282 	 * You can cast this element to the given interface afterwards.  If you want
283 	 * all elements that implement the interface, use
284 	 * gst_bin_iterate_all_by_interface(). This function recurses into child bins.
285 	 *
286 	 * MT safe.  Caller owns returned reference.
287 	 *
288 	 * Params:
289 	 *     iface = the #GType of an interface
290 	 *
291 	 * Returns: A #GstElement inside the bin
292 	 *     implementing the interface
293 	 */
294 	public Element getByInterface(GType iface)
295 	{
296 		auto p = gst_bin_get_by_interface(gstBin, iface);
297 
298 		if(p is null)
299 		{
300 			return null;
301 		}
302 
303 		return ObjectG.getDObject!(Element)(cast(GstElement*) p, true);
304 	}
305 
306 	/**
307 	 * Gets the element with the given name from a bin. This
308 	 * function recurses into child bins.
309 	 *
310 	 * Returns %NULL if no element with the given name is found in the bin.
311 	 *
312 	 * MT safe.  Caller owns returned reference.
313 	 *
314 	 * Params:
315 	 *     name = the element name to search for
316 	 *
317 	 * Returns: the #GstElement with the given
318 	 *     name, or %NULL
319 	 */
320 	public Element getByName(string name)
321 	{
322 		auto p = gst_bin_get_by_name(gstBin, Str.toStringz(name));
323 
324 		if(p is null)
325 		{
326 			return null;
327 		}
328 
329 		return ObjectG.getDObject!(Element)(cast(GstElement*) p, true);
330 	}
331 
332 	/**
333 	 * Gets the element with the given name from this bin. If the
334 	 * element is not found, a recursion is performed on the parent bin.
335 	 *
336 	 * Returns %NULL if:
337 	 * - no element with the given name is found in the bin
338 	 *
339 	 * MT safe.  Caller owns returned reference.
340 	 *
341 	 * Params:
342 	 *     name = the element name to search for
343 	 *
344 	 * Returns: the #GstElement with the given
345 	 *     name, or %NULL
346 	 */
347 	public Element getByNameRecurseUp(string name)
348 	{
349 		auto p = gst_bin_get_by_name_recurse_up(gstBin, Str.toStringz(name));
350 
351 		if(p is null)
352 		{
353 			return null;
354 		}
355 
356 		return ObjectG.getDObject!(Element)(cast(GstElement*) p, true);
357 	}
358 
359 	/**
360 	 * Return the suppressed flags of the bin.
361 	 *
362 	 * MT safe.
363 	 *
364 	 * Returns: the bin's suppressed #GstElementFlags.
365 	 *
366 	 * Since: 1.10
367 	 */
368 	public GstElementFlags getSuppressedFlags()
369 	{
370 		return gst_bin_get_suppressed_flags(gstBin);
371 	}
372 
373 	/**
374 	 * Looks for all elements inside the bin that implements the given
375 	 * interface. You can safely cast all returned elements to the given interface.
376 	 * The function recurses inside child bins. The iterator will yield a series
377 	 * of #GstElement that should be unreffed after use.
378 	 *
379 	 * MT safe.  Caller owns returned value.
380 	 *
381 	 * Params:
382 	 *     iface = the #GType of an interface
383 	 *
384 	 * Returns: a #GstIterator of #GstElement
385 	 *     for all elements in the bin implementing the given interface,
386 	 *     or %NULL
387 	 */
388 	public Iterator iterateAllByInterface(GType iface)
389 	{
390 		auto p = gst_bin_iterate_all_by_interface(gstBin, iface);
391 
392 		if(p is null)
393 		{
394 			return null;
395 		}
396 
397 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
398 	}
399 
400 	/**
401 	 * Gets an iterator for the elements in this bin.
402 	 *
403 	 * MT safe.  Caller owns returned value.
404 	 *
405 	 * Returns: a #GstIterator of #GstElement,
406 	 *     or %NULL
407 	 */
408 	public Iterator iterateElements()
409 	{
410 		auto p = gst_bin_iterate_elements(gstBin);
411 
412 		if(p is null)
413 		{
414 			return null;
415 		}
416 
417 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
418 	}
419 
420 	/**
421 	 * Gets an iterator for the elements in this bin.
422 	 * This iterator recurses into GstBin children.
423 	 *
424 	 * MT safe.  Caller owns returned value.
425 	 *
426 	 * Returns: a #GstIterator of #GstElement,
427 	 *     or %NULL
428 	 */
429 	public Iterator iterateRecurse()
430 	{
431 		auto p = gst_bin_iterate_recurse(gstBin);
432 
433 		if(p is null)
434 		{
435 			return null;
436 		}
437 
438 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
439 	}
440 
441 	/**
442 	 * Gets an iterator for all elements in the bin that have the
443 	 * #GST_ELEMENT_FLAG_SINK flag set.
444 	 *
445 	 * MT safe.  Caller owns returned value.
446 	 *
447 	 * Returns: a #GstIterator of #GstElement,
448 	 *     or %NULL
449 	 */
450 	public Iterator iterateSinks()
451 	{
452 		auto p = gst_bin_iterate_sinks(gstBin);
453 
454 		if(p is null)
455 		{
456 			return null;
457 		}
458 
459 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
460 	}
461 
462 	/**
463 	 * Gets an iterator for the elements in this bin in topologically
464 	 * sorted order. This means that the elements are returned from
465 	 * the most downstream elements (sinks) to the sources.
466 	 *
467 	 * This function is used internally to perform the state changes
468 	 * of the bin elements and for clock selection.
469 	 *
470 	 * MT safe.  Caller owns returned value.
471 	 *
472 	 * Returns: a #GstIterator of #GstElement,
473 	 *     or %NULL
474 	 */
475 	public Iterator iterateSorted()
476 	{
477 		auto p = gst_bin_iterate_sorted(gstBin);
478 
479 		if(p is null)
480 		{
481 			return null;
482 		}
483 
484 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
485 	}
486 
487 	/**
488 	 * Gets an iterator for all elements in the bin that have the
489 	 * #GST_ELEMENT_FLAG_SOURCE flag set.
490 	 *
491 	 * MT safe.  Caller owns returned value.
492 	 *
493 	 * Returns: a #GstIterator of #GstElement,
494 	 *     or %NULL
495 	 */
496 	public Iterator iterateSources()
497 	{
498 		auto p = gst_bin_iterate_sources(gstBin);
499 
500 		if(p is null)
501 		{
502 			return null;
503 		}
504 
505 		return ObjectG.getDObject!(Iterator)(cast(GstIterator*) p, true);
506 	}
507 
508 	/**
509 	 * Query @bin for the current latency using and reconfigures this latency to all the
510 	 * elements with a LATENCY event.
511 	 *
512 	 * This method is typically called on the pipeline when a #GST_MESSAGE_LATENCY
513 	 * is posted on the bus.
514 	 *
515 	 * This function simply emits the 'do-latency' signal so any custom latency
516 	 * calculations will be performed.
517 	 *
518 	 * Returns: %TRUE if the latency could be queried and reconfigured.
519 	 */
520 	public bool recalculateLatency()
521 	{
522 		return gst_bin_recalculate_latency(gstBin) != 0;
523 	}
524 
525 	/**
526 	 * Removes the element from the bin, unparenting it as well.
527 	 * Unparenting the element means that the element will be dereferenced,
528 	 * so if the bin holds the only reference to the element, the element
529 	 * will be freed in the process of removing it from the bin.  If you
530 	 * want the element to still exist after removing, you need to call
531 	 * gst_object_ref() before removing it from the bin.
532 	 *
533 	 * If the element's pads are linked to other pads, the pads will be unlinked
534 	 * before the element is removed from the bin.
535 	 *
536 	 * MT safe.
537 	 *
538 	 * Params:
539 	 *     element = the #GstElement to remove
540 	 *
541 	 * Returns: %TRUE if the element could be removed, %FALSE if
542 	 *     the bin does not want to remove the element.
543 	 */
544 	public bool remove(Element element)
545 	{
546 		return gst_bin_remove(gstBin, (element is null) ? null : element.getElementStruct()) != 0;
547 	}
548 
549 	/**
550 	 * Suppress the given flags on the bin. #GstElementFlags of a
551 	 * child element are propagated when it is added to the bin.
552 	 * When suppressed flags are set, those specified flags will
553 	 * not be propagated to the bin.
554 	 *
555 	 * MT safe.
556 	 *
557 	 * Params:
558 	 *     flags = the #GstElementFlags to suppress
559 	 *
560 	 * Since: 1.10
561 	 */
562 	public void setSuppressedFlags(GstElementFlags flags)
563 	{
564 		gst_bin_set_suppressed_flags(gstBin, flags);
565 	}
566 
567 	/**
568 	 * Synchronizes the state of every child of @bin with the state
569 	 * of @bin. See also gst_element_sync_state_with_parent().
570 	 *
571 	 * Returns: %TRUE if syncing the state was successful for all children,
572 	 *     otherwise %FALSE.
573 	 *
574 	 * Since: 1.6
575 	 */
576 	public bool syncChildrenStates()
577 	{
578 		return gst_bin_sync_children_states(gstBin) != 0;
579 	}
580 
581 	/**
582 	 * Will be emitted after the element was added to sub_bin.
583 	 *
584 	 * Params:
585 	 *     subBin = the #GstBin the element was added to
586 	 *     element = the #GstElement that was added to @sub_bin
587 	 *
588 	 * Since: 1.10
589 	 */
590 	gulong addOnDeepElementAdded(void delegate(Bin, Element, Bin) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
591 	{
592 		return Signals.connect(this, "deep-element-added", dlg, connectFlags ^ ConnectFlags.SWAPPED);
593 	}
594 
595 	/**
596 	 * Will be emitted after the element was removed from sub_bin.
597 	 *
598 	 * Params:
599 	 *     subBin = the #GstBin the element was removed from
600 	 *     element = the #GstElement that was removed from @sub_bin
601 	 *
602 	 * Since: 1.10
603 	 */
604 	gulong addOnDeepElementRemoved(void delegate(Bin, Element, Bin) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
605 	{
606 		return Signals.connect(this, "deep-element-removed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
607 	}
608 
609 	/**
610 	 * Will be emitted when the bin needs to perform latency calculations. This
611 	 * signal is only emitted for toplevel bins or when async-handling is
612 	 * enabled.
613 	 *
614 	 * Only one signal handler is invoked. If no signals are connected, the
615 	 * default handler is invoked, which will query and distribute the lowest
616 	 * possible latency to all sinks.
617 	 *
618 	 * Connect to this signal if the default latency calculations are not
619 	 * sufficient, like when you need different latencies for different sinks in
620 	 * the same pipeline.
621 	 */
622 	gulong addOnDoLatency(bool delegate(Bin) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
623 	{
624 		return Signals.connect(this, "do-latency", dlg, connectFlags ^ ConnectFlags.SWAPPED);
625 	}
626 
627 	/**
628 	 * Will be emitted after the element was added to the bin.
629 	 *
630 	 * Params:
631 	 *     element = the #GstElement that was added to the bin
632 	 */
633 	gulong addOnElementAdded(void delegate(Element, Bin) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
634 	{
635 		return Signals.connect(this, "element-added", dlg, connectFlags ^ ConnectFlags.SWAPPED);
636 	}
637 
638 	/**
639 	 * Will be emitted after the element was removed from the bin.
640 	 *
641 	 * Params:
642 	 *     element = the #GstElement that was removed from the bin
643 	 */
644 	gulong addOnElementRemoved(void delegate(Element, Bin) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
645 	{
646 		return Signals.connect(this, "element-removed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
647 	}
648 }