1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 The connection between Elements
7 <!-- ##### SECTION Long_Description ##### -->
9 A #GstElement is connected to other elements via "pads", which are extremely
10 light-weight generic connections points.
11 After two pads are retrieved from an element with gst_element_get_pad(),
12 the pads can be connected with gst_pad_connect(). (For quick connections,
13 you can also use gst_element_connect(), which will make the obvious
14 connection for you if it's straightforward).
17 Pads are typically created from a #GstPadTemplate with
18 gst_pad_new_from_template().
21 Pads have #GstCaps attached to it to describe the media type they
22 are capable of dealing with.
23 gst_pad_get_caps() and gst_pad_try_set_caps() are used to
24 manipulate the caps of the pads.
25 Pads created from a pad template cannot set capabilities that are
26 incompatible with the pad template capabilities.
29 Pads without pad templates can be created with gst_pad_new(),
30 which takes a direction and a name as an argument. If the name is NULL,
31 then a guaranteed unique name will be assigned to it.
34 gst_pad_get_parent() will retrieve the #GstElement that owns the pad.
37 A #GstElement creating a pad will typically use the various
38 gst_pad_set_*_function() calls to register callbacks for various events
42 GstElements will use gst_pad_push() and gst_pad_pull() to push out
44 The gst_pad_pullregion() function can be used to request for a buffer
45 with a specific offset (in time or in bytes).
46 gst_pad_select() and gst_pad_selectv() are used by plugins to wait for the
47 first incoming buffer or event on any of the given set of pads.
50 To send a #GstEvent on a pad, use gst_pad_send_event().
54 Last reviewed on September 1st, 2002 (0.4.0.1)
57 <!-- ##### SECTION See_Also ##### -->
59 #GstPadTemplate, #GstElement, #GstEvent
62 <!-- ##### MACRO GST_PAD_NAME ##### -->
64 Gets the name of the pad.
67 @pad: a #GstPad to get the name of.
68 @Returns: the pad's name.
71 <!-- ##### MACRO GST_PAD_ELEMENT_PRIVATE ##### -->
73 Gets the private data set by the element that owns the pad.
76 @pad: a #GstPad to get the private data of.
77 #Returns: a gpointer to the private data.
80 <!-- ##### MACRO GST_PAD_PARENT ##### -->
82 Gets the parent element of this pad.
85 @pad: a #GstPad to get the parent of.
86 @Returns: the parent #GstElement of this pad.
89 <!-- ##### MACRO GST_PAD_PAD_TEMPLATE ##### -->
91 Gets the pad template that was used to create this pad.
94 @pad: a #GstPad to get the pad template of.
95 #Returns: the #GstPadTemplate used to create the pad, or NULL if none was
99 <!-- ##### MACRO GST_PAD_REALIZE ##### -->
101 Returns the real pad of this pad.
104 @pad: a #GstPad to realize.
105 @Returns: the actual #GstPad.
108 <!-- ##### MACRO GST_PAD_DIRECTION ##### -->
110 Gets the pad's direction.
113 @pad: a #GstPad to get the direction of.
114 @Returns: the #GstPadDirection of the pad.
117 <!-- ##### MACRO GST_PAD_CAPS ##### -->
119 Gets the capabilities of a pad.
122 @pad: a #GstPad to get the capabilities of.
123 @Returns: the #GstCaps of the pad.
126 <!-- ##### MACRO GST_PAD_PEER ##### -->
128 Gets the peer pad of this pad. The peer pad is the pad on to which the parent
129 element is connected through this pad.
132 @pad: a #GstPad to get the peer pad of.
133 @Returns: the peer #GstPad.
136 <!-- ##### MACRO GST_PAD_CAN_PULL ##### -->
138 Checks if buffers can be pulled from this buffer.
141 @pad: a #GstPad to check on if a buffer can be pulled from it.
144 <!-- ##### MACRO GST_PAD_IS_SINK ##### -->
146 Checks if the pad is a sink pad.
149 @pad: a #GstPad to check.
152 <!-- ##### MACRO GST_PAD_IS_SRC ##### -->
154 Checks if the pad is a source pad.
157 @pad: a #GstPad to check.
160 <!-- ##### MACRO GST_PAD_IS_CONNECTED ##### -->
162 Checks if the pad is connected.
165 @pad: a #GstPad to check.
168 <!-- ##### STRUCT GstPad ##### -->
174 <!-- ##### USER_FUNCTION GstPadChainFunction ##### -->
176 A function that will be called when chaining buffers.
179 @pad: the #GstPad that performed the chain.
180 @buf: the #GstBuffer that is chained.
183 <!-- ##### USER_FUNCTION GstPadGetFunction ##### -->
185 A function that will be called when pulling a buffer.
188 @pad: the #GstPad to get a buffer from.
189 @Returns: the #GstBuffer pulled.
192 <!-- ##### USER_FUNCTION GstPadBufferPoolFunction ##### -->
194 A function that will be called when a buffer pool is requested
198 @pad: the #GstPad to which the buffer pool is associated.
199 @Returns: the #GstBufferPool associated with this pad.
202 <!-- ##### USER_FUNCTION GstPadGetCapsFunction ##### -->
204 Returns the capabilities of the specified pad. By default this function
205 will return the pad template capabilities, but can optionally be overridden.
208 @pad: the #GstPad to get the capabilities of.
209 @caps: the peer's #GstCaps, can be used to filter the capabilities.
210 @Returns: the #GstCaps of the pad.
213 <!-- ##### USER_FUNCTION GstPadEventFunction ##### -->
215 Function signature to handle an event for the pad.
218 @pad: the #GstPad to handle the event.
219 @event: the #GstEvent to handle.
220 @Returns: TRUE if the pad could handle the event.
223 <!-- ##### USER_FUNCTION GstPadConnectFunction ##### -->
225 Function signature to handle a new connection on the pad.
228 @pad: the #GstPad that is connected.
229 @caps: the peer's #GstCaps.
230 @Returns: the result of the connection with the specified caps.
233 <!-- ##### ENUM GstPadConnectReturn ##### -->
235 The result of a pad connection.
238 @GST_PAD_CONNECT_REFUSED: the connection was refused.
239 @GST_PAD_CONNECT_DELAYED: the connection was delayed, probably because the
240 element needs more specific pad capabilitiess.
241 @GST_PAD_CONNECT_OK: the connection succeeded.
242 @GST_PAD_CONNECT_DONE: the connection succeeded,
243 any more attempts are not needed.
245 <!-- ##### USER_FUNCTION GstPadConvertFunction ##### -->
247 The signature of a convert function.
250 @pad: the #GstPad to perform the convert on.
251 @src_format: the source #GstFormat of the conversion.
252 @src_value: the source value of the conversion.
253 @dest_format: a pointer to the destination #GstFormat.
254 @dest_value: a pointer to the destination value.
255 @Returns: TRUE if the conversion could be performed.
258 <!-- ##### USER_FUNCTION GstPadDispatcherFunction ##### -->
260 A dispatcher function is called for all internally connected pads, see
261 gst_pad_dispatcher().
264 @pad: the #GstPad that is dispatched.
265 @data: the gpointer to optional user data.
266 @Returns: TRUE if the dispatching procedure has to be stopped.
269 <!-- ##### USER_FUNCTION GstPadIntConnFunction ##### -->
271 The signature of the internal pad connection function.
274 @pad: The #GstPad to query.
275 @Returns: a newly allocated #GList of pads that are connected to
276 the given pad on the inside of the parent element.
277 The caller must call g_list_free() on it after use.
280 <!-- ##### ENUM GstPadQueryType ##### -->
282 The different supported query types.
286 @GST_PAD_QUERY_TOTAL: Query the total stream time.
287 @GST_PAD_QUERY_POSITION: Query the current stream position.
288 @GST_PAD_QUERY_LATENCY: Query the latency on the pad.
289 @GST_PAD_QUERY_JITTER: Query the average jitter beteen optimal processing
290 and current processing.
291 @GST_PAD_QUERY_START:
292 @GST_PAD_QUERY_SEGMENT_END: Query the end position of the currently
296 <!-- ##### USER_FUNCTION GstPadQueryFunction ##### -->
298 The signature of the query function.
301 @pad: the #GstPad to query.
302 @type: the #GstPadQueryType.
303 @format: a pointer to the target #GstFormat.
304 @value: a pointer to the target value.
305 @Returns: TRUE if the query could be performed.
308 <!-- ##### ENUM GstPadDirection ##### -->
310 The direction of a pad.
313 @GST_PAD_UNKNOWN: direction is unknown.
314 @GST_PAD_SRC: the pad is a source pad.
315 @GST_PAD_SINK: the pad is a sink pad.
317 <!-- ##### ENUM GstPadFlags ##### -->
322 @GST_PAD_DISABLED: the pad is disabled.
323 @GST_PAD_EOS: the pad is in end of stream state.
324 @GST_PAD_FLAG_LAST: subclasses can use this number to enumerate their flags.
326 <!-- ##### FUNCTION gst_pad_new ##### -->
336 <!-- ##### FUNCTION gst_pad_custom_new ##### -->
347 <!-- ##### FUNCTION gst_pad_custom_new_from_template ##### -->
358 <!-- ##### MACRO gst_pad_destroy ##### -->
363 @pad: the pad to destroy
366 <!-- ##### FUNCTION gst_pad_new_from_template ##### -->
374 <!-- # Unused Parameters # -->
378 <!-- ##### FUNCTION gst_pad_get_direction ##### -->
387 <!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
396 <!-- ##### FUNCTION gst_pad_set_get_function ##### -->
405 <!-- ##### FUNCTION gst_pad_set_bufferpool_function ##### -->
414 <!-- ##### FUNCTION gst_pad_set_connect_function ##### -->
423 <!-- ##### FUNCTION gst_pad_set_getcaps_function ##### -->
432 <!-- ##### FUNCTION gst_pad_try_set_caps ##### -->
442 <!-- ##### FUNCTION gst_pad_get_caps ##### -->
451 <!-- ##### FUNCTION gst_pad_check_compatibility ##### -->
461 <!-- ##### FUNCTION gst_pad_set_name ##### -->
470 <!-- ##### FUNCTION gst_pad_get_name ##### -->
479 <!-- ##### FUNCTION gst_pad_set_element_private ##### -->
488 <!-- ##### FUNCTION gst_pad_get_element_private ##### -->
497 <!-- ##### FUNCTION gst_pad_set_parent ##### -->
506 <!-- ##### FUNCTION gst_pad_get_parent ##### -->
515 <!-- ##### FUNCTION gst_pad_get_scheduler ##### -->
524 <!-- ##### FUNCTION gst_pad_get_real_parent ##### -->
533 <!-- ##### FUNCTION gst_pad_add_ghost_pad ##### -->
542 <!-- ##### FUNCTION gst_pad_remove_ghost_pad ##### -->
551 <!-- ##### FUNCTION gst_pad_get_ghost_pad_list ##### -->
560 <!-- ##### FUNCTION gst_pad_get_peer ##### -->
569 <!-- ##### FUNCTION gst_pad_connect ##### -->
579 <!-- ##### FUNCTION gst_pad_connect_filtered ##### -->
590 <!-- ##### FUNCTION gst_pad_reconnect_filtered ##### -->
599 <!-- # Unused Parameters # -->
603 <!-- ##### FUNCTION gst_pad_try_reconnect_filtered ##### -->
612 <!-- # Unused Parameters # -->
616 <!-- ##### FUNCTION gst_pad_disconnect ##### -->
625 <!-- ##### FUNCTION gst_pad_can_connect ##### -->
635 <!-- ##### FUNCTION gst_pad_can_connect_filtered ##### -->
646 <!-- ##### FUNCTION gst_pad_push ##### -->
653 <!-- # Unused Parameters # -->
657 <!-- ##### FUNCTION gst_pad_pull ##### -->
666 <!-- ##### FUNCTION gst_pad_get_bufferpool ##### -->
675 <!-- ##### FUNCTION gst_pad_load_and_connect ##### -->
682 <!-- # Unused Parameters # -->
687 <!-- ##### FUNCTION gst_pad_proxy_connect ##### -->
697 <!-- ##### FUNCTION gst_pad_get_pad_template ##### -->
706 <!-- ##### FUNCTION gst_pad_get_pad_template_caps ##### -->
715 <!-- ##### FUNCTION gst_pad_get_allowed_caps ##### -->
724 <!-- ##### FUNCTION gst_pad_recalc_allowed_caps ##### -->
733 <!-- ##### FUNCTION gst_pad_perform_negotiate ##### -->
743 <!-- ##### FUNCTION gst_pad_select ##### -->
752 <!-- ##### FUNCTION gst_pad_selectv ##### -->
762 <!-- ##### FUNCTION gst_pad_dispatcher ##### -->
773 <!-- ##### FUNCTION gst_pad_send_event ##### -->
783 <!-- ##### FUNCTION gst_pad_event_default ##### -->
793 <!-- ##### FUNCTION gst_pad_set_event_function ##### -->
802 <!-- ##### FUNCTION gst_pad_set_convert_function ##### -->
811 <!-- ##### FUNCTION gst_pad_convert ##### -->
824 <!-- ##### FUNCTION gst_pad_convert_default ##### -->
837 <!-- ##### FUNCTION gst_pad_get_internal_connections ##### -->
846 <!-- ##### FUNCTION gst_pad_get_internal_connections_default ##### -->
855 <!-- ##### FUNCTION gst_pad_set_internal_connection_function ##### -->
864 <!-- ##### FUNCTION gst_pad_set_query_function ##### -->
873 <!-- ##### FUNCTION gst_pad_query ##### -->
885 <!-- ##### FUNCTION gst_pad_query_default ##### -->
897 <!-- ##### STRUCT GstRealPad ##### -->
927 <!-- ##### MACRO GST_RPAD_DIRECTION ##### -->
929 Get the direction of the real pad.
932 @pad: the realpad to query.
935 <!-- ##### MACRO GST_RPAD_CAPS ##### -->
937 Get the caps of the real pad.
940 @pad: the real pad to query.
943 <!-- ##### MACRO GST_RPAD_PEER ##### -->
945 Get the peer element of the real pad.
948 @pad: the real pad to query.
951 <!-- ##### MACRO GST_RPAD_CHAINFUNC ##### -->
953 Get the chain function of the real pad.
956 @pad: the real pad to query.
959 <!-- ##### MACRO GST_RPAD_FILTER ##### -->
961 Get the filter from the pad
964 @pad: the pad to query
967 <!-- ##### MACRO GST_RPAD_APPFILTER ##### -->
969 Get the application filter for this pad
972 @pad: the pad to query
975 <!-- ##### MACRO GST_RPAD_GETFUNC ##### -->
977 Get get getfunction of the real pad.
980 @pad: the real pad to query.
983 <!-- ##### MACRO GST_RPAD_BUFFERPOOLFUNC ##### -->
985 Get the bufferpoolfunction from the real pad.
988 @pad: the real pad to query.
991 <!-- ##### MACRO GST_RPAD_CHAINHANDLER ##### -->
993 Get the eventhandler function from the real pad.
996 @pad: the real pad to query.
999 <!-- ##### MACRO GST_RPAD_EVENTFUNC ##### -->
1001 Get the event function of this real pad.
1004 @pad: the real pad to query.
1007 <!-- ##### MACRO GST_RPAD_EVENTHANDLER ##### -->
1009 Get the eventhandler function of this real pad.
1012 @pad: the real pad to query.
1015 <!-- ##### MACRO GST_RPAD_GETHANDLER ##### -->
1017 Get the gethandler function of this real pad.
1020 @pad: the real pad to query.
1023 <!-- ##### MACRO GST_RPAD_CONNECTFUNC ##### -->
1025 Get the connect function of the pad
1028 @pad: the pad to query
1031 <!-- ##### MACRO GST_RPAD_GETCAPSFUNC ##### -->
1033 Get the getcaps function of this pad
1036 @pad: the pad to query
1039 <!-- ##### MACRO GST_RPAD_CONVERTFUNC ##### -->
1041 Get the convert function of this pad
1044 @pad: the pad to query
1047 <!-- ##### MACRO GST_RPAD_INTCONNFUNC ##### -->
1049 Get the internal connection function of this pad
1052 @pad: the pad to query
1055 <!-- ##### MACRO GST_RPAD_QUERYFUNC ##### -->
1057 Get the query function of this pad
1060 @pad: the pad to query
1063 <!-- ##### MACRO GST_GPAD_REALPAD ##### -->
1065 Get the real pad of this ghost pad.
1068 @pad: the real pad to query.
1071 <!-- ##### STRUCT GstGhostPad ##### -->
1077 <!-- ##### FUNCTION gst_ghost_pad_new ##### -->