1/* GStreamer
2 * Copyright (C) 2005 Wim Taymans <[email protected]>
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
28G_BEGIN_DECLS
29
30#define GST_TYPE_SEGMENT (gst_segment_get_type())
31
32typedef 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 */
43typedef 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 */
124typedef 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 */
160typedef 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 */
191struct _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
212GST_API
213GType gst_segment_get_type (void);
214
215GST_API
216GstSegment * gst_segment_new (void) G_GNUC_MALLOC;
217
218GST_API
219GstSegment * gst_segment_copy (const GstSegment *segment) G_GNUC_MALLOC;
220
221GST_API
222void gst_segment_copy_into (const GstSegment *src, GstSegment *dest);
223
224GST_API
225void gst_segment_free (GstSegment *segment);
226
227GST_API
228void gst_segment_init (GstSegment *segment, GstFormat format);
229
230GST_API
231gint gst_segment_to_stream_time_full (const GstSegment *segment, GstFormat format, guint64 position, guint64 * stream_time);
232
233GST_API
234guint64 gst_segment_to_stream_time (const GstSegment *segment, GstFormat format, guint64 position);
235
236GST_API
237gint gst_segment_position_from_stream_time_full (const GstSegment * segment, GstFormat format, guint64 stream_time, guint64 * position);
238
239GST_API
240guint64 gst_segment_position_from_stream_time (const GstSegment * segment, GstFormat format, guint64 stream_time);
241
242GST_API
243guint64 gst_segment_to_running_time (const GstSegment *segment, GstFormat format, guint64 position);
244
245GST_API
246gint gst_segment_to_running_time_full (const GstSegment *segment, GstFormat format, guint64 position,
247 guint64 * running_time);
248
249GST_DEPRECATED_FOR(gst_segment_position_from_running_time)
250guint64 gst_segment_to_position (const GstSegment *segment, GstFormat format, guint64 running_time);
251
252GST_API
253gint gst_segment_position_from_running_time_full (const GstSegment *segment, GstFormat format, guint64 running_time, guint64 * position);
254
255GST_API
256guint64 gst_segment_position_from_running_time (const GstSegment *segment, GstFormat format, guint64 running_time);
257
258GST_API
259gboolean gst_segment_set_running_time (GstSegment *segment, GstFormat format, guint64 running_time);
260
261GST_API
262gboolean gst_segment_offset_running_time (GstSegment *segment, GstFormat format, gint64 offset);
263
264GST_API
265gboolean gst_segment_clip (const GstSegment *segment, GstFormat format, guint64 start,
266 guint64 stop, guint64 *clip_start, guint64 *clip_stop);
267GST_API
268gboolean 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);
272GST_API
273gboolean gst_segment_is_equal (const GstSegment * s0, const GstSegment * s1);
274
275#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
276G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstSegment, gst_segment_free)
277#endif
278
279G_END_DECLS
280
281#endif /* __GST_SEGMENT_H__ */
282