gst/gstsegment.c

   1 /* GStreamer
   2  * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
   3  *
   4  * gstsegment.c: 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 #include "gst_private.h"
  24
  25 #include "gstutils.h"
  26 #include "gstsegment.h"
  27
  28 /**
  29  * SECTION:gstsegment
  30  * @short_description: Structure describing the configured region of interest
  31  *                     in a media file.
  32  * @see_also: #GstEvent
  33  *
  34  * This helper structure holds the relevant values for tracking the region of
  35  * interest in a media file, called a segment.
  36  *
  37  * Last reviewed on 2005-20-09 (0.9.5)
  38  */
  39
  40 /**
  41  * gst_segment_init:
  42  * @segment: a #GstSegment structure.
  43  * @format: the format of the segment.
  44  *
  45  * Initialize @segment to its default values, which is a rate of 1.0, a
  46  * start time of 0.
  47  */
  48 void
  49 gst_segment_init (GstSegment * segment, GstFormat format)
  50 {
  51   g_return_if_fail (segment != NULL);
  52
  53   segment->rate = 1.0;
  54   segment->format = format;
  55   segment->flags = 0;
  56   segment->start = 0;
  57   segment->stop = -1;
  58   segment->time = 0;
  59   segment->accum = 0;
  60   segment->last_stop = 0;
  61   segment->duration = -1;
  62 }
  63
  64 /**
  65  * gst_segment_set_duration:
  66  * @segment: a #GstSegment structure.
  67  * @format: the format of the segment.
  68  * @duration: the duration of the segment info.
  69  *
  70  * Set the duration of the segment to @duration. This function is mainly
  71  * used by elements that perform seeking and know the total duration of the
  72  * segment.
  73  */
  74 void
  75 gst_segment_set_duration (GstSegment * segment, GstFormat format,
  76     gint64 duration)
  77 {
  78   g_return_if_fail (segment != NULL);
  79   g_return_if_fail (segment->format == format);
  80
  81   segment->duration = duration;
  82 }
  83
  84 /**
  85  * gst_segment_set_seek:
  86  * @segment: a #GstSegment structure.
  87  * @rate: the rate of the segment.
  88  * @format: the format of the segment.
  89  * @flags: the seek flags for the segment
  90  * @cur_type: the seek method
  91  * @cur: the seek start value
  92  * @stop_type: the seek method
  93  * @stop: the seek stop value
  94  *
  95  * Update the segment structure with the field values of a seek event.
  96  */
  97 void
  98 gst_segment_set_seek (GstSegment * segment, gdouble rate,
  99     GstFormat format, GstSeekFlags flags,
 100     GstSeekType cur_type, gint64 cur, GstSeekType stop_type, gint64 stop)
 101 {
 102   gboolean update_stop, update_start;
 103
 104   g_return_if_fail (rate != 0.0);
 105   g_return_if_fail (segment != NULL);
 106   g_return_if_fail (segment->format == format);
 107
 108   update_stop = update_start = TRUE;
 109
 110   /* start is never invalid */
 111   switch (cur_type) {
 112     case GST_SEEK_TYPE_NONE:
 113       /* no update to segment */
 114       cur = segment->start;
 115       update_start = FALSE;
 116       break;
 117     case GST_SEEK_TYPE_SET:
 118       /* cur holds desired position */
 119       break;
 120     case GST_SEEK_TYPE_CUR:
 121       /* add cur to currently configure segment */
 122       cur = segment->start + cur;
 123       break;
 124     case GST_SEEK_TYPE_END:
 125       if (segment->duration != -1) {
 126         /* add cur to total length */
 127         cur = segment->duration + cur;
 128       } else {
 129         /* no update if duration unknown */
 130         cur = segment->start;
 131         update_start = FALSE;
 132       }
 133       break;
 134   }
 135   /* bring in sane range */
 136   if (segment->duration != -1)
 137     cur = CLAMP (cur, 0, segment->duration);
 138   else
 139     cur = MAX (cur, 0);
 140
 141   /* stop can be -1 if we have not configured a stop. */
 142   switch (stop_type) {
 143     case GST_SEEK_TYPE_NONE:
 144       stop = segment->stop;
 145       update_stop = FALSE;
 146       break;
 147     case GST_SEEK_TYPE_SET:
 148       /* stop folds required value */
 149       break;
 150     case GST_SEEK_TYPE_CUR:
 151       if (segment->stop != -1)
 152         stop = segment->stop + stop;
 153       else
 154         stop = -1;
 155       break;
 156     case GST_SEEK_TYPE_END:
 157       if (segment->duration != -1)
 158         stop = segment->duration + stop;
 159       else {
 160         stop = segment->stop;
 161         update_stop = FALSE;
 162       }
 163       break;
 164   }
 165
 166   /* if we have a valid stop time, make sure it is clipped */
 167   if (stop != -1) {
 168     if (segment->duration != -1)
 169       stop = CLAMP (stop, 0, segment->duration);
 170     else
 171       stop = MAX (stop, 0);
 172   }
 173
 174   /* we can't have stop before start */
 175   if (stop != -1)
 176     g_return_if_fail (cur <= stop);
 177
 178   segment->rate = rate;
 179   segment->abs_rate = ABS (rate);
 180   segment->flags = flags;
 181   segment->start = cur;
 182   segment->stop = stop;
 183 }
 184
 185 /**
 186  * gst_segment_set_newsegment:
 187  * @segment: a #GstSegment structure.
 188  * @update: flag indicating a new segment is started or updated
 189  * @rate: the rate of the segment.
 190  * @format: the format of the segment.
 191  * @start: the new start value
 192  * @stop: the new stop value
 193  * @time: the new stream time
 194  *
 195  * Update the segment structure with the field values of a new segment event.
 196  */
 197 void
 198 gst_segment_set_newsegment (GstSegment * segment, gboolean update, gdouble rate,
 199     GstFormat format, gint64 start, gint64 stop, gint64 time)
 200 {
 201   gint64 duration;
 202
 203   g_return_if_fail (rate != 0.0);
 204   g_return_if_fail (segment != NULL);
 205   g_return_if_fail (segment->format == format);
 206
 207   if (update) {
 208     /* an update to the current segment is done, elapsed time is
 209      * difference between the old start and new start. */
 210     duration = start - segment->start;
 211   } else {
 212     /* the new segment has to be aligned with the old segment.
 213      * We first update the accumulated time of the previous
 214      * segment. the accumulated time is used when syncing to the
 215      * clock. A flush event sets the accumulated time back to 0
 216      */
 217     if (GST_CLOCK_TIME_IS_VALID (segment->stop)) {
 218       duration = segment->stop - segment->start;
 219     } else if (GST_CLOCK_TIME_IS_VALID (segment->duration)) {
 220       /* else use last seen timestamp as segment stop */
 221       duration = segment->duration - segment->start;
 222     } else {
 223       /* else we don't know */
 224       duration = 0;
 225     }
 226   }
 227   /* use previous rate to calculate duration */
 228   segment->accum += gst_gdouble_to_guint64 (
 229       (gst_guint64_to_gdouble (duration) / segment->abs_rate));
 230   /* then update the current segment */
 231   segment->rate = rate;
 232   segment->abs_rate = ABS (rate);
 233   segment->start = start;
 234   segment->stop = stop;
 235   segment->time = time;
 236
 237   GST_DEBUG ("received NEWSEGMENT %" GST_TIME_FORMAT " -- %"
 238       GST_TIME_FORMAT ", time %" GST_TIME_FORMAT ", accum %"
 239       GST_TIME_FORMAT,
 240       GST_TIME_ARGS (segment->start),
 241       GST_TIME_ARGS (segment->stop),
 242       GST_TIME_ARGS (segment->time), GST_TIME_ARGS (segment->accum));
 243 }
 244
 245 /**
 246  * gst_segment_to_stream_time:
 247  * @segment: a #GstSegment structure.
 248  * @format: the format of the segment.
 249  * @position: the position in the segment
 250  *
 251  * Translate @position to stream time using the currently configured
 252  * segment.
 253  *
 254  * This function is typically used by elements that need to operate on
 255  * the stream time of the buffers it receives, such as effect plugins.
 256  *
 257  * Returns: the position in stream_time.
 258  */
 259 gint64
 260 gst_segment_to_stream_time (GstSegment * segment, GstFormat format,
 261     gint64 position)
 262 {
 263   gint64 result;
 264
 265   g_return_val_if_fail (segment != NULL, FALSE);
 266   g_return_val_if_fail (segment->format == format, FALSE);
 267
 268   result = ((position - segment->start) / segment->abs_rate) + segment->time;
 269
 270   return result;
 271 }
 272
 273 /**
 274  * gst_segment_to_running_time:
 275  * @segment: a #GstSegment structure.
 276  * @format: the format of the segment.
 277  * @position: the position in the segment
 278  *
 279  * Translate @position to the total running time using the currently configured
 280  * segment.
 281  *
 282  * This function is typically used by elements that need to synchronize to the
 283  * global clock in a pipeline.
 284  *
 285  * Returns: the position as the total running time.
 286  */
 287 gint64
 288 gst_segment_to_running_time (GstSegment * segment, GstFormat format,
 289     gint64 position)
 290 {
 291   gint64 result;
 292
 293   g_return_val_if_fail (segment != NULL, FALSE);
 294   g_return_val_if_fail (segment->format == format, FALSE);
 295
 296   result = ((position - segment->start) / segment->abs_rate) + segment->accum;
 297
 298   return result;
 299 }
 300
 301 /**
 302  * gst_segment_clip:
 303  * @segment: a #GstSegment structure.
 304  * @format: the format of the segment.
 305  * @start: the start position in the segment
 306  * @stop: the stop position in the segment
 307  * @clip_start: the clipped start position in the segment
 308  * @clip_stop: the clipped stop position in the segment
 309  *
 310  * Clip the given @start and @stop values to the segment boundaries given
 311  * in @segment.
 312  *
 313  * Returns: TRUE if the given @start and @stop times fall partially in
 314  *     @segment, FALSE if the values are completely outside of the segment.
 315  */
 316 gboolean
 317 gst_segment_clip (GstSegment * segment, GstFormat format, gint64 start,
 318     gint64 stop, gint64 * clip_start, gint64 * clip_stop)
 319 {
 320   g_return_val_if_fail (segment != NULL, FALSE);
 321   g_return_val_if_fail (segment->format == format, FALSE);
 322
 323   /* we need a valid start position */
 324   if (start == -1)
 325     return FALSE;
 326
 327   /* if we have a stop position and start is bigger, we're
 328    * outside of the segment */
 329   if (segment->stop != -1 && start >= segment->stop)
 330     return FALSE;
 331
 332   /* if a stop position is given and is before the segment start,
 333    * we're outside of the segment */
 334   if (stop != -1 && stop <= segment->start)
 335     return FALSE;
 336
 337   if (clip_start)
 338     *clip_start = MAX (start, segment->start);
 339
 340   if (clip_stop) {
 341     if (stop == -1)
 342       *clip_stop = segment->stop;
 343     else if (segment->stop == -1)
 344       *clip_stop = MAX (-1, stop);
 345     else
 346       *clip_stop = MIN (stop, segment->stop);
 347
 348     if (segment->duration != -1)
 349       *clip_stop = MIN (*clip_stop, segment->duration);
 350   }
 351
 352   return TRUE;
 353 }