mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-26 11:41:09 +00:00
Documentation updates. Make BaseSink and BaseSrc docs contain the class structure so that people can actually see the...
Original commit message from CVS: * docs/libs/gstreamer-libs-sections.txt: * gst/gsttaglist.c: * libs/gst/base/gstbasesink.c: * libs/gst/base/gstbasesink.h: * libs/gst/base/gstbasesrc.c: * libs/gst/base/gstbasesrc.h: Documentation updates. Make BaseSink and BaseSrc docs contain the class structure so that people can actually see the prototypes for virtual functions they're supposed to be overriding.
This commit is contained in:
Jan Schmidt
parent
3b67b0ad82
commit
fb8ad07b59
7 changed files with 158 additions and 80 deletions
12
ChangeLog
12
ChangeLog
|
|
@ -1,3 +1,15 @@
|
|||
2006-04-04 Jan Schmidt <thaytan@mad.scientist.com>
|
||||
|
||||
* docs/libs/gstreamer-libs-sections.txt:
|
||||
* gst/gsttaglist.c:
|
||||
* libs/gst/base/gstbasesink.c:
|
||||
* libs/gst/base/gstbasesink.h:
|
||||
* libs/gst/base/gstbasesrc.c:
|
||||
* libs/gst/base/gstbasesrc.h:
|
||||
Documentation updates. Make BaseSink and BaseSrc docs contain the
|
||||
class structure so that people can actually see the prototypes for
|
||||
virtual functions they're supposed to be overriding.
|
||||
|
||||
2006-04-04 Tim-Philipp Müller <tim at centricular dot net>
|
||||
|
||||
* plugins/elements/gsttypefindelement.c:
|
||||
|
|
|
|||
|
|
@ -129,6 +129,7 @@ gst_adapter_get_type
|
|||
<TITLE>GstBaseSrc</TITLE>
|
||||
<INCLUDE>gst/base/gstbasesrc.h</INCLUDE>
|
||||
GstBaseSrc
|
||||
GstBaseSrcClass
|
||||
GstBaseSrcFlags
|
||||
|
||||
gst_base_src_is_live
|
||||
|
|
@ -137,7 +138,6 @@ gst_base_src_set_format
|
|||
|
||||
GST_BASE_SRC_PAD
|
||||
<SUBSECTION Standard>
|
||||
GstBaseSrcClass
|
||||
GstBaseSrcPrivate
|
||||
GST_BASE_SRC
|
||||
GST_BASE_SRC_CAST
|
||||
|
|
@ -156,6 +156,7 @@ gst_base_src_get_type
|
|||
<TITLE>GstBaseSink</TITLE>
|
||||
<INCLUDE>gst/base/gstbasesink.h</INCLUDE>
|
||||
GstBaseSink
|
||||
GstBaseSinkClass
|
||||
|
||||
GST_BASE_SINK_PAD
|
||||
|
||||
|
|
@ -165,7 +166,6 @@ gst_base_sink_set_max_lateness
|
|||
gst_base_sink_get_max_lateness
|
||||
|
||||
<SUBSECTION Standard>
|
||||
GstBaseSinkClass
|
||||
GST_BASE_SINK
|
||||
GST_BASE_SINK_CAST
|
||||
GST_IS_BASE_SINK
|
||||
|
|
|
|||
|
|
@ -1256,6 +1256,9 @@ TAG_MERGE_FUNCS (pointer, gpointer)
|
|||
*
|
||||
* Copies the contents for the given tag into the value, merging multiple values
|
||||
* into one if multiple values are associated with the tag.
|
||||
*
|
||||
* The resulting string in @value should be freed by the caller using g_free
|
||||
* when no longer needed
|
||||
*
|
||||
* Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
|
||||
* given list.
|
||||
|
|
@ -1270,6 +1273,9 @@ TAG_MERGE_FUNCS (pointer, gpointer)
|
|||
* Gets the value that is at the given index for the given tag in the given
|
||||
* list.
|
||||
*
|
||||
* The resulting string in @value should be freed by the caller using g_free
|
||||
* when no longer needed
|
||||
*
|
||||
* Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
|
||||
* given list.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -26,15 +26,17 @@
|
|||
*
|
||||
* #GstBaseSink is the base class for sink elements in GStreamer, such as
|
||||
* xvimagesink or filesink. It is a layer on top of #GstElement that provides a
|
||||
* simplified interface to plugin writers. #GstBaseSink handles many details for
|
||||
* you, for example preroll, clock synchronization, state changes, activation in
|
||||
* push or pull mode, and queries. In most cases, when writing sink elements,
|
||||
* there is no need to implement class methods from #GstElement or to set
|
||||
* functions on pads, because the #GstBaseSink infrastructure should be sufficient.
|
||||
* simplified interface to plugin writers. #GstBaseSink handles many details
|
||||
* for you, for example: preroll, clock synchronization, state changes,
|
||||
* activation in push or pull mode, and queries.
|
||||
*
|
||||
* In most cases, when writing sink elements, there is no need to implement
|
||||
* class methods from #GstElement or to set functions on pads, because the
|
||||
* #GstBaseSink infrastructure should be sufficient.
|
||||
*
|
||||
* There is only support in GstBaseSink for one sink pad, which should be named
|
||||
* "sink". A sink implementation (subclass of GstBaseSink) should install a pad
|
||||
* template in its base_init function, like so:
|
||||
* #GstBaseSink provides support for exactly one sink pad, which should be
|
||||
* named "sink". A sink implementation (subclass of GstBaseSink) should
|
||||
* install a pad template in its base_init function, like so:
|
||||
* <programlisting>
|
||||
* static void
|
||||
* my_element_base_init (gpointer g_class)
|
||||
|
|
@ -51,75 +53,81 @@
|
|||
* </programlisting>
|
||||
*
|
||||
* #GstBaseSink will handle the prerolling correctly. This means that it will
|
||||
* return GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first buffer
|
||||
* arrives in this element. The base class will call the GstBaseSink::preroll
|
||||
* vmethod with this preroll buffer and will then commit the state change to the
|
||||
* next asynchronously pending state.
|
||||
* return GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first
|
||||
* buffer arrives in this element. The base class will call the
|
||||
* GstBaseSink::preroll vmethod with this preroll buffer and will then commit
|
||||
* the state change to the next asynchronously pending state.
|
||||
*
|
||||
* When the element is set to PLAYING, #GstBaseSink will synchronize on the clock
|
||||
* using the times returned from ::get_times. If this function returns
|
||||
* When the element is set to PLAYING, #GstBaseSink will synchronise on the
|
||||
* clock using the times returned from ::get_times. If this function returns
|
||||
* #GST_CLOCK_TIME_NONE for the start time, no synchronisation will be done.
|
||||
* Synchronisation can be disabled entirely by setting the object "sync" property
|
||||
* to FALSE.
|
||||
* Synchronisation can be disabled entirely by setting the object "sync"
|
||||
* property to FALSE.
|
||||
*
|
||||
* After synchronisation the virtual method #GstBaseSink::render will be called.
|
||||
* Subclasses should minimally implement this method.
|
||||
*
|
||||
* Since 0.10.3 subclasses that synchronize on the clock in the ::render method
|
||||
* Since 0.10.3 subclasses that synchronise on the clock in the ::render method
|
||||
* are supported as well. These classes typically receive a buffer in the render
|
||||
* method and can then potentially block on the clock while rendering. A typical
|
||||
* example would be an audiosink.
|
||||
* example is an audiosink.
|
||||
*
|
||||
* Upon receiving the EOS event in the PLAYING state, #GstBaseSink will wait for
|
||||
* the clock to reach the time indicated by the stop time of the last ::get_times
|
||||
* call before posting an EOS message. When the element receives EOS in PAUSED,
|
||||
* preroll completes, the event is queued and an EOS message is posted when going
|
||||
* to PLAYING.
|
||||
* Upon receiving the EOS event in the PLAYING state, #GstBaseSink will wait
|
||||
* for the clock to reach the time indicated by the stop time of the last
|
||||
* ::get_times call before posting an EOS message. When the element receives
|
||||
* EOS in PAUSED, preroll completes, the event is queued and an EOS message is
|
||||
* posted when going to PLAYING.
|
||||
*
|
||||
* #GstBaseSink will internally use the GST_EVENT_NEW_SEGMENT events to schedule
|
||||
* synchronisation and clipping of buffers. Buffers that fall completely outside
|
||||
* of the segment are dropped. Buffers that fall partially in the segment are
|
||||
* rendered (and prerolled), subclasses should do any subbuffer clipping themselves
|
||||
* when needed.
|
||||
* of the current segment are dropped. Buffers that fall partially in the
|
||||
* segment are rendered (and prerolled). Subclasses should do any subbuffer
|
||||
* clipping themselves when needed.
|
||||
*
|
||||
* #GstBaseSink will by default report the current playback position in
|
||||
* GST_FORMAT_TIME based on the current clock time and segment information.
|
||||
* If no clock has been set on the element, the query will be forwarded upstream.
|
||||
* If no clock has been set on the element, the query will be forwarded
|
||||
* upstream.
|
||||
*
|
||||
* The ::set_caps function will be called when the subclass should configure itself
|
||||
* to process a specific media type.
|
||||
* The ::set_caps function will be called when the subclass should configure
|
||||
* itself to process a specific media type.
|
||||
*
|
||||
* The ::start and ::stop virtual methods will be called when resources should be
|
||||
* allocated. Any ::preroll, ::render and ::set_caps function will be called
|
||||
* between the ::start and ::stop calls.
|
||||
* The ::start and ::stop virtual methods will be called when resources should
|
||||
* be allocated. Any ::preroll, ::render and ::set_caps function will be
|
||||
* called between the ::start and ::stop calls.
|
||||
*
|
||||
* The ::event virtual method will be called when an event is received by
|
||||
* #GstBaseSink. Normally this method should only be overriden by very specific
|
||||
* elements such as file sinks that need to handle the newsegment event specially.
|
||||
* elements (such as file sinks) which need to handle the newsegment event
|
||||
* specially.
|
||||
*
|
||||
* #GstBaseSink provides an overridable ::buffer_alloc function that can be used
|
||||
* by specific sinks that want to do reverse negotiation or want to provided
|
||||
* hardware accelerated buffers for downstream elements.
|
||||
* #GstBaseSink provides an overridable ::buffer_alloc function that can be
|
||||
* used by sinks that want to do reverse negotiation or to provide
|
||||
* custom buffers (hardware buffers for example) to upstream elements.
|
||||
*
|
||||
* The ::unlock method is called when the elements should unblock any blocking
|
||||
* operations they perform in the ::render method. This is mostly usefull when
|
||||
* the ::render method performs a blocking write on a file descripter.
|
||||
* operations they perform in the ::render method. This is mostly useful when
|
||||
* the ::render method performs a blocking write on a file descriptor, for
|
||||
* example.
|
||||
*
|
||||
* The max-lateness property defines how the sink deals with buffers that arrive
|
||||
* too late in the sink. A buffer arrives too late in the sink when the presentation
|
||||
* time (as a combination of the last segment, buffer timestamp and element
|
||||
* base_time) plus the duration is before the current time of the clock.
|
||||
* If the frame is later than max-lateness, the sink will drop the buffer.
|
||||
* This feature is disabled if sync is disabled, the ::get-times method does not
|
||||
* return a valid start time or max-lateness is set to -1 (the default).
|
||||
* Subclasses can use gst_base_sink_set_max_lateness() to configure the max-lateness.
|
||||
* The max-lateness property affects how the sink deals with buffers that
|
||||
* arrive too late in the sink. A buffer arrives too late in the sink when
|
||||
* the presentation time (as a combination of the last segment, buffer
|
||||
* timestamp and element base_time) plus the duration is before the current
|
||||
* time of the clock.
|
||||
* If the frame is later than max-lateness, the sink will drop the buffer
|
||||
* without calling the render method.
|
||||
* This feature is disabled if sync is disabled, the ::get-times method does
|
||||
* not return a valid start time or max-lateness is set to -1 (the default).
|
||||
* Subclasses can use gst_base_sink_set_max_lateness() to configure the
|
||||
* max-lateness value.
|
||||
*
|
||||
* The qos property will enable the quality-of-service features of the basesink
|
||||
* which gather statistics about the real-time performance of the clock
|
||||
* synchronisation. For each dropped buffer it will also send a QoS message
|
||||
* upstream.
|
||||
*
|
||||
* Last reviewed on 2006-03-21 (0.10.5)
|
||||
* Last reviewed on 2006-03-31 (0.10.5)
|
||||
*/
|
||||
|
||||
#ifdef HAVE_CONFIG_H
|
||||
|
|
|
|||
|
|
@ -102,6 +102,31 @@ struct _GstBaseSink {
|
|||
GstBaseSinkPrivate *priv;
|
||||
};
|
||||
|
||||
/**
|
||||
* GstBaseSinkClass:
|
||||
* @parent_class: Element parent class
|
||||
* @get_caps: Called to get sink pad caps from the subclass
|
||||
* @set_caps: Notify subclass of changed caps
|
||||
* @buffer_alloc: Subclasses can override to perform custom buffer allocations
|
||||
* @get_times: Called to get the start and end times for synchronising
|
||||
* the passed buffer to the clock
|
||||
* @start: Start processing. Ideal for opening resources in the subclass
|
||||
* @stop: Stop processing. Subclasses should use this to close resources.
|
||||
* @unlock: Unlock any pending access to the resource. Subclasses should
|
||||
* unblock any blocked function ASAP
|
||||
* @event: Override this to handle events arriving on the sink pad
|
||||
* @preroll: Called to present the preroll buffer if desired
|
||||
* @render: Called when a buffer should be presented or output, at the
|
||||
* correct moment if the #GstBaseSink has been set to sync to
|
||||
* the clock.
|
||||
* @async_play: Subclasses should override this when they need to perform
|
||||
* special processing when changing to the PLAYING state asynchronously.
|
||||
* Called with the OBJECT_LOCK held.
|
||||
*
|
||||
* Subclasses can override any of the available virtual methods or not, as
|
||||
* needed. At the minimum, the render method should be overridden to
|
||||
* output/present buffers
|
||||
*/
|
||||
struct _GstBaseSinkClass {
|
||||
GstElementClass parent_class;
|
||||
|
||||
|
|
|
|||
|
|
@ -35,23 +35,25 @@
|
|||
*
|
||||
* <refsect2>
|
||||
* <para>
|
||||
* The source can be configured to operate in a any #GstFormat with the
|
||||
* gst_base_src_set_format(). This format determines the format of the
|
||||
* internal #GstSegment and the #GST_EVENT_NEW_SEGMENT. The default format for
|
||||
* #GstBaseSrc is GST_FORMAT_BYTES.
|
||||
* The source can be configured to operate in any #GstFormat with the
|
||||
* gst_base_src_set_format() method. The currently set format determines
|
||||
* the format of the internal #GstSegment and any #GST_EVENT_NEW_SEGMENT
|
||||
* events. The default format for #GstBaseSrc is #GST_FORMAT_BYTES.
|
||||
* </para>
|
||||
* <para>
|
||||
* #GstBaseSrc always supports the push mode scheduling. If the following
|
||||
* #GstBaseSrc always supports push mode scheduling. If the following
|
||||
* conditions are met, it also supports pull mode scheduling:
|
||||
* <itemizedlist>
|
||||
* <listitem><para>the format is set to GST_FORMAT_BYTES (default).</para></listitem>
|
||||
* <listitem><para>#GstBaseSrc::is_seekable returns TRUE.</para></listitem>
|
||||
* <listitem><para>The format is set to GST_FORMAT_BYTES (default).</para>
|
||||
* </listitem>
|
||||
* <listitem><para>#GstBaseSrc::is_seekable returns TRUE.</para>
|
||||
* </listitem>
|
||||
* </itemizedlist>
|
||||
* </para>
|
||||
* <para>
|
||||
* If all the conditions are met for operating in pull mode, #GstBaseSrc is
|
||||
* automatically seekable in push mode as well. The following conditions must be
|
||||
* met to make the element seekable in push mode when the format is not
|
||||
* automatically seekable in push mode as well. The following conditions must
|
||||
* be met to make the element seekable in push mode when the format is not
|
||||
* GST_FORMAT_BYTES:
|
||||
* <itemizedlist>
|
||||
* <listitem><para>
|
||||
|
|
@ -67,37 +69,39 @@
|
|||
* </itemizedlist>
|
||||
* </para>
|
||||
* <para>
|
||||
* When the default format is not GST_FORMAT_BYTES, the element should ignore the
|
||||
* offset and length in the #GstBaseSrc::create method. It is recommended to subclass
|
||||
* #GstPushSrc instead in this situation.
|
||||
* When the default format is not GST_FORMAT_BYTES, the subclass should ignore
|
||||
* the offset and length in the #GstBaseSrc::create method. It is recommended
|
||||
* to subclass #GstPushSrc instead in this situation.
|
||||
* </para>
|
||||
* <para>
|
||||
* #GstBaseSrc has support for live sources. Live sources are sources that produce
|
||||
* data at a fixed rate, such as audio or video capture. A typical live source also
|
||||
* provides a clock to export the rate at which they produce data.
|
||||
* #GstBaseSrc has support for live sources. Live sources are sources that
|
||||
* produce data at a fixed rate, such as audio or video capture devices. A
|
||||
* typical live source also provides a clock to publish the rate at which
|
||||
* they produce data.
|
||||
* Use gst_base_src_set_live() to activate the live source mode.
|
||||
* </para>
|
||||
* <para>
|
||||
* A live source does not produce data in the PAUSED state, this means that the
|
||||
* A live source does not produce data in the PAUSED state. This means that the
|
||||
* #GstBaseSrc::create method will not be called in PAUSED but only in PLAYING.
|
||||
* To signal the pipeline that the element will not produce data, its return
|
||||
* To signal the pipeline that the element will not produce data, the return
|
||||
* value from the READY to PAUSED state will be GST_STATE_CHANGE_NO_PREROLL.
|
||||
* </para>
|
||||
* <para>
|
||||
* A typical live source will timestamp the buffers they create with the current
|
||||
* stream time of the pipeline. This is why they can only produce data in PLAYING,
|
||||
* when the clock is actually distributed and running.
|
||||
* A typical live source will timestamp the buffers they create with the
|
||||
* current stream time of the pipeline. This is one reason that they can only
|
||||
* produce data in PLAYING, when the clock is actually distributed and running.
|
||||
* </para>
|
||||
* <para>
|
||||
* The #GstBaseSrc::get_times method can be used to implement pseudo-live sources.
|
||||
* The base source will wait for the specified stream time returned in
|
||||
* #GstBaseSrc::get_times before pushing out the buffer. It only makes sense to implement
|
||||
* the ::get_times function if the source is a live source.
|
||||
* The #GstBaseSrc::get_times method can be used to implement pseudo-live
|
||||
* sources. The base source will wait for the specified stream time returned in
|
||||
* #GstBaseSrc::get_times before pushing out the buffer.
|
||||
* It only makes sense to implement the ::get_times function if the source is
|
||||
* a live source.
|
||||
* </para>
|
||||
* <para>
|
||||
* There is only support in GstBaseSrc for one source pad, which should be named
|
||||
* "src". A source implementation (subclass of GstBaseSrc) should install a pad
|
||||
* template in its base_init function, like so:
|
||||
* There is only support in GstBaseSrc for exactly one source pad, which
|
||||
* should be named "src". A source implementation (subclass of GstBaseSrc)
|
||||
* should install a pad template in its base_init function, like so:
|
||||
* </para>
|
||||
* <para>
|
||||
* <programlisting>
|
||||
|
|
@ -118,7 +122,7 @@
|
|||
* <para>
|
||||
* Applications that record from a live source may want to stop recording
|
||||
* in a controlled way, so that the recording is stopped, but the data
|
||||
* already in the pipeline processed to the end (remember that many live
|
||||
* already in the pipeline is processed to the end (remember that many live
|
||||
* sources would go on recording forever otherwise). For that to happen the
|
||||
* application needs to make the source stop recording and send an EOS
|
||||
* event down the pipeline. The application would then wait for an
|
||||
|
|
@ -150,7 +154,7 @@
|
|||
* </programlisting>
|
||||
* </para>
|
||||
* <para>
|
||||
* Last reviewed on 2006-03-07 (0.10.4)
|
||||
* Last reviewed on 2006-03-31 (0.10.5)
|
||||
* </para>
|
||||
* </refsect2>
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -117,8 +117,31 @@ struct _GstBaseSrc {
|
|||
|
||||
/**
|
||||
* GstBaseSrcClass:
|
||||
* @create: ask the subclass to create a buffer with offset and size
|
||||
* @start: start processing
|
||||
* @parent_class: Element parent class
|
||||
* @get_caps: Called to get the caps to report
|
||||
* @set_caps: Notify subclass of changed output caps
|
||||
* @negotiate: Negotiated the caps with the peer.
|
||||
* @newsegment: Generate and send a new_segment event.
|
||||
* @start: Start processing. Subclasses should open resources and prepare
|
||||
* to produce data.
|
||||
* @stop: Stop processing. Subclasses should use this to close resources.
|
||||
* @get_times: Given a buffer, return the start and stop time when it
|
||||
* should be pushed out. The base class will sync on the clock using
|
||||
* these times.
|
||||
* @get_size: Return the total size of the resource, in the configured format.
|
||||
* @is_seekable: Check if the source can seek
|
||||
* @unlock: Unlock any pending access to the resource. Subclasses should
|
||||
* unblock any blocked function ASAP
|
||||
* @event: Override this to implement custom event handling.
|
||||
* @create: Ask the subclass to create a buffer with offset and size.
|
||||
* @do_seek: Perform seeking on the resource to the indicated segment.
|
||||
* @query: Handle a requested query.
|
||||
* @check_get_range: Check whether the source would support pull-based
|
||||
* operation if it were to be opened now. This vfunc is optional, but
|
||||
* should be implemented if possible to avoid unnecessary start/stop
|
||||
* cycles. The default implementation will open and close the resource
|
||||
* to find out whether get_range is supported, and that is usually
|
||||
* undesirable.
|
||||
*/
|
||||
struct _GstBaseSrcClass {
|
||||
GstElementClass parent_class;
|
||||
|
|
|
|||
Loading…
Reference in a new issue