docs/gst/tmpl/gstelement.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstElement
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Base class for all pipeline elements
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GstElement is the base class needed to construct an element that can be
  10 used in a GStreamer pipeline.  As such, it is not a functional entity, and
  11 cannot do anything when placed in a pipeline.
  12 </para>
  13
  14 <para>
  15 The name of a GstElement can be get with gst_element_get_name() and set with
  16 gst_element_set_name().  For speed, GST_ELEMENT_NAME() can be used in the
  17 core.
  18 Do not use this in plug-ins or applications in order to retain ABI
  19 compatibility.
  20 </para>
  21
  22 <para>
  23 All elements have pads (of the type #GstPad).  These pads connect to pads on
  24 other elements.  Buffers flow between these connected pads.
  25 A GstElement has a GList of #GstPad structures for all their input (or sink)
  26 and output (or source) pads.
  27 Core and plug-in writers can add and remove pads with gst_element_add_pad()
  28 and gst_element_remove_pad().
  29 Application writers can manipulate ghost pads (copies of real pads inside a bin)
  30 with gst_element_add_ghost_pad() and gst_element_remove_ghost_pad().
  31 A pad of an element can be retrieved by name with gst_element_get_pad().
  32 A GList of all pads can be retrieved with gst_element_get_pad_list().
  33 </para>
  34
  35 <para>
  36 Elements can be connected through their pads.
  37 If the connection is straightforward, use the gst_element_connect()
  38 convenience function to connect two elements, or gst_element_connect_many()
  39 for more elements in a row.
  40 Use gst_element_connect_filtered() to connect two elements constrained by
  41 a specified set of #GstCaps.
  42 For finer control, use gst_element_connect_pads() and
  43 gst_element_connect_pads_filtered() to specify the pads to connect on
  44 each element by name.
  45 </para>
  46
  47 <para>
  48 Each element has a state (see #GstElementState).  You can get and set the state
  49 of an element with gst_element_get_state() and gst_element_set_state().
  50 You can wait for an element to change it's state with gst_element_wait_state_change().
  51 To get a string representation of a #GstElementState, use
  52 gst_element_state_get_name().
  53 </para>
  54
  55 <para>
  56 You can get and set a #GstClock on an element using gst_element_get_clock()
  57 and gst_element_set_clock().  You can wait for the clock to reach a given
  58 #GstClockTime using gst_element_clock_wait().
  59 </para>
  60
  61 <!-- ##### SECTION See_Also ##### -->
  62 <para>
  63 #GstElementFactory, #GstPad
  64 </para>
  65
  66 <!-- basic object functions -->
  67
  68 <!-- ##### STRUCT GstElement ##### -->
  69 <para>
  70
  71 </para>
  72
  73
  74 <!-- ##### MACRO gst_element_destroy ##### -->
  75 <para>
  76 Destroys the element (without taking the refcount into account).
  77 An application programmer should use #gst_object_unref instead to dispose
  78 of an element he doesn't need anymore.
  79 </para>
  80
  81 @element: a #GstElement to destroy
  82
  83
  84 <!-- ##### MACRO gst_element_set_name ##### -->
  85 <para>
  86 Sets the name of the element, getting rid of the old name if there was one.
  87 </para>
  88
  89 @element: a #GstElement to set the name of.
  90 @name: the new name of the element.
  91
  92 <!-- ##### MACRO gst_element_get_name ##### -->
  93 <para>
  94 Gets the name of the element.
  95 </para>
  96
  97 @element: a #GstElement to get the name of.
  98 @Returns: the name of the element.
  99
 100
 101 <!-- connection -->
 102
 103
 104 <!-- ##### FUNCTION gst_element_get_factory ##### -->
 105 <para>
 106
 107 </para>
 108
 109 @element:
 110 @Returns:
 111
 112
 113 <!-- ##### FUNCTION gst_element_add_pad ##### -->
 114 <para>
 115
 116 </para>
 117
 118 @element:
 119 @pad:
 120
 121
 122 <!-- ##### FUNCTION gst_element_remove_pad ##### -->
 123 <para>
 124
 125 </para>
 126
 127 @element:
 128 @pad:
 129
 130
 131 <!-- ##### FUNCTION gst_element_add_ghost_pad ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @element:
 137 @pad:
 138 @name:
 139 @Returns:
 140
 141
 142 <!-- ##### FUNCTION gst_element_remove_ghost_pad ##### -->
 143 <para>
 144
 145 </para>
 146
 147 @element:
 148 @pad:
 149
 150
 151 <!-- pad template manipulation -->
 152
 153
 154 <!-- ##### FUNCTION gst_element_get_pad ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @element:
 160 @name:
 161 @Returns: GList of #GstPads
 162
 163
 164 <!-- ##### FUNCTION gst_element_get_static_pad ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @element:
 170 @name:
 171 @Returns:
 172
 173
 174 <!-- ##### FUNCTION gst_element_get_request_pad ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @element:
 180 @name:
 181 @Returns:
 182
 183
 184 <!-- ##### FUNCTION gst_element_release_request_pad ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @element:
 190 @pad:
 191
 192
 193 <!-- ##### FUNCTION gst_element_get_pad_list ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @element:
 199 @Returns:
 200
 201
 202 <!-- ##### FUNCTION gst_element_get_pad_template ##### -->
 203 <para>
 204
 205 </para>
 206
 207 @element:
 208 @name:
 209 @Returns:
 210
 211
 212 <!-- ##### FUNCTION gst_element_get_pad_template_list ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @element:
 218 @Returns:
 219
 220
 221
 222 <!-- scheduling -->
 223
 224
 225 <!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
 226 <para>
 227
 228 </para>
 229
 230 @klass:
 231 @templ:
 232 <!-- # Unused Parameters # -->
 233 @element:
 234
 235
 236 <!-- ##### FUNCTION gst_element_connect ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @src:
 242 @dest:
 243 @Returns:
 244
 245
 246 <!-- ##### FUNCTION gst_element_connect_many ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @element_1:
 252 @element_2:
 253 @Varargs:
 254 @Returns:
 255
 256
 257 <!-- ##### FUNCTION gst_element_connect_filtered ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @src:
 263 @dest:
 264 @filtercaps:
 265 @Returns:
 266
 267
 268 <!-- ##### FUNCTION gst_element_connect_pads ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @src:
 274 @srcpadname:
 275 @dest:
 276 @destpadname:
 277 @Returns:
 278
 279
 280 <!-- ##### FUNCTION gst_element_connect_pads_filtered ##### -->
 281 <para>
 282
 283 </para>
 284
 285 @src:
 286 @srcpadname:
 287 @dest:
 288 @destpadname:
 289 @filtercaps:
 290 @Returns:
 291
 292
 293 <!-- ##### FUNCTION gst_element_disconnect ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @src:
 299 @dest:
 300 <!-- # Unused Parameters # -->
 301 @srcpadname:
 302 @destpadname:
 303
 304
 305 <!-- ##### FUNCTION gst_element_disconnect_many ##### -->
 306 <para>
 307
 308 </para>
 309
 310 @element_1:
 311 @element_2:
 312 @Varargs:
 313
 314
 315 <!-- ##### FUNCTION gst_element_disconnect_pads ##### -->
 316 <para>
 317
 318 </para>
 319
 320 @src:
 321 @srcpadname:
 322 @dest:
 323 @destpadname:
 324
 325
 326 <!-- pad manipulation -->
 327
 328
 329 <!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
 330 <para>
 331
 332 </para>
 333
 334 @element:
 335 @pad:
 336 @Returns:
 337
 338
 339 <!-- ##### FUNCTION gst_element_get_compatible_pad_filtered ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @element:
 345 @pad:
 346 @filtercaps:
 347 @Returns:
 348
 349
 350 <!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
 351 <para>
 352
 353 </para>
 354
 355 @element:
 356 @compattempl:
 357 @Returns:
 358
 359
 360 <!-- ##### FUNCTION gst_element_set_state ##### -->
 361 <para>
 362
 363 </para>
 364
 365 @element:
 366 @state:
 367 @Returns:
 368
 369
 370 <!-- ##### FUNCTION gst_element_get_state ##### -->
 371 <para>
 372
 373 </para>
 374
 375 @element:
 376 @Returns:
 377 <!-- # Unused Parameters # -->
 378 @elem:
 379
 380
 381 <!-- ##### FUNCTION gst_element_state_get_name ##### -->
 382 <para>
 383
 384 </para>
 385
 386 @state:
 387 @Returns:
 388
 389
 390 <!-- ##### FUNCTION gst_element_wait_state_change ##### -->
 391 <para>
 392
 393 </para>
 394
 395 @element:
 396
 397
 398 <!-- ##### FUNCTION gst_element_error ##### -->
 399 <para>
 400
 401 </para>
 402
 403 @element:
 404 @error:
 405 @Varargs:
 406
 407
 408 <!-- ##### FUNCTION gst_element_set_eos ##### -->
 409 <para>
 410
 411 </para>
 412
 413 @element:
 414
 415
 416 <!-- ##### FUNCTION gst_element_interrupt ##### -->
 417 <para>
 418
 419 </para>
 420
 421 @element:
 422 @Returns:
 423
 424
 425 <!-- ##### FUNCTION gst_element_yield ##### -->
 426 <para>
 427
 428 </para>
 429
 430 @element:
 431
 432
 433 <!-- ##### FUNCTION gst_element_release_locks ##### -->
 434 <para>
 435
 436 </para>
 437
 438 @element:
 439 @Returns:
 440
 441
 442 <!-- ##### FUNCTION gst_element_get_clock ##### -->
 443 <para>
 444
 445 </para>
 446
 447 @element:
 448 @Returns:
 449
 450
 451 <!-- ##### FUNCTION gst_element_set_clock ##### -->
 452 <para>
 453
 454 </para>
 455
 456 @element:
 457 @clock:
 458
 459
 460 <!-- ##### FUNCTION gst_element_clock_wait ##### -->
 461 <para>
 462
 463 </para>
 464
 465 @element:
 466 @clock:
 467 @time:
 468 @jitter:
 469 @Returns:
 470
 471
 472 <!-- ##### FUNCTION gst_element_set_loop_function ##### -->
 473 <para>
 474
 475 </para>
 476
 477 @element:
 478 @loop:
 479
 480
 481 <!-- ##### USER_FUNCTION GstElementLoopFunction ##### -->
 482 <para>
 483 This function type is used to specify a loop function for the element.  It
 484 is passed the element in question, and is expect to return only in error
 485 circumstances.
 486 </para>
 487
 488 @element: The element in question.
 489
 490
 491 <!-- ##### FUNCTION gst_element_get_scheduler ##### -->
 492 <para>
 493
 494 </para>
 495
 496 @element:
 497 @Returns:
 498
 499
 500 <!-- ##### FUNCTION gst_element_set_scheduler ##### -->
 501 <para>
 502
 503 </para>
 504
 505 @element:
 506 @sched:
 507
 508
 509 <!-- ##### MACRO gst_element_get_parent ##### -->
 510 <para>
 511 Gets the parent of an element.
 512 </para>
 513
 514 @element: a #GstElement to get the parent of.
 515 @Returns: the #GstObject parent of the element.
 516
 517
 518 <!-- ##### MACRO gst_element_set_parent ##### -->
 519 <para>
 520 Sets the parent of an element.
 521 </para>
 522
 523 @element: a #GstElement to set the parent of.
 524 @parent:  the new #GstObject parent of the object.
 525
 526
 527 <!-- ##### FUNCTION gst_element_get_managing_bin ##### -->
 528 <para>
 529
 530 </para>
 531
 532 @element:
 533 @Returns:
 534
 535 <!-- clocking -->
 536
 537
 538 <!-- ##### USER_FUNCTION GstElementPostRunFunction ##### -->
 539 <para>
 540 The signature of the function to execute before this element
 541 is scheduled.
 542 </para>
 543
 544 @element: The element
 545
 546
 547 <!-- ##### USER_FUNCTION GstElementPreRunFunction ##### -->
 548 <para>
 549 The signature of the function to execute after this element
 550 is scheduled.
 551 </para>
 552
 553 @element: The element
 554
 555
 556 <!-- ##### FUNCTION gst_element_disable_threadsafe_properties ##### -->
 557 <para>
 558
 559 </para>
 560
 561 @element:
 562
 563
 564 <!-- ##### FUNCTION gst_element_enable_threadsafe_properties ##### -->
 565 <para>
 566
 567 </para>
 568
 569 @element:
 570
 571
 572 <!-- ##### FUNCTION gst_element_get ##### -->
 573 <para>
 574
 575 </para>
 576
 577 @element:
 578 @first_property_name:
 579 @Varargs:
 580
 581
 582 <!-- ##### FUNCTION gst_element_get_property ##### -->
 583 <para>
 584
 585 </para>
 586
 587 @element:
 588 @property_name:
 589 @value:
 590
 591
 592 <!-- ##### FUNCTION gst_element_get_valist ##### -->
 593 <para>
 594
 595 </para>
 596
 597 @element:
 598 @first_property_name:
 599 @var_args:
 600
 601
 602 <!-- ##### FUNCTION gst_element_set ##### -->
 603 <para>
 604
 605 </para>
 606
 607 @element:
 608 @first_property_name:
 609 @Varargs:
 610
 611
 612 <!-- ##### FUNCTION gst_element_set_pending_properties ##### -->
 613 <para>
 614
 615 </para>
 616
 617 @element:
 618
 619
 620 <!-- ##### FUNCTION gst_element_set_property ##### -->
 621 <para>
 622
 623 </para>
 624
 625 @element:
 626 @property_name:
 627 @value:
 628
 629
 630 <!-- ##### FUNCTION gst_element_set_valist ##### -->
 631 <para>
 632
 633 </para>
 634
 635 @element:
 636 @first_property_name:
 637 @var_args:
 638
 639
 640 <!-- ##### FUNCTION gst_element_query ##### -->
 641 <para>
 642
 643 </para>
 644
 645 @element:
 646 @type:
 647 @format:
 648 @value:
 649 @Returns:
 650
 651
 652 <!-- ##### FUNCTION gst_element_send_event ##### -->
 653 <para>
 654
 655 </para>
 656
 657 @element:
 658 @event:
 659 @Returns:
 660
 661
 662 <!-- ##### ENUM GstElementState ##### -->
 663 <para>
 664 This enum defines the standard states an element may be in.  You will normally
 665 use gst_element_set_state() to change the state of an element.
 666
 667 </para>
 668
 669 @GST_STATE_VOID_PENDING:
 670 @GST_STATE_NULL: Reset the state of an element.
 671 @GST_STATE_READY: will make the element ready to start processing data. some
 672 elements might have a non trivial way to initialize themselves.
 673 @GST_STATE_PAUSED: means there really is data flowing temporary stops the data flow.
 674 @GST_STATE_PLAYING: means there really is data flowing through the graph.
 675
 676 <!-- ##### ENUM GstElementStateReturn ##### -->
 677 <para>
 678 This enum defines the standard return values that an element
 679 can return after a state change.
 680
 681 </para>
 682
 683 @GST_STATE_FAILURE: the element could not perform the state change
 684 @GST_STATE_SUCCESS: the element successfully changed its state
 685 @GST_STATE_ASYNC: the element will asynchronously change its state as soon as possible
 686
 687 <!-- ##### MACRO GST_NUM_STATES ##### -->
 688 <para>
 689 The maximun number of states.
 690 </para>
 691
 692
 693
 694 <!-- ##### MACRO GST_STATE ##### -->
 695 <para>
 696 This macro returns the current state of the element.
 697 </para>
 698
 699 @obj: Element to return state for.
 700
 701
 702 <!-- ##### MACRO GST_STATE_PENDING ##### -->
 703 <para>
 704 This macro returns the currently pending state of the element.
 705 </para>
 706
 707 @obj: Element to return the pending state for.
 708
 709
 710 <!-- ##### MACRO GST_STATE_TRANSITION ##### -->
 711 <para>
 712 Returns the state transition this object is going through.
 713 </para>
 714
 715 @obj: the Element to return the state transition for
 716
 717
 718 <!-- ##### MACRO GST_STATE_NULL_TO_READY ##### -->
 719 <para>
 720 The Element is going from the NULL state to the READY state.
 721 </para>
 722
 723
 724
 725 <!-- ##### MACRO GST_STATE_READY_TO_PAUSED ##### -->
 726 <para>
 727 The Element is going from the READY state to the PAUSED state.
 728 </para>
 729
 730
 731
 732 <!-- ##### MACRO GST_STATE_PAUSED_TO_READY ##### -->
 733 <para>
 734 The Element is going from the PAUSED state to the READY state.
 735 </para>
 736
 737
 738
 739 <!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### -->
 740 <para>
 741 The Element is going from the PLAYING state to the PAUSED state.
 742 </para>
 743
 744
 745
 746 <!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### -->
 747 <para>
 748 The Element is going from the PAUSED state to the PLAYING state.
 749 </para>
 750
 751
 752
 753 <!-- ##### MACRO GST_STATE_READY_TO_NULL ##### -->
 754 <para>
 755 The Element is going from the READY state to the NULL state.
 756 </para>
 757
 758
 759
 760 <!-- ##### ENUM GstElementFlags ##### -->
 761 <para>
 762 This enum defines the standard flags that an element may have.
 763 </para>
 764
 765 @GST_ELEMENT_COMPLEX:
 766 @GST_ELEMENT_DECOUPLED:
 767 @GST_ELEMENT_THREAD_SUGGESTED:
 768 @GST_ELEMENT_INFINITE_LOOP:
 769 @GST_ELEMENT_NEW_LOOPFUNC:
 770 @GST_ELEMENT_EVENT_AWARE:
 771 @GST_ELEMENT_USE_THREADSAFE_PROPERTIES:
 772 @GST_ELEMENT_SCHEDULER_PRIVATE1:
 773 @GST_ELEMENT_SCHEDULER_PRIVATE2:
 774 @GST_ELEMENT_FLAG_LAST:
 775
 776 <!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### -->
 777 <para>
 778 Queries whether the Element should be placed in a thread.
 779 </para>
 780
 781 @obj: a #GstElement to query
 782
 783
 784 <!-- ##### MACRO GST_ELEMENT_IS_DECOUPLED ##### -->
 785 <para>
 786 Queries if the Element is decoupled.
 787 </para>
 788
 789 @obj: a #GstElement to query
 790
 791
 792 <!-- ##### MACRO GST_ELEMENT_IS_EOS ##### -->
 793 <para>
 794 Query wether this element is in the End Of Stream state.
 795 </para>
 796
 797 @obj: a #GstElement to query
 798
 799
 800 <!-- ##### MACRO GST_ELEMENT_IS_EVENT_AWARE ##### -->
 801 <para>
 802 Query wether this element can handle events.
 803 </para>
 804
 805 @obj: a #GstElement to query
 806
 807
 808 <!-- ##### MACRO GST_ELEMENT_PARENT ##### -->
 809 <para>
 810 Get the parent object of this element.
 811 </para>
 812
 813 @obj: a #GstElement to query
 814
 815
 816 <!-- ##### MACRO GST_ELEMENT_NAME ##### -->
 817 <para>
 818 Gets the name of this element.  Used in the core.  Not ABI-compatible.
 819 </para>
 820
 821 @obj: A #GstElement to query
 822
 823
 824 <!-- ##### MACRO GST_ELEMENT_PADS ##### -->
 825 <para>
 826 Get the pads of this elements.
 827 </para>
 828
 829 @obj: a #GstElement to query
 830
 831
 832 <!-- ##### MACRO GST_ELEMENT_SCHED ##### -->
 833 <para>
 834 Get the scheduler of this element.
 835 </para>
 836
 837 @obj: a #GstElement to query
 838
 839
 840 <!-- ##### MACRO GST_ELEMENT_MANAGER ##### -->
 841 <para>
 842 Get the manager of this element.
 843 </para>
 844
 845 @obj: a #GstElement to query
 846
 847
 848 <!-- ##### MACRO GST_ELEMENT_CLOCK ##### -->
 849 <para>
 850 Get the clock of this element
 851 </para>
 852
 853 @obj: a #GstElement to query
 854
 855
 856 <!-- ##### SIGNAL GstElement::eos ##### -->
 857 <para>
 858
 859 </para>
 860
 861 @gstelement: the object which received the signal.
 862
 863 <!-- ##### SIGNAL GstElement::error ##### -->
 864 <para>
 865 Is trigered whenever an error occured
 866
 867 </para>
 868
 869 @gstelement: the object which received the signal.
 870 @arg1: the error message
 871 @arg2:
 872
 873 <!-- ##### SIGNAL GstElement::new-pad ##### -->
 874 <para>
 875 Is trigered whenever a new pad is added to an element
 876 </para>
 877
 878 @gstelement: the object which received the signal.
 879 @arg1: the new pad that was added
 880
 881 <!-- ##### SIGNAL GstElement::pad-removed ##### -->
 882 <para>
 883
 884 </para>
 885
 886 @gstelement: the object which received the signal.
 887 @arg1: The pad that was removed.
 888
 889 <!-- ##### SIGNAL GstElement::state-change ##### -->
 890 <para>
 891 Is trigered whenever the state of an element changes
 892 </para>
 893
 894 @gstelement: the object which received the signal.
 895 @arg1: the new state of the object
 896 @arg2:
 897