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