gstreamer/gst/gstsegment.h
Niels De Graef 09141c6e1f Use G_DEFINE_AUTOPTR_CLEANUP_FUNC unconditionally
Since we started depending on GLib 2.44, we can be sure this macro is
defined (it will be a no-op on compilers that don't support it). For
plugins we should just start using `G_DECLARE_FINAL_TYPE` which means
we no longer need the macro there, but for most types in core we don't
want to break ABI, which means it's better to just keep it like it is
(and use the `#ifdef` instead).
2019-06-04 08:50:59 +02:00

288 lines
13 KiB
C

/* 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_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 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),
} 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;
/**
* GstSegment:
* @flags: flags for this segment
* @rate: the playback rate of the segment
* @applied_rate: the already applied rate to the segment
* @format: the format of the segment values
* @base: the running time (plus elapsed time, see offset) of the segment start
* @offset: the amount (in buffer timestamps) that has already been elapsed in
* the segment
* @start: the start of the segment in buffer timestamp time (PTS)
* @stop: the stop of the segment in buffer timestamp time (PTS)
* @time: the stream time of the segment start
* @position: the buffer timestamp position in the segment (used internally by
* elements such as sources, demuxers or parsers to track progress)
* @duration: the duration of the stream
*
* A helper 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__ */