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 = -1;
  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_last_stop:
  86  * @segment: a #GstSegment structure.
  87  * @format: the format of the segment.
  88  * @position: the position
  89  *
  90  * Set the last observed stop position in the segment to @position.
  91  */
  92 void
  93 gst_segment_set_last_stop (GstSegment * segment, GstFormat format,
  94     gint64 position)
  95 {
  96   g_return_if_fail (segment != NULL);
  97   g_return_if_fail (segment->format == format);
  98
  99   segment->last_stop = position;
 100 }
 101
 102 /**
 103  * gst_segment_set_seek:
 104  * @segment: a #GstSegment structure.
 105  * @rate: the rate of the segment.
 106  * @format: the format of the segment.
 107  * @flags: the seek flags for the segment
 108  * @cur_type: the seek method
 109  * @cur: the seek start value
 110  * @stop_type: the seek method
 111  * @stop: the seek stop value
 112  *
 113  * Update the segment structure with the field values of a seek event.
 114  */
 115 void
 116 gst_segment_set_seek (GstSegment * segment, gdouble rate,
 117     GstFormat format, GstSeekFlags flags,
 118     GstSeekType cur_type, gint64 cur, GstSeekType stop_type, gint64 stop)
 119 {
 120   gboolean update_stop, update_start;
 121
 122   g_return_if_fail (rate != 0.0);
 123   g_return_if_fail (segment != NULL);
 124   g_return_if_fail (segment->format == format);
 125
 126   update_stop = update_start = TRUE;
 127
 128   /* start is never invalid */
 129   switch (cur_type) {
 130     case GST_SEEK_TYPE_NONE:
 131       /* no update to segment */
 132       cur = segment->start;
 133       update_start = FALSE;
 134       break;
 135     case GST_SEEK_TYPE_SET:
 136       /* cur holds desired position */
 137       break;
 138     case GST_SEEK_TYPE_CUR:
 139       /* add cur to currently configure segment */
 140       cur = segment->start + cur;
 141       break;
 142     case GST_SEEK_TYPE_END:
 143       if (segment->duration != -1) {
 144         /* add cur to total length */
 145         cur = segment->duration + cur;
 146       } else {
 147         /* no update if duration unknown */
 148         cur = segment->start;
 149         update_start = FALSE;
 150       }
 151       break;
 152   }
 153   /* bring in sane range */
 154   if (segment->duration != -1)
 155     cur = CLAMP (cur, 0, segment->duration);
 156   else
 157     cur = MAX (cur, 0);
 158
 159   /* stop can be -1 if we have not configured a stop. */
 160   switch (stop_type) {
 161     case GST_SEEK_TYPE_NONE:
 162       stop = segment->stop;
 163       update_stop = FALSE;
 164       break;
 165     case GST_SEEK_TYPE_SET:
 166       /* stop folds required value */
 167       break;
 168     case GST_SEEK_TYPE_CUR:
 169       if (segment->stop != -1)
 170         stop = segment->stop + stop;
 171       else
 172         stop = -1;
 173       break;
 174     case GST_SEEK_TYPE_END:
 175       if (segment->duration != -1)
 176         stop = segment->duration + stop;
 177       else {
 178         stop = segment->stop;
 179         update_stop = FALSE;
 180       }
 181       break;
 182   }
 183
 184   /* if we have a valid stop time, make sure it is clipped */
 185   if (stop != -1) {
 186     if (segment->duration != -1)
 187       stop = CLAMP (stop, 0, segment->duration);
 188     else
 189       stop = MAX (stop, 0);
 190   }
 191
 192   /* we can't have stop before start */
 193   if (stop != -1)
 194     g_return_if_fail (cur <= stop);
 195
 196   segment->rate = rate;
 197   segment->abs_rate = ABS (rate);
 198   segment->flags = flags;
 199   segment->start = cur;
 200   segment->stop = stop;
 201 }
 202
 203 /**
 204  * gst_segment_set_newsegment:
 205  * @segment: a #GstSegment structure.
 206  * @update: flag indicating a new segment is started or updated
 207  * @rate: the rate of the segment.
 208  * @format: the format of the segment.
 209  * @start: the new start value
 210  * @stop: the new stop value
 211  * @time: the new stream time
 212  *
 213  * Update the segment structure with the field values of a new segment event.
 214  */
 215 void
 216 gst_segment_set_newsegment (GstSegment * segment, gboolean update, gdouble rate,
 217     GstFormat format, gint64 start, gint64 stop, gint64 time)
 218 {
 219   gint64 duration;
 220
 221   g_return_if_fail (rate != 0.0);
 222   g_return_if_fail (segment != NULL);
 223
 224   /* any other format with 0 also gives time 0, the other values are
 225    * invalid in the format though. */
 226   if (format != segment->format && start == 0) {
 227     format = segment->format;
 228     if (stop != 0)
 229       stop = -1;
 230     if (time != 0)
 231       time = -1;
 232   }
 233
 234   g_return_if_fail (segment->format == format);
 235
 236   if (update) {
 237     /* an update to the current segment is done, elapsed time is
 238      * difference between the old start and new start. */
 239     duration = start - segment->start;
 240   } else {
 241     /* the new segment has to be aligned with the old segment.
 242      * We first update the accumulated time of the previous
 243      * segment. the accumulated time is used when syncing to the
 244      * clock.
 245      */
 246     if (GST_CLOCK_TIME_IS_VALID (segment->stop)) {
 247       duration = segment->stop - segment->start;
 248     } else if (GST_CLOCK_TIME_IS_VALID (segment->last_stop)) {
 249       /* else use last seen timestamp as segment stop */
 250       duration = segment->last_stop - segment->start;
 251     } else {
 252       /* else we don't know */
 253       duration = 0;
 254     }
 255   }
 256   /* use previous rate to calculate duration */
 257   segment->accum += gst_gdouble_to_guint64 (
 258       (gst_guint64_to_gdouble (duration) / segment->abs_rate));
 259   /* then update the current segment */
 260   segment->rate = rate;
 261   segment->abs_rate = ABS (rate);
 262   segment->start = start;
 263   segment->stop = stop;
 264   segment->time = time;
 265 }
 266
 267 /**
 268  * gst_segment_to_stream_time:
 269  * @segment: a #GstSegment structure.
 270  * @format: the format of the segment.
 271  * @position: the position in the segment
 272  *
 273  * Translate @position to stream time using the currently configured
 274  * segment.
 275  *
 276  * This function is typically used by elements that need to operate on
 277  * the stream time of the buffers it receives, such as effect plugins.
 278  *
 279  * Returns: the position in stream_time.
 280  */
 281 gint64
 282 gst_segment_to_stream_time (GstSegment * segment, GstFormat format,
 283     gint64 position)
 284 {
 285   gint64 result;
 286
 287   g_return_val_if_fail (segment != NULL, FALSE);
 288   g_return_val_if_fail (segment->format == format, FALSE);
 289
 290   result = ((position - segment->start) / segment->abs_rate) + segment->time;
 291
 292   return result;
 293 }
 294
 295 /**
 296  * gst_segment_to_running_time:
 297  * @segment: a #GstSegment structure.
 298  * @format: the format of the segment.
 299  * @position: the position in the segment
 300  *
 301  * Translate @position to the total running time using the currently configured
 302  * segment.
 303  *
 304  * This function is typically used by elements that need to synchronize to the
 305  * global clock in a pipeline.
 306  *
 307  * Returns: the position as the total running time.
 308  */
 309 gint64
 310 gst_segment_to_running_time (GstSegment * segment, GstFormat format,
 311     gint64 position)
 312 {
 313   gint64 result;
 314
 315   g_return_val_if_fail (segment != NULL, FALSE);
 316   g_return_val_if_fail (segment->format == format, FALSE);
 317
 318   result = ((position - segment->start) / segment->abs_rate) + segment->accum;
 319
 320   return result;
 321 }
 322
 323 /**
 324  * gst_segment_clip:
 325  * @segment: a #GstSegment structure.
 326  * @format: the format of the segment.
 327  * @start: the start position in the segment
 328  * @stop: the stop position in the segment
 329  * @clip_start: the clipped start position in the segment
 330  * @clip_stop: the clipped stop position in the segment
 331  *
 332  * Clip the given @start and @stop values to the segment boundaries given
 333  * in @segment.
 334  *
 335  * Returns: TRUE if the given @start and @stop times fall partially in
 336  *     @segment, FALSE if the values are completely outside of the segment.
 337  */
 338 gboolean
 339 gst_segment_clip (GstSegment * segment, GstFormat format, gint64 start,
 340     gint64 stop, gint64 * clip_start, gint64 * clip_stop)
 341 {
 342   g_return_val_if_fail (segment != NULL, FALSE);
 343   g_return_val_if_fail (segment->format == format, FALSE);
 344
 345   /* we need a valid start position */
 346   if (start == -1)
 347     return FALSE;
 348
 349   /* if we have a stop position and start is bigger, we're
 350    * outside of the segment */
 351   if (segment->stop != -1 && start >= segment->stop)
 352     return FALSE;
 353
 354   /* if a stop position is given and is before the segment start,
 355    * we're outside of the segment */
 356   if (stop != -1 && stop <= segment->start)
 357     return FALSE;
 358
 359   if (clip_start)
 360     *clip_start = MAX (start, segment->start);
 361
 362   if (clip_stop) {
 363     if (stop == -1)
 364       *clip_stop = segment->stop;
 365     else if (segment->stop == -1)
 366       *clip_stop = MAX (-1, stop);
 367     else
 368       *clip_stop = MIN (stop, segment->stop);
 369
 370     if (segment->duration != -1)
 371       *clip_stop = MIN (*clip_stop, segment->duration);
 372   }
 373
 374   return TRUE;
 375 }