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__ */ 282