mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-24 01:00:37 +00:00
Code Issues 1 Projects Releases Wiki Activity
gstreamer/gst/gstsegment.h

351 lines
17 KiB
C
Raw Blame History

/* GStreamer
* Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
*
* gstsegment.h: Header for GstSegment subsystem
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
#ifndef __GST_SEGMENT_H__
#define __GST_SEGMENT_H__
#include <gst/gstformat.h>
G_BEGIN_DECLS
#define GST_TYPE_SEGMENT (gst_segment_get_type())
typedef struct _GstSegment GstSegment;
/**
* GstSeekType:
* @GST_SEEK_TYPE_NONE: no change in position is required
* @GST_SEEK_TYPE_SET: absolute position is requested
* @GST_SEEK_TYPE_END: relative position to duration is requested
*
* The different types of seek events. When constructing a seek event with
* gst_event_new_seek() or when doing gst_segment_do_seek ().
*/
typedef enum {
/* one of these */
GST_SEEK_TYPE_NONE = 0,
GST_SEEK_TYPE_SET = 1,
GST_SEEK_TYPE_END = 2
} GstSeekType;
/**
* GstSeekFlags:
* @GST_SEEK_FLAG_NONE: no flag
* @GST_SEEK_FLAG_FLUSH: flush pipeline
* @GST_SEEK_FLAG_ACCURATE: accurate position is requested, this might
* be considerably slower for some formats.
* @GST_SEEK_FLAG_KEY_UNIT: seek to the nearest keyframe. This might be
* faster but less accurate.
* @GST_SEEK_FLAG_SEGMENT: perform a segment seek.
* @GST_SEEK_FLAG_TRICKMODE: when doing fast forward or fast reverse playback, allow
* elements to skip frames instead of generating all
* frames. (Since: 1.6)
* @GST_SEEK_FLAG_SNAP_BEFORE: go to a location before the requested position,
* if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at or before
* the requested position the one at or before the seek target.
* @GST_SEEK_FLAG_SNAP_AFTER: go to a location after the requested position,
* if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at of after the
* requested position.
* @GST_SEEK_FLAG_SNAP_NEAREST: go to a position near the requested position,
* if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe closest
* to the requested position, if both keyframes are at an equal
* distance, behaves like %GST_SEEK_FLAG_SNAP_BEFORE.
* @GST_SEEK_FLAG_TRICKMODE_KEY_UNITS: when doing fast forward or fast reverse
* playback, request that elements only decode keyframes
* and skip all other content, for formats that have
* keyframes. (Since: 1.6)
* @GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED: When doing fast forward or fast reverse
* playback, request that elements only decode keyframes and
* forward predicted frames and skip all other content (for example
* B-Frames), for formats that have keyframes and forward predicted
* frames. (Since: 1.18)
* @GST_SEEK_FLAG_TRICKMODE_NO_AUDIO: when doing fast forward or fast reverse
* playback, request that audio decoder elements skip
* decoding and output only gap events or silence. (Since: 1.6)
* @GST_SEEK_FLAG_INSTANT_RATE_CHANGE: Signals that a rate change should be
* applied immediately. Only valid if start/stop position
* are GST_CLOCK_TIME_NONE, the playback direction does not change
* and the seek is not flushing. (Since: 1.18)
* @GST_SEEK_FLAG_SKIP: Deprecated backward compatibility flag, replaced
* by %GST_SEEK_FLAG_TRICKMODE
*
* Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags
* can be used together.
*
* A non flushing seek might take some time to perform as the currently
* playing data in the pipeline will not be cleared.
*
* An accurate seek might be slower for formats that don't have any indexes
* or timestamp markers in the stream. Specifying this flag might require a
* complete scan of the file in those cases.
*
* When performing a segment seek: after the playback of the segment completes,
* no EOS will be emitted by the element that performed the seek, but a
* %GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element.
* When this message is posted, it is possible to send a new seek event to
* continue playback. With this seek method it is possible to perform seamless
* looping or simple linear editing.
*
* When only changing the playback rate and not the direction, the
* %GST_SEEK_FLAG_INSTANT_RATE_CHANGE flag can be used for a non-flushing seek
* to signal that the rate change should be applied immediately. This requires
* special support in the seek handlers (e.g. demuxers) and any elements
* synchronizing to the clock, and in general can't work in all cases (for example
* UDP streaming where the delivery rate is controlled by a remote server). The
* instant-rate-change mode supports changing the trickmode-related GST_SEEK_ flags,
* but can't be used in conjunction with other seek flags that affect the new
* playback position - as the playback position will not be changing.
*
* When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode
* playback, the %GST_SEEK_FLAG_TRICKMODE flag can be used to instruct decoders
* and demuxers to adjust the playback rate by skipping frames. This can improve
* performance and decrease CPU usage because not all frames need to be decoded.
*
* Beyond that, the %GST_SEEK_FLAG_TRICKMODE_KEY_UNITS flag can be used to
* request that decoders skip all frames except key units, and
* %GST_SEEK_FLAG_TRICKMODE_NO_AUDIO flags can be used to request that audio
* decoders do no decoding at all, and simple output silence.
*
* The %GST_SEEK_FLAG_SNAP_BEFORE flag can be used to snap to the previous
* relevant location, and the %GST_SEEK_FLAG_SNAP_AFTER flag can be used to
* select the next relevant location. If %GST_SEEK_FLAG_KEY_UNIT is specified,
* the relevant location is a keyframe. If both flags are specified, the nearest
* of these locations will be selected. If none are specified, the implementation is
* free to select whichever it wants.
*
* The before and after here are in running time, so when playing backwards,
* the next location refers to the one that will played in next, and not the
* one that is located after in the actual source stream.
*
* Also see part-seeking.txt in the GStreamer design documentation for more
* details on the meaning of these flags and the behaviour expected of
* elements that handle them.
*/
typedef enum {
GST_SEEK_FLAG_NONE = 0,
GST_SEEK_FLAG_FLUSH = (1 << 0),
GST_SEEK_FLAG_ACCURATE = (1 << 1),
GST_SEEK_FLAG_KEY_UNIT = (1 << 2),
GST_SEEK_FLAG_SEGMENT = (1 << 3),
GST_SEEK_FLAG_TRICKMODE = (1 << 4),
/* FIXME 2.0: Remove _SKIP flag,
* which was kept for backward compat when _TRICKMODE was added */
GST_SEEK_FLAG_SKIP = (1 << 4),
GST_SEEK_FLAG_SNAP_BEFORE = (1 << 5),
GST_SEEK_FLAG_SNAP_AFTER = (1 << 6),
GST_SEEK_FLAG_SNAP_NEAREST = GST_SEEK_FLAG_SNAP_BEFORE | GST_SEEK_FLAG_SNAP_AFTER,
/* Careful to restart next flag with 1<<7 here */
GST_SEEK_FLAG_TRICKMODE_KEY_UNITS = (1 << 7),
GST_SEEK_FLAG_TRICKMODE_NO_AUDIO = (1 << 8),
GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED = (1 << 9),
GST_SEEK_FLAG_INSTANT_RATE_CHANGE = (1 << 10),
} GstSeekFlags;
/**
* GstSegmentFlags:
* @GST_SEGMENT_FLAG_NONE: no flags
* @GST_SEGMENT_FLAG_RESET: reset the pipeline running_time to the segment
* running_time
* @GST_SEGMENT_FLAG_TRICKMODE: perform skip playback (Since: 1.6)
* @GST_SEGMENT_FLAG_SEGMENT: send SEGMENT_DONE instead of EOS
* @GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS: Decode only keyframes, where
* possible (Since: 1.6)
* @GST_SEGMENT_FLAG_TRICKMODE_FORWARD_PREDICTED: Decode only keyframes or forward
* predicted frames, where possible (Since: 1.18)
* @GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO: Do not decode any audio, where
* possible (Since: 1.6)
* @GST_SEGMENT_FLAG_SKIP: Deprecated backward compatibility flag, replaced
* by @GST_SEGMENT_FLAG_TRICKMODE
*
* Flags for the GstSegment structure. Currently mapped to the corresponding
* values of the seek flags.
*/
/* Note: update gst_segment_do_seek() when adding new flags here */
typedef enum { /*< flags >*/
GST_SEGMENT_FLAG_NONE = GST_SEEK_FLAG_NONE,
GST_SEGMENT_FLAG_RESET = GST_SEEK_FLAG_FLUSH,
GST_SEGMENT_FLAG_TRICKMODE = GST_SEEK_FLAG_TRICKMODE,
/* FIXME 2.0: Remove _SKIP flag,
* which was kept for backward compat when _TRICKMODE was added */
GST_SEGMENT_FLAG_SKIP = GST_SEEK_FLAG_TRICKMODE,
GST_SEGMENT_FLAG_SEGMENT = GST_SEEK_FLAG_SEGMENT,
GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS = GST_SEEK_FLAG_TRICKMODE_KEY_UNITS,
GST_SEGMENT_FLAG_TRICKMODE_FORWARD_PREDICTED = GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED,
GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO = GST_SEEK_FLAG_TRICKMODE_NO_AUDIO
} GstSegmentFlags;
/* Flags that are reflected for instant-rate-change seeks */
#define GST_SEGMENT_INSTANT_FLAGS \
(GST_SEGMENT_FLAG_TRICKMODE|GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS|GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED|GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO)
/**
* GstSegment:
* @flags: flags for this segment
* @rate: the playback rate of the segment is set in response to a seek
* event and, without any seek, the value should be `1.0`. This
* value is used by elements that synchronize buffer [running
* times](additional/design/synchronisation.md#running-time) on
* the clock (usually the sink elements), leading to consuming
* buffers faster (for a value `> 1.0`) or slower (for `0.0 <
* value < 1.0`) than normal playback speed. The rate also
* defines the playback direction, meaning that when the value is
* lower than `0.0`, the playback happens in reverse, and the
* [stream-time](additional/design/synchronisation.md#stream-time)
* is going backward. The `rate` value should never be `0.0`.
* @applied_rate: The applied rate is the rate that has been applied to the stream.
* The effective/resulting playback rate of a stream is
* `rate * applied_rate`.
* The applied rate can be set by source elements when a server is
* sending the stream with an already modified playback speed
* rate. Filter elements that modify the stream in a way that
* modifies the playback speed should also modify the applied
* rate. For example the #videorate element when its
* #videorate:rate property is set will set the applied rate of
* the segment it pushed downstream. Also #scaletempo applies the
* input segment rate to the stream and outputs a segment with
* rate=1.0 and applied_rate=<inputsegment.rate>.
* @format: the unit used for all of the segment's values.
* @base: the running time (plus elapsed time, see offset) of the
* segment [start](GstSegment.start) ([stop](GstSegment.stop) if
* rate < 0.0).
* @offset: the offset expresses the elapsed time (in buffer timestamps)
* before a seek with its start (stop if rate < 0.0) seek type
* set to #GST_SEEK_TYPE_NONE, the value is set to the position
* of the segment at the time of the seek.
* @start: the start time of the segment (in buffer timestamps)
* [(PTS)](GstBuffer.pts), that is the timestamp of the first
* buffer to output inside the segment (last one during
* reverse playback). For example decoders will
* [clip](gst_segment_clip) out the buffers before the start
* time.
* @stop: the stop time of the segment (in buffer timestamps)
* [(PTS)](GstBuffer.pts), that is the timestamp of the last
* buffer to output inside the segment (first one during
* reverse playback). For example decoders will
* [clip](gst_segment_clip) out buffers after the stop time.
* @time: the stream time of the segment [start](GstSegment.start)
* ([stop](GstSegment.stop) if rate < 0.0).
* @position: the buffer timestamp position in the segment is supposed to be
* updated by elements such as sources, demuxers or parsers to
* track progress by setting it to the last pushed buffer' end time
* ([timestamp](GstBuffer.pts) + #GstBuffer.duration) for that
* specific segment. The position is used when reconfiguring the
* segment with #gst_segment_do_seek when the seek is only
* updating the segment (see [offset](GstSegment.offset)).
* @duration: the duration of the segment is the maximum absolute difference
* between #GstSegment.start and #GstSegment.stop if stop is not
* set, otherwise it should be the difference between those
* two values. This should be set by elements that know the
* overall stream duration (like demuxers) and will be used when
* seeking with #GST_SEEK_TYPE_END.
*
* The structure that holds the configured region of interest in a media file.
*/
struct _GstSegment {
/*< public >*/
GstSegmentFlags flags;
gdouble rate;
gdouble applied_rate;
GstFormat format;
guint64 base;
guint64 offset;
guint64 start;
guint64 stop;
guint64 time;
guint64 position;
guint64 duration;
/* < private > */
gpointer _gst_reserved[GST_PADDING];
};
GST_API
GType gst_segment_get_type (void);
GST_API
GstSegment * gst_segment_new (void) G_GNUC_MALLOC;
GST_API
GstSegment * gst_segment_copy (const GstSegment *segment) G_GNUC_MALLOC;
GST_API
void gst_segment_copy_into (const GstSegment *src, GstSegment *dest);
GST_API
void gst_segment_free (GstSegment *segment);
GST_API
void gst_segment_init (GstSegment *segment, GstFormat format);
GST_API
gint gst_segment_to_stream_time_full (const GstSegment *segment, GstFormat format, guint64 position, guint64 * stream_time);
GST_API
guint64 gst_segment_to_stream_time (const GstSegment *segment, GstFormat format, guint64 position);
GST_API
gint gst_segment_position_from_stream_time_full (const GstSegment * segment, GstFormat format, guint64 stream_time, guint64 * position);
GST_API
guint64 gst_segment_position_from_stream_time (const GstSegment * segment, GstFormat format, guint64 stream_time);
GST_API
guint64 gst_segment_to_running_time (const GstSegment *segment, GstFormat format, guint64 position);
GST_API
gint gst_segment_to_running_time_full (const GstSegment *segment, GstFormat format, guint64 position,
guint64 * running_time);
GST_DEPRECATED_FOR(gst_segment_position_from_running_time)
guint64 gst_segment_to_position (const GstSegment *segment, GstFormat format, guint64 running_time);
GST_API
gint gst_segment_position_from_running_time_full (const GstSegment *segment, GstFormat format, guint64 running_time, guint64 * position);
GST_API
guint64 gst_segment_position_from_running_time (const GstSegment *segment, GstFormat format, guint64 running_time);
GST_API
gboolean gst_segment_set_running_time (GstSegment *segment, GstFormat format, guint64 running_time);
GST_API
gboolean gst_segment_offset_running_time (GstSegment *segment, GstFormat format, gint64 offset);
GST_API
gboolean gst_segment_clip (const GstSegment *segment, GstFormat format, guint64 start,
guint64 stop, guint64 *clip_start, guint64 *clip_stop);
GST_API
gboolean gst_segment_do_seek (GstSegment * segment, gdouble rate,
GstFormat format, GstSeekFlags flags,
GstSeekType start_type, guint64 start,
GstSeekType stop_type, guint64 stop, gboolean * update);
GST_API
gboolean gst_segment_is_equal (const GstSegment * s0, const GstSegment * s1);
G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstSegment, gst_segment_free)
G_END_DECLS
#endif /* __GST_SEGMENT_H__ */
Reference in a new issue View git blame Copy permalink