1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Abstract base class for all pipeline elements
7 <!-- ##### SECTION Long_Description ##### -->
9 GstElement is the base class needed to construct an element that can be
10 used in a GStreamer pipeline. As such, it is not a functional entity, and
11 cannot do anything when placed in a pipeline.
15 The name of a GstElement can be get with gst_element_get_name() and set with
16 gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the
18 Do not use this in plug-ins or applications in order to retain ABI
23 All elements have pads (of the type #GstPad). These pads link to pads on
24 other elements. Buffers flow between these linked pads.
25 A GstElement has a GList of #GstPad structures for all their input (or sink)
26 and output (or source) pads.
27 Core and plug-in writers can add and remove pads with gst_element_add_pad()
28 and gst_element_remove_pad().
29 Application writers can manipulate ghost pads (copies of real pads inside a bin)
30 with gst_element_add_ghost_pad() and gst_element_remove_ghost_pad().
31 A pad of an element can be retrieved by name with gst_element_get_pad().
32 A GList of all pads can be retrieved with gst_element_get_pad_list().
36 Elements can be linked through their pads.
37 If the link is straightforward, use the gst_element_link()
38 convenience function to link two elements, or gst_element_link_many()
39 for more elements in a row.
40 Use gst_element_link_filtered() to link two elements constrained by
41 a specified set of #GstCaps.
42 For finer control, use gst_element_link_pads() and
43 gst_element_link_pads_filtered() to specify the pads to link on
48 Each element has a state (see #GstElementState). You can get and set the state
49 of an element with gst_element_get_state() and gst_element_set_state().
50 You can wait for an element to change it's state with gst_element_wait_state_change().
51 To get a string representation of a #GstElementState, use
52 gst_element_state_get_name().
56 You can get and set a #GstClock on an element using gst_element_get_clock()
57 and gst_element_set_clock(). You can wait for the clock to reach a given
58 #GstClockTime using gst_element_clock_wait().
61 <!-- ##### SECTION See_Also ##### -->
63 #GstElementFactory, #GstPad
66 <!-- basic object functions -->
68 <!-- ##### STRUCT GstElement ##### -->
74 <!-- ##### SIGNAL GstElement::eos ##### -->
81 @gstelement: the object which received the signal.
83 <!-- ##### SIGNAL GstElement::error ##### -->
93 @gstelement: the object which received the signal.
98 <!-- ##### SIGNAL GstElement::found-tag ##### -->
107 @gstelement: the object which received the signal.
111 <!-- ##### SIGNAL GstElement::new-pad ##### -->
119 @gstelement: the object which received the signal.
122 <!-- ##### SIGNAL GstElement::no-more-pads ##### -->
129 @gstelement: the object which received the signal.
131 <!-- ##### SIGNAL GstElement::pad-removed ##### -->
139 @gstelement: the object which received the signal.
142 <!-- ##### SIGNAL GstElement::state-change ##### -->
151 @gstelement: the object which received the signal.
155 <!-- ##### MACRO GST_TYPE_ELEMENT ##### -->
162 <!-- ##### MACRO GST_NUM_STATES ##### -->
164 The maximun number of states.
169 <!-- ##### MACRO GST_STATE ##### -->
171 This macro returns the current state of the element.
174 @obj: Element to return state for.
177 <!-- ##### MACRO GST_STATE_PENDING ##### -->
179 This macro returns the currently pending state of the element.
182 @obj: Element to return the pending state for.
185 <!-- ##### MACRO GST_STATE_TRANSITION ##### -->
187 Returns the state transition this object is going through.
190 @obj: the Element to return the state transition for
193 <!-- ##### MACRO GST_STATE_NULL_TO_READY ##### -->
195 The Element is going from the NULL state to the READY state.
200 <!-- ##### MACRO GST_STATE_READY_TO_PAUSED ##### -->
202 The Element is going from the READY state to the PAUSED state.
207 <!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### -->
209 The Element is going from the PAUSED state to the PLAYING state.
214 <!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### -->
216 The Element is going from the PLAYING state to the PAUSED state.
221 <!-- ##### MACRO GST_STATE_PAUSED_TO_READY ##### -->
223 The Element is going from the PAUSED state to the READY state.
228 <!-- ##### MACRO GST_STATE_READY_TO_NULL ##### -->
230 The Element is going from the READY state to the NULL state.
235 <!-- ##### MACRO GST_ELEMENT_QUERY_TYPE_FUNCTION ##### -->
237 Helper macro to create query type functions
240 @functionname: The function name
241 @...: list of query types.
244 <!-- ##### MACRO GST_ELEMENT_FORMATS_FUNCTION ##### -->
246 Halper macro to create element format functions
249 @functionname: The function name
253 <!-- ##### MACRO GST_ELEMENT_EVENT_MASK_FUNCTION ##### -->
255 A helper macro to create a mask function
258 @functionname: the name of the mask function
262 <!-- ##### ENUM GstElementFlags ##### -->
264 This enum defines the standard flags that an element may have.
267 @GST_ELEMENT_COMPLEX:
268 @GST_ELEMENT_DECOUPLED:
269 @GST_ELEMENT_THREAD_SUGGESTED:
270 @GST_ELEMENT_INFINITE_LOOP:
271 @GST_ELEMENT_NEW_LOOPFUNC:
272 @GST_ELEMENT_EVENT_AWARE:
273 @GST_ELEMENT_USE_THREADSAFE_PROPERTIES:
274 @GST_ELEMENT_SCHEDULER_PRIVATE1:
275 @GST_ELEMENT_SCHEDULER_PRIVATE2:
276 @GST_ELEMENT_LOCKED_STATE:
277 @GST_ELEMENT_IN_ERROR:
278 @GST_ELEMENT_FLAG_LAST:
280 <!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### -->
282 Queries whether the Element should be placed in a thread.
285 @obj: a #GstElement to query
288 <!-- ##### MACRO GST_ELEMENT_IS_EVENT_AWARE ##### -->
290 Query wether this element can handle events.
293 @obj: a #GstElement to query
296 <!-- ##### MACRO GST_ELEMENT_IS_DECOUPLED ##### -->
298 Queries if the Element is decoupled.
301 @obj: a #GstElement to query
304 <!-- ##### MACRO GST_ELEMENT_NAME ##### -->
306 Gets the name of this element. Used in the core. Not ABI-compatible.
309 @obj: A #GstElement to query
312 <!-- ##### MACRO GST_ELEMENT_PARENT ##### -->
314 Get the parent object of this element.
317 @obj: a #GstElement to query
320 <!-- ##### MACRO GST_ELEMENT_SCHED ##### -->
322 Get the scheduler of this element.
325 @obj: a #GstElement to query
328 <!-- ##### MACRO GST_ELEMENT_CLOCK ##### -->
330 Get the clock of this element
333 @obj: a #GstElement to query
336 <!-- ##### MACRO GST_ELEMENT_PADS ##### -->
338 Get the pads of this elements.
341 @obj: a #GstElement to query
344 <!-- ##### MACRO GST_ELEMENT_ERROR ##### -->
346 Utility function that elements can use in case they encountered a fatal
347 data processing error. The pipeline will throw an error signal and the
348 application will be requested to stop further media processing.
351 @el: the element that throws the error
354 @message: the message to display
358 <!-- ##### USER_FUNCTION GstElementLoopFunction ##### -->
360 This function type is used to specify a loop function for the element. It
361 is passed the element in question, and is expect to return only in error
365 @element: The element in question.
368 <!-- ##### USER_FUNCTION GstElementPreRunFunction ##### -->
370 The signature of the function to execute after this element
374 @element: The element
377 <!-- ##### USER_FUNCTION GstElementPostRunFunction ##### -->
379 The signature of the function to execute before this element
383 @element: The element
386 <!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
395 <!-- ##### FUNCTION gst_element_class_install_std_props ##### -->
405 <!-- ##### FUNCTION gst_element_class_set_details ##### -->
414 <!-- ##### MACRO gst_element_default_deep_notify ##### -->
416 The default deep notify handler that prints out the property change
417 notifications to stdout.
422 <!-- ##### FUNCTION gst_element_default_error ##### -->
433 <!-- ##### FUNCTION gst_element_set_loop_function ##### -->
442 <!-- ##### MACRO gst_element_get_name ##### -->
444 Gets the name of the element.
448 @Returns: the name of the element.
454 <!-- ##### MACRO gst_element_set_name ##### -->
456 Sets the name of the element, getting rid of the old name if there was one.
459 @elem: a #GstElement to set the name of.
460 @name: the new name of the element.
463 <!-- ##### MACRO gst_element_get_parent ##### -->
465 Gets the parent of an element.
468 @elem: a #GstElement to get the parent of.
469 @Returns: the #GstObject parent of the element.
472 <!-- ##### MACRO gst_element_set_parent ##### -->
474 Sets the parent of an element.
477 @elem: a #GstElement to set the parent of.
478 @parent: the new #GstObject parent of the object.
481 <!-- ##### FUNCTION gst_element_set ##### -->
487 @first_property_name:
491 <!-- ##### FUNCTION gst_element_get ##### -->
497 @first_property_name:
501 <!-- ##### FUNCTION gst_element_set_valist ##### -->
507 @first_property_name:
511 <!-- ##### FUNCTION gst_element_get_valist ##### -->
517 @first_property_name:
521 <!-- ##### FUNCTION gst_element_set_property ##### -->
531 <!-- ##### FUNCTION gst_element_get_property ##### -->
541 <!-- ##### FUNCTION gst_element_enable_threadsafe_properties ##### -->
549 <!-- ##### FUNCTION gst_element_disable_threadsafe_properties ##### -->
557 <!-- ##### FUNCTION gst_element_set_pending_properties ##### -->
565 <!-- ##### FUNCTION gst_element_requires_clock ##### -->
574 <!-- ##### FUNCTION gst_element_provides_clock ##### -->
583 <!-- ##### FUNCTION gst_element_get_clock ##### -->
592 <!-- ##### FUNCTION gst_element_set_clock ##### -->
601 <!-- ##### FUNCTION gst_element_clock_wait ##### -->
610 <!-- # Unused Parameters # -->
615 <!-- ##### FUNCTION gst_element_get_time ##### -->
624 <!-- ##### FUNCTION gst_element_wait ##### -->
634 <!-- ##### FUNCTION gst_element_set_time ##### -->
643 <!-- ##### FUNCTION gst_element_set_time_delay ##### -->
653 <!-- ##### FUNCTION gst_element_adjust_time ##### -->
662 <!-- ##### FUNCTION gst_element_is_indexable ##### -->
671 <!-- ##### FUNCTION gst_element_set_index ##### -->
680 <!-- ##### FUNCTION gst_element_get_index ##### -->
689 <!-- ##### FUNCTION gst_element_release_locks ##### -->
698 <!-- ##### FUNCTION gst_element_yield ##### -->
706 <!-- ##### FUNCTION gst_element_interrupt ##### -->
715 <!-- ##### FUNCTION gst_element_set_scheduler ##### -->
724 <!-- ##### FUNCTION gst_element_get_scheduler ##### -->
733 <!-- ##### FUNCTION gst_element_add_pad ##### -->
742 <!-- ##### FUNCTION gst_element_remove_pad ##### -->
751 <!-- ##### FUNCTION gst_element_add_ghost_pad ##### -->
762 <!-- ##### FUNCTION gst_element_remove_ghost_pad ##### -->
771 <!-- pad template manipulation -->
774 <!-- ##### FUNCTION gst_element_get_pad ##### -->
781 @Returns: GList of #GstPads
784 <!-- ##### FUNCTION gst_element_get_static_pad ##### -->
794 <!-- ##### FUNCTION gst_element_get_request_pad ##### -->
804 <!-- ##### FUNCTION gst_element_release_request_pad ##### -->
813 <!-- ##### FUNCTION gst_element_get_pad_list ##### -->
822 <!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
832 <!-- ##### FUNCTION gst_element_get_compatible_pad_filtered ##### -->
843 <!-- ##### FUNCTION gst_element_class_get_pad_template ##### -->
853 <!-- ##### FUNCTION gst_element_class_get_pad_template_list ##### -->
862 <!-- ##### FUNCTION gst_element_get_pad_template ##### -->
872 <!-- ##### FUNCTION gst_element_get_pad_template_list ##### -->
885 <!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
895 <!-- ##### FUNCTION gst_element_link ##### -->
905 <!-- ##### FUNCTION gst_element_link_many ##### -->
916 <!-- ##### FUNCTION gst_element_link_filtered ##### -->
927 <!-- ##### FUNCTION gst_element_unlink ##### -->
936 <!-- ##### FUNCTION gst_element_unlink_many ##### -->
946 <!-- ##### FUNCTION gst_element_link_pads ##### -->
958 <!-- ##### FUNCTION gst_element_link_pads_filtered ##### -->
971 <!-- ##### FUNCTION gst_element_unlink_pads ##### -->
982 <!-- pad manipulation -->
985 <!-- ##### FUNCTION gst_element_get_event_masks ##### -->
994 <!-- ##### FUNCTION gst_element_send_event ##### -->
1004 <!-- ##### FUNCTION gst_element_seek ##### -->
1015 <!-- ##### FUNCTION gst_element_get_query_types ##### -->
1024 <!-- ##### FUNCTION gst_element_query ##### -->
1036 <!-- ##### FUNCTION gst_element_get_formats ##### -->
1045 <!-- ##### FUNCTION gst_element_convert ##### -->
1058 <!-- ##### FUNCTION gst_element_found_tags ##### -->
1067 <!-- ##### FUNCTION gst_element_found_tags_for_pad ##### -->
1078 <!-- ##### FUNCTION gst_element_set_eos ##### -->
1086 <!-- ##### FUNCTION gst_element_error_full ##### -->
1101 <!-- ##### FUNCTION gst_element_is_locked_state ##### -->
1110 <!-- ##### FUNCTION gst_element_set_locked_state ##### -->
1119 <!-- ##### FUNCTION gst_element_sync_state_with_parent ##### -->
1128 <!-- ##### FUNCTION gst_element_get_state ##### -->
1137 <!-- ##### FUNCTION gst_element_set_state ##### -->
1147 <!-- ##### FUNCTION gst_element_wait_state_change ##### -->
1155 <!-- ##### FUNCTION gst_element_state_get_name ##### -->
1164 <!-- ##### FUNCTION gst_element_get_factory ##### -->
1173 <!-- ##### FUNCTION gst_element_get_managing_bin ##### -->
1184 <!-- ##### FUNCTION gst_element_no_more_pads ##### -->