1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Object contained by elements that allows links to other elements
7 <!-- ##### SECTION Long_Description ##### -->
9 A #GstElement is linked to other elements via "pads", which are extremely
10 light-weight generic link points.
11 After two pads are retrieved from an element with gst_element_get_pad(),
12 the pads can be link with gst_pad_link(). (For quick links,
13 you can also use gst_element_link(), which will make the obvious
14 link 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 gst_pad_select() and gst_pad_selectv() are used by plugins to wait for the
45 first incoming buffer or event on any of the given set of pads.
48 To send a #GstEvent on a pad, use gst_pad_send_event().
52 Last reviewed on December 13th, 2002 (0.5.0.1)
55 <!-- ##### SECTION See_Also ##### -->
57 #GstPadTemplate, #GstElement, #GstEvent
60 <!-- ##### STRUCT GstPad ##### -->
96 <!-- ##### SIGNAL GstPad::have-data ##### -->
101 @gstpad: the object which received the signal.
105 <!-- ##### SIGNAL GstPad::linked ##### -->
110 @gstpad: the object which received the signal.
113 <!-- ##### SIGNAL GstPad::request-link ##### -->
118 @gstpad: the object which received the signal.
120 <!-- ##### SIGNAL GstPad::unlinked ##### -->
125 @gstpad: the object which received the signal.
128 <!-- ##### ARG GstPad:caps ##### -->
133 <!-- ##### ARG GstPad:direction ##### -->
138 <!-- ##### ARG GstPad:template ##### -->
143 <!-- ##### MACRO GST_PAD_LINK_FAILED ##### -->
145 Macro to test if the given #GstPadLinkReturn value indicates a
146 failed negotiation step (REFUSED/DELAYED).
149 @ret: the #GstPadLinkReturn value
152 <!-- ##### MACRO GST_PAD_LINK_SUCCESSFUL ##### -->
154 Macro to test if the given #GstPadLinkReturn value indicates a
155 successfull negotiation step (OK/DONE).
158 @ret: the #GstPadLinkReturn value
161 <!-- ##### USER_FUNCTION GstPadActivateFunction ##### -->
170 <!-- ##### USER_FUNCTION GstPadActivateModeFunction ##### -->
180 <!-- ##### USER_FUNCTION GstPadBlockCallback ##### -->
190 <!-- ##### USER_FUNCTION GstPadChainFunction ##### -->
192 A function that will be called when chaining buffers.
195 @pad: the #GstPad that performed the chain.
198 <!-- # Unused Parameters # -->
200 @buf: the #GstBuffer that is chained.
203 <!-- ##### USER_FUNCTION GstPadEventFunction ##### -->
205 Function signature to handle an event for the pad.
208 @pad: the #GstPad to handle the event.
209 @event: the #GstEvent to handle.
210 @Returns: TRUE if the pad could handle the event.
213 <!-- ##### USER_FUNCTION GstPadCheckGetRangeFunction ##### -->
222 <!-- ##### USER_FUNCTION GstPadGetRangeFunction ##### -->
234 <!-- ##### USER_FUNCTION GstPadQueryFunction ##### -->
236 The signature of the query function.
239 @pad: the #GstPad to query.
241 @Returns: TRUE if the query could be performed.
242 <!-- # Unused Parameters # -->
243 @type: the #GstPadQueryType.
244 @format: a pointer to the target #GstFormat.
245 @value: a pointer to the target value.
248 <!-- ##### USER_FUNCTION GstPadIntLinkFunction ##### -->
250 The signature of the internal pad link function.
253 @pad: The #GstPad to query.
254 @Returns: a newly allocated #GList of pads that are linked to
255 the given pad on the inside of the parent element.
256 The caller must call g_list_free() on it after use.
259 <!-- ##### USER_FUNCTION GstPadQueryTypeFunction ##### -->
261 The signature of the query types function.
264 @pad: a #GstPad to query
265 @Returns: an array of query types
268 <!-- ##### USER_FUNCTION GstPadLinkFunction ##### -->
270 Function signature to handle a new link on the pad.
273 @pad: the #GstPad that is linked.
275 @Returns: the result of the link with the specified caps.
276 <!-- # Unused Parameters # -->
277 @caps: the peer's #GstCaps.
280 <!-- ##### USER_FUNCTION GstPadUnlinkFunction ##### -->
288 <!-- ##### USER_FUNCTION GstPadAcceptCapsFunction ##### -->
298 <!-- ##### USER_FUNCTION GstPadFixateCapsFunction ##### -->
307 <!-- ##### USER_FUNCTION GstPadGetCapsFunction ##### -->
309 Returns a copy of the capabilities of the specified pad. By default this
310 function will return the pad template capabilities, but can optionally
314 @pad: the #GstPad to get the capabilities of.
315 @Returns: a newly allocated copy #GstCaps of the pad.
316 <!-- # Unused Parameters # -->
317 @caps: the peer's #GstCaps, can be used to filter the capabilities.
320 <!-- ##### USER_FUNCTION GstPadSetCapsFunction ##### -->
330 <!-- ##### USER_FUNCTION GstPadBufferAllocFunction ##### -->
343 <!-- ##### USER_FUNCTION GstPadDispatcherFunction ##### -->
345 A dispatcher function is called for all internally linked pads, see
346 gst_pad_dispatcher().
349 @pad: the #GstPad that is dispatched.
350 @data: the gpointer to optional user data.
351 @Returns: TRUE if the dispatching procedure has to be stopped.
354 <!-- ##### ENUM GstPadDirection ##### -->
356 The direction of a pad.
359 @GST_PAD_UNKNOWN: direction is unknown.
360 @GST_PAD_SRC: the pad is a source pad.
361 @GST_PAD_SINK: the pad is a sink pad.
363 <!-- ##### ENUM GstPadFlags ##### -->
374 <!-- ##### ENUM GstPadLinkReturn ##### -->
378 @GST_PAD_LINK_WRONG_HIERARCHY:
379 @GST_PAD_LINK_WAS_LINKED:
380 @GST_PAD_LINK_WRONG_DIRECTION:
381 @GST_PAD_LINK_NOFORMAT:
382 @GST_PAD_LINK_NOSCHED:
383 @GST_PAD_LINK_REFUSED:
385 <!-- ##### ENUM GstPadPresence ##### -->
387 Indicates when this pad will become available.
390 @GST_PAD_ALWAYS: the pad is always available
391 @GST_PAD_SOMETIMES: the pad will become available depending on the media stream
392 @GST_PAD_REQUEST: the pad is only available on request with
393 gst_element_request_pad_by_name() or gst_element_request_compatible_pad().
395 <!-- ##### ENUM GstFlowReturn ##### -->
402 @GST_FLOW_NOT_LINKED:
403 @GST_FLOW_WRONG_STATE:
404 @GST_FLOW_UNEXPECTED:
405 @GST_FLOW_NOT_NEGOTIATED:
407 @GST_FLOW_NOT_SUPPORTED:
409 <!-- ##### ENUM GstActivateMode ##### -->
418 <!-- ##### MACRO GST_PREROLL_BROADCAST ##### -->
426 <!-- ##### MACRO GST_PREROLL_GET_COND ##### -->
434 <!-- ##### MACRO GST_PREROLL_GET_LOCK ##### -->
442 <!-- ##### MACRO GST_PREROLL_LOCK ##### -->
450 <!-- ##### MACRO GST_PREROLL_SIGNAL ##### -->
458 <!-- ##### MACRO GST_PREROLL_TIMED_WAIT ##### -->
467 <!-- ##### MACRO GST_PREROLL_TRYLOCK ##### -->
475 <!-- ##### MACRO GST_PREROLL_UNLOCK ##### -->
483 <!-- ##### MACRO GST_PREROLL_WAIT ##### -->
491 <!-- ##### MACRO GST_STREAM_GET_LOCK ##### -->
499 <!-- ##### MACRO GST_STREAM_LOCK ##### -->
507 <!-- ##### MACRO GST_STREAM_LOCK_FULL ##### -->
516 <!-- ##### MACRO GST_STREAM_TRYLOCK ##### -->
524 <!-- ##### MACRO GST_STREAM_UNLOCK ##### -->
532 <!-- ##### MACRO GST_STREAM_UNLOCK_FULL ##### -->
540 <!-- ##### MACRO GST_FLOW_IS_FATAL ##### -->
548 <!-- ##### FUNCTION gst_pad_new ##### -->
558 <!-- ##### FUNCTION gst_pad_new_from_template ##### -->
568 <!-- ##### MACRO gst_pad_get_name ##### -->
577 <!-- ##### FUNCTION gst_pad_get_direction ##### -->
586 <!-- ##### MACRO gst_pad_get_parent ##### -->
595 <!-- ##### FUNCTION gst_pad_get_parent_element ##### -->
604 <!-- ##### FUNCTION gst_pad_set_active ##### -->
612 <!-- # Unused Parameters # -->
616 <!-- ##### FUNCTION gst_pad_is_active ##### -->
625 <!-- ##### FUNCTION gst_pad_set_blocked ##### -->
635 <!-- ##### FUNCTION gst_pad_set_blocked_async ##### -->
647 <!-- ##### FUNCTION gst_pad_is_blocked ##### -->
656 <!-- ##### FUNCTION gst_pad_set_element_private ##### -->
665 <!-- ##### FUNCTION gst_pad_get_element_private ##### -->
674 <!-- ##### FUNCTION gst_pad_get_pad_template ##### -->
683 <!-- ##### FUNCTION gst_pad_set_bufferalloc_function ##### -->
690 <!-- # Unused Parameters # -->
694 <!-- ##### FUNCTION gst_pad_alloc_buffer ##### -->
707 <!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
716 <!-- ##### FUNCTION gst_pad_chain ##### -->
726 <!-- ##### FUNCTION gst_pad_set_checkgetrange_function ##### -->
735 <!-- ##### FUNCTION gst_pad_set_getrange_function ##### -->
744 <!-- ##### FUNCTION gst_pad_get_range ##### -->
756 <!-- ##### FUNCTION gst_pad_set_event_function ##### -->
765 <!-- ##### FUNCTION gst_pad_set_unlink_function ##### -->
774 <!-- ##### FUNCTION gst_pad_set_activate_function ##### -->
783 <!-- ##### FUNCTION gst_pad_set_activatepull_function ##### -->
792 <!-- ##### FUNCTION gst_pad_start_task ##### -->
803 <!-- ##### FUNCTION gst_pad_pause_task ##### -->
812 <!-- ##### FUNCTION gst_pad_stop_task ##### -->
821 <!-- ##### FUNCTION gst_pad_link ##### -->
831 <!-- ##### FUNCTION gst_pad_unlink ##### -->
841 <!-- ##### FUNCTION gst_pad_is_linked ##### -->
850 <!-- ##### FUNCTION gst_pad_set_link_function ##### -->
859 <!-- ##### FUNCTION gst_pad_can_link ##### -->
869 <!-- ##### FUNCTION gst_pad_accept_caps ##### -->
879 <!-- ##### FUNCTION gst_pad_get_negotiated_caps ##### -->
888 <!-- ##### FUNCTION gst_pad_get_caps ##### -->
897 <!-- ##### FUNCTION gst_pad_set_caps ##### -->
907 <!-- ##### FUNCTION gst_pad_get_pad_template_caps ##### -->
916 <!-- ##### FUNCTION gst_pad_set_acceptcaps_function ##### -->
925 <!-- ##### FUNCTION gst_pad_set_getcaps_function ##### -->
934 <!-- ##### FUNCTION gst_pad_set_setcaps_function ##### -->
943 <!-- ##### FUNCTION gst_pad_proxy_getcaps ##### -->
952 <!-- ##### FUNCTION gst_pad_proxy_setcaps ##### -->
962 <!-- ##### FUNCTION gst_pad_get_allowed_caps ##### -->
969 <!-- # Unused Parameters # -->
973 <!-- ##### FUNCTION gst_pad_get_fixed_caps_func ##### -->
982 <!-- ##### FUNCTION gst_pad_get_peer ##### -->
991 <!-- ##### FUNCTION gst_pad_peer_get_caps ##### -->
1000 <!-- ##### FUNCTION gst_pad_peer_accept_caps ##### -->
1010 <!-- ##### FUNCTION gst_pad_use_fixed_caps ##### -->
1018 <!-- ##### FUNCTION gst_pad_fixate_caps ##### -->
1027 <!-- ##### FUNCTION gst_pad_set_fixatecaps_function ##### -->
1036 <!-- ##### FUNCTION gst_pad_set_activatepush_function ##### -->
1045 <!-- ##### FUNCTION gst_pad_push ##### -->
1053 <!-- # Unused Parameters # -->
1058 <!-- ##### FUNCTION gst_pad_push_event ##### -->
1068 <!-- ##### FUNCTION gst_pad_check_pull_range ##### -->
1077 <!-- ##### FUNCTION gst_pad_pull_range ##### -->
1089 <!-- ##### FUNCTION gst_pad_activate_pull ##### -->
1099 <!-- ##### FUNCTION gst_pad_activate_push ##### -->
1109 <!-- ##### FUNCTION gst_pad_send_event ##### -->
1119 <!-- ##### FUNCTION gst_pad_event_default ##### -->
1129 <!-- ##### FUNCTION gst_pad_set_query_function ##### -->
1138 <!-- ##### FUNCTION gst_pad_set_query_type_function ##### -->
1147 <!-- ##### FUNCTION gst_pad_get_query_types ##### -->
1156 <!-- ##### FUNCTION gst_pad_get_query_types_default ##### -->
1165 <!-- ##### FUNCTION gst_pad_query ##### -->
1173 <!-- # Unused Parameters # -->
1179 <!-- ##### FUNCTION gst_pad_query_default ##### -->
1187 <!-- # Unused Parameters # -->
1193 <!-- ##### FUNCTION gst_pad_query_position ##### -->
1205 <!-- ##### FUNCTION gst_pad_query_convert ##### -->
1216 <!-- # Unused Parameters # -->
1220 <!-- ##### FUNCTION gst_pad_set_internal_link_function ##### -->
1229 <!-- ##### FUNCTION gst_pad_get_internal_links ##### -->
1238 <!-- ##### FUNCTION gst_pad_get_internal_links_default ##### -->
1247 <!-- ##### FUNCTION gst_pad_dispatcher ##### -->
1258 <!-- ##### FUNCTION gst_pad_load_and_link ##### -->
1267 <!-- ##### FUNCTION gst_pad_add_data_probe ##### -->
1278 <!-- ##### FUNCTION gst_pad_add_buffer_probe ##### -->
1289 <!-- ##### FUNCTION gst_pad_add_event_probe ##### -->
1300 <!-- ##### FUNCTION gst_pad_remove_data_probe ##### -->
1310 <!-- ##### FUNCTION gst_pad_remove_buffer_probe ##### -->
1320 <!-- ##### FUNCTION gst_pad_remove_event_probe ##### -->