mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-24 09:10:36 +00:00
baseparse: Documentation improvements
* Remove references to old functions and methods * Use proper #ClassName.vmethod() decorator for vmethod
This commit is contained in:
Edward Hervey
Edward Hervey
parent
cc869065a5
commit
dfe5467209
2 changed files with 82 additions and 59 deletions
|
|
@ -47,17 +47,17 @@
|
|||
*
|
||||
* ## Set-up phase
|
||||
*
|
||||
* * #GstBaseParse calls @start to inform subclass that data processing is
|
||||
* about to start now.
|
||||
* * #GstBaseParse calls #GstBaseParseClass.start() to inform subclass
|
||||
* that data processing is about to start now.
|
||||
*
|
||||
* * #GstBaseParse class calls @set_sink_caps to inform the subclass about
|
||||
* incoming sinkpad caps. Subclass could already set the srcpad caps
|
||||
* accordingly, but this might be delayed until calling
|
||||
* gst_base_parse_finish_frame() with a non-queued frame.
|
||||
* * #GstBaseParse class calls #GstBaseParseClass.set_sink_caps() to
|
||||
* inform the subclass about incoming sinkpad caps. Subclass could
|
||||
* already set the srcpad caps accordingly, but this might be delayed
|
||||
* until calling gst_base_parse_finish_frame() with a non-queued frame.
|
||||
*
|
||||
* * At least at this point subclass needs to tell the #GstBaseParse class
|
||||
* how big data chunks it wants to receive (min_frame_size). It can do
|
||||
* this with gst_base_parse_set_min_frame_size().
|
||||
* how big data chunks it wants to receive (minimum frame size ). It can
|
||||
* do this with gst_base_parse_set_min_frame_size().
|
||||
*
|
||||
* * #GstBaseParse class sets up appropriate data passing mode (pull/push)
|
||||
* and starts to process the data.
|
||||
|
|
@ -68,24 +68,27 @@
|
|||
* by pulling it from upstream or collecting buffers in an internal
|
||||
* #GstAdapter.
|
||||
*
|
||||
* * A buffer of (at least) min_frame_size bytes is passed to subclass with
|
||||
* @handle_frame. Subclass checks the contents and can optionally
|
||||
* return GST_FLOW_OK along with an amount of data to be skipped to find
|
||||
* a valid frame (which will result in a subsequent DISCONT).
|
||||
* If, otherwise, the buffer does not hold a complete frame,
|
||||
* @handle_frame can merely return and will be called again when additional
|
||||
* data is available. In push mode this amounts to an
|
||||
* additional input buffer (thus minimal additional latency), in pull mode
|
||||
* this amounts to some arbitrary reasonable buffer size increase.
|
||||
* Of course, gst_base_parse_set_min_frame_size() could also be used if a
|
||||
* very specific known amount of additional data is required.
|
||||
* If, however, the buffer holds a complete valid frame, it can pass
|
||||
* the size of this frame to gst_base_parse_finish_frame().
|
||||
* If acting as a converter, it can also merely indicate consumed input data
|
||||
* while simultaneously providing custom output data.
|
||||
* Note that baseclass performs some processing (such as tracking
|
||||
* overall consumed data rate versus duration) for each finished frame,
|
||||
* but other state is only updated upon each call to @handle_frame
|
||||
* * A buffer of (at least) min_frame_size bytes is passed to subclass
|
||||
* with #GstBaseParseClass.handle_frame(). Subclass checks the contents
|
||||
* and can optionally return #GST_FLOW_OK along with an amount of data
|
||||
* to be skipped to find a valid frame (which will result in a
|
||||
* subsequent DISCONT). If, otherwise, the buffer does not hold a
|
||||
* complete frame, #GstBaseParseClass.handle_frame() can merely return
|
||||
* and will be called again when additional data is available. In push
|
||||
* mode this amounts to an additional input buffer (thus minimal
|
||||
* additional latency), in pull mode this amounts to some arbitrary
|
||||
* reasonable buffer size increase.
|
||||
*
|
||||
* Of course, gst_base_parse_set_min_frame_size() could also be used if
|
||||
* a very specific known amount of additional data is required. If,
|
||||
* however, the buffer holds a complete valid frame, it can pass the
|
||||
* size of this frame to gst_base_parse_finish_frame().
|
||||
*
|
||||
* If acting as a converter, it can also merely indicate consumed input
|
||||
* data while simultaneously providing custom output data. Note that
|
||||
* baseclass performs some processing (such as tracking overall consumed
|
||||
* data rate versus duration) for each finished frame, but other state
|
||||
* is only updated upon each call to #GstBaseParseClass.handle_frame()
|
||||
* (such as tracking upstream input timestamp).
|
||||
*
|
||||
* Subclass is also responsible for setting the buffer metadata
|
||||
|
|
@ -96,28 +99,30 @@
|
|||
* duration obtained from configuration (see below), and offset
|
||||
* if meaningful (in pull mode).
|
||||
*
|
||||
* Note that @check_valid_frame might receive any small
|
||||
* amount of input data when leftover data is being drained (e.g. at EOS).
|
||||
* Note that #GstBaseParseClass.handle_frame() might receive any small
|
||||
* amount of input data when leftover data is being drained (e.g. at
|
||||
* EOS).
|
||||
*
|
||||
* * As part of finish frame processing,
|
||||
* just prior to actually pushing the buffer in question,
|
||||
* it is passed to @pre_push_frame which gives subclass yet one
|
||||
* last chance to examine buffer metadata, or to send some custom (tag)
|
||||
* * As part of finish frame processing, just prior to actually pushing
|
||||
* the buffer in question, it is passed to
|
||||
* #GstBaseParseClass.pre_push_frame() which gives subclass yet one last
|
||||
* chance to examine buffer metadata, or to send some custom (tag)
|
||||
* events, or to perform custom (segment) filtering.
|
||||
*
|
||||
* * During the parsing process #GstBaseParseClass will handle both srcpad
|
||||
* and sinkpad events. They will be passed to subclass if @event or
|
||||
* @src_event callbacks have been provided.
|
||||
* and sinkpad events. They will be passed to subclass if
|
||||
* #GstBaseParseClass.event() or #GstBaseParseClass.src_event()
|
||||
* implementations have been provided.
|
||||
*
|
||||
* ## Shutdown phase
|
||||
*
|
||||
* * #GstBaseParse class calls @stop to inform the subclass that data
|
||||
* parsing will be stopped.
|
||||
* * #GstBaseParse class calls #GstBaseParseClass.stop() to inform the
|
||||
* subclass that data parsing will be stopped.
|
||||
*
|
||||
* Subclass is responsible for providing pad template caps for
|
||||
* source and sink pads. The pads need to be named "sink" and "src". It also
|
||||
* needs to set the fixed caps on srcpad, when the format is ensured (e.g.
|
||||
* when base class calls subclass' @set_sink_caps function).
|
||||
* Subclass is responsible for providing pad template caps for source and
|
||||
* sink pads. The pads need to be named "sink" and "src". It also needs to
|
||||
* set the fixed caps on srcpad, when the format is ensured (e.g. when
|
||||
* base class calls subclass' #GstBaseParseClass.set_sink_caps() function).
|
||||
*
|
||||
* This base class uses %GST_FORMAT_DEFAULT as a meaning of frames. So,
|
||||
* subclass conversion routine needs to know that conversion from
|
||||
|
|
@ -136,9 +141,10 @@
|
|||
* * Fixate the source pad caps when appropriate
|
||||
* * Inform base class how big data chunks should be retrieved. This is
|
||||
* done with gst_base_parse_set_min_frame_size() function.
|
||||
* * Examine data chunks passed to subclass with @handle_frame and pass
|
||||
* proper frame(s) to gst_base_parse_finish_frame(), and setting src pad
|
||||
* caps and timestamps on frame.
|
||||
* * Examine data chunks passed to subclass with
|
||||
* #GstBaseParseClass.handle_frame() and pass proper frame(s) to
|
||||
* gst_base_parse_finish_frame(), and setting src pad caps and timestamps
|
||||
* on frame.
|
||||
* * Provide conversion functions
|
||||
* * Update the duration information with gst_base_parse_set_duration()
|
||||
* * Optionally passthrough using gst_base_parse_set_passthrough()
|
||||
|
|
@ -148,13 +154,14 @@
|
|||
*
|
||||
* * In particular, if subclass is unable to determine a duration, but
|
||||
* parsing (or specs) yields a frames per seconds rate, then this can be
|
||||
* provided to #GstBaseParse to enable it to cater for
|
||||
* buffer time metadata (which will be taken from upstream as much as
|
||||
* provided to #GstBaseParse to enable it to cater for buffer time
|
||||
* metadata (which will be taken from upstream as much as
|
||||
* possible). Internally keeping track of frame durations and respective
|
||||
* sizes that have been pushed provides #GstBaseParse with an estimated
|
||||
* bitrate. A default @convert (used if not overridden) will then use these
|
||||
* rates to perform obvious conversions. These rates are also used to
|
||||
* update (estimated) duration at regular frame intervals.
|
||||
* bitrate. A default #GstBaseParseClass.convert() (used if not
|
||||
* overridden) will then use these rates to perform obvious conversions.
|
||||
* These rates are also used to update (estimated) duration at regular
|
||||
* frame intervals.
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
@ -655,6 +662,15 @@ gst_base_parse_get_property (GObject * object, guint prop_id, GValue * value,
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* gst_base_parse_frame_copy:
|
||||
* @frame: a #GstBaseParseFrame
|
||||
*
|
||||
* Copies a #GstBaseParseFrame.
|
||||
*
|
||||
* Returns: A copy of @frame
|
||||
*/
|
||||
|
||||
GstBaseParseFrame *
|
||||
gst_base_parse_frame_copy (GstBaseParseFrame * frame)
|
||||
{
|
||||
|
|
@ -669,6 +685,12 @@ gst_base_parse_frame_copy (GstBaseParseFrame * frame)
|
|||
return copy;
|
||||
}
|
||||
|
||||
/**
|
||||
* gst_base_parse_frame_free:
|
||||
* @frame: A #GstBaseParseFrame
|
||||
*
|
||||
* Frees the provided @frame.
|
||||
*/
|
||||
void
|
||||
gst_base_parse_frame_free (GstBaseParseFrame * frame)
|
||||
{
|
||||
|
|
@ -1651,7 +1673,7 @@ gst_base_parse_src_event_default (GstBaseParse * parse, GstEvent * event)
|
|||
* @dest_format: #GstFormat defining the converted format.
|
||||
* @dest_value: (out): Pointer where the conversion result will be put.
|
||||
*
|
||||
* Default implementation of "convert" vmethod in #GstBaseParse class.
|
||||
* Default implementation of #GstBaseParseClass.convert().
|
||||
*
|
||||
* Returns: %TRUE if conversion was successful.
|
||||
*/
|
||||
|
|
@ -3818,11 +3840,11 @@ gst_base_parse_set_average_bitrate (GstBaseParse * parse, guint bitrate)
|
|||
/**
|
||||
* gst_base_parse_set_min_frame_size:
|
||||
* @parse: #GstBaseParse.
|
||||
* @min_size: Minimum size of the data that this base class should give to
|
||||
* subclass.
|
||||
* @min_size: Minimum size in bytes of the data that this base class should
|
||||
* give to subclass.
|
||||
*
|
||||
* Subclass can use this function to tell the base class that it needs to
|
||||
* give at least #min_size buffers.
|
||||
* be given buffers of at least @min_size bytes.
|
||||
*/
|
||||
void
|
||||
gst_base_parse_set_min_frame_size (GstBaseParse * parse, guint min_size)
|
||||
|
|
@ -3930,10 +3952,10 @@ gst_base_parse_set_syncable (GstBaseParse * parse, gboolean syncable)
|
|||
* Set if the nature of the format or configuration does not allow (much)
|
||||
* parsing, and the parser should operate in passthrough mode (which only
|
||||
* applies when operating in push mode). That is, incoming buffers are
|
||||
* pushed through unmodified, i.e. no @check_valid_frame or @parse_frame
|
||||
* callbacks will be invoked, but @pre_push_frame will still be invoked,
|
||||
* so subclass can perform as much or as little is appropriate for
|
||||
* passthrough semantics in @pre_push_frame.
|
||||
* pushed through unmodified, i.e. no #GstBaseParseClass.handle_frame()
|
||||
* will be invoked, but #GstBaseParseClass.pre_push_frame() will still be
|
||||
* invoked, so subclass can perform as much or as little is appropriate for
|
||||
* passthrough semantics in #GstBaseParseClass.pre_push_frame().
|
||||
*/
|
||||
void
|
||||
gst_base_parse_set_passthrough (GstBaseParse * parse, gboolean passthrough)
|
||||
|
|
|
|||
|
|
@ -54,9 +54,10 @@ G_BEGIN_DECLS
|
|||
/**
|
||||
* GST_BASE_PARSE_FLOW_DROPPED:
|
||||
*
|
||||
* A #GstFlowReturn that can be returned from parse_frame to
|
||||
* indicate that no output buffer was generated, or from pre_push_frame to
|
||||
* to forego pushing buffer.
|
||||
* A #GstFlowReturn that can be returned from
|
||||
* #GstBaseParseClass.handle_frame() to indicate that no output buffer was
|
||||
* generated, or from #GstBaseParseClass.pre_push_frame() to to forego
|
||||
* pushing buffer.
|
||||
*/
|
||||
#define GST_BASE_PARSE_FLOW_DROPPED GST_FLOW_CUSTOM_SUCCESS
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue