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., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, 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_SKIP: when doing fast foward or fast reverse playback, allow
  60  *                     elements to skip frames instead of generating all
  61  *                     frames. Since 0.10.22.
  62  *
  63  * Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags
  64  * can be used together.
  65  *
  66  * A non flushing seek might take some time to perform as the currently
  67  * playing data in the pipeline will not be cleared.
  68  *
  69  * An accurate seek might be slower for formats that don't have any indexes
  70  * or timestamp markers in the stream. Specifying this flag might require a
  71  * complete scan of the file in those cases.
  72  *
  73  * When performing a segment seek: after the playback of the segment completes,
  74  * no EOS will be emmited by the element that performed the seek, but a
  75  * #GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element.
  76  * When this message is posted, it is possible to send a new seek event to
  77  * continue playback. With this seek method it is possible to perform seamless
  78  * looping or simple linear editing.
  79  *
  80  * When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode
  81  * playback, the @GST_SEEK_FLAG_SKIP flag can be used to instruct decoders
  82  * and demuxers to adjust the playback rate by skipping frames. This can improve
  83  * performance and decrease CPU usage because not all frames need to be decoded.
  84  *
  85  * Also see part-seeking.txt in the GStreamer design documentation for more
  86  * details on the meaning of these flags and the behaviour expected of
  87  * elements that handle them.
  88  */
  89 typedef enum {
  90   GST_SEEK_FLAG_NONE            = 0,
  91   GST_SEEK_FLAG_FLUSH           = (1 << 0),
  92   GST_SEEK_FLAG_ACCURATE        = (1 << 1),
  93   GST_SEEK_FLAG_KEY_UNIT        = (1 << 2),
  94   GST_SEEK_FLAG_SEGMENT         = (1 << 3),
  95   GST_SEEK_FLAG_SKIP            = (1 << 4)
  96 } GstSeekFlags;
  97
  98 /**
  99  * GstSegmentFlags:
 100  * @GST_SEGMENT_FLAG_NONE: no flags
 101  * @GST_SEGMENT_FLAG_RESET: reset the pipeline running_time to the segment
 102  *                          running_time
 103  * @GST_SEGMENT_FLAG_SKIP: perform skip playback
 104  *
 105  * Flags for the GstSegment structure. Currently mapped to the corresponding
 106  * values of the seek flags.
 107  */
 108 typedef enum {
 109   GST_SEGMENT_FLAG_NONE            = GST_SEEK_FLAG_NONE,
 110   GST_SEGMENT_FLAG_RESET           = GST_SEEK_FLAG_FLUSH,
 111   GST_SEGMENT_FLAG_SKIP            = GST_SEEK_FLAG_SKIP
 112 } GstSegmentFlags;
 113
 114 /**
 115  * GstSegment:
 116  * @flags: flags for this segment
 117  * @rate: the rate of the segment
 118  * @applied_rate: the already applied rate to the segment
 119  * @format: the format of the segment values
 120  * @base: the base time of the segment
 121  * @start: the start of the segment
 122  * @stop: the stop of the segment
 123  * @time: the stream time of the segment
 124  * @position: the position in the segment
 125  * @duration: the duration of the segment
 126  *
 127  * A helper structure that holds the configured region of
 128  * interest in a media file.
 129  */
 130 struct _GstSegment {
 131   /*< public >*/
 132   GstSegmentFlags flags;
 133
 134   gdouble         rate;
 135   gdouble         applied_rate;
 136
 137   GstFormat       format;
 138   guint64         base;
 139   guint64         start;
 140   guint64         stop;
 141   guint64         time;
 142
 143   guint64         position;
 144   guint64         duration;
 145 };
 146
 147 GType        gst_segment_get_type            (void);
 148
 149 GstSegment * gst_segment_new                 (void) G_GNUC_MALLOC;
 150 GstSegment * gst_segment_copy                (const GstSegment *segment) G_GNUC_MALLOC;
 151 void         gst_segment_copy_into           (const GstSegment *src, GstSegment *dest);
 152 void         gst_segment_free                (GstSegment *segment);
 153
 154 void         gst_segment_init                (GstSegment *segment, GstFormat format);
 155
 156 guint64      gst_segment_to_stream_time      (const GstSegment *segment, GstFormat format, guint64 position);
 157 guint64      gst_segment_to_running_time     (const GstSegment *segment, GstFormat format, guint64 position);
 158 guint64      gst_segment_to_position         (const GstSegment *segment, GstFormat format, guint64 running_time);
 159
 160 gboolean     gst_segment_set_running_time    (GstSegment *segment, GstFormat format, guint64 running_time);
 161
 162 gboolean     gst_segment_clip                (const GstSegment *segment, GstFormat format, guint64 start,
 163                                               guint64 stop, guint64 *clip_start, guint64 *clip_stop);
 164
 165
 166 gboolean     gst_segment_do_seek             (GstSegment * segment, gdouble rate,
 167                                               GstFormat format, GstSeekFlags flags,
 168                                               GstSeekType start_type, guint64 start,
 169                                               GstSeekType stop_type, guint64 stop, gboolean * update);
 170
 171 G_END_DECLS
 172
 173 #endif /* __GST_SEGMENT_H__ */