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 GstPadDispatcherFunc ##### -->
237 The signature of the dispatcher callback.
240 @pad: The pad that is being dispatched
242 @Returns: TRUE if no further pads need to be processed
245 <!-- ##### USER_FUNCTION GstPadIntConnFunction ##### -->
247 The signature of the internal pad connection function
250 @pad: The pad to query
251 @Returns: a Glist of pads that connect to the requested pad internally to the
252 parent element. g_list_free() after use.
255 <!-- ##### ENUM GstPadQueryType ##### -->
257 The different supported query types
260 @GST_PAD_QUERY_TOTAL: Query the total stream time
261 @GST_PAD_QUERY_POSITION: Query the current stream position
262 @GST_PAD_QUERY_LATENCY: Query the latency on the pad
264 <!-- ##### USER_FUNCTION GstPadQueryFunction ##### -->
266 The signature of query function
269 @pad: The pad to query
270 @type: The query type
271 @format: a pointer to the target format
272 @value: a pointer to the target value
273 @Returns: TRUE if the query could be performed
276 <!-- ##### ENUM GstPadDirection ##### -->
278 The direction this pad is.
281 @GST_PAD_UNKNOWN: direction is unknown
282 @GST_PAD_SRC: this is a source pad
283 @GST_PAD_SINK: this is a sink pad
285 <!-- ##### ENUM GstPadFlags ##### -->
290 @GST_PAD_DISABLED: the pad is disabled
291 @GST_PAD_EOS: the pad is in end of stream state
292 @GST_PAD_FLAG_LAST: subclasses can use this number to enumerate their flags
294 <!-- ##### FUNCTION gst_pad_new ##### -->
304 <!-- ##### FUNCTION gst_pad_custom_new ##### -->
315 <!-- ##### FUNCTION gst_pad_custom_new_from_template ##### -->
326 <!-- ##### MACRO gst_pad_destroy ##### -->
331 @pad: the pad to destroy
334 <!-- ##### FUNCTION gst_pad_new_from_template ##### -->
342 <!-- # Unused Parameters # -->
346 <!-- ##### FUNCTION gst_pad_get_direction ##### -->
355 <!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
364 <!-- ##### FUNCTION gst_pad_set_get_function ##### -->
373 <!-- ##### FUNCTION gst_pad_set_bufferpool_function ##### -->
382 <!-- ##### FUNCTION gst_pad_set_connect_function ##### -->
391 <!-- ##### FUNCTION gst_pad_set_getcaps_function ##### -->
400 <!-- ##### FUNCTION gst_pad_try_set_caps ##### -->
410 <!-- ##### FUNCTION gst_pad_get_caps ##### -->
419 <!-- ##### FUNCTION gst_pad_check_compatibility ##### -->
429 <!-- ##### FUNCTION gst_pad_set_name ##### -->
438 <!-- ##### FUNCTION gst_pad_get_name ##### -->
447 <!-- ##### FUNCTION gst_pad_set_element_private ##### -->
456 <!-- ##### FUNCTION gst_pad_get_element_private ##### -->
465 <!-- ##### FUNCTION gst_pad_set_parent ##### -->
474 <!-- ##### FUNCTION gst_pad_get_parent ##### -->
483 <!-- ##### FUNCTION gst_pad_get_scheduler ##### -->
492 <!-- ##### FUNCTION gst_pad_set_scheduler ##### -->
501 <!-- ##### FUNCTION gst_pad_unset_scheduler ##### -->
509 <!-- ##### FUNCTION gst_pad_get_real_parent ##### -->
518 <!-- ##### FUNCTION gst_pad_add_ghost_pad ##### -->
527 <!-- ##### FUNCTION gst_pad_remove_ghost_pad ##### -->
536 <!-- ##### FUNCTION gst_pad_get_ghost_pad_list ##### -->
545 <!-- ##### FUNCTION gst_pad_get_peer ##### -->
554 <!-- ##### FUNCTION gst_pad_connect ##### -->
564 <!-- ##### FUNCTION gst_pad_connect_filtered ##### -->
575 <!-- ##### FUNCTION gst_pad_reconnect_filtered ##### -->
584 <!-- # Unused Parameters # -->
588 <!-- ##### FUNCTION gst_pad_try_reconnect_filtered ##### -->
597 <!-- # Unused Parameters # -->
601 <!-- ##### FUNCTION gst_pad_disconnect ##### -->
610 <!-- ##### FUNCTION gst_pad_can_connect ##### -->
620 <!-- ##### FUNCTION gst_pad_can_connect_filtered ##### -->
631 <!-- ##### FUNCTION gst_pad_push ##### -->
638 <!-- # Unused Parameters # -->
642 <!-- ##### FUNCTION gst_pad_pull ##### -->
651 <!-- ##### FUNCTION gst_pad_get_bufferpool ##### -->
660 <!-- ##### FUNCTION gst_pad_load_and_connect ##### -->
667 <!-- # Unused Parameters # -->
672 <!-- ##### FUNCTION gst_pad_proxy_connect ##### -->
682 <!-- ##### FUNCTION gst_pad_get_pad_template ##### -->
691 <!-- ##### FUNCTION gst_pad_get_pad_template_caps ##### -->
700 <!-- ##### FUNCTION gst_pad_get_allowed_caps ##### -->
709 <!-- ##### FUNCTION gst_pad_recalc_allowed_caps ##### -->
718 <!-- ##### FUNCTION gst_pad_perform_negotiate ##### -->
728 <!-- ##### FUNCTION gst_pad_ghost_save_thyself ##### -->
739 <!-- ##### FUNCTION gst_pad_peek ##### -->
748 <!-- ##### FUNCTION gst_pad_select ##### -->
757 <!-- ##### FUNCTION gst_pad_selectv ##### -->
767 <!-- ##### FUNCTION gst_pad_dispatcher ##### -->
778 <!-- ##### FUNCTION gst_pad_send_event ##### -->
788 <!-- ##### FUNCTION gst_pad_event_default ##### -->
798 <!-- ##### FUNCTION gst_pad_set_event_function ##### -->
807 <!-- ##### FUNCTION gst_pad_set_convert_function ##### -->
816 <!-- ##### FUNCTION gst_pad_convert ##### -->
829 <!-- ##### FUNCTION gst_pad_convert_default ##### -->
842 <!-- ##### FUNCTION gst_pad_get_internal_connections ##### -->
851 <!-- ##### FUNCTION gst_pad_get_internal_connections_default ##### -->
860 <!-- ##### FUNCTION gst_pad_set_internal_connection_function ##### -->
869 <!-- ##### FUNCTION gst_pad_set_query_function ##### -->
878 <!-- ##### FUNCTION gst_pad_query ##### -->
890 <!-- ##### FUNCTION gst_pad_query_default ##### -->
902 <!-- ##### STRUCT GstRealPad ##### -->
930 <!-- ##### MACRO GST_RPAD_SCHED ##### -->
932 Get the scheduler of this real pad.
935 @pad: the real pad to query.
938 <!-- ##### MACRO GST_RPAD_DIRECTION ##### -->
940 Get the direction of the real pad.
943 @pad: the realpad to query.
946 <!-- ##### MACRO GST_RPAD_CAPS ##### -->
948 Get the caps of the real pad.
951 @pad: the real pad to query.
954 <!-- ##### MACRO GST_RPAD_PEER ##### -->
956 Get the peer element of the real pad.
959 @pad: the real pad to query.
962 <!-- ##### MACRO GST_RPAD_BUFPEN ##### -->
964 Get the bufpen of the real pad.
967 @pad: the real pad to query.
970 <!-- ##### MACRO GST_RPAD_CHAINFUNC ##### -->
972 Get the chain function of the real pad.
975 @pad: the real pad to query.
978 <!-- ##### MACRO GST_RPAD_FILTER ##### -->
980 Get the filter from the pad
983 @pad: the pad to query
986 <!-- ##### MACRO GST_RPAD_APPFILTER ##### -->
988 Get the application filter for this pad
991 @pad: the pad to query
994 <!-- ##### MACRO GST_RPAD_GETFUNC ##### -->
996 Get get getfunction of the real pad.
999 @pad: the real pad to query.
1002 <!-- ##### MACRO GST_RPAD_BUFFERPOOLFUNC ##### -->
1004 Get the bufferpoolfunction from the real pad.
1007 @pad: the real pad to query.
1010 <!-- ##### MACRO GST_RPAD_CHAINHANDLER ##### -->
1012 Get the eventhandler function from the real pad.
1015 @pad: the real pad to query.
1018 <!-- ##### MACRO GST_RPAD_EVENTFUNC ##### -->
1020 Get the event function of this real pad.
1023 @pad: the real pad to query.
1026 <!-- ##### MACRO GST_RPAD_EVENTHANDLER ##### -->
1028 Get the eventhandler function of this real pad.
1031 @pad: the real pad to query.
1034 <!-- ##### MACRO GST_RPAD_GETHANDLER ##### -->
1036 Get the gethandler function of this real pad.
1039 @pad: the real pad to query.
1042 <!-- ##### MACRO GST_RPAD_CONNECTFUNC ##### -->
1044 Get the connect function of the pad
1047 @pad: the pad to query
1050 <!-- ##### MACRO GST_RPAD_GETCAPSFUNC ##### -->
1052 Get the getcaps function of this pad
1055 @pad: the pad to query
1058 <!-- ##### MACRO GST_RPAD_CONVERTFUNC ##### -->
1060 Get the convert function of this pad
1063 @pad: the pad to query
1066 <!-- ##### MACRO GST_RPAD_INTCONNFUNC ##### -->
1068 Get the internal connection function of this pad
1071 @pad: the pad to query
1074 <!-- ##### MACRO GST_RPAD_QUERYFUNC ##### -->
1076 Get the query function of this pad
1079 @pad: the pad to query
1082 <!-- ##### MACRO GST_GPAD_REALPAD ##### -->
1084 Get the real pad of this ghost pad.
1087 @pad: the real pad to query.
1090 <!-- ##### STRUCT GstGhostPad ##### -->
1096 <!-- ##### FUNCTION gst_ghost_pad_new ##### -->