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 Pads are typically created from a #GstPadTemplate with gst_pad_new_from_template().
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.
24 Pads without padtemplates can be created with gst_pad_new() which takes a direction and
25 a name as an argument.
28 gst_pad_get_parent() will retrieve the #GstElement that owns the pad.
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.
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.
41 To send an event on a pad, use gst_pad_send_event().
44 <!-- ##### SECTION See_Also ##### -->
46 #GstPadTemplate, #GstElement, #GstEvent
49 <!-- ##### MACRO GST_PAD_NAME ##### -->
51 Get the name of the pad.
54 @pad: the pad to query
57 <!-- ##### MACRO GST_PAD_ELEMENT_PRIVATE ##### -->
59 Get the private data set by the element that owns the pad.
62 @pad: the pad to query
65 <!-- ##### MACRO GST_PAD_PARENT ##### -->
67 Get the parent element of this pad.
70 @pad: the pad to query
73 <!-- ##### MACRO GST_PAD_PAD_TEMPLATE ##### -->
75 Get the padtemplate that was used to create this pad. NULL if no padtemplate
79 @pad: the pad to query
82 <!-- ##### MACRO GST_PAD_REALIZE ##### -->
84 Return the real pad of this pad.
87 @pad: the pad to query
90 <!-- ##### MACRO GST_PAD_DIRECTION ##### -->
92 Get the pad direction.
95 @pad: the pad to query
98 <!-- ##### MACRO GST_PAD_CAPS ##### -->
100 Get the capabilities of a pad.
103 @pad: the pad to query
106 <!-- ##### MACRO GST_PAD_PEER ##### -->
108 Get the peerpad of this pad.
111 @pad: the pad to query
114 <!-- ##### MACRO GST_PAD_CAN_PULL ##### -->
116 Can this pad be used to pull a buffer.
119 @pad: the pad to check
122 <!-- ##### MACRO GST_PAD_IS_SINK ##### -->
124 Check if the pad is a sinkpad.
127 @pad: the pad to query
130 <!-- ##### MACRO GST_PAD_IS_SRC ##### -->
132 Check if the pad is a srcpad.
135 @pad: the pad to query
138 <!-- ##### MACRO GST_PAD_IS_CONNECTED ##### -->
140 Checks if the pad is connected
143 @pad: the pad to query
146 <!-- ##### STRUCT GstPad ##### -->
152 <!-- ##### USER_FUNCTION GstPadChainFunction ##### -->
154 The function that will be called when chaining buffers.
157 @pad: the pad that performed the chain
158 @buf: the buffer that is chained
161 <!-- ##### USER_FUNCTION GstPadGetFunction ##### -->
163 The function that will be called when pulling a buffer.
166 @pad: the pad to get a buffer from
167 @Returns: a #GstBuffer
170 <!-- ##### USER_FUNCTION GstPadBufferPoolFunction ##### -->
172 The function that will be called when a bufferpool is requested
176 @pad: the pad with the bufferpool
177 @Returns: the GstBufferPool associated with this pad.
180 <!-- ##### USER_FUNCTION GstPadGetCapsFunction ##### -->
182 Return the caps of the specified pad. By default this function
183 will return the pad template caps but can optionally be overridden.
186 @pad: The pad to get the caps of
187 @caps: The peer caps, can be used to filter the caps.
188 @Returns: The caps of the pad.
191 <!-- ##### USER_FUNCTION GstPadEventFunction ##### -->
193 Function signature to handle an event for the pad.
196 @pad: The pad to handle the event
197 @event: The event to handle
198 @Returns: TRUE if the pad could handle the event.
201 <!-- ##### USER_FUNCTION GstPadConnectFunction ##### -->
203 Function signature to handle a new connection on the pad.
206 @pad: The pad that is connected.
207 @caps: The peer caps.
208 @Returns: the result of the connection with the specified caps.
211 <!-- ##### ENUM GstPadConnectReturn ##### -->
213 The result of a pad connection.
216 @GST_PAD_CONNECT_REFUSED: The connectino was refused
217 @GST_PAD_CONNECT_DELAYED: The connection was delayed, probably because the
218 element needs more specific pad caps.
219 @GST_PAD_CONNECT_OK: The connection succeeded.
220 @GST_PAD_CONNECT_DONE: The connection succeeded, any more attempts are not needed.
222 <!-- ##### USER_FUNCTION GstPadConvertFunction ##### -->
224 The signature of a convert function.
227 @pad: The pad to perform the convert on
228 @src_format: The source format of the conversion
229 @src_value: The source value of the conversion
230 @dest_format: a pointer to the destination format
231 @dest_value: a pointer to the destination value
232 @Returns: TRUE if the conversion could be performed.
235 <!-- ##### USER_FUNCTION GstPadIntConnFunction ##### -->
237 The signature of the internal pad connection function
240 @pad: The pad to query
241 @Returns: a Glist of pads that connect to the requested pad internally to the
242 parent element. g_list_free() after use.
245 <!-- ##### ENUM GstPadQueryType ##### -->
247 The different supported query types
250 @GST_PAD_QUERY_TOTAL: Query the total stream time
251 @GST_PAD_QUERY_POSITION: Query the current stream position
252 @GST_PAD_QUERY_LATENCY: Query the latency on the pad
253 @GST_PAD_QUERY_JITTER:
255 <!-- ##### USER_FUNCTION GstPadQueryFunction ##### -->
257 The signature of query function
260 @pad: The pad to query
261 @type: The query type
262 @format: a pointer to the target format
263 @value: a pointer to the target value
264 @Returns: TRUE if the query could be performed
267 <!-- ##### ENUM GstPadDirection ##### -->
269 The direction this pad is.
272 @GST_PAD_UNKNOWN: direction is unknown
273 @GST_PAD_SRC: this is a source pad
274 @GST_PAD_SINK: this is a sink pad
276 <!-- ##### ENUM GstPadFlags ##### -->
281 @GST_PAD_DISABLED: the pad is disabled
282 @GST_PAD_EOS: the pad is in end of stream state
283 @GST_PAD_FLAG_LAST: subclasses can use this number to enumerate their flags
285 <!-- ##### FUNCTION gst_pad_new ##### -->
295 <!-- ##### FUNCTION gst_pad_custom_new ##### -->
306 <!-- ##### FUNCTION gst_pad_custom_new_from_template ##### -->
317 <!-- ##### MACRO gst_pad_destroy ##### -->
322 @pad: the pad to destroy
325 <!-- ##### FUNCTION gst_pad_new_from_template ##### -->
333 <!-- # Unused Parameters # -->
337 <!-- ##### FUNCTION gst_pad_get_direction ##### -->
346 <!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
355 <!-- ##### FUNCTION gst_pad_set_get_function ##### -->
364 <!-- ##### FUNCTION gst_pad_set_bufferpool_function ##### -->
373 <!-- ##### FUNCTION gst_pad_set_connect_function ##### -->
382 <!-- ##### FUNCTION gst_pad_set_getcaps_function ##### -->
391 <!-- ##### FUNCTION gst_pad_try_set_caps ##### -->
401 <!-- ##### FUNCTION gst_pad_get_caps ##### -->
410 <!-- ##### FUNCTION gst_pad_check_compatibility ##### -->
420 <!-- ##### FUNCTION gst_pad_set_name ##### -->
429 <!-- ##### FUNCTION gst_pad_get_name ##### -->
438 <!-- ##### FUNCTION gst_pad_set_element_private ##### -->
447 <!-- ##### FUNCTION gst_pad_get_element_private ##### -->
456 <!-- ##### FUNCTION gst_pad_set_parent ##### -->
465 <!-- ##### FUNCTION gst_pad_get_parent ##### -->
474 <!-- ##### FUNCTION gst_pad_get_scheduler ##### -->
483 <!-- ##### FUNCTION gst_pad_set_scheduler ##### -->
492 <!-- ##### FUNCTION gst_pad_unset_scheduler ##### -->
500 <!-- ##### FUNCTION gst_pad_get_real_parent ##### -->
509 <!-- ##### FUNCTION gst_pad_add_ghost_pad ##### -->
518 <!-- ##### FUNCTION gst_pad_remove_ghost_pad ##### -->
527 <!-- ##### FUNCTION gst_pad_get_ghost_pad_list ##### -->
536 <!-- ##### FUNCTION gst_pad_get_peer ##### -->
545 <!-- ##### FUNCTION gst_pad_connect ##### -->
555 <!-- ##### FUNCTION gst_pad_connect_filtered ##### -->
566 <!-- ##### FUNCTION gst_pad_reconnect_filtered ##### -->
575 <!-- # Unused Parameters # -->
579 <!-- ##### FUNCTION gst_pad_try_reconnect_filtered ##### -->
588 <!-- # Unused Parameters # -->
592 <!-- ##### FUNCTION gst_pad_disconnect ##### -->
601 <!-- ##### FUNCTION gst_pad_can_connect ##### -->
611 <!-- ##### FUNCTION gst_pad_can_connect_filtered ##### -->
622 <!-- ##### FUNCTION gst_pad_push ##### -->
629 <!-- # Unused Parameters # -->
633 <!-- ##### FUNCTION gst_pad_pull ##### -->
642 <!-- ##### FUNCTION gst_pad_get_bufferpool ##### -->
651 <!-- ##### FUNCTION gst_pad_load_and_connect ##### -->
658 <!-- # Unused Parameters # -->
663 <!-- ##### FUNCTION gst_pad_proxy_connect ##### -->
673 <!-- ##### FUNCTION gst_pad_get_pad_template ##### -->
682 <!-- ##### FUNCTION gst_pad_get_pad_template_caps ##### -->
691 <!-- ##### FUNCTION gst_pad_get_allowed_caps ##### -->
700 <!-- ##### FUNCTION gst_pad_recalc_allowed_caps ##### -->
709 <!-- ##### FUNCTION gst_pad_perform_negotiate ##### -->
719 <!-- ##### FUNCTION gst_pad_ghost_save_thyself ##### -->
730 <!-- ##### FUNCTION gst_pad_peek ##### -->
739 <!-- ##### FUNCTION gst_pad_select ##### -->
748 <!-- ##### FUNCTION gst_pad_selectv ##### -->
758 <!-- ##### FUNCTION gst_pad_dispatcher ##### -->
769 <!-- ##### FUNCTION gst_pad_send_event ##### -->
779 <!-- ##### FUNCTION gst_pad_event_default ##### -->
789 <!-- ##### FUNCTION gst_pad_set_event_function ##### -->
798 <!-- ##### FUNCTION gst_pad_set_convert_function ##### -->
807 <!-- ##### FUNCTION gst_pad_convert ##### -->
820 <!-- ##### FUNCTION gst_pad_convert_default ##### -->
833 <!-- ##### FUNCTION gst_pad_get_internal_connections ##### -->
842 <!-- ##### FUNCTION gst_pad_get_internal_connections_default ##### -->
851 <!-- ##### FUNCTION gst_pad_set_internal_connection_function ##### -->
860 <!-- ##### FUNCTION gst_pad_set_query_function ##### -->
869 <!-- ##### FUNCTION gst_pad_query ##### -->
881 <!-- ##### FUNCTION gst_pad_query_default ##### -->
893 <!-- ##### STRUCT GstRealPad ##### -->
921 <!-- ##### MACRO GST_RPAD_SCHED ##### -->
923 Get the scheduler of this real pad.
926 @pad: the real pad to query.
929 <!-- ##### MACRO GST_RPAD_DIRECTION ##### -->
931 Get the direction of the real pad.
934 @pad: the realpad to query.
937 <!-- ##### MACRO GST_RPAD_CAPS ##### -->
939 Get the caps of the real pad.
942 @pad: the real pad to query.
945 <!-- ##### MACRO GST_RPAD_PEER ##### -->
947 Get the peer element of the real pad.
950 @pad: the real pad to query.
953 <!-- ##### MACRO GST_RPAD_BUFPEN ##### -->
955 Get the bufpen of the real pad.
958 @pad: the real pad to query.
961 <!-- ##### MACRO GST_RPAD_CHAINFUNC ##### -->
963 Get the chain function of the real pad.
966 @pad: the real pad to query.
969 <!-- ##### MACRO GST_RPAD_FILTER ##### -->
971 Get the filter from the pad
974 @pad: the pad to query
977 <!-- ##### MACRO GST_RPAD_APPFILTER ##### -->
979 Get the application filter for this pad
982 @pad: the pad to query
985 <!-- ##### MACRO GST_RPAD_GETFUNC ##### -->
987 Get get getfunction of the real pad.
990 @pad: the real pad to query.
993 <!-- ##### MACRO GST_RPAD_BUFFERPOOLFUNC ##### -->
995 Get the bufferpoolfunction from the real pad.
998 @pad: the real pad to query.
1001 <!-- ##### MACRO GST_RPAD_CHAINHANDLER ##### -->
1003 Get the eventhandler function from the real pad.
1006 @pad: the real pad to query.
1009 <!-- ##### MACRO GST_RPAD_EVENTFUNC ##### -->
1011 Get the event function of this real pad.
1014 @pad: the real pad to query.
1017 <!-- ##### MACRO GST_RPAD_EVENTHANDLER ##### -->
1019 Get the eventhandler function of this real pad.
1022 @pad: the real pad to query.
1025 <!-- ##### MACRO GST_RPAD_GETHANDLER ##### -->
1027 Get the gethandler function of this real pad.
1030 @pad: the real pad to query.
1033 <!-- ##### MACRO GST_RPAD_CONNECTFUNC ##### -->
1035 Get the connect function of the pad
1038 @pad: the pad to query
1041 <!-- ##### MACRO GST_RPAD_GETCAPSFUNC ##### -->
1043 Get the getcaps function of this pad
1046 @pad: the pad to query
1049 <!-- ##### MACRO GST_RPAD_CONVERTFUNC ##### -->
1051 Get the convert function of this pad
1054 @pad: the pad to query
1057 <!-- ##### MACRO GST_RPAD_INTCONNFUNC ##### -->
1059 Get the internal connection function of this pad
1062 @pad: the pad to query
1065 <!-- ##### MACRO GST_RPAD_QUERYFUNC ##### -->
1067 Get the query function of this pad
1070 @pad: the pad to query
1073 <!-- ##### MACRO GST_GPAD_REALPAD ##### -->
1075 Get the real pad of this ghost pad.
1078 @pad: the real pad to query.
1081 <!-- ##### STRUCT GstGhostPad ##### -->
1087 <!-- ##### FUNCTION gst_ghost_pad_new ##### -->