1/* gstreamermm - a C++ wrapper for gstreamer
2 *
3 * Copyright 2008-2016 The gstreamermm Development Team
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free
17 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 */
19
20#include <gstreamermm/clock.h>
21#include <gstreamermm/format.h>
22
23_DEFS(gstreamermm,gst)
24
25namespace Gst
26{
27
28_WRAP_ENUM(SeekFlags, GstSeekFlags)
29_WRAP_ENUM(SeekType, GstSeekType)
30
31/** A class that describes the configured region of interest in a media file.
32 * This helper structure holds the relevant values for tracking the region of
33 * interest in a media file, called a segment.
34 *
35 * The structure can be used for two purposes:
36 *
37 *  - performing seeks (handling seek events)
38 *  - tracking playback regions (handling newsegment events)
39 *
40 * The segment is usually configured by the application with a seek event which
41 * is propagated upstream and eventually handled by an element that performs
42 * the seek.
43 *
44 * The configured segment is then propagated back downstream with a newsegment
45 * event. This information is then used to clip media to the segment
46 * boundaries.
47 *
48 * A segment structure is initialized with init(), which takes a Format that
49 * will be used as the format of the segment values. The segment will be
50 * configured with a start value of 0 and a stop/duration of -1, which is
51 * undefined. The default rate and applied_rate is 1.0.
52 *
53 * The current position in the segment should be set with the set_last_stop().
54 * The public last_stop field contains the last set stop position in the
55 * segment.
56 *
57 * For elements that perform seeks, the current segment should be updated with
58 * the set_seek() and the values from the seek event. This method will update
59 * all the segment fields. The last_stop field will contain the new playback
60 * position. If the cur_type was different from Gst::SEEK_TYPE_NONE, playback
61 * continues from the last_stop position, possibly with updated flags or rate.
62 *
63 * For elements that want to synchronize to the pipeline clock,
64 * to_running_time() can be used to convert a timestamp to a value that can be
65 * used to synchronize to the clock. This function takes into account all
66 * accumulated segments as well as any rate or applied_rate conversions.
67 *
68 * For elements that need to perform operations on media data in stream_time,
69 * to_stream_time() can be used to convert a timestamp and the segment info to
70 * stream time (which is always between 0 and the duration of the stream).
71 *
72 * Last reviewed on 2016-07-12 (1.8.0)
73 */
74class Segment
75{
76  _CLASS_BOXEDTYPE(Segment, GstSegment, gst_segment_new, gst_segment_copy, gst_segment_free)
77  _IGNORE(gst_segment_free, gst_segment_copy)
78  _IGNORE(gst_segment_copy_into)
79
80public:
81  _WRAP_METHOD(bool clip(Format format, guint64 start, guint64 stop, guint64& clip_start, guint64& clip_stop) const, gst_segment_clip)
82  _WRAP_METHOD(void init(Format format), gst_segment_init)
83  _WRAP_METHOD_DOCS_ONLY(gst_segment_do_seek)
84  void set_seek(double rate, Format format, SeekFlags flags, SeekType start_type, gint64 start, SeekType stop_type, gint64 stop, bool& update);
85  _WRAP_METHOD(guint64 to_running_time(Format format, guint64 position) const, gst_segment_to_running_time)
86  _WRAP_METHOD(int to_running_time(Format format, guint64 position, guint64& running_time) const, gst_segment_to_running_time_full)
87  _WRAP_METHOD(guint64 to_stream_time(Format format, guint64 position) const, gst_segment_to_stream_time)
88  _WRAP_METHOD(int to_stream_time(Format format, guint64 position, guint64& stream_time) const, gst_segment_to_stream_time_full)
89  _WRAP_METHOD(guint64 to_position(Format format, guint64 running_time) const, gst_segment_to_position)
90  _WRAP_METHOD(bool set_running_time(Format format, guint64 running_time), gst_segment_set_running_time)
91  _WRAP_METHOD(guint64 position_from_running_time(Gst::Format format, guint64 running_time) const, gst_segment_position_from_running_time)
92  _WRAP_METHOD(int position_from_running_time(Gst::Format format, guint64 running_time, guint64& position) const, gst_segment_position_from_running_time_full)
93  _WRAP_METHOD(guint64 position_from_stream_time(Gst::Format format, guint64 stream_time) const, gst_segment_position_from_stream_time)
94  _WRAP_METHOD(int position_from_stream_time(Gst::Format format, guint64 stream_time, guint64& position) const, gst_segment_position_from_stream_time_full)
95  _WRAP_METHOD(bool offset_running_time(Gst::Format format, gint64 offset), gst_segment_offset_running_time)
96  _WRAP_METHOD(bool is_equal(const Gst::Segment& s2) const, gst_segment_is_equal)
97
98};
99
100} //namespace Gst
101