docs/gst/tmpl/gstelement.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstElement
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Abstract 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 link to pads on
  24 other elements.  Buffers flow between these linked 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 linked through their pads.
  37 If the link is straightforward, use the gst_element_link()
  38 convenience function to link two elements, or gst_element_link_many()
  39 for more elements in a row.
  40 Use gst_element_link_filtered() to link two elements constrained by
  41 a specified set of #GstCaps.
  42 For finer control, use gst_element_link_pads() and
  43 gst_element_link_pads_filtered() to specify the pads to link on
  44 each element by name.
  45 </para>
  46
  47 <para>
  48 Each element has a state (see #GstState).  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 #GstState, 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 <!-- ##### SECTION Stability_Level ##### -->
  69
  70
  71 <!-- ##### STRUCT GstElement ##### -->
  72 <para>
  73
  74 </para>
  75
  76 @state_lock:
  77 @state_cond:
  78 @current_state:
  79 @pending_state:
  80 @final_state:
  81 @state_error:
  82 @no_preroll:
  83 @bus:
  84 @clock:
  85 @base_time:
  86 @numpads:
  87 @pads:
  88 @numsrcpads:
  89 @srcpads:
  90 @numsinkpads:
  91 @sinkpads:
  92 @pads_cookie:
  93
  94 <!-- ##### SIGNAL GstElement::no-more-pads ##### -->
  95 <para>
  96
  97 </para>
  98
  99 @gstelement: the object which received the signal.
 100
 101 <!-- ##### SIGNAL GstElement::pad-added ##### -->
 102 <para>
 103
 104 </para>
 105
 106 @gstelement: the object which received the signal.
 107 @arg1:
 108
 109 <!-- ##### SIGNAL GstElement::pad-removed ##### -->
 110 <para>
 111
 112 </para>
 113
 114 @gstelement: the object which received the signal.
 115 @arg1:
 116
 117 <!-- ##### SIGNAL GstElement::state-changed ##### -->
 118 <para>
 119
 120 </para>
 121
 122 @gstelement: the object which received the signal.
 123 @arg1:
 124 @arg2:
 125
 126 <!-- ##### STRUCT GstElementClass ##### -->
 127 <para>
 128
 129 </para>
 130
 131 @parent_class:
 132 @details:
 133 @elementfactory:
 134 @padtemplates:
 135 @numpadtemplates:
 136 @pad_templ_cookie:
 137 @request_new_pad:
 138 @release_pad:
 139 @get_state:
 140 @change_state:
 141 @set_bus:
 142 @get_clock:
 143 @set_clock:
 144 @get_index:
 145 @set_index:
 146 @send_event:
 147 @get_query_types:
 148 @query:
 149
 150 <!-- ##### ENUM GstElementFlags ##### -->
 151 <para>
 152 This enum defines the standard flags that an element may have.
 153 </para>
 154
 155 @GST_ELEMENT_LOCKED_STATE:
 156 @GST_ELEMENT_IS_SINK:
 157 @GST_ELEMENT_UNPARENTING:
 158 @GST_ELEMENT_FLAG_LAST:
 159
 160 <!-- ##### ENUM GstStateChange ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @GST_STATE_CHANGE_NULL_TO_READY:
 166 @GST_STATE_CHANGE_READY_TO_PAUSED:
 167 @GST_STATE_CHANGE_PAUSED_TO_PLAYING:
 168 @GST_STATE_CHANGE_PLAYING_TO_PAUSED:
 169 @GST_STATE_CHANGE_PAUSED_TO_READY:
 170 @GST_STATE_CHANGE_READY_TO_NULL:
 171
 172 <!-- ##### MACRO GST_STATE ##### -->
 173 <para>
 174 This macro returns the current state of the element.
 175 </para>
 176
 177 @obj: Element to return state for.
 178
 179
 180 <!-- ##### MACRO GST_STATE_PENDING ##### -->
 181 <para>
 182 This macro returns the currently pending state of the element.
 183 </para>
 184
 185 @obj: Element to return the pending state for.
 186
 187
 188 <!-- ##### MACRO GST_STATE_CHANGE ##### -->
 189 <para>
 190
 191 </para>
 192
 193 @obj:
 194
 195
 196 <!-- ##### MACRO GST_STATE_BROADCAST ##### -->
 197 <para>
 198
 199 </para>
 200
 201 @elem:
 202
 203
 204 <!-- ##### MACRO GST_STATE_ERROR ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @obj:
 210
 211
 212 <!-- ##### MACRO GST_STATE_FINAL ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @obj:
 218
 219
 220 <!-- ##### MACRO GST_STATE_GET_COND ##### -->
 221 <para>
 222
 223 </para>
 224
 225 @elem:
 226
 227
 228 <!-- ##### MACRO GST_STATE_GET_LOCK ##### -->
 229 <para>
 230
 231 </para>
 232
 233 @elem:
 234
 235
 236 <!-- ##### MACRO GST_STATE_LOCK ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @elem:
 242
 243
 244 <!-- ##### MACRO GST_STATE_NO_PREROLL ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @obj:
 250
 251
 252 <!-- ##### MACRO GST_STATE_SIGNAL ##### -->
 253 <para>
 254
 255 </para>
 256
 257 @elem:
 258
 259
 260 <!-- ##### MACRO GST_STATE_TIMED_WAIT ##### -->
 261 <para>
 262
 263 </para>
 264
 265 @elem:
 266 @timeval:
 267
 268
 269 <!-- ##### MACRO GST_STATE_TRYLOCK ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @elem:
 275
 276
 277 <!-- ##### MACRO GST_STATE_UNLOCK ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @elem:
 283
 284
 285 <!-- ##### MACRO GST_STATE_WAIT ##### -->
 286 <para>
 287
 288 </para>
 289
 290 @elem:
 291
 292
 293 <!-- ##### MACRO GST_ELEMENT_NAME ##### -->
 294 <para>
 295 Gets the name of this element.  Used in the core.  Not ABI-compatible.
 296 </para>
 297
 298 @obj: A #GstElement to query
 299
 300
 301 <!-- ##### MACRO GST_ELEMENT_PARENT ##### -->
 302 <para>
 303 Get the parent object of this element.
 304 </para>
 305
 306 @obj: a #GstElement to query
 307
 308
 309 <!-- ##### MACRO GST_ELEMENT_CLOCK ##### -->
 310 <para>
 311 Get the clock of this element
 312 </para>
 313
 314 @obj: a #GstElement to query
 315
 316
 317 <!-- ##### MACRO GST_ELEMENT_PADS ##### -->
 318 <para>
 319 Get the pads of this elements.
 320 </para>
 321
 322 @obj: a #GstElement to query
 323
 324
 325 <!-- ##### MACRO GST_ELEMENT_ERROR ##### -->
 326 <para>
 327
 328 </para>
 329
 330 @el:
 331 @domain:
 332 @code:
 333 @text:
 334 @debug:
 335 <!-- # Unused Parameters # -->
 336 @message:
 337
 338
 339 <!-- ##### MACRO GST_ELEMENT_BUS ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @obj:
 345
 346
 347 <!-- ##### MACRO GST_ELEMENT_WARNING ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @el:
 353 @domain:
 354 @code:
 355 @text:
 356 @debug:
 357
 358
 359 <!-- ##### MACRO GST_ELEMENT_IS_LOCKED_STATE ##### -->
 360 <para>
 361
 362 </para>
 363
 364 @obj:
 365
 366
 367 <!-- ##### FUNCTION gst_element_abort_preroll ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @element:
 373 @Returns:
 374
 375
 376 <!-- ##### FUNCTION gst_element_abort_state ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @element:
 382
 383
 384 <!-- ##### FUNCTION gst_element_add_pad ##### -->
 385 <para>
 386
 387 </para>
 388
 389 @element:
 390 @pad:
 391 @Returns:
 392
 393
 394 <!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @klass:
 400 @templ:
 401
 402
 403 <!-- ##### FUNCTION gst_element_class_get_pad_template ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @element_class:
 409 @name:
 410 @Returns:
 411
 412
 413 <!-- ##### FUNCTION gst_element_class_get_pad_template_list ##### -->
 414 <para>
 415
 416 </para>
 417
 418 @element_class:
 419 @Returns:
 420
 421
 422 <!-- ##### FUNCTION gst_element_class_install_std_props ##### -->
 423 <para>
 424
 425 </para>
 426
 427 @klass:
 428 @first_name:
 429 @Varargs:
 430
 431
 432 <!-- ##### FUNCTION gst_element_class_set_details ##### -->
 433 <para>
 434
 435 </para>
 436
 437 @klass:
 438 @details:
 439
 440
 441 <!-- ##### FUNCTION gst_element_commit_state ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @element:
 447
 448
 449 <!-- ##### FUNCTION gst_element_create_all_pads ##### -->
 450 <para>
 451
 452 </para>
 453
 454 @element:
 455
 456
 457 <!-- ##### FUNCTION gst_element_factory_can_sink_caps ##### -->
 458 <para>
 459
 460 </para>
 461
 462 @factory:
 463 @caps:
 464 @Returns:
 465
 466
 467 <!-- ##### FUNCTION gst_element_factory_can_src_caps ##### -->
 468 <para>
 469
 470 </para>
 471
 472 @factory:
 473 @caps:
 474 @Returns:
 475
 476
 477 <!-- ##### FUNCTION gst_element_factory_get_static_pad_templates ##### -->
 478 <para>
 479
 480 </para>
 481
 482 @factory:
 483 @Returns:
 484
 485
 486 <!-- ##### FUNCTION gst_element_finish_preroll ##### -->
 487 <para>
 488
 489 </para>
 490
 491 @element:
 492 @pad:
 493 @Returns:
 494
 495
 496 <!-- ##### FUNCTION gst_element_found_tags ##### -->
 497 <para>
 498
 499 </para>
 500
 501 @element:
 502 @list:
 503
 504
 505 <!-- ##### FUNCTION gst_element_found_tags_for_pad ##### -->
 506 <para>
 507
 508 </para>
 509
 510 @element:
 511 @pad:
 512 @list:
 513
 514
 515 <!-- ##### FUNCTION gst_element_get_base_time ##### -->
 516 <para>
 517
 518 </para>
 519
 520 @element:
 521 @Returns:
 522
 523
 524 <!-- ##### FUNCTION gst_element_get_bus ##### -->
 525 <para>
 526
 527 </para>
 528
 529 @element:
 530 @Returns:
 531
 532
 533 <!-- ##### FUNCTION gst_element_get_clock ##### -->
 534 <para>
 535
 536 </para>
 537
 538 @element:
 539 @Returns:
 540
 541
 542 <!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
 543 <para>
 544
 545 </para>
 546
 547 @element:
 548 @pad:
 549 @caps:
 550 @Returns:
 551
 552
 553 <!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
 554 <para>
 555
 556 </para>
 557
 558 @element:
 559 @compattempl:
 560 @Returns:
 561
 562
 563 <!-- ##### FUNCTION gst_element_get_factory ##### -->
 564 <para>
 565
 566 </para>
 567
 568 @element:
 569 @Returns:
 570
 571
 572 <!-- ##### FUNCTION gst_element_get_index ##### -->
 573 <para>
 574
 575 </para>
 576
 577 @element:
 578 @Returns:
 579
 580
 581 <!-- ##### MACRO gst_element_get_name ##### -->
 582 <para>
 583 Gets the name of the element.
 584 </para>
 585
 586 @elem:
 587 @Returns: the name of the element.
 588
 589
 590 <!-- link -->
 591
 592
 593 <!-- ##### FUNCTION gst_element_get_pad ##### -->
 594 <para>
 595
 596 </para>
 597
 598 @element:
 599 @name:
 600 @Returns: GList of #GstPads
 601
 602
 603 <!-- ##### MACRO gst_element_get_parent ##### -->
 604 <para>
 605 Gets the parent of an element.
 606 </para>
 607
 608 @elem: a #GstElement to get the parent of.
 609 @Returns: the #GstObject parent of the element.
 610
 611
 612 <!-- ##### FUNCTION gst_element_get_query_types ##### -->
 613 <para>
 614
 615 </para>
 616
 617 @element:
 618 @Returns:
 619
 620
 621 <!-- ##### FUNCTION gst_element_get_request_pad ##### -->
 622 <para>
 623
 624 </para>
 625
 626 @element:
 627 @name:
 628 @Returns:
 629
 630
 631 <!-- ##### FUNCTION gst_element_get_state ##### -->
 632 <para>
 633
 634 </para>
 635
 636 @element:
 637 @state:
 638 @pending:
 639 @timeout:
 640 @Returns:
 641
 642
 643 <!-- ##### FUNCTION gst_element_get_static_pad ##### -->
 644 <para>
 645
 646 </para>
 647
 648 @element:
 649 @name:
 650 @Returns:
 651
 652
 653 <!-- ##### FUNCTION gst_element_is_indexable ##### -->
 654 <para>
 655
 656 </para>
 657
 658 @element:
 659 @Returns:
 660
 661
 662 <!-- ##### FUNCTION gst_element_is_locked_state ##### -->
 663 <para>
 664
 665 </para>
 666
 667 @element:
 668 @Returns:
 669
 670
 671 <!-- ##### FUNCTION gst_element_iterate_pads ##### -->
 672 <para>
 673
 674 </para>
 675
 676 @element:
 677 @Returns:
 678
 679
 680 <!-- ##### FUNCTION gst_element_iterate_sink_pads ##### -->
 681 <para>
 682
 683 </para>
 684
 685 @element:
 686 @Returns:
 687
 688
 689 <!-- ##### FUNCTION gst_element_iterate_src_pads ##### -->
 690 <para>
 691
 692 </para>
 693
 694 @element:
 695 @Returns:
 696
 697
 698 <!-- ##### FUNCTION gst_element_link ##### -->
 699 <para>
 700
 701 </para>
 702
 703 @src:
 704 @dest:
 705 @Returns:
 706
 707
 708 <!-- ##### FUNCTION gst_element_link_many ##### -->
 709 <para>
 710
 711 </para>
 712
 713 @element_1:
 714 @element_2:
 715 @Varargs:
 716 @Returns:
 717
 718
 719 <!-- ##### FUNCTION gst_element_link_filtered ##### -->
 720 <para>
 721
 722 </para>
 723
 724 @src:
 725 @dest:
 726 @filter:
 727 @Returns:
 728
 729
 730 <!-- ##### FUNCTION gst_element_link_pads ##### -->
 731 <para>
 732
 733 </para>
 734
 735 @src:
 736 @srcpadname:
 737 @dest:
 738 @destpadname:
 739 @Returns:
 740
 741
 742 <!-- ##### FUNCTION gst_element_link_pads_filtered ##### -->
 743 <para>
 744
 745 </para>
 746
 747 @src:
 748 @srcpadname:
 749 @dest:
 750 @destpadname:
 751 @filter:
 752 @Returns:
 753
 754
 755 <!-- ##### FUNCTION gst_element_lost_state ##### -->
 756 <para>
 757
 758 </para>
 759
 760 @element:
 761
 762
 763 <!-- ##### FUNCTION gst_element_message_full ##### -->
 764 <para>
 765
 766 </para>
 767
 768 @element:
 769 @type:
 770 @domain:
 771 @code:
 772 @text:
 773 @debug:
 774 @file:
 775 @function:
 776 @line:
 777
 778
 779 <!-- ##### FUNCTION gst_element_no_more_pads ##### -->
 780 <para>
 781
 782 </para>
 783
 784 @element:
 785
 786
 787 <!-- ##### FUNCTION gst_element_post_message ##### -->
 788 <para>
 789
 790 </para>
 791
 792 @element:
 793 @message:
 794 @Returns:
 795
 796
 797 <!-- ##### FUNCTION gst_element_provides_clock ##### -->
 798 <para>
 799
 800 </para>
 801
 802 @element:
 803 @Returns:
 804
 805
 806 <!-- ##### FUNCTION gst_element_query ##### -->
 807 <para>
 808
 809 </para>
 810
 811 @element:
 812 @query:
 813 @Returns:
 814 <!-- # Unused Parameters # -->
 815 @type:
 816 @format:
 817 @value:
 818
 819
 820 <!-- ##### FUNCTION gst_element_query_convert ##### -->
 821 <para>
 822
 823 </para>
 824
 825 @element:
 826 @src_format:
 827 @src_val:
 828 @dest_fmt:
 829 @dest_val:
 830 @Returns:
 831
 832
 833 <!-- ##### FUNCTION gst_element_query_position ##### -->
 834 <para>
 835
 836 </para>
 837
 838 @element:
 839 @format:
 840 @cur:
 841 @end:
 842 @Returns:
 843
 844
 845 <!-- ##### FUNCTION gst_element_release_request_pad ##### -->
 846 <para>
 847
 848 </para>
 849
 850 @element:
 851 @pad:
 852
 853
 854 <!-- ##### FUNCTION gst_element_remove_pad ##### -->
 855 <para>
 856
 857 </para>
 858
 859 @element:
 860 @pad:
 861 @Returns:
 862
 863
 864 <!-- ##### FUNCTION gst_element_requires_clock ##### -->
 865 <para>
 866
 867 </para>
 868
 869 @element:
 870 @Returns:
 871
 872
 873 <!-- ##### FUNCTION gst_element_seek ##### -->
 874 <para>
 875
 876 </para>
 877
 878 @element:
 879 @rate:
 880 @format:
 881 @flags:
 882 @cur_type:
 883 @cur:
 884 @stop_type:
 885 @stop:
 886 @Returns:
 887 <!-- # Unused Parameters # -->
 888 @seek_type:
 889 @offset:
 890
 891
 892 <!-- ##### FUNCTION gst_element_send_event ##### -->
 893 <para>
 894
 895 </para>
 896
 897 @element:
 898 @event:
 899 @Returns:
 900
 901
 902 <!-- ##### FUNCTION gst_element_set_base_time ##### -->
 903 <para>
 904
 905 </para>
 906
 907 @element:
 908 @time:
 909
 910
 911 <!-- ##### FUNCTION gst_element_set_bus ##### -->
 912 <para>
 913
 914 </para>
 915
 916 @element:
 917 @bus:
 918
 919
 920 <!-- ##### FUNCTION gst_element_set_clock ##### -->
 921 <para>
 922
 923 </para>
 924
 925 @element:
 926 @clock:
 927
 928
 929 <!-- ##### FUNCTION gst_element_set_index ##### -->
 930 <para>
 931
 932 </para>
 933
 934 @element:
 935 @index:
 936
 937
 938 <!-- ##### FUNCTION gst_element_set_locked_state ##### -->
 939 <para>
 940
 941 </para>
 942
 943 @element:
 944 @locked_state:
 945 @Returns:
 946
 947
 948 <!-- ##### MACRO gst_element_set_name ##### -->
 949 <para>
 950 Sets the name of the element, getting rid of the old name if there was one.
 951 </para>
 952
 953 @elem: a #GstElement to set the name of.
 954 @name: the new name of the element.
 955
 956
 957 <!-- ##### MACRO gst_element_set_parent ##### -->
 958 <para>
 959 Sets the parent of an element.
 960 </para>
 961
 962 @elem: a #GstElement to set the parent of.
 963 @parent:  the new #GstObject parent of the object.
 964
 965
 966 <!-- ##### FUNCTION gst_element_set_state ##### -->
 967 <para>
 968
 969 </para>
 970
 971 @element:
 972 @state:
 973 @Returns:
 974
 975
 976 <!-- ##### FUNCTION gst_element_state_get_name ##### -->
 977 <para>
 978
 979 </para>
 980
 981 @state:
 982 @Returns:
 983
 984
 985 <!-- ##### FUNCTION gst_element_sync_state_with_parent ##### -->
 986 <para>
 987
 988 </para>
 989
 990 @element:
 991 @Returns:
 992
 993
 994 <!-- ##### FUNCTION gst_element_unlink ##### -->
 995 <para>
 996
 997 </para>
 998
 999 @src:
1000 @dest:
1001
1002
1003 <!-- ##### FUNCTION gst_element_unlink_many ##### -->
1004 <para>
1005
1006 </para>
1007
1008 @element_1:
1009 @element_2:
1010 @Varargs:
1011
1012
1013 <!-- ##### FUNCTION gst_element_unlink_pads ##### -->
1014 <para>
1015
1016 </para>
1017
1018 @src:
1019 @srcpadname:
1020 @dest:
1021 @destpadname:
1022
1023
1024 <!-- pad manipulation -->
1025
1026