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