docs/gst/tmpl/gstpad.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstPad
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 The connection between Elements
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #GstElement are connected to each other via "pads", which are extremely light-weight generic
  10 connections. After two pad are retrieved from an element with gst_element_get_pad(), the pads
  11 can be connected with gst_pad_connect().
  12 </para>
  13 <para>
  14 Pads are typically created from a #GstPadTemplate with gst_pad_new_from_template().
  15 </para>
  16 <para>
  17 Pad have #GstCaps attached to it to describe the media type they
  18 are capable of dealing with. gst_pad_get_caps() and gst_pad_set_caps() are used to
  19 manipulate the caps of the pads.
  20 Pads created from a padtemplate cannot set capabilities that are incompatible with
  21 the padtemplates capabilities.
  22 </para>
  23 <para>
  24 Pads without padtemplates can be created with gst_pad_new() which takes a direction and
  25 a name as an argument.
  26 </para>
  27 <para>
  28 gst_pad_get_parent() will retrieve the #GstElement that owns the pad.
  29 </para>
  30 <para>
  31 GstElements creating a pad will typicilally use the various gst_pad_set_*_function() calls
  32 to register callbacks for various events on the pads.
  33 </para>
  34 <para>
  35 GstElements will use gst_pad_push() and gst_pad_pull() to push out or pull a buffer in. The
  36 gst_pad_pullregion() function can be used to request for a buffer with a specific offset (in
  37 time or in bytes). gst_pad_select() and gst_pad_selectv() are use by plugins to wait on a set
  38 of pads for a new #GstBuffer or #GstEvent.
  39 </para>
  40 <para>
  41 To send an event on a pad, use gst_pad_send_event().
  42 </para>
  43
  44 <!-- ##### SECTION See_Also ##### -->
  45 <para>
  46 #GstPadTemplate, #GstElement, #GstEvent
  47 </para>
  48
  49 <!-- ##### MACRO GST_PAD_NAME ##### -->
  50 <para>
  51 Get the name of the pad.
  52 </para>
  53
  54 @pad: the pad to query
  55
  56
  57 <!-- ##### MACRO GST_PAD_ELEMENT_PRIVATE ##### -->
  58 <para>
  59 Get the private data set by the element that owns the pad.
  60 </para>
  61
  62 @pad: the pad to query
  63
  64
  65 <!-- ##### MACRO GST_PAD_PARENT ##### -->
  66 <para>
  67 Get the parent element of this pad.
  68 </para>
  69
  70 @pad: the pad to query
  71
  72
  73 <!-- ##### MACRO GST_PAD_PADTEMPLATE ##### -->
  74 <para>
  75 Get the padtemplate that was used to create this pad. NULL if no padtemplate
  76 was used.
  77 </para>
  78
  79 @pad: the pad to query
  80
  81
  82 <!-- ##### MACRO GST_PAD_REALIZE ##### -->
  83 <para>
  84 Return the real pad of this pad.
  85 </para>
  86
  87 @pad: the pad to query
  88
  89
  90 <!-- ##### MACRO GST_PAD_DIRECTION ##### -->
  91 <para>
  92 Get the pad direction.
  93 </para>
  94
  95 @pad: the pad to query
  96
  97
  98 <!-- ##### MACRO GST_PAD_CAPS ##### -->
  99 <para>
 100 Get the capabilities of a pad.
 101 </para>
 102
 103 @pad: the pad to query
 104
 105
 106 <!-- ##### MACRO GST_PAD_PEER ##### -->
 107 <para>
 108 Get the peerpad of this pad.
 109 </para>
 110
 111 @pad: the pad to query
 112
 113
 114 <!-- ##### MACRO GST_PAD_CONNECTED ##### -->
 115 <para>
 116 Is this pad connected.
 117 </para>
 118
 119 @pad: the pad to check
 120
 121
 122 <!-- ##### MACRO GST_PAD_CAN_PULL ##### -->
 123 <para>
 124 Can this pad be used to pull a buffer.
 125 </para>
 126
 127 @pad: the pad to check
 128
 129
 130 <!-- ##### STRUCT GstPad ##### -->
 131 <para>
 132
 133 </para>
 134
 135
 136 <!-- ##### USER_FUNCTION GstPadChainFunction ##### -->
 137 <para>
 138 The function that will be called when chaining buffers.
 139 </para>
 140
 141 @pad: the pad that performed the chain
 142 @buf: the buffer that is chained
 143
 144
 145 <!-- ##### USER_FUNCTION GstPadGetFunction ##### -->
 146 <para>
 147 The function that will be called when pulling a buffer.
 148 </para>
 149
 150 @pad: the pad to get a buffer from
 151 @Returns: a #GstBuffer
 152
 153
 154 <!-- ##### USER_FUNCTION GstPadGetRegionFunction ##### -->
 155 <para>
 156 The function that will be called when pulling a region buffer.
 157 You can specify which buffer to get using an offset/length pair or
 158 a start/stop timecode pair.
 159 </para>
 160
 161 @pad: the pad to get a buffer from
 162 @type: the type of region to get (time or offset based)
 163 @offset: the offset of the region to get
 164 @len: the length of the region to get
 165 @Returns: a #GstBuffer
 166
 167
 168 <!-- ##### USER_FUNCTION GstPadNewCapsFunction ##### -->
 169 <para>
 170 The function that will be called when the caps of the pad has
 171 changed.
 172 </para>
 173
 174 @pad: The pad that has its caps changed
 175 @caps: the new caps of the pad
 176
 177
 178 <!-- ##### USER_FUNCTION GstPadBufferPoolFunction ##### -->
 179 <para>
 180 The function that will be called when a bufferpool is requested
 181 from this pad.
 182 </para>
 183
 184 @pad: the pad with the bufferpool
 185 @Returns: the GstBufferPool associated with this pad.
 186
 187
 188 <!-- ##### ENUM GstPadNegotiateReturn ##### -->
 189 <para>
 190 The possible results from padnegotiation.
 191 </para>
 192
 193 @GST_PAD_NEGOTIATE_FAIL: The pads could not agree about the media type.
 194 @GST_PAD_NEGOTIATE_AGREE: The pads agreed about the media type.
 195 @GST_PAD_NEGOTIATE_TRY: The pad did not agree and suggests another media type.
 196
 197 <!-- ##### USER_FUNCTION GstPadNegotiateFunction ##### -->
 198 <para>
 199 The function that will be called when negotiating.
 200 </para>
 201
 202 @pad: The pad that is being negotiated
 203 @caps: The current caps that are being negotiated
 204 @data: A generic gpointer that can be used to store user_data
 205 @Returns: The result of the negotiation process
 206
 207
 208 <!-- ##### ENUM GstRegionType ##### -->
 209 <para>
 210 the region types for #gst_pad_pullregion.
 211 </para>
 212
 213 @GST_REGION_VOID:
 214 @GST_REGION_OFFSET_LEN: an offet/length pair
 215 @GST_REGION_TIME_LEN: a time start/length pair
 216
 217 <!-- ##### USER_FUNCTION GstPadPullRegionFunction ##### -->
 218 <para>
 219 The function that will be called when pulling a region buffer.
 220 You can specify which buffer to get using an offset/length pair or
 221 a start/stop timecode pair.
 222 </para>
 223
 224 @pad: the pad to get a buffer from
 225 @type: the type of region to get (time or offset based)
 226 @offset: the offset of the region to get
 227 @len: the length of the region to get
 228 @Returns: a #GstBuffer
 229
 230
 231 <!-- ##### USER_FUNCTION GstPadEventFunction ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @pad:
 237 @event:
 238 @Returns:
 239
 240
 241 <!-- ##### ENUM GstPadDirection ##### -->
 242 <para>
 243 The direction this pad is.
 244 </para>
 245
 246 @GST_PAD_UNKNOWN: direction is unknown
 247 @GST_PAD_SRC: this is a source pad
 248 @GST_PAD_SINK: this is a sink pad
 249
 250 <!-- ##### ENUM GstPadFlags ##### -->
 251 <para>
 252 Flags for the pad.
 253 </para>
 254
 255 @GST_PAD_DISABLED: the pad is disabled
 256 @GST_PAD_EOS: the pad is in end of stream state
 257 @GST_PAD_FLAG_LAST: subclasses can use this number to enumerate their flags
 258
 259 <!-- ##### FUNCTION gst_pad_new ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @name:
 265 @direction:
 266 @Returns:
 267
 268
 269 <!-- ##### MACRO gst_pad_destroy ##### -->
 270 <para>
 271 Destroy the pad.
 272 </para>
 273
 274 @pad: the pad to destroy
 275
 276
 277 <!-- ##### FUNCTION gst_pad_new_from_template ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @templ:
 283 @name:
 284 @Returns:
 285 <!-- # Unused Parameters # -->
 286 @temp:
 287
 288
 289 <!-- ##### FUNCTION gst_pad_get_direction ##### -->
 290 <para>
 291
 292 </para>
 293
 294 @pad:
 295 @Returns:
 296
 297
 298 <!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @pad:
 304 @chain:
 305
 306
 307 <!-- ##### FUNCTION gst_pad_set_get_function ##### -->
 308 <para>
 309
 310 </para>
 311
 312 @pad:
 313 @get:
 314
 315
 316 <!-- ##### FUNCTION gst_pad_set_getregion_function ##### -->
 317 <para>
 318
 319 </para>
 320
 321 @pad:
 322 @getregion:
 323
 324
 325 <!-- ##### FUNCTION gst_pad_set_negotiate_function ##### -->
 326 <para>
 327
 328 </para>
 329
 330 @pad:
 331 @nego:
 332
 333
 334 <!-- ##### FUNCTION gst_pad_set_newcaps_function ##### -->
 335 <para>
 336
 337 </para>
 338
 339 @pad:
 340 @newcaps:
 341
 342
 343 <!-- ##### FUNCTION gst_pad_set_bufferpool_function ##### -->
 344 <para>
 345
 346 </para>
 347
 348 @pad:
 349 @bufpool:
 350
 351
 352 <!-- ##### FUNCTION gst_pad_set_caps ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @pad:
 358 @caps:
 359 @Returns:
 360
 361
 362 <!-- ##### FUNCTION gst_pad_get_caps ##### -->
 363 <para>
 364
 365 </para>
 366
 367 @pad:
 368 @Returns:
 369
 370
 371 <!-- ##### FUNCTION gst_pad_check_compatibility ##### -->
 372 <para>
 373
 374 </para>
 375
 376 @srcpad:
 377 @sinkpad:
 378 @Returns:
 379
 380
 381 <!-- ##### FUNCTION gst_pad_set_name ##### -->
 382 <para>
 383
 384 </para>
 385
 386 @pad:
 387 @name:
 388
 389
 390 <!-- ##### FUNCTION gst_pad_get_name ##### -->
 391 <para>
 392
 393 </para>
 394
 395 @pad:
 396 @Returns:
 397
 398
 399 <!-- ##### FUNCTION gst_pad_set_element_private ##### -->
 400 <para>
 401
 402 </para>
 403
 404 @pad:
 405 @priv:
 406
 407
 408 <!-- ##### FUNCTION gst_pad_get_element_private ##### -->
 409 <para>
 410
 411 </para>
 412
 413 @pad:
 414 @Returns:
 415
 416
 417 <!-- ##### FUNCTION gst_pad_set_parent ##### -->
 418 <para>
 419
 420 </para>
 421
 422 @pad:
 423 @parent:
 424
 425
 426 <!-- ##### FUNCTION gst_pad_get_parent ##### -->
 427 <para>
 428
 429 </para>
 430
 431 @pad:
 432 @Returns:
 433
 434
 435 <!-- ##### FUNCTION gst_pad_get_sched ##### -->
 436 <para>
 437
 438 </para>
 439
 440 @pad:
 441 @Returns:
 442
 443
 444 <!-- ##### FUNCTION gst_pad_set_sched ##### -->
 445 <para>
 446
 447 </para>
 448
 449 @pad:
 450 @sched:
 451
 452
 453 <!-- ##### FUNCTION gst_pad_get_real_parent ##### -->
 454 <para>
 455
 456 </para>
 457
 458 @pad:
 459 @Returns:
 460
 461
 462 <!-- ##### FUNCTION gst_pad_add_ghost_pad ##### -->
 463 <para>
 464
 465 </para>
 466
 467 @pad:
 468 @ghostpad:
 469
 470
 471 <!-- ##### FUNCTION gst_pad_remove_ghost_pad ##### -->
 472 <para>
 473
 474 </para>
 475
 476 @pad:
 477 @ghostpad:
 478
 479
 480 <!-- ##### FUNCTION gst_pad_get_ghost_pad_list ##### -->
 481 <para>
 482
 483 </para>
 484
 485 @pad:
 486 @Returns:
 487
 488
 489 <!-- ##### FUNCTION gst_pad_get_peer ##### -->
 490 <para>
 491
 492 </para>
 493
 494 @pad:
 495 @Returns:
 496
 497
 498 <!-- ##### FUNCTION gst_pad_connect ##### -->
 499 <para>
 500
 501 </para>
 502
 503 @srcpad:
 504 @sinkpad:
 505 <!-- # Unused Parameters # -->
 506 @Returns:
 507
 508
 509 <!-- ##### FUNCTION gst_pad_try_connect ##### -->
 510 <para>
 511
 512 </para>
 513
 514 @srcpad:
 515 @sinkpad:
 516 @Returns:
 517
 518
 519 <!-- ##### FUNCTION gst_pad_disconnect ##### -->
 520 <para>
 521
 522 </para>
 523
 524 @srcpad:
 525 @sinkpad:
 526
 527
 528 <!-- ##### FUNCTION gst_pad_push ##### -->
 529 <para>
 530
 531 </para>
 532
 533 @pad:
 534 @buf:
 535 <!-- # Unused Parameters # -->
 536 @buffer:
 537
 538
 539 <!-- ##### FUNCTION gst_pad_pull ##### -->
 540 <para>
 541
 542 </para>
 543
 544 @pad:
 545 @Returns:
 546
 547
 548 <!-- ##### FUNCTION gst_pad_pullregion ##### -->
 549 <para>
 550
 551 </para>
 552
 553 @pad:
 554 @type:
 555 @offset:
 556 @len:
 557 @Returns:
 558 <!-- # Unused Parameters # -->
 559 @size:
 560
 561
 562 <!-- ##### FUNCTION gst_pad_get_bufferpool ##### -->
 563 <para>
 564
 565 </para>
 566
 567 @pad:
 568 @Returns:
 569
 570
 571 <!-- ##### FUNCTION gst_pad_load_and_connect ##### -->
 572 <para>
 573
 574 </para>
 575
 576 @self:
 577 @parent:
 578 <!-- # Unused Parameters # -->
 579 @element:
 580 @elements:
 581
 582
 583 <!-- ##### FUNCTION gst_pad_negotiate_proxy ##### -->
 584 <para>
 585
 586 </para>
 587
 588 @srcpad:
 589 @destpad:
 590 @caps:
 591 @Returns:
 592 <!-- # Unused Parameters # -->
 593 @counter:
 594 @count:
 595
 596
 597 <!-- ##### FUNCTION gst_pad_renegotiate ##### -->
 598 <para>
 599
 600 </para>
 601
 602 @pad:
 603 @Returns:
 604
 605
 606 <!-- ##### FUNCTION gst_pad_get_padtemplate ##### -->
 607 <para>
 608
 609 </para>
 610
 611 @pad:
 612 @Returns:
 613
 614
 615 <!-- ##### FUNCTION gst_pad_get_padtemplate_caps ##### -->
 616 <para>
 617
 618 </para>
 619
 620 @pad:
 621 @Returns:
 622
 623
 624 <!-- ##### FUNCTION gst_pad_ghost_save_thyself ##### -->
 625 <para>
 626
 627 </para>
 628
 629 @pad:
 630 @bin:
 631 @parent:
 632 @Returns:
 633
 634
 635 <!-- ##### FUNCTION gst_pad_peek ##### -->
 636 <para>
 637
 638 </para>
 639
 640 @pad:
 641 @Returns:
 642
 643
 644 <!-- ##### FUNCTION gst_pad_select ##### -->
 645 <para>
 646
 647 </para>
 648
 649 @padlist:
 650 @Returns:
 651
 652
 653 <!-- ##### FUNCTION gst_pad_selectv ##### -->
 654 <para>
 655
 656 </para>
 657
 658 @pad:
 659 @Varargs:
 660 @Returns:
 661
 662
 663 <!-- ##### FUNCTION gst_pad_send_event ##### -->
 664 <para>
 665
 666 </para>
 667
 668 @pad:
 669 @event:
 670 @Returns:
 671
 672
 673 <!-- ##### FUNCTION gst_pad_event_default ##### -->
 674 <para>
 675
 676 </para>
 677
 678 @pad:
 679 @event:
 680
 681
 682 <!-- ##### FUNCTION gst_pad_set_event_function ##### -->
 683 <para>
 684
 685 </para>
 686
 687 @pad:
 688 @event:
 689
 690
 691 <!-- ##### STRUCT GstRealPad ##### -->
 692 <para>
 693
 694 </para>
 695
 696 @pad:
 697 @caps:
 698 @direction:
 699 @threadstate:
 700 @peer:
 701 @bufpen:
 702 @regiontype:
 703 @offset:
 704 @len:
 705 @sched:
 706 @chainfunc:
 707 @chainhandler:
 708 @getfunc:
 709 @gethandler:
 710 @eventfunc:
 711 @eventhandler:
 712 @getregionfunc:
 713 @pullregionfunc:
 714 @negotiatefunc:
 715 @newcapsfunc:
 716 @bufferpoolfunc:
 717 @ghostpads:
 718
 719 <!-- ##### MACRO GST_RPAD_LEN ##### -->
 720 <para>
 721 Get the length of the region that is being pulled.
 722 </para>
 723
 724 @pad: the real pad to query.
 725
 726
 727 <!-- ##### MACRO GST_RPAD_OFFSET ##### -->
 728 <para>
 729 Get the offset of the region that is being pulled.
 730 </para>
 731
 732 @pad: the real pad to query.
 733
 734
 735 <!-- ##### MACRO GST_RPAD_SCHED ##### -->
 736 <para>
 737 Get the scheduler of this real pad.
 738 </para>
 739
 740 @pad: the real pad to query.
 741
 742
 743 <!-- ##### MACRO GST_RPAD_REGIONTYPE ##### -->
 744 <para>
 745 Get the type of the region that is being pulled.
 746 </para>
 747
 748 @pad: the real pad to query.
 749
 750
 751 <!-- ##### MACRO GST_RPAD_DIRECTION ##### -->
 752 <para>
 753 Get the direction of the real pad.
 754 </para>
 755
 756 @pad: the realpad to query.
 757
 758
 759 <!-- ##### MACRO GST_RPAD_CAPS ##### -->
 760 <para>
 761 Get the caps of the real pad.
 762 </para>
 763
 764 @pad: the real pad to query.
 765
 766
 767 <!-- ##### MACRO GST_RPAD_PEER ##### -->
 768 <para>
 769 Get the peer element of the real pad.
 770 </para>
 771
 772 @pad: the real pad to query.
 773
 774
 775 <!-- ##### MACRO GST_RPAD_BUFPEN ##### -->
 776 <para>
 777 Get the bufpen of the real pad.
 778 </para>
 779
 780 @pad: the real pad to query.
 781
 782
 783 <!-- ##### MACRO GST_RPAD_CHAINFUNC ##### -->
 784 <para>
 785 Get the chain function of the real pad.
 786 </para>
 787
 788 @pad: the real pad to query.
 789
 790
 791 <!-- ##### MACRO GST_RPAD_GETFUNC ##### -->
 792 <para>
 793 Get get getfunction of the real pad.
 794 </para>
 795
 796 @pad: the real pad to query.
 797
 798
 799 <!-- ##### MACRO GST_RPAD_GETREGIONFUNC ##### -->
 800 <para>
 801 Get the getregion function of the real pad.
 802 </para>
 803
 804 @pad: the real pad to query.
 805
 806
 807 <!-- ##### MACRO GST_RPAD_PULLREGIONFUNC ##### -->
 808 <para>
 809 Get the pullregion function of the real pad.
 810 </para>
 811
 812 @pad: the real pad to query.
 813
 814
 815 <!-- ##### MACRO GST_RPAD_NEGOTIATEFUNC ##### -->
 816 <para>
 817 Get the negotiate function from the real pad.
 818 </para>
 819
 820 @pad: the real pad to query.
 821
 822
 823 <!-- ##### MACRO GST_RPAD_NEWCAPSFUNC ##### -->
 824 <para>
 825 Get the newcaps function from the real pad.
 826 </para>
 827
 828 @pad: the real pad to query.
 829
 830
 831 <!-- ##### MACRO GST_RPAD_BUFFERPOOLFUNC ##### -->
 832 <para>
 833 Get the bufferpoolfunction from the real pad.
 834 </para>
 835
 836 @pad: the real pad to query.
 837
 838
 839 <!-- ##### MACRO GST_RPAD_CHAINHANDLER ##### -->
 840 <para>
 841 Get the eventhandler function from the real pad.
 842 </para>
 843
 844 @pad: the real pad to query.
 845
 846
 847 <!-- ##### MACRO GST_RPAD_EVENTFUNC ##### -->
 848 <para>
 849 Get the event function of this real pad.
 850 </para>
 851
 852 @pad: the real pad to query.
 853
 854
 855 <!-- ##### MACRO GST_RPAD_EVENTHANDLER ##### -->
 856 <para>
 857 Get the eventhandler function of this real pad.
 858 </para>
 859
 860 @pad: the real pad to query.
 861
 862
 863 <!-- ##### MACRO GST_RPAD_GETHANDLER ##### -->
 864 <para>
 865 Get the gethandler function of this real pad.
 866 </para>
 867
 868 @pad: the real pad to query.
 869
 870
 871 <!-- ##### MACRO GST_GPAD_REALPAD ##### -->
 872 <para>
 873 Get the real pad of this ghost pad.
 874 </para>
 875
 876 @pad: the real pad to query.
 877
 878
 879 <!-- ##### STRUCT GstGhostPad ##### -->
 880 <para>
 881
 882 </para>
 883
 884 @pad:
 885 @realpad:
 886
 887 <!-- ##### FUNCTION gst_ghost_pad_new ##### -->
 888 <para>
 889
 890 </para>
 891
 892 @name:
 893 @pad:
 894 @Returns:
 895
 896