1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 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 <!-- ##### MACRO gst_element_get_name ##### -->
76 Gets the name of the element.
80 @Returns: the name of the element.
86 <!-- ##### MACRO gst_element_set_name ##### -->
88 Sets the name of the element, getting rid of the old name if there was one.
91 @elem: a #GstElement to set the name of.
92 @name: the new name of the element.
95 <!-- ##### FUNCTION gst_element_get_factory ##### -->
104 <!-- ##### FUNCTION gst_element_add_pad ##### -->
113 <!-- ##### FUNCTION gst_element_remove_pad ##### -->
122 <!-- ##### FUNCTION gst_element_add_ghost_pad ##### -->
133 <!-- ##### FUNCTION gst_element_remove_ghost_pad ##### -->
142 <!-- pad template manipulation -->
145 <!-- ##### FUNCTION gst_element_get_pad ##### -->
152 @Returns: GList of #GstPads
155 <!-- ##### FUNCTION gst_element_get_static_pad ##### -->
165 <!-- ##### FUNCTION gst_element_get_request_pad ##### -->
175 <!-- ##### FUNCTION gst_element_release_request_pad ##### -->
184 <!-- ##### FUNCTION gst_element_get_pad_list ##### -->
193 <!-- ##### FUNCTION gst_element_get_pad_template ##### -->
203 <!-- ##### FUNCTION gst_element_get_pad_template_list ##### -->
216 <!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
225 <!-- ##### FUNCTION gst_element_link ##### -->
235 <!-- ##### FUNCTION gst_element_link_many ##### -->
246 <!-- ##### FUNCTION gst_element_link_filtered ##### -->
257 <!-- ##### FUNCTION gst_element_link_pads ##### -->
269 <!-- ##### FUNCTION gst_element_link_pads_filtered ##### -->
282 <!-- ##### FUNCTION gst_element_unlink ##### -->
291 <!-- ##### FUNCTION gst_element_unlink_many ##### -->
301 <!-- ##### FUNCTION gst_element_unlink_pads ##### -->
312 <!-- pad manipulation -->
315 <!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
325 <!-- ##### FUNCTION gst_element_get_compatible_pad_filtered ##### -->
336 <!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
346 <!-- ##### FUNCTION gst_element_set_state ##### -->
356 <!-- ##### FUNCTION gst_element_get_state ##### -->
365 <!-- ##### FUNCTION gst_element_state_get_name ##### -->
374 <!-- ##### FUNCTION gst_element_wait_state_change ##### -->
382 <!-- ##### FUNCTION gst_element_set_eos ##### -->
390 <!-- ##### FUNCTION gst_element_interrupt ##### -->
399 <!-- ##### FUNCTION gst_element_yield ##### -->
407 <!-- ##### FUNCTION gst_element_release_locks ##### -->
416 <!-- ##### FUNCTION gst_element_get_clock ##### -->
425 <!-- ##### FUNCTION gst_element_set_clock ##### -->
434 <!-- ##### FUNCTION gst_element_clock_wait ##### -->
443 <!-- # Unused Parameters # -->
448 <!-- ##### FUNCTION gst_element_provides_clock ##### -->
457 <!-- ##### FUNCTION gst_element_requires_clock ##### -->
466 <!-- ##### FUNCTION gst_element_set_index ##### -->
475 <!-- ##### FUNCTION gst_element_get_index ##### -->
484 <!-- ##### FUNCTION gst_element_is_indexable ##### -->
493 <!-- ##### FUNCTION gst_element_set_loop_function ##### -->
502 <!-- ##### USER_FUNCTION GstElementLoopFunction ##### -->
504 This function type is used to specify a loop function for the element. It
505 is passed the element in question, and is expect to return only in error
509 @element: The element in question.
512 <!-- ##### FUNCTION gst_element_get_scheduler ##### -->
521 <!-- ##### FUNCTION gst_element_set_scheduler ##### -->
530 <!-- ##### MACRO gst_element_get_parent ##### -->
532 Gets the parent of an element.
535 @elem: a #GstElement to get the parent of.
536 @Returns: the #GstObject parent of the element.
539 <!-- ##### MACRO gst_element_set_parent ##### -->
541 Sets the parent of an element.
544 @elem: a #GstElement to set the parent of.
545 @parent: the new #GstObject parent of the object.
548 <!-- ##### FUNCTION gst_element_get_managing_bin ##### -->
559 <!-- ##### USER_FUNCTION GstElementPostRunFunction ##### -->
561 The signature of the function to execute before this element
565 @element: The element
568 <!-- ##### USER_FUNCTION GstElementPreRunFunction ##### -->
570 The signature of the function to execute after this element
574 @element: The element
577 <!-- ##### FUNCTION gst_element_disable_threadsafe_properties ##### -->
585 <!-- ##### FUNCTION gst_element_enable_threadsafe_properties ##### -->
593 <!-- ##### FUNCTION gst_element_get ##### -->
599 @first_property_name:
603 <!-- ##### FUNCTION gst_element_get_property ##### -->
613 <!-- ##### FUNCTION gst_element_get_valist ##### -->
619 @first_property_name:
623 <!-- ##### FUNCTION gst_element_set ##### -->
629 @first_property_name:
633 <!-- ##### FUNCTION gst_element_set_pending_properties ##### -->
641 <!-- ##### FUNCTION gst_element_set_property ##### -->
651 <!-- ##### FUNCTION gst_element_set_valist ##### -->
657 @first_property_name:
661 <!-- ##### FUNCTION gst_element_query ##### -->
673 <!-- ##### FUNCTION gst_element_send_event ##### -->
683 <!-- ##### FUNCTION gst_element_get_event_masks ##### -->
692 <!-- ##### FUNCTION gst_element_get_formats ##### -->
701 <!-- ##### FUNCTION gst_element_get_query_types ##### -->
710 <!-- ##### FUNCTION gst_element_convert ##### -->
723 <!-- ##### MACRO gst_element_default_deep_notify ##### -->
725 The default deep notify handler that prints out the property change
726 notifications to stdout.
731 <!-- ##### FUNCTION gst_element_default_error ##### -->
742 <!-- ##### ENUM GstElementState ##### -->
744 This enum defines the standard states an element may be in. You will normally
745 use gst_element_set_state() to change the state of an element.
749 @GST_STATE_VOID_PENDING:
750 @GST_STATE_NULL: Reset the state of an element.
751 @GST_STATE_READY: will make the element ready to start processing data. some
752 elements might have a non trivial way to initialize themselves.
753 @GST_STATE_PAUSED: means there really is data flowing temporary stops the data flow.
754 @GST_STATE_PLAYING: means there really is data flowing through the graph.
756 <!-- ##### ENUM GstElementStateReturn ##### -->
758 This enum defines the standard return values that an element
759 can return after a state change.
763 @GST_STATE_FAILURE: the element could not perform the state change
764 @GST_STATE_SUCCESS: the element successfully changed its state
765 @GST_STATE_ASYNC: the element will asynchronously change its state as soon as possible
767 <!-- ##### MACRO GST_NUM_STATES ##### -->
769 The maximun number of states.
774 <!-- ##### MACRO GST_STATE ##### -->
776 This macro returns the current state of the element.
779 @obj: Element to return state for.
782 <!-- ##### MACRO GST_STATE_PENDING ##### -->
784 This macro returns the currently pending state of the element.
787 @obj: Element to return the pending state for.
790 <!-- ##### MACRO GST_STATE_TRANSITION ##### -->
792 Returns the state transition this object is going through.
795 @obj: the Element to return the state transition for
798 <!-- ##### MACRO GST_STATE_NULL_TO_READY ##### -->
800 The Element is going from the NULL state to the READY state.
805 <!-- ##### MACRO GST_STATE_READY_TO_PAUSED ##### -->
807 The Element is going from the READY state to the PAUSED state.
812 <!-- ##### MACRO GST_STATE_PAUSED_TO_READY ##### -->
814 The Element is going from the PAUSED state to the READY state.
819 <!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### -->
821 The Element is going from the PLAYING state to the PAUSED state.
826 <!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### -->
828 The Element is going from the PAUSED state to the PLAYING state.
833 <!-- ##### MACRO GST_STATE_READY_TO_NULL ##### -->
835 The Element is going from the READY state to the NULL state.
840 <!-- ##### ENUM GstElementFlags ##### -->
842 This enum defines the standard flags that an element may have.
845 @GST_ELEMENT_COMPLEX:
846 @GST_ELEMENT_DECOUPLED:
847 @GST_ELEMENT_THREAD_SUGGESTED:
848 @GST_ELEMENT_INFINITE_LOOP:
849 @GST_ELEMENT_NEW_LOOPFUNC:
850 @GST_ELEMENT_EVENT_AWARE:
851 @GST_ELEMENT_USE_THREADSAFE_PROPERTIES:
852 @GST_ELEMENT_SCHEDULER_PRIVATE1:
853 @GST_ELEMENT_SCHEDULER_PRIVATE2:
854 @GST_ELEMENT_LOCKED_STATE:
855 @GST_ELEMENT_IN_ERROR:
856 @GST_ELEMENT_FLAG_LAST:
858 <!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### -->
860 Queries whether the Element should be placed in a thread.
863 @obj: a #GstElement to query
866 <!-- ##### MACRO GST_ELEMENT_IS_DECOUPLED ##### -->
868 Queries if the Element is decoupled.
871 @obj: a #GstElement to query
874 <!-- ##### MACRO GST_ELEMENT_IS_EVENT_AWARE ##### -->
876 Query wether this element can handle events.
879 @obj: a #GstElement to query
882 <!-- ##### MACRO GST_ELEMENT_PARENT ##### -->
884 Get the parent object of this element.
887 @obj: a #GstElement to query
890 <!-- ##### MACRO GST_ELEMENT_NAME ##### -->
892 Gets the name of this element. Used in the core. Not ABI-compatible.
895 @obj: A #GstElement to query
898 <!-- ##### MACRO GST_ELEMENT_PADS ##### -->
900 Get the pads of this elements.
903 @obj: a #GstElement to query
906 <!-- ##### MACRO GST_ELEMENT_SCHED ##### -->
908 Get the scheduler of this element.
911 @obj: a #GstElement to query
914 <!-- ##### MACRO GST_ELEMENT_MANAGER ##### -->
916 Get the manager of this element.
919 @obj: a #GstElement to query
922 <!-- ##### MACRO GST_ELEMENT_CLOCK ##### -->
924 Get the clock of this element
927 @obj: a #GstElement to query
930 <!-- ##### MACRO GST_ELEMENT_EVENT_MASK_FUNCTION ##### -->
932 A helper macro to create a mask function
935 @functionname: the name of the mask function
939 <!-- ##### MACRO GST_ELEMENT_FORMATS_FUNCTION ##### -->
941 Halper macro to create element format functions
944 @functionname: The function name
948 <!-- ##### MACRO GST_ELEMENT_QUERY_TYPE_FUNCTION ##### -->
950 Helper macro to create query type functions
953 @functionname: The function name
954 @...: list of query types.
957 <!-- ##### SIGNAL GstElement::eos ##### -->
959 Signal emited when the element goes to PAUSED due to an end-of-stream
963 @gstelement: the object which received the signal.
965 <!-- ##### SIGNAL GstElement::error ##### -->
967 Is triggered whenever an error occured.
971 @gstelement: the object which received the signal.
972 @arg1: the error message
993 <!-- ##### SIGNAL GstElement::found-tag ##### -->
998 @gstelement: the object which received the signal.
1002 <!-- ##### SIGNAL GstElement::new-pad ##### -->
1004 Is triggered whenever a new pad is added to an element.
1007 @gstelement: the object which received the signal.
1008 @arg1: the new pad that was added
1010 <!-- ##### SIGNAL GstElement::pad-removed ##### -->
1012 Is triggered whenever a pad has been removed from the element.
1015 @gstelement: the object which received the signal.
1016 @arg1: The pad that was removed.
1018 <!-- ##### SIGNAL GstElement::state-change ##### -->
1020 Is triggered whenever the state of an element changes.
1023 @gstelement: the object which received the signal.
1024 @arg1: the new state of the object