gst/gstsegment.h

   1 /* GStreamer
   2  * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
   3  *
   4  * gstsegment.h: Header for GstSegment subsystem
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22
  23 #ifndef __GST_SEGMENT_H__
  24 #define __GST_SEGMENT_H__
  25
  26 #include <gst/gstformat.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define GST_TYPE_SEGMENT             (gst_segment_get_type())
  31
  32 typedef struct _GstSegment GstSegment;
  33
  34 /**
  35  * GstSeekType:
  36  * @GST_SEEK_TYPE_NONE: no change in position is required
  37  * @GST_SEEK_TYPE_SET: absolute position is requested
  38  * @GST_SEEK_TYPE_END: relative position to duration is requested
  39  *
  40  * The different types of seek events. When constructing a seek event with
  41  * gst_event_new_seek() or when doing gst_segment_do_seek ().
  42  */
  43 typedef enum {
  44   /* one of these */
  45   GST_SEEK_TYPE_NONE            = 0,
  46   GST_SEEK_TYPE_SET             = 1,
  47   GST_SEEK_TYPE_END             = 2
  48 } GstSeekType;
  49
  50 /**
  51  * GstSeekFlags:
  52  * @GST_SEEK_FLAG_NONE: no flag
  53  * @GST_SEEK_FLAG_FLUSH: flush pipeline
  54  * @GST_SEEK_FLAG_ACCURATE: accurate position is requested, this might
  55  *                     be considerably slower for some formats.
  56  * @GST_SEEK_FLAG_KEY_UNIT: seek to the nearest keyframe. This might be
  57  *                     faster but less accurate.
  58  * @GST_SEEK_FLAG_SEGMENT: perform a segment seek.
  59  * @GST_SEEK_FLAG_TRICKMODE: when doing fast forward or fast reverse playback, allow
  60  *                     elements to skip frames instead of generating all
  61  *                     frames. (Since: 1.6)
  62  * @GST_SEEK_FLAG_SNAP_BEFORE: go to a location before the requested position,
  63  *                     if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at or before
  64  *                     the requested position the one at or before the seek target.
  65  * @GST_SEEK_FLAG_SNAP_AFTER: go to a location after the requested position,
  66  *                     if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at of after the
  67  *                     requested position.
  68  * @GST_SEEK_FLAG_SNAP_NEAREST: go to a position near the requested position,
  69  *                     if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe closest
  70  *                     to the requested position, if both keyframes are at an equal
  71  *                     distance, behaves like %GST_SEEK_FLAG_SNAP_BEFORE.
  72  * @GST_SEEK_FLAG_TRICKMODE_KEY_UNITS: when doing fast forward or fast reverse
  73  *                     playback, request that elements only decode keyframes
  74  *                     and skip all other content, for formats that have
  75  *                     keyframes. (Since: 1.6)
  76  * @GST_SEEK_FLAG_TRICKMODE_NO_AUDIO: when doing fast forward or fast reverse
  77  *                     playback, request that audio decoder elements skip
  78  *                     decoding and output only gap events or silence. (Since: 1.6)
  79  * @GST_SEEK_FLAG_SKIP: Deprecated backward compatibility flag, replaced
  80  *                     by %GST_SEEK_FLAG_TRICKMODE
  81  *
  82  * Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags
  83  * can be used together.
  84  *
  85  * A non flushing seek might take some time to perform as the currently
  86  * playing data in the pipeline will not be cleared.
  87  *
  88  * An accurate seek might be slower for formats that don't have any indexes
  89  * or timestamp markers in the stream. Specifying this flag might require a
  90  * complete scan of the file in those cases.
  91  *
  92  * When performing a segment seek: after the playback of the segment completes,
  93  * no EOS will be emitted by the element that performed the seek, but a
  94  * %GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element.
  95  * When this message is posted, it is possible to send a new seek event to
  96  * continue playback. With this seek method it is possible to perform seamless
  97  * looping or simple linear editing.
  98  *
  99  * When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode
 100  * playback, the %GST_SEEK_FLAG_TRICKMODE flag can be used to instruct decoders
 101  * and demuxers to adjust the playback rate by skipping frames. This can improve
 102  * performance and decrease CPU usage because not all frames need to be decoded.
 103  *
 104  * Beyond that, the %GST_SEEK_FLAG_TRICKMODE_KEY_UNITS flag can be used to
 105  * request that decoders skip all frames except key units, and
 106  * %GST_SEEK_FLAG_TRICKMODE_NO_AUDIO flags can be used to request that audio
 107  * decoders do no decoding at all, and simple output silence.
 108  *
 109  * The %GST_SEEK_FLAG_SNAP_BEFORE flag can be used to snap to the previous
 110  * relevant location, and the %GST_SEEK_FLAG_SNAP_AFTER flag can be used to
 111  * select the next relevant location. If %GST_SEEK_FLAG_KEY_UNIT is specified,
 112  * the relevant location is a keyframe. If both flags are specified, the nearest
 113  * of these locations will be selected. If none are specified, the implementation is
 114  * free to select whichever it wants.
 115  *
 116  * The before and after here are in running time, so when playing backwards,
 117  * the next location refers to the one that will played in next, and not the
 118  * one that is located after in the actual source stream.
 119  *
 120  * Also see part-seeking.txt in the GStreamer design documentation for more
 121  * details on the meaning of these flags and the behaviour expected of
 122  * elements that handle them.
 123  */
 124 typedef enum {
 125   GST_SEEK_FLAG_NONE            = 0,
 126   GST_SEEK_FLAG_FLUSH           = (1 << 0),
 127   GST_SEEK_FLAG_ACCURATE        = (1 << 1),
 128   GST_SEEK_FLAG_KEY_UNIT        = (1 << 2),
 129   GST_SEEK_FLAG_SEGMENT         = (1 << 3),
 130   GST_SEEK_FLAG_TRICKMODE       = (1 << 4),
 131   /* FIXME 2.0: Remove _SKIP flag,
 132    * which was kept for backward compat when _TRICKMODE was added */
 133   GST_SEEK_FLAG_SKIP            = (1 << 4),
 134   GST_SEEK_FLAG_SNAP_BEFORE     = (1 << 5),
 135   GST_SEEK_FLAG_SNAP_AFTER      = (1 << 6),
 136   GST_SEEK_FLAG_SNAP_NEAREST    = GST_SEEK_FLAG_SNAP_BEFORE | GST_SEEK_FLAG_SNAP_AFTER,
 137   /* Careful to restart next flag with 1<<7 here */
 138   GST_SEEK_FLAG_TRICKMODE_KEY_UNITS = (1 << 7),
 139   GST_SEEK_FLAG_TRICKMODE_NO_AUDIO  = (1 << 8),
 140 } GstSeekFlags;
 141
 142 /**
 143  * GstSegmentFlags:
 144  * @GST_SEGMENT_FLAG_NONE: no flags
 145  * @GST_SEGMENT_FLAG_RESET: reset the pipeline running_time to the segment
 146  *                          running_time
 147  * @GST_SEGMENT_FLAG_TRICKMODE: perform skip playback (Since: 1.6)
 148  * @GST_SEGMENT_FLAG_SEGMENT: send SEGMENT_DONE instead of EOS
 149  * @GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS: Decode only keyframes, where
 150  *                                        possible (Since: 1.6)
 151  * @GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO: Do not decode any audio, where
 152  *                                        possible (Since: 1.6)
 153  * @GST_SEGMENT_FLAG_SKIP: Deprecated backward compatibility flag, replaced
 154  *                         by @GST_SEGMENT_FLAG_TRICKMODE
 155  *
 156  * Flags for the GstSegment structure. Currently mapped to the corresponding
 157  * values of the seek flags.
 158  */
 159 /* Note: update gst_segment_do_seek() when adding new flags here */
 160 typedef enum { /*< flags >*/
 161   GST_SEGMENT_FLAG_NONE            = GST_SEEK_FLAG_NONE,
 162   GST_SEGMENT_FLAG_RESET           = GST_SEEK_FLAG_FLUSH,
 163   GST_SEGMENT_FLAG_TRICKMODE       = GST_SEEK_FLAG_TRICKMODE,
 164   /* FIXME 2.0: Remove _SKIP flag,
 165    * which was kept for backward compat when _TRICKMODE was added */
 166   GST_SEGMENT_FLAG_SKIP            = GST_SEEK_FLAG_TRICKMODE,
 167   GST_SEGMENT_FLAG_SEGMENT         = GST_SEEK_FLAG_SEGMENT,
 168   GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS = GST_SEEK_FLAG_TRICKMODE_KEY_UNITS,
 169   GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO      = GST_SEEK_FLAG_TRICKMODE_NO_AUDIO
 170 } GstSegmentFlags;
 171
 172 /**
 173  * GstSegment:
 174  * @flags: flags for this segment
 175  * @rate: the playback rate of the segment
 176  * @applied_rate: the already applied rate to the segment
 177  * @format: the format of the segment values
 178  * @base: the running time (plus elapsed time, see offset) of the segment start
 179  * @offset: the amount (in buffer timestamps) that has already been elapsed in
 180  *     the segment
 181  * @start: the start of the segment in buffer timestamp time (PTS)
 182  * @stop: the stop of the segment in buffer timestamp time (PTS)
 183  * @time: the stream time of the segment start
 184  * @position: the buffer timestamp position in the segment (used internally by
 185  *     elements such as sources, demuxers or parsers to track progress)
 186  * @duration: the duration of the stream
 187  *
 188  * A helper structure that holds the configured region of
 189  * interest in a media file.
 190  */
 191 struct _GstSegment {
 192   /*< public >*/
 193   GstSegmentFlags flags;
 194
 195   gdouble         rate;
 196   gdouble         applied_rate;
 197
 198   GstFormat       format;
 199   guint64         base;
 200   guint64         offset;
 201   guint64         start;
 202   guint64         stop;
 203   guint64         time;
 204
 205   guint64         position;
 206   guint64         duration;
 207
 208   /* < private > */
 209   gpointer        _gst_reserved[GST_PADDING];
 210 };
 211
 212 GST_API
 213 GType        gst_segment_get_type            (void);
 214
 215 GST_API
 216 GstSegment * gst_segment_new                 (void) G_GNUC_MALLOC;
 217
 218 GST_API
 219 GstSegment * gst_segment_copy                (const GstSegment *segment) G_GNUC_MALLOC;
 220
 221 GST_API
 222 void         gst_segment_copy_into           (const GstSegment *src, GstSegment *dest);
 223
 224 GST_API
 225 void         gst_segment_free                (GstSegment *segment);
 226
 227 GST_API
 228 void         gst_segment_init                (GstSegment *segment, GstFormat format);
 229
 230 GST_API
 231 gint         gst_segment_to_stream_time_full (const GstSegment *segment, GstFormat format, guint64 position, guint64 * stream_time);
 232
 233 GST_API
 234 guint64      gst_segment_to_stream_time      (const GstSegment *segment, GstFormat format, guint64 position);
 235
 236 GST_API
 237 gint         gst_segment_position_from_stream_time_full (const GstSegment * segment, GstFormat format, guint64 stream_time, guint64 * position);
 238
 239 GST_API
 240 guint64      gst_segment_position_from_stream_time (const GstSegment * segment, GstFormat format, guint64 stream_time);
 241
 242 GST_API
 243 guint64      gst_segment_to_running_time     (const GstSegment *segment, GstFormat format, guint64 position);
 244
 245 GST_API
 246 gint         gst_segment_to_running_time_full (const GstSegment *segment, GstFormat format, guint64 position,
 247                                                guint64 * running_time);
 248
 249 GST_DEPRECATED_FOR(gst_segment_position_from_running_time)
 250 guint64      gst_segment_to_position         (const GstSegment *segment, GstFormat format, guint64 running_time);
 251
 252 GST_API
 253 gint         gst_segment_position_from_running_time_full (const GstSegment *segment, GstFormat format, guint64 running_time, guint64 * position);
 254
 255 GST_API
 256 guint64      gst_segment_position_from_running_time (const GstSegment *segment, GstFormat format, guint64 running_time);
 257
 258 GST_API
 259 gboolean     gst_segment_set_running_time    (GstSegment *segment, GstFormat format, guint64 running_time);
 260
 261 GST_API
 262 gboolean     gst_segment_offset_running_time (GstSegment *segment, GstFormat format, gint64 offset);
 263
 264 GST_API
 265 gboolean     gst_segment_clip                (const GstSegment *segment, GstFormat format, guint64 start,
 266                                               guint64 stop, guint64 *clip_start, guint64 *clip_stop);
 267 GST_API
 268 gboolean     gst_segment_do_seek             (GstSegment * segment, gdouble rate,
 269                                               GstFormat format, GstSeekFlags flags,
 270                                               GstSeekType start_type, guint64 start,
 271                                               GstSeekType stop_type, guint64 stop, gboolean * update);
 272 GST_API
 273 gboolean     gst_segment_is_equal            (const GstSegment * s0, const GstSegment * s1);
 274
 275 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 276 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstSegment, gst_segment_free)
 277 #endif
 278
 279 G_END_DECLS
 280
 281 #endif /* __GST_SEGMENT_H__ */