1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 The connection between Elements
7 <!-- ##### SECTION Long_Description ##### -->
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().
14 PedTemplates are use to describe the runtime behaviour of an element and what pads it
15 will have during its lifetime. Pads are typically created from a padtemplate with
16 GST_PADTEMPLATE_NEW() or with the factory macro GST_PADTEMPLATE_FACTORY().
19 Pad and PadTemplates have #GstCaps attached to it to describe the media type they
20 are capable of dealing with. gst_pad_get_caps() and gst_pad_set_caps() are used to
21 manipulate the caps of the pads. gst_padtemplate_get_caps() is used to get the
22 caps of a padtemplate. It's not possible to modify the caps of a padtemplate after
23 creation. The following code example shows the code to create a pad from a padtemplate.
25 GST_PADTEMPLATE_FACTORY (my_factory,
26 "sink", /* the name of the pad */
27 GST_PAD_SINK, /* the direction of the pad */
28 GST_PAD_ALWAYS, /* when this pad will be present */
29 GST_CAPS_NEW ( /* the capabilities of the padtemplate */
32 "format", GST_PROPS_STRING ("int"),
33 "channels", GST_PROPS_INT_RANGE (1, 6)
42 pad = gst_pad_new_from_template (GST_PADTEMPLATE_GET (my_factory), "sink");
46 Pads created from a padtemplate cannot set capabilities that are incompatible with
47 the padtemplates capabilities.
50 Pads without padtemplates can be created with gst_pad_new() which takes a direction and
51 a name as an argument.
54 gst_pad_get_parent() will retrieve the GstElement that owns the pad.
57 GstElements creating a pad will typicilally use the various gst_pad_set_*_function() calls
58 to register callbacks for various events on the pads.
61 GstElements will use gst_pad_push() and gst_pad_pull() to push out or pull a buffer in. The
62 gst_pad_pullregion() function can be used to request for a buffer with a specific offset (in
66 <!-- ##### SECTION See_Also ##### -->
71 <!-- ##### MACRO GST_PAD_NAME ##### -->
73 Get the name of the pad.
76 @pad: the pad to query
79 <!-- ##### MACRO GST_PAD_ELEMENT_PRIVATE ##### -->
81 Get the private data set by the element that owns the pad.
84 @pad: the pad to query
87 <!-- ##### MACRO GST_PAD_PARENT ##### -->
89 Get the parent element of this pad.
92 @pad: the pad to query
95 <!-- ##### MACRO GST_PAD_PADTEMPLATE ##### -->
97 Get the padtemplate that was used to create this pad. NULL if no padtemplate
101 @pad: the pad to query
104 <!-- ##### MACRO GST_PAD_REALIZE ##### -->
106 Return the real pad of this pad.
109 @pad: the pad to query
112 <!-- ##### MACRO GST_PAD_DIRECTION ##### -->
114 Get the pad direction.
117 @pad: the pad to query
120 <!-- ##### MACRO GST_PAD_CAPS ##### -->
122 Get the capabilities of a pad.
125 @pad: the pad to query
128 <!-- ##### MACRO GST_PAD_PEER ##### -->
130 Get the peerpad of this pad.
133 @pad: the pad to query
136 <!-- ##### MACRO GST_PAD_CONNECTED ##### -->
138 Is this pad connected.
141 @pad: the pad to check
144 <!-- ##### MACRO GST_PAD_CAN_PULL ##### -->
146 Can this pad be used to pull a buffer.
149 @pad: the pad to check
152 <!-- ##### STRUCT GstPad ##### -->
158 <!-- ##### USER_FUNCTION GstPadChainFunction ##### -->
160 The function that will be called when chaining buffers.
163 @pad: the pad that performed the chain
164 @buf: the buffer that is chained
167 <!-- ##### USER_FUNCTION GstPadGetFunction ##### -->
169 The function that will be called when pulling a buffer.
172 @pad: the pad to get a buffer from
173 @Returns: a #GstBuffer
176 <!-- ##### USER_FUNCTION GstPadGetRegionFunction ##### -->
178 The function that will be called when pulling a region buffer.
179 You can specify which buffer to get using an offset/length pair or
180 a start/stop timecode pair.
183 @pad: the pad to get a buffer from
184 @type: the type of region to get (time or offset based)
185 @offset: the offset of the region to get
186 @len: the length of the region to get
187 @Returns: a #GstBuffer
190 <!-- ##### USER_FUNCTION GstPadNewCapsFunction ##### -->
192 The function that will be called when the caps of the pad has
196 @pad: The pad that has its caps changed
197 @caps: the new caps of the pad
200 <!-- ##### USER_FUNCTION GstPadBufferPoolFunction ##### -->
202 The function that will be called when a bufferpool is requested
206 @pad: the pad with the bufferpool
207 @Returns: the GstBufferPool associated with this pad.
210 <!-- ##### ENUM GstPadNegotiateReturn ##### -->
212 The possible results from padnegotiation.
215 @GST_PAD_NEGOTIATE_FAIL: The pads could not agree about the media type.
216 @GST_PAD_NEGOTIATE_AGREE: The pads agreed about the media type.
217 @GST_PAD_NEGOTIATE_TRY: The pad did not agree and suggests another media type.
219 <!-- ##### USER_FUNCTION GstPadNegotiateFunction ##### -->
221 The function that will be called when negotiating.
224 @pad: The pad that is being negotiated
225 @caps: The current caps that are being negotiated
226 @data: A generic gpointer that can be used to store user_data
227 @Returns: The result of the negotiation process
230 <!-- ##### ENUM GstRegionType ##### -->
232 the region types for #gst_pad_pullregion.
236 @GST_REGION_OFFSET_LEN: an offet/length pair
237 @GST_REGION_TIME_LEN: a time start/length pair
239 <!-- ##### USER_FUNCTION GstPadPullRegionFunction ##### -->
241 The function that will be called when pulling a region buffer.
242 You can specify which buffer to get using an offset/length pair or
243 a start/stop timecode pair.
246 @pad: the pad to get a buffer from
247 @type: the type of region to get (time or offset based)
248 @offset: the offset of the region to get
249 @len: the length of the region to get
250 @Returns: a #GstBuffer
253 <!-- ##### USER_FUNCTION GstPadEventFunction ##### -->
263 <!-- ##### ENUM GstPadDirection ##### -->
265 The direction this pad is.
268 @GST_PAD_UNKNOWN: direction is unknown
269 @GST_PAD_SRC: this is a source pad
270 @GST_PAD_SINK: this is a sink pad
272 <!-- ##### ENUM GstPadFlags ##### -->
277 @GST_PAD_DISABLED: the pad is disabled
278 @GST_PAD_EOS: the pad is in end of stream state
279 @GST_PAD_FLAG_LAST: subclasses can use this number to enumerate their flags
281 <!-- ##### FUNCTION gst_pad_new ##### -->
291 <!-- ##### MACRO gst_pad_destroy ##### -->
296 @pad: the pad to destroy
299 <!-- ##### FUNCTION gst_pad_new_from_template ##### -->
307 <!-- # Unused Parameters # -->
311 <!-- ##### FUNCTION gst_pad_get_direction ##### -->
320 <!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
329 <!-- ##### FUNCTION gst_pad_set_get_function ##### -->
338 <!-- ##### FUNCTION gst_pad_set_getregion_function ##### -->
347 <!-- ##### FUNCTION gst_pad_set_negotiate_function ##### -->
356 <!-- ##### FUNCTION gst_pad_set_newcaps_function ##### -->
365 <!-- ##### FUNCTION gst_pad_set_bufferpool_function ##### -->
374 <!-- ##### FUNCTION gst_pad_set_caps ##### -->
384 <!-- ##### FUNCTION gst_pad_get_caps ##### -->
393 <!-- ##### FUNCTION gst_pad_check_compatibility ##### -->
403 <!-- ##### FUNCTION gst_pad_set_name ##### -->
412 <!-- ##### FUNCTION gst_pad_get_name ##### -->
421 <!-- ##### FUNCTION gst_pad_set_element_private ##### -->
430 <!-- ##### FUNCTION gst_pad_get_element_private ##### -->
439 <!-- ##### FUNCTION gst_pad_set_parent ##### -->
448 <!-- ##### FUNCTION gst_pad_get_parent ##### -->
457 <!-- ##### FUNCTION gst_pad_get_sched ##### -->
466 <!-- ##### FUNCTION gst_pad_set_sched ##### -->
475 <!-- ##### FUNCTION gst_pad_get_real_parent ##### -->
484 <!-- ##### FUNCTION gst_pad_add_ghost_pad ##### -->
493 <!-- ##### FUNCTION gst_pad_remove_ghost_pad ##### -->
502 <!-- ##### FUNCTION gst_pad_get_ghost_pad_list ##### -->
511 <!-- ##### FUNCTION gst_pad_get_peer ##### -->
520 <!-- ##### FUNCTION gst_pad_connect ##### -->
527 <!-- # Unused Parameters # -->
531 <!-- ##### FUNCTION gst_pad_try_connect ##### -->
541 <!-- ##### FUNCTION gst_pad_disconnect ##### -->
550 <!-- ##### FUNCTION gst_pad_push ##### -->
557 <!-- # Unused Parameters # -->
561 <!-- ##### FUNCTION gst_pad_pull ##### -->
570 <!-- ##### FUNCTION gst_pad_pullregion ##### -->
580 <!-- # Unused Parameters # -->
584 <!-- ##### FUNCTION gst_pad_get_bufferpool ##### -->
593 <!-- ##### FUNCTION gst_pad_load_and_connect ##### -->
600 <!-- # Unused Parameters # -->
605 <!-- ##### FUNCTION gst_pad_negotiate_proxy ##### -->
614 <!-- # Unused Parameters # -->
619 <!-- ##### FUNCTION gst_pad_renegotiate ##### -->
628 <!-- ##### FUNCTION gst_pad_get_padtemplate ##### -->
637 <!-- ##### FUNCTION gst_pad_get_padtemplate_caps ##### -->
646 <!-- ##### FUNCTION gst_pad_event ##### -->
658 <!-- ##### FUNCTION gst_pad_ghost_save_thyself ##### -->
669 <!-- ##### FUNCTION gst_pad_peek ##### -->
678 <!-- ##### FUNCTION gst_pad_select ##### -->
687 <!-- ##### FUNCTION gst_pad_selectv ##### -->
697 <!-- ##### FUNCTION gst_pad_send_event ##### -->
707 <!-- ##### FUNCTION gst_pad_set_event_function ##### -->
716 <!-- ##### STRUCT GstRealPad ##### -->
744 <!-- ##### MACRO GST_RPAD_LEN ##### -->
746 Get the length of the region that is being pulled.
749 @pad: the real pad to query.
752 <!-- ##### MACRO GST_RPAD_OFFSET ##### -->
754 Get the offset of the region that is being pulled.
757 @pad: the real pad to query.
760 <!-- ##### MACRO GST_RPAD_SCHED ##### -->
762 Get the scheduler of this real pad.
765 @pad: the real pad to query.
768 <!-- ##### MACRO GST_RPAD_REGIONTYPE ##### -->
770 Get the type of the region that is being pulled.
773 @pad: the real pad to query.
776 <!-- ##### MACRO GST_RPAD_DIRECTION ##### -->
778 Get the direction of the real pad.
781 @pad: the realpad to query.
784 <!-- ##### MACRO GST_RPAD_CAPS ##### -->
786 Get the caps of the real pad.
789 @pad: the real pad to query.
792 <!-- ##### MACRO GST_RPAD_PEER ##### -->
794 Get the peer element of the real pad.
797 @pad: the real pad to query.
800 <!-- ##### MACRO GST_RPAD_BUFPEN ##### -->
802 Get the bufpen of the real pad.
805 @pad: the real pad to query.
808 <!-- ##### MACRO GST_RPAD_CHAINFUNC ##### -->
810 Get the chain function of the real pad.
813 @pad: the real pad to query.
816 <!-- ##### MACRO GST_RPAD_GETFUNC ##### -->
818 Get get getfunction of the real pad.
821 @pad: the real pad to query.
824 <!-- ##### MACRO GST_RPAD_GETREGIONFUNC ##### -->
826 Get the getregion function of the real pad.
829 @pad: the real pad to query.
832 <!-- ##### MACRO GST_RPAD_PULLREGIONFUNC ##### -->
834 Get the pullregion function of the real pad.
837 @pad: the real pad to query.
840 <!-- ##### MACRO GST_RPAD_NEGOTIATEFUNC ##### -->
842 Get the negotiate function from the real pad.
845 @pad: the real pad to query.
848 <!-- ##### MACRO GST_RPAD_NEWCAPSFUNC ##### -->
850 Get the newcaps function from the real pad.
853 @pad: the real pad to query.
856 <!-- ##### MACRO GST_RPAD_BUFFERPOOLFUNC ##### -->
858 Get the bufferpoolfunction from the real pad.
861 @pad: the real pad to query.
864 <!-- ##### MACRO GST_RPAD_CHAINHANDLER ##### -->
866 Get the eventhandler function from the real pad.
869 @pad: the real pad to query.
872 <!-- ##### MACRO GST_RPAD_EVENTFUNC ##### -->
874 Get the event function of this real pad.
877 @pad: the real pad to query.
880 <!-- ##### MACRO GST_RPAD_EVENTHANDLER ##### -->
882 Get the eventhandler function of this real pad.
885 @pad: the real pad to query.
888 <!-- ##### MACRO GST_RPAD_GETHANDLER ##### -->
890 Get the gethandler function of this real pad.
893 @pad: the real pad to query.
896 <!-- ##### MACRO GST_GPAD_REALPAD ##### -->
898 Get the real pad of this ghost pad.
901 @pad: the real pad to query.
904 <!-- ##### STRUCT GstGhostPad ##### -->
912 <!-- ##### FUNCTION gst_ghost_pad_new ##### -->
922 <!-- ##### ENUM GstPadPresence ##### -->
924 Indicates when this pad will become available.
927 @GST_PAD_ALWAYS: the pad is always available
928 @GST_PAD_SOMETIMES: the pad will become available depending on the media stream
929 @GST_PAD_REQUEST: th pad is only available on request with
930 gst_element_request_pad_by_name() or gst_element_request_compatible_pad().
932 <!-- ##### STRUCT GstPadTemplate ##### -->
943 <!-- ##### MACRO GST_PADTEMPLATE_CAPS ##### -->
945 Get a handle to the padtemplate #GstCaps
948 @templ: the template to query
951 <!-- ##### MACRO GST_PADTEMPLATE_DIRECTION ##### -->
953 Get the direction of the padtemplate.
956 @templ: the template to query
959 <!-- ##### MACRO GST_PADTEMPLATE_NAME_TEMPLATE ##### -->
961 Get the nametemplate of the padtemplate.
964 @templ: the template to query
967 <!-- ##### MACRO GST_PADTEMPLATE_PRESENCE ##### -->
969 Get the presence of the padtemplate.
972 @templ: the template to query
975 <!-- ##### MACRO GST_PADTEMPLATE_NEW ##### -->
977 Create a new padtemplate.
980 @padname: the nametemplate for the pads that will be created with this template
981 @dir: the direction of the pads.
982 @pres: the presence of the pads.
983 @a...: the capabilities of this padtemplate usually created with GST_CAPS_NEW()
986 <!-- ##### MACRO GST_PADTEMPLATE_FACTORY ##### -->
988 Create a factory for a padtemplate. This can be used if you only want one instance
989 of the padtemplate. Use GST_PADTEMPLATE_GET() to get the unique padtemplate.
992 @name: th name of the factory
993 @padname: the nametemplate of the pads
994 @dir: the direction of the pads.
995 @pres: the presence of the pads.
996 @a...: the capabilities of this padtemplate, usually created with GST_CAPS_NEW()
999 <!-- ##### MACRO GST_PADTEMPLATE_GET ##### -->
1001 Get the padtemplate of the factory created with GST_PADTEMPLATE_FACTORY()
1004 @fact: the factory name to get the padtemplate from.
1007 <!-- ##### FUNCTION gst_padtemplate_new ##### -->
1020 <!-- ##### FUNCTION gst_padtemplate_load_thyself ##### -->
1029 <!-- ##### FUNCTION gst_padtemplate_save_thyself ##### -->
1039 <!-- ##### FUNCTION gst_padtemplate_get_caps ##### -->
1048 <!-- ##### FUNCTION gst_padtemplate_get_caps_by_name ##### -->