From: Thomas V. S. <tho...@us...> - 2002-04-19 10:25:55
|
CVS Root: /cvsroot/gstreamer Module: gstreamer Changes by: thomasvs Date: Fri Apr 19 2002 03:25:53 PDT Log message: doc changes Modified files: docs/gst/tmpl : gstelement.sgml Links: http://cvs.sf.net/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/gstelement.sgml.diff?r1=1.40&r2=1.41 ====Begin Diffs==== Index: gstelement.sgml =================================================================== RCS file: /cvsroot/gstreamer/gstreamer/docs/gst/tmpl/gstelement.sgml,v retrieving revision 1.40 retrieving revision 1.41 diff -u -d -r1.40 -r1.41 --- gstelement.sgml 17 Apr 2002 12:28:32 -0000 1.40 +++ gstelement.sgml 19 Apr 2002 10:25:40 -0000 1.41 @@ -7,339 +7,403 @@ <!-- ##### SECTION Long_Description ##### --> <para> GstElement is the base class needed to construct an element that can be -used in a GST pipeline. As such, it is not a functional entity, and +used in a GStreamer pipeline. As such, it is not a functional entity, and cannot do anything when placed in a pipeline. </para> <para> -All GstElements have a list containing the #GstPad structure for all their -inputs and outputs. These can be added with gst_element_add_pad() or -gst_element_add_ghost_pad(), and retrieved by name with -gst_element_get_pad(), or in a list form by gst_element_get_pad_list(). +The name of a GstElement can be get with gst_element_get_name() and set with +gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the +core. +Do not use this in plug-ins or applications in order to retain ABI +compatibility. </para> <para> -gst_element_connect() is a convenience function provided to make it -simpler to connect pads of two elements together. +All elements have pads (of the type #GstPad). These pads connect to pads on +other elements. Buffers flow between these connected pads. +A GstElement has a GList of #GstPad structures for all their input (or sink) +and output (or source) pads. +Core and plug-in writers can add and remove pads with gst_element_add_pad() +and gst_element_remove_pad(). +Application writers can manipulate ghost pads (copies of real pads inside a bin) +with gst_element_add_ghost_pad() and gst_element_remove_ghost_pad(). +A pad of an element can be retrieved by name with gst_element_get_pad(). +A GList of all pads can be retrieved with gst_element_get_pad_list(). </para> -<!-- ##### SECTION See_Also ##### --> <para> -#GstElementFactory +Elements can be connected through their pads. +If the connection is straightforward, use the gst_element_connect() +convenience function to connect two elements, or gst_element_connect_many() +for more elements in a row. +Use gst_element_connect_filtered() to connect two elements constrained by +a specified set of #GstCaps. +For finer control, use gst_element_connect_pads() and +gst_element_connect_pads_filtered() to specify the pads to connect on +each element by name. </para> -<!-- ##### ENUM GstElementState ##### --> <para> -This enum defines the standard states an element may be in. You will normally -use gst_element_set_state() to change the state of an element. +Each element has a state (see #GstElementState). You can get and set the state +of an element with gst_element_get_state() and gst_element_set_state(). +You can wait for an element to change it's state with gst_element_wait_state_change(). +To get a string representation of a #GstElementState, use +gst_element_statename(), which is a really bad name for what it does +and should probably be renamed +to gst_element_state_get_name if we can be bothered to do that. +</para> +<para> +You can get and set a #GstClock on an element using gst_element_get_clock() +and gst_element_set_clock(). You can wait for the clock to reach a given +#GstClockTime using gst_element_clock_wait(). +</para> +<!-- ##### SECTION See_Also ##### --> +<para> +#GstElementFactory, #GstPad </para> -@GST_STATE_VOID_PENDING: -@GST_STATE_NULL: Reset the state of an element. -@GST_STATE_READY: will make the element ready to start processing data. some -elements might have a non trivial way to initialize themselves. -@GST_STATE_PAUSED: means there really is data flowing temporary stops the data flow. -@GST_STATE_PLAYING: means there really is data flowing through the graph. +<!-- basic object functions --> -<!-- ##### ENUM GstElementStateReturn ##### --> +<!-- ##### STRUCT GstElement ##### --> <para> -This enum defines the standard return values that an element -can return after a state change. </para> -@GST_STATE_FAILURE: the element could not perform the state change -@GST_STATE_SUCCESS: the element successfully changed its state -@GST_STATE_ASYNC: the element will asynchronously change its state as soon as possible -<!-- ##### MACRO GST_NUM_STATES ##### --> +<!-- ##### MACRO gst_element_destroy ##### --> <para> -The maximun number of states. +Destroys the element (without taking the refcount into account). +An application programmer should use #gst_object_unref instead to dispose +of an element he doesn't need anymore. </para> +@element: a #GstElement to destroy -<!-- ##### MACRO GST_STATE ##### --> +<!-- ##### FUNCTION gst_element_get_name ##### --> <para> -This macro returns the current state of the element. + </para> -@obj: Element to return state for. +@element: +@Returns: -<!-- ##### MACRO GST_STATE_PENDING ##### --> +<!-- ##### FUNCTION gst_element_set_name ##### --> <para> -This macro returns the currently pending state of the element. + </para> -@obj: Element to return the pending state for. +@element: +@name: -<!-- ##### MACRO GST_STATE_TRANSITION ##### --> -<para> -Returns the state transition this object is going through. -</para> - -@obj: the Element to return the state transition for +<!-- connection --> -<!-- ##### MACRO GST_STATE_NULL_TO_READY ##### --> +<!-- ##### FUNCTION gst_element_get_factory ##### --> <para> -The Element is going from the NULL state to the READY state. + </para> +@element: +@Returns: -<!-- ##### MACRO GST_STATE_READY_TO_PAUSED ##### --> +<!-- ##### FUNCTION gst_element_add_pad ##### --> <para> -The Element is going from the READY state to the PAUSED state. + </para> +@element: +@pad: -<!-- ##### MACRO GST_STATE_PAUSED_TO_READY ##### --> +<!-- ##### FUNCTION gst_element_remove_pad ##### --> <para> -The Element is going from the PAUSED state to the READY state. + </para> +@element: +@pad: -<!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### --> +<!-- ##### FUNCTION gst_element_add_ghost_pad ##### --> <para> -The Element is going from the PLAYING state to the PAUSED state. + </para> +@element: +@pad: +@name: +@Returns: -<!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### --> +<!-- ##### FUNCTION gst_element_remove_ghost_pad ##### --> <para> -The Element is going from the PAUSED state to the PLAYING state. + </para> +@element: +@pad: -<!-- ##### MACRO GST_STATE_READY_TO_NULL ##### --> +<!-- pad template manipulation --> + + +<!-- ##### FUNCTION gst_element_get_pad ##### --> <para> -The Element is going from the READY state to the NULL state. + </para> +@element: +@name: +@Returns: GList of #GstPads -<!-- ##### ENUM GstElementFlags ##### --> +<!-- ##### FUNCTION gst_element_get_static_pad ##### --> <para> -This enum defines the standard flags that an element may have. + </para> -@GST_ELEMENT_COMPLEX: -@GST_ELEMENT_DECOUPLED: -@GST_ELEMENT_THREAD_SUGGESTED: -@GST_ELEMENT_NO_SEEK: -@GST_ELEMENT_INFINITE_LOOP: -@GST_ELEMENT_SCHEDULER_PRIVATE1: -@GST_ELEMENT_SCHEDULER_PRIVATE2: -@GST_ELEMENT_NEW_LOOPFUNC: -@GST_ELEMENT_EVENT_AWARE: -@GST_ELEMENT_FLAG_LAST: +@element: +@name: +@Returns: -<!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### --> + +<!-- ##### FUNCTION gst_element_get_request_pad ##### --> <para> -Queries whether the Element should be placed in a thread. + </para> -@obj: The element to query +@element: +@name: +@Returns: -<!-- ##### MACRO GST_ELEMENT_IS_DECOUPLED ##### --> +<!-- ##### FUNCTION gst_element_get_pad_list ##### --> <para> -Queries if the Element is decoupled. + </para> -@obj: The element to query +@element: +@Returns: -<!-- ##### MACRO GST_ELEMENT_IS_EOS ##### --> +<!-- ##### FUNCTION gst_element_get_pad_template_list ##### --> <para> -Query wether this element is in the End Of Stream state. + </para> -@obj: The element to query +@element: +@Returns: -<!-- ##### MACRO GST_ELEMENT_IS_EVENT_AWARE ##### --> -<para> -Query wether this element can handle events. -</para> -@obj: The element to query +<!-- scheduling --> -<!-- ##### MACRO GST_ELEMENT_PARENT ##### --> +<!-- ##### FUNCTION gst_element_class_add_pad_template ##### --> <para> -Get the parent object of this element. + </para> -@obj: The element to query +@klass: +@templ: +<!-- # Unused Parameters # --> +@element: -<!-- ##### MACRO GST_ELEMENT_NAME ##### --> +<!-- ##### FUNCTION gst_element_connect ##### --> <para> -Get the name of this element. + </para> -@obj: The element to query +@src: +@dest: +@Returns: -<!-- ##### MACRO GST_ELEMENT_PADS ##### --> +<!-- ##### FUNCTION gst_element_connect_many ##### --> <para> -Get the pads of this elements. + </para> -@obj: The element to query +@element_1: +@element_2: +@Varargs: +@Returns: -<!-- ##### MACRO GST_ELEMENT_SCHED ##### --> +<!-- ##### FUNCTION gst_element_connect_filtered ##### --> <para> -Get the scheduler of this element. + </para> -@obj: The element to query +@src: +@dest: +@filtercaps: +@Returns: -<!-- ##### MACRO GST_ELEMENT_MANAGER ##### --> +<!-- ##### FUNCTION gst_element_connect_pads ##### --> <para> -Get the manager of this element. + </para> -@obj: The element to query +@src: +@srcpadname: +@dest: +@destpadname: +@Returns: -<!-- ##### MACRO GST_ELEMENT_CLOCK ##### --> +<!-- ##### FUNCTION gst_element_connect_pads_filtered ##### --> <para> -Get the clock of this element + </para> -@obj: the Element to query +@src: +@srcpadname: +@dest: +@destpadname: +@filtercaps: +@Returns: -<!-- ##### STRUCT GstElement ##### --> +<!-- ##### FUNCTION gst_element_disconnect ##### --> <para> </para> +@src: +@dest: +<!-- # Unused Parameters # --> +@srcpadname: +@destpadname: -<!-- ##### USER_FUNCTION GstElementLoopFunction ##### --> + +<!-- ##### FUNCTION gst_element_disconnect_many ##### --> <para> -This function type is used to specify a loop function for the element. It -is passed the element in question, and is expect to return only in error -circumstances. + </para> -@element: The element in question. +@element_1: +@element_2: +@Varargs: -<!-- ##### USER_FUNCTION GstElementGetClockFunction ##### --> +<!-- ##### FUNCTION gst_element_disconnect_pads ##### --> <para> -The function to get the clock from a clock providing element + </para> -@element: The element to get the clock of -@Returns: The clock provided by the element +@src: +@srcpadname: +@dest: +@destpadname: -<!-- ##### USER_FUNCTION GstElementSetClockFunction ##### --> +<!-- pad manipulation --> + + +<!-- ##### FUNCTION gst_element_get_compatible_pad ##### --> <para> -The function to set the clock on a clock receiving element. + </para> -@element: The element to set the clock on -@clock: The clock to set on the element +@element: +@pad: +@Returns: -<!-- ##### FUNCTION gst_element_class_add_pad_template ##### --> +<!-- ##### FUNCTION gst_element_get_compatible_pad_filtered ##### --> <para> </para> -@klass: -@templ: -<!-- # Unused Parameters # --> @element: +@pad: +@filtercaps: +@Returns: -<!-- ##### MACRO gst_element_destroy ##### --> +<!-- ##### FUNCTION gst_element_set_state ##### --> <para> -Destroy the element. This is potentially dangerous, use gst_object_unref -instead. + </para> -@element: the element to destroy +@element: +@state: +@Returns: -<!-- ##### FUNCTION gst_element_set_loop_function ##### --> +<!-- ##### FUNCTION gst_element_get_state ##### --> <para> </para> @element: -@loop: +@Returns: +<!-- # Unused Parameters # --> +@elem: -<!-- ##### FUNCTION gst_element_set_name ##### --> +<!-- ##### FUNCTION gst_element_wait_state_change ##### --> <para> </para> @element: -@name: -<!-- ##### FUNCTION gst_element_get_name ##### --> +<!-- ##### FUNCTION gst_element_statename ##### --> <para> </para> -@element: +@state: @Returns: -<!-- ##### FUNCTION gst_element_get_sched ##### --> +<!-- ##### FUNCTION gst_element_error ##### --> <para> </para> @element: -@Returns: +@error: +@Varargs: -<!-- ##### FUNCTION gst_element_set_sched ##### --> +<!-- ##### FUNCTION gst_element_set_eos ##### --> <para> </para> @element: -@sched: -<!-- ##### FUNCTION gst_element_set_parent ##### --> +<!-- ##### FUNCTION gst_element_interrupt ##### --> <para> </para> @element: -@parent: +@Returns: -<!-- ##### FUNCTION gst_element_get_parent ##### --> +<!-- ##### FUNCTION gst_element_yield ##### --> <para> </para> @element: -@Returns: -<!-- ##### FUNCTION gst_element_get_managing_bin ##### --> +<!-- ##### FUNCTION gst_element_get_clock ##### --> <para> </para> @@ -348,55 +412,64 @@ @Returns: -<!-- ##### FUNCTION gst_element_add_pad ##### --> +<!-- ##### FUNCTION gst_element_set_clock ##### --> <para> </para> @element: -@pad: +@clock: -<!-- ##### FUNCTION gst_element_remove_pad ##### --> +<!-- ##### FUNCTION gst_element_clock_wait ##### --> <para> </para> @element: -@pad: +@clock: +@time: +@Returns: -<!-- ##### FUNCTION gst_element_get_pad ##### --> +<!-- ##### USER_FUNCTION GstElementGetClockFunction ##### --> <para> +The function to get the clock from a clock providing element +</para> + +@element: The element to get the clock of +@Returns: The clock provided by the element + +<!-- ##### USER_FUNCTION GstElementSetClockFunction ##### --> +<para> +The function to set the clock on a clock receiving element. </para> -@element: -@name: -@Returns: GList of pads +@element: The element to set the clock on +@clock: The clock to set on the element -<!-- ##### FUNCTION gst_element_get_static_pad ##### --> +<!-- ##### FUNCTION gst_element_set_loop_function ##### --> <para> </para> @element: -@name: -@Returns: +@loop: -<!-- ##### FUNCTION gst_element_get_request_pad ##### --> +<!-- ##### USER_FUNCTION GstElementLoopFunction ##### --> <para> - +This function type is used to specify a loop function for the element. It +is passed the element in question, and is expect to return only in error +circumstances. </para> -@element: -@name: -@Returns: +@element: The element in question. -<!-- ##### FUNCTION gst_element_get_pad_list ##### --> +<!-- ##### FUNCTION gst_element_get_sched ##### --> <para> </para> @@ -405,261 +478,236 @@ @Returns: -<!-- ##### FUNCTION gst_element_get_pad_template_list ##### --> +<!-- ##### FUNCTION gst_element_set_sched ##### --> <para> </para> @element: -@Returns: +@sched: -<!-- ##### FUNCTION gst_element_add_ghost_pad ##### --> +<!-- ##### FUNCTION gst_element_get_parent ##### --> <para> </para> @element: -@pad: -@name: @Returns: -<!-- ##### FUNCTION gst_element_remove_ghost_pad ##### --> +<!-- ##### FUNCTION gst_element_set_parent ##### --> <para> </para> @element: -@pad: +@parent: -<!-- ##### FUNCTION gst_element_get_compatible_pad ##### --> +<!-- ##### FUNCTION gst_element_get_managing_bin ##### --> <para> </para> @element: -@pad: @Returns: +<!-- clocking --> -<!-- ##### FUNCTION gst_element_get_compatible_pad_filtered ##### --> + +<!-- ##### ENUM GstElementState ##### --> <para> +This enum defines the standard states an element may be in. You will normally +use gst_element_set_state() to change the state of an element. </para> -@element: -@pad: -@filtercaps: -@Returns: - +@GST_STATE_VOID_PENDING: +@GST_STATE_NULL: Reset the state of an element. +@GST_STATE_READY: will make the element ready to start processing data. some +elements might have a non trivial way to initialize themselves. +@GST_STATE_PAUSED: means there really is data flowing temporary stops the data flow. +@GST_STATE_PLAYING: means there really is data flowing through the graph. -<!-- ##### FUNCTION gst_element_connect ##### --> +<!-- ##### ENUM GstElementStateReturn ##### --> <para> +This enum defines the standard return values that an element +can return after a state change. </para> -@src: -@dest: -@Returns: -<!-- # Unused Parameters # --> -@srcpadname: -@destpadname: - +@GST_STATE_FAILURE: the element could not perform the state change +@GST_STATE_SUCCESS: the element successfully changed its state +@GST_STATE_ASYNC: the element will asynchronously change its state as soon as possible -<!-- ##### FUNCTION gst_element_connect_many ##### --> +<!-- ##### MACRO GST_NUM_STATES ##### --> <para> - +The maximun number of states. </para> -@element_1: -@element_2: -@Varargs: -@Returns: -<!-- ##### FUNCTION gst_element_connect_filtered ##### --> +<!-- ##### MACRO GST_STATE ##### --> <para> - +This macro returns the current state of the element. </para> -@src: -@dest: -@filtercaps: -@Returns: -<!-- # Unused Parameters # --> -@srcpadname: -@destpadname: +@obj: Element to return state for. -<!-- ##### FUNCTION gst_element_connect_pads ##### --> +<!-- ##### MACRO GST_STATE_PENDING ##### --> <para> - +This macro returns the currently pending state of the element. </para> -@src: -@srcpadname: -@dest: -@destpadname: -@Returns: +@obj: Element to return the pending state for. -<!-- ##### FUNCTION gst_element_connect_pads_filtered ##### --> +<!-- ##### MACRO GST_STATE_TRANSITION ##### --> <para> - +Returns the state transition this object is going through. </para> -@src: -@srcpadname: -@dest: -@destpadname: -@filtercaps: -@Returns: +@obj: the Element to return the state transition for -<!-- ##### FUNCTION gst_element_disconnect ##### --> +<!-- ##### MACRO GST_STATE_NULL_TO_READY ##### --> <para> - +The Element is going from the NULL state to the READY state. </para> -@src: -@dest: -<!-- # Unused Parameters # --> -@srcpadname: -@destpadname: -<!-- ##### FUNCTION gst_element_disconnect_many ##### --> +<!-- ##### MACRO GST_STATE_READY_TO_PAUSED ##### --> <para> - +The Element is going from the READY state to the PAUSED state. </para> -@element_1: -@element_2: -@Varargs: -<!-- ##### FUNCTION gst_element_disconnect_pads ##### --> +<!-- ##### MACRO GST_STATE_PAUSED_TO_READY ##### --> <para> - +The Element is going from the PAUSED state to the READY state. </para> -@src: -@srcpadname: -@dest: -@destpadname: -<!-- ##### FUNCTION gst_element_set_state ##### --> +<!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### --> <para> - +The Element is going from the PLAYING state to the PAUSED state. </para> -@element: -@state: -@Returns: -<!-- ##### FUNCTION gst_element_get_state ##### --> +<!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### --> <para> - +The Element is going from the PAUSED state to the PLAYING state. </para> -@element: -@Returns: -<!-- # Unused Parameters # --> -@elem: -<!-- ##### FUNCTION gst_element_wait_state_change ##### --> +<!-- ##### MACRO GST_STATE_READY_TO_NULL ##### --> <para> - +The Element is going from the READY state to the NULL state. </para> -@element: -<!-- ##### FUNCTION gst_element_statename ##### --> +<!-- ##### ENUM GstElementFlags ##### --> <para> +This enum defines the standard flags that an element may have. +</para> + +@GST_ELEMENT_COMPLEX: +@GST_ELEMENT_DECOUPLED: +@GST_ELEMENT_THREAD_SUGGESTED: +@GST_ELEMENT_NO_SEEK: +@GST_ELEMENT_INFINITE_LOOP: +@GST_ELEMENT_SCHEDULER_PRIVATE1: +@GST_ELEMENT_SCHEDULER_PRIVATE2: +@GST_ELEMENT_NEW_LOOPFUNC: +@GST_ELEMENT_EVENT_AWARE: +@GST_ELEMENT_FLAG_LAST: +<!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### --> +<para> +Queries whether the Element should be placed in a thread. </para> -@state: -@Returns: +@obj: a #GstElement to query -<!-- ##### FUNCTION gst_element_error ##### --> +<!-- ##### MACRO GST_ELEMENT_IS_DECOUPLED ##### --> <para> - +Queries if the Element is decoupled. </para> -@element: -@error: -@Varargs: +@obj: a #GstElement to query -<!-- ##### FUNCTION gst_element_get_factory ##### --> +<!-- ##### MACRO GST_ELEMENT_IS_EOS ##### --> <para> - +Query wether this element is in the End Of Stream state. </para> -@element: -@Returns: +@obj: a #GstElement to query -<!-- ##### FUNCTION gst_element_set_eos ##### --> +<!-- ##### MACRO GST_ELEMENT_IS_EVENT_AWARE ##### --> <para> - +Query wether this element can handle events. </para> -@element: +@obj: a #GstElement to query -<!-- ##### FUNCTION gst_element_interrupt ##### --> +<!-- ##### MACRO GST_ELEMENT_PARENT ##### --> <para> - +Get the parent object of this element. </para> -@element: -@Returns: +@obj: a #GstElement to query -<!-- ##### FUNCTION gst_element_yield ##### --> +<!-- ##### MACRO GST_ELEMENT_NAME ##### --> <para> - +Gets the name of this element. Used in the core. Not ABI-compatible. </para> -@element: +@obj: A #GstElement to query -<!-- ##### FUNCTION gst_element_clock_wait ##### --> +<!-- ##### MACRO GST_ELEMENT_PADS ##### --> <para> - +Get the pads of this elements. </para> -@element: -@clock: -@time: -@Returns: +@obj: a #GstElement to query -<!-- ##### FUNCTION gst_element_get_clock ##### --> +<!-- ##### MACRO GST_ELEMENT_SCHED ##### --> <para> - +Get the scheduler of this element. </para> -@element: -@Returns: +@obj: a #GstElement to query -<!-- ##### FUNCTION gst_element_set_clock ##### --> +<!-- ##### MACRO GST_ELEMENT_MANAGER ##### --> <para> +Get the manager of this element. +</para> +@obj: a #GstElement to query + + +<!-- ##### MACRO GST_ELEMENT_CLOCK ##### --> +<para> +Get the clock of this element </para> -@element: -@clock: +@obj: a #GstElement to query <!-- ##### SIGNAL GstElement::eos ##### --> |