2 * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
4 * gstsegment.h: Header for GstSegment subsystem
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.
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.
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.
23 #ifndef __GST_SEGMENT_H__
24 #define __GST_SEGMENT_H__
26 #include <gst/gstformat.h>
30 #define GST_TYPE_SEGMENT (gst_segment_get_type())
32 typedef struct _GstSegment GstSegment;
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
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 ().
45 GST_SEEK_TYPE_NONE = 0,
46 GST_SEEK_TYPE_SET = 1,
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
62 * @GST_SEEK_FLAG_SNAP_BEFORE: go to a location before the requested position,
63 * if KEY_UNIT this means the keyframe at or before the
64 * 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 KEY_UNIT this means the keyframe at of after the
68 * @GST_SEEK_FLAG_SNAP_NEAREST: go to a position near the requested position,
69 * if KEY_UNIT this means the keyframe closest to the
70 * requested position, if both keyframes are at an equal
71 * distance, behaves like SNAP_BEFORE.
73 * Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags
74 * can be used together.
76 * A non flushing seek might take some time to perform as the currently
77 * playing data in the pipeline will not be cleared.
79 * An accurate seek might be slower for formats that don't have any indexes
80 * or timestamp markers in the stream. Specifying this flag might require a
81 * complete scan of the file in those cases.
83 * When performing a segment seek: after the playback of the segment completes,
84 * no EOS will be emmited by the element that performed the seek, but a
85 * #GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element.
86 * When this message is posted, it is possible to send a new seek event to
87 * continue playback. With this seek method it is possible to perform seamless
88 * looping or simple linear editing.
90 * When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode
91 * playback, the @GST_SEEK_FLAG_SKIP flag can be used to instruct decoders
92 * and demuxers to adjust the playback rate by skipping frames. This can improve
93 * performance and decrease CPU usage because not all frames need to be decoded.
95 * The @GST_SEEK_FLAG_SNAP_BEFORE flag can be used to snap to the previous
96 * relevant location, and the @GST_SEEK_FLAG_SNAP_AFTER flag can be used to
97 * select the next relevant location. If KEY_UNIT is specified, the relevant
98 * location is a keyframe. If both flags are specified, the nearest of these
99 * locations will be selected. If none are specified, the implementation is
100 * free to select whichever it wants.
101 * The before and after here are in running time, so when playing backwards,
102 * the next location refers to the one that will played in next, and not the
103 * one that is located after in the actual source stream.
105 * Also see part-seeking.txt in the GStreamer design documentation for more
106 * details on the meaning of these flags and the behaviour expected of
107 * elements that handle them.
110 GST_SEEK_FLAG_NONE = 0,
111 GST_SEEK_FLAG_FLUSH = (1 << 0),
112 GST_SEEK_FLAG_ACCURATE = (1 << 1),
113 GST_SEEK_FLAG_KEY_UNIT = (1 << 2),
114 GST_SEEK_FLAG_SEGMENT = (1 << 3),
115 GST_SEEK_FLAG_SKIP = (1 << 4),
116 GST_SEEK_FLAG_SNAP_BEFORE = (1 << 5),
117 GST_SEEK_FLAG_SNAP_AFTER = (1 << 6),
118 GST_SEEK_FLAG_SNAP_NEAREST = GST_SEEK_FLAG_SNAP_BEFORE | GST_SEEK_FLAG_SNAP_AFTER,
119 /* Careful to restart next flag with 1<<7 here */
124 * @GST_SEGMENT_FLAG_NONE: no flags
125 * @GST_SEGMENT_FLAG_RESET: reset the pipeline running_time to the segment
127 * @GST_SEGMENT_FLAG_SKIP: perform skip playback
128 * @GST_SEGMENT_FLAG_SEGMENT: send SEGMENT_DONE instead of EOS
130 * Flags for the GstSegment structure. Currently mapped to the corresponding
131 * values of the seek flags.
133 /* Note: update gst_segment_do_seek() when adding new flags here */
134 typedef enum { /*< flags >*/
135 GST_SEGMENT_FLAG_NONE = GST_SEEK_FLAG_NONE,
136 GST_SEGMENT_FLAG_RESET = GST_SEEK_FLAG_FLUSH,
137 GST_SEGMENT_FLAG_SKIP = GST_SEEK_FLAG_SKIP,
138 GST_SEGMENT_FLAG_SEGMENT = GST_SEEK_FLAG_SEGMENT
143 * @flags: flags for this segment
144 * @rate: the rate of the segment
145 * @applied_rate: the already applied rate to the segment
146 * @format: the format of the segment values
147 * @base: the base of the segment
148 * @offset: the offset to apply to @start or @stop
149 * @start: the start of the segment
150 * @stop: the stop of the segment
151 * @time: the stream time of the segment
152 * @position: the position in the segment
153 * @duration: the duration of the segment
155 * A helper structure that holds the configured region of
156 * interest in a media file.
160 GstSegmentFlags flags;
163 gdouble applied_rate;
176 gpointer _gst_reserved[GST_PADDING];
179 GType gst_segment_get_type (void);
181 GstSegment * gst_segment_new (void) G_GNUC_MALLOC;
182 GstSegment * gst_segment_copy (const GstSegment *segment) G_GNUC_MALLOC;
183 void gst_segment_copy_into (const GstSegment *src, GstSegment *dest);
184 void gst_segment_free (GstSegment *segment);
186 void gst_segment_init (GstSegment *segment, GstFormat format);
188 guint64 gst_segment_to_stream_time (const GstSegment *segment, GstFormat format, guint64 position);
189 guint64 gst_segment_to_running_time (const GstSegment *segment, GstFormat format, guint64 position);
190 guint64 gst_segment_to_position (const GstSegment *segment, GstFormat format, guint64 running_time);
192 gboolean gst_segment_set_running_time (GstSegment *segment, GstFormat format, guint64 running_time);
194 gboolean gst_segment_clip (const GstSegment *segment, GstFormat format, guint64 start,
195 guint64 stop, guint64 *clip_start, guint64 *clip_stop);
198 gboolean gst_segment_do_seek (GstSegment * segment, gdouble rate,
199 GstFormat format, GstSeekFlags flags,
200 GstSeekType start_type, guint64 start,
201 GstSeekType stop_type, guint64 stop, gboolean * update);
205 #endif /* __GST_SEGMENT_H__ */