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