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 <math.h>
  24
  25 #include "gst_private.h"
  26
  27 #include "gstutils.h"
  28 #include "gstsegment.h"
  29
  30 /**
  31  * SECTION:gstsegment
  32  * @short_description: Structure describing the configured region of interest
  33  *                     in a media file.
  34  * @see_also: #GstEvent
  35  *
  36  * This helper structure holds the relevant values for tracking the region of
  37  * interest in a media file, called a segment.
  38  *
  39  * The structure can be used for two purposes:
  40  * <itemizedlist>
  41  *   <listitem><para>performing seeks (handling seek events)</para></listitem>
  42  *   <listitem><para>tracking playback regions (handling newsegment events)</para></listitem>
  43  * </itemizedlist>
  44  *
  45  * The segment is usually configured by the application with a seek event which
  46  * is propagated upstream and eventually handled by an element that performs the seek.
  47  *
  48  * The configured segment is then propagated back downstream with a newsegment event.
  49  * This information is then used to clip media to the segment boundaries.
  50  *
  51  * A segment structure is initialized with gst_segment_init(), which takes a #GstFormat
  52  * that will be used as the format of the segment values. The segment will be configured
  53  * with a start value of 0 and a stop/duration of -1, which is undefined. The default
  54  * rate and applied_rate is 1.0.
  55  *
  56  * If the segment is used for managing seeks, the segment duration should be set with
  57  * gst_segment_set_duration(). The public duration field contains the duration of the
  58  * segment. When using the segment for seeking, the start and time members should
  59  * normally be left to their default 0 value. The stop position is left to -1 unless
  60  * explicitly configured to a different value after a seek event.
  61  *
  62  * The current position in the segment should be set with the gst_segment_set_last_stop().
  63  * The public last_stop field contains the last set stop position in the segment.
  64  *
  65  * For elements that perform seeks, the current segment should be updated with the
  66  * gst_segment_set_seek() and the values from the seek event. This method will update
  67  * all the segment fields. The last_stop field will contain the new playback position.
  68  * If the cur_type was different from GST_SEEK_TYPE_NONE, playback continues from
  69  * the last_stop position, possibly with updated flags or rate.
  70  *
  71  * For elements that want to use #GstSegment to track the playback region, use
  72  * gst_segment_set_newsegment() to update the segment fields with the information from
  73  * the newsegment event. The gst_segment_clip() method can be used to check and clip
  74  * the media data to the segment boundaries.
  75  *
  76  * For elements that want to synchronize to the pipeline clock, gst_segment_to_running_time()
  77  * can be used to convert a timestamp to a value that can be used to synchronize
  78  * to the clock. This function takes into account all accumulated segments as well as
  79  * any rate or applied_rate conversions.
  80  *
  81  * For elements that need to perform operations on media data in stream_time,
  82  * gst_segment_to_stream_time() can be used to convert a timestamp and the segment
  83  * info to stream time (which is always between 0 and the duration of the stream).
  84  *
  85  * Last reviewed on 2007-05-17 (0.10.13)
  86  */
  87
  88 /**
  89  * gst_segment_copy:
  90  * @segment: a #GstSegment
  91  *
  92  * Create a copy of given @segment.
  93  *
  94  * Returns: a new #GstSegment, free with gst_segment_free().
  95  *
  96  * Since: 0.10.20
  97  */
  98 GstSegment *
  99 gst_segment_copy (GstSegment * segment)
 100 {
 101   GstSegment *result = NULL;
 102
 103   if (segment) {
 104     result = (GstSegment *) g_slice_copy (sizeof (GstSegment), segment);
 105   }
 106   return result;
 107 }
 108
 109 GType
 110 gst_segment_get_type (void)
 111 {
 112   static GType gst_segment_type = 0;
 113
 114   if (G_UNLIKELY (gst_segment_type == 0)) {
 115     gst_segment_type = g_boxed_type_register_static ("GstSegment",
 116         (GBoxedCopyFunc) gst_segment_copy, (GBoxedFreeFunc) gst_segment_free);
 117   }
 118
 119   return gst_segment_type;
 120 }
 121
 122 /**
 123  * gst_segment_new:
 124  *
 125  * Allocate a new #GstSegment structure and initialize it using
 126  * gst_segment_init().
 127  *
 128  * Returns: a new #GstSegment, free with gst_segment_free().
 129  */
 130 GstSegment *
 131 gst_segment_new (void)
 132 {
 133   GstSegment *result;
 134
 135   result = g_slice_new0 (GstSegment);
 136   gst_segment_init (result, GST_FORMAT_UNDEFINED);
 137
 138   return result;
 139 }
 140
 141 /**
 142  * gst_segment_free:
 143  * @segment: a #GstSegment
 144  *
 145  * Free the allocated segment @segment.
 146  */
 147 void
 148 gst_segment_free (GstSegment * segment)
 149 {
 150   g_slice_free (GstSegment, segment);
 151 }
 152
 153 /**
 154  * gst_segment_init:
 155  * @segment: a #GstSegment structure.
 156  * @format: the format of the segment.
 157  *
 158  * The start/last_stop positions are set to 0 and the stop/duration
 159  * fields are set to -1 (unknown). The default rate of 1.0 and no
 160  * flags are set.
 161  *
 162  * Initialize @segment to its default values.
 163  */
 164 void
 165 gst_segment_init (GstSegment * segment, GstFormat format)
 166 {
 167   g_return_if_fail (segment != NULL);
 168
 169   segment->rate = 1.0;
 170   segment->abs_rate = 1.0;
 171   segment->applied_rate = 1.0;
 172   segment->format = format;
 173   segment->flags = 0;
 174   segment->start = 0;
 175   segment->stop = -1;
 176   segment->time = 0;
 177   segment->accum = 0;
 178   segment->last_stop = 0;
 179   segment->duration = -1;
 180 }
 181
 182 /**
 183  * gst_segment_set_duration:
 184  * @segment: a #GstSegment structure.
 185  * @format: the format of the segment.
 186  * @duration: the duration of the segment info or -1 if unknown.
 187  *
 188  * Set the duration of the segment to @duration. This function is mainly
 189  * used by elements that perform seeking and know the total duration of the
 190  * segment.
 191  *
 192  * This field should be set to allow seeking requests relative to the
 193  * duration.
 194  */
 195 void
 196 gst_segment_set_duration (GstSegment * segment, GstFormat format,
 197     gint64 duration)
 198 {
 199   g_return_if_fail (segment != NULL);
 200
 201   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 202     segment->format = format;
 203   else
 204     g_return_if_fail (segment->format == format);
 205
 206   segment->duration = duration;
 207 }
 208
 209 /**
 210  * gst_segment_set_last_stop:
 211  * @segment: a #GstSegment structure.
 212  * @format: the format of the segment.
 213  * @position: the position
 214  *
 215  * Set the last observed stop position in the segment to @position.
 216  *
 217  * This field should be set to allow seeking requests relative to the
 218  * current playing position.
 219  */
 220 void
 221 gst_segment_set_last_stop (GstSegment * segment, GstFormat format,
 222     gint64 position)
 223 {
 224   g_return_if_fail (segment != NULL);
 225
 226   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 227     segment->format = format;
 228   else
 229     g_return_if_fail (segment->format == format);
 230
 231   segment->last_stop = MAX (segment->start, position);
 232 }
 233
 234 /**
 235  * gst_segment_set_seek:
 236  * @segment: a #GstSegment structure.
 237  * @rate: the rate of the segment.
 238  * @format: the format of the segment.
 239  * @flags: the seek flags for the segment
 240  * @start_type: the seek method
 241  * @start: the seek start value
 242  * @stop_type: the seek method
 243  * @stop: the seek stop value
 244  * @update: boolean holding whether last_stop was updated.
 245  *
 246  * Update the segment structure with the field values of a seek event (see
 247  * gst_event_new_seek()).
 248  *
 249  * After calling this method, the segment field last_stop and time will
 250  * contain the requested new position in the segment. The new requested
 251  * position in the segment depends on @rate and @start_type and @stop_type.
 252  *
 253  * For positive @rate, the new position in the segment is the new @segment
 254  * start field when it was updated with a @start_type different from
 255  * #GST_SEEK_TYPE_NONE. If no update was performed on @segment start position
 256  * (#GST_SEEK_TYPE_NONE), @start is ignored and @segment last_stop is
 257  * unmodified.
 258  *
 259  * For negative @rate, the new position in the segment is the new @segment
 260  * stop field when it was updated with a @stop_type different from
 261  * #GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the
 262  * duration of the segment will be used to update the stop position.
 263  * If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE),
 264  * @stop is ignored and @segment last_stop is unmodified.
 265  *
 266  * The applied rate of the segment will be set to 1.0 by default.
 267  * If the caller can apply a rate change, it should update @segment
 268  * rate and applied_rate after calling this function.
 269  *
 270  * @update will be set to TRUE if a seek should be performed to the segment
 271  * last_stop field. This field can be FALSE if, for example, only the @rate
 272  * has been changed but not the playback position.
 273  */
 274 void
 275 gst_segment_set_seek (GstSegment * segment, gdouble rate,
 276     GstFormat format, GstSeekFlags flags,
 277     GstSeekType start_type, gint64 start,
 278     GstSeekType stop_type, gint64 stop, gboolean * update)
 279 {
 280   gboolean update_stop, update_start;
 281   gint64 last_stop;
 282
 283   g_return_if_fail (rate != 0.0);
 284   g_return_if_fail (segment != NULL);
 285
 286   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 287     segment->format = format;
 288
 289   update_start = update_stop = TRUE;
 290
 291   /* segment->start is never invalid */
 292   switch (start_type) {
 293     case GST_SEEK_TYPE_NONE:
 294       /* no update to segment, take previous start */
 295       start = segment->start;
 296       update_start = FALSE;
 297       break;
 298     case GST_SEEK_TYPE_SET:
 299       /* start holds desired position, map -1 to the start */
 300       if (start == -1)
 301         start = 0;
 302       /* start must be 0 or the formats must match */
 303       g_return_if_fail (start == 0 || segment->format == format);
 304       break;
 305     case GST_SEEK_TYPE_CUR:
 306       g_return_if_fail (start == 0 || segment->format == format);
 307       /* add start to currently configured segment */
 308       start = segment->start + start;
 309       break;
 310     case GST_SEEK_TYPE_END:
 311       if (segment->duration != -1) {
 312         g_return_if_fail (start == 0 || segment->format == format);
 313         /* add start to total length */
 314         start = segment->duration + start;
 315       } else {
 316         /* no update if duration unknown */
 317         start = segment->start;
 318         update_start = FALSE;
 319       }
 320       break;
 321   }
 322   /* bring in sane range */
 323   if (segment->duration != -1)
 324     start = CLAMP (start, 0, segment->duration);
 325   else
 326     start = MAX (start, 0);
 327
 328   /* stop can be -1 if we have not configured a stop. */
 329   switch (stop_type) {
 330     case GST_SEEK_TYPE_NONE:
 331       stop = segment->stop;
 332       update_stop = FALSE;
 333       break;
 334     case GST_SEEK_TYPE_SET:
 335       /* stop holds required value, if it's not -1, it must be of the same
 336        * format as the segment. */
 337       g_return_if_fail (stop == -1 || segment->format == format);
 338       break;
 339     case GST_SEEK_TYPE_CUR:
 340       if (segment->stop != -1) {
 341         /* only add compatible formats or 0 */
 342         g_return_if_fail (stop == 0 || segment->format == format);
 343         stop = segment->stop + stop;
 344       } else
 345         stop = -1;
 346       break;
 347     case GST_SEEK_TYPE_END:
 348       if (segment->duration != -1) {
 349         /* only add compatible formats or 0 */
 350         g_return_if_fail (stop == 0 || segment->format == format);
 351         stop = segment->duration + stop;
 352       } else {
 353         stop = segment->stop;
 354         update_stop = FALSE;
 355       }
 356       break;
 357   }
 358
 359   /* if we have a valid stop time, make sure it is clipped */
 360   if (stop != -1) {
 361     if (segment->duration != -1)
 362       stop = CLAMP (stop, 0, segment->duration);
 363     else
 364       stop = MAX (stop, 0);
 365   }
 366
 367   /* we can't have stop before start */
 368   if (stop != -1)
 369     g_return_if_fail (start <= stop);
 370
 371   segment->rate = rate;
 372   segment->abs_rate = ABS (rate);
 373   segment->applied_rate = 1.0;
 374   segment->flags = flags;
 375   segment->start = start;
 376   segment->stop = stop;
 377   segment->time = start;
 378
 379   last_stop = segment->last_stop;
 380   if (update_start && rate > 0.0) {
 381     last_stop = start;
 382   }
 383   if (update_stop && rate < 0.0) {
 384     if (stop != -1)
 385       last_stop = stop;
 386     else {
 387       if (segment->duration != -1)
 388         last_stop = segment->duration;
 389       else
 390         last_stop = 0;
 391     }
 392   }
 393   /* set update arg to reflect update of last_stop */
 394   if (update)
 395     *update = last_stop != segment->last_stop;
 396
 397   /* update new position */
 398   segment->last_stop = last_stop;
 399 }
 400
 401 /**
 402  * gst_segment_set_newsegment:
 403  * @segment: a #GstSegment structure.
 404  * @update: flag indicating a new segment is started or updated
 405  * @rate: the rate of the segment.
 406  * @format: the format of the segment.
 407  * @start: the new start value
 408  * @stop: the new stop value
 409  * @time: the new stream time
 410  *
 411  * Update the segment structure with the field values of a new segment event and
 412  * with a default applied_rate of 1.0.
 413  *
 414  * Since: 0.10.6
 415  */
 416 void
 417 gst_segment_set_newsegment (GstSegment * segment, gboolean update, gdouble rate,
 418     GstFormat format, gint64 start, gint64 stop, gint64 time)
 419 {
 420   gst_segment_set_newsegment_full (segment, update, rate, 1.0, format, start,
 421       stop, time);
 422 }
 423
 424 /**
 425  * gst_segment_set_newsegment_full:
 426  * @segment: a #GstSegment structure.
 427  * @update: flag indicating a new segment is started or updated
 428  * @rate: the rate of the segment.
 429  * @applied_rate: the applied rate of the segment.
 430  * @format: the format of the segment.
 431  * @start: the new start value
 432  * @stop: the new stop value
 433  * @time: the new stream time
 434  *
 435  * Update the segment structure with the field values of a new segment event.
 436  */
 437 void
 438 gst_segment_set_newsegment_full (GstSegment * segment, gboolean update,
 439     gdouble rate, gdouble applied_rate, GstFormat format, gint64 start,
 440     gint64 stop, gint64 time)
 441 {
 442   gint64 duration, last_stop;
 443
 444   g_return_if_fail (rate != 0.0);
 445   g_return_if_fail (applied_rate != 0.0);
 446   g_return_if_fail (segment != NULL);
 447
 448   GST_DEBUG ("configuring segment update %d, rate %lf, format %s, "
 449       "start %" G_GINT64_FORMAT ", stop %" G_GINT64_FORMAT ", position %"
 450       G_GINT64_FORMAT, update, rate, gst_format_get_name (format), start,
 451       stop, time);
 452   GST_DEBUG ("old segment was: %" GST_SEGMENT_FORMAT, segment);
 453
 454   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 455     segment->format = format;
 456
 457   /* any other format with 0 also gives time 0, the other values are
 458    * invalid in the format though. */
 459   if (format != segment->format && start == 0) {
 460     format = segment->format;
 461     if (stop != 0)
 462       stop = -1;
 463     if (time != 0)
 464       time = -1;
 465   }
 466
 467   g_return_if_fail (segment->format == format);
 468
 469   if (update) {
 470     if (G_LIKELY (segment->rate > 0.0)) {
 471       /* an update to the current segment is done, elapsed time is
 472        * difference between the old start and new start. */
 473       if (start > segment->start)
 474         duration = start - segment->start;
 475       else
 476         duration = 0;
 477     } else {
 478       /* for negative rates, the elapsed duration is the diff between the stop
 479        * positions */
 480       if (stop != -1 && stop < segment->stop)
 481         duration = segment->stop - stop;
 482       else
 483         duration = 0;
 484     }
 485     /* update last_stop to be a valid value in the updated segment */
 486     if (start > segment->last_stop)
 487       last_stop = start;
 488     else if (stop != -1 && stop < segment->last_stop)
 489       last_stop = stop;
 490     else
 491       last_stop = segment->last_stop;
 492   } else {
 493     /* the new segment has to be aligned with the old segment.
 494      * We first update the accumulated time of the previous
 495      * segment. the accumulated time is used when syncing to the
 496      * clock. */
 497     if (segment->stop != -1) {
 498       duration = segment->stop - segment->start;
 499     } else if (segment->last_stop != -1) {
 500       /* else use last seen timestamp as segment stop */
 501       duration = segment->last_stop - segment->start;
 502     } else {
 503       /* else we don't know and throw a warning.. really, this should
 504        * be fixed in the element. */
 505       g_warning ("closing segment of unknown duration, assuming duration of 0");
 506       duration = 0;
 507     }
 508     /* position the last_stop to the next expected position in the new segment,
 509      * which is the start or the stop of the segment */
 510     if (rate > 0.0)
 511       last_stop = start;
 512     else
 513       last_stop = stop;
 514   }
 515   /* use previous rate to calculate duration */
 516   if (G_LIKELY (segment->abs_rate != 1.0))
 517     duration /= segment->abs_rate;
 518
 519   /* accumulate duration */
 520   segment->accum += duration;
 521
 522   /* then update the current segment */
 523   segment->rate = rate;
 524   segment->abs_rate = ABS (rate);
 525   segment->applied_rate = applied_rate;
 526   segment->start = start;
 527   segment->last_stop = last_stop;
 528   segment->stop = stop;
 529   segment->time = time;
 530 }
 531
 532 /**
 533  * gst_segment_to_stream_time:
 534  * @segment: a #GstSegment structure.
 535  * @format: the format of the segment.
 536  * @position: the position in the segment
 537  *
 538  * Translate @position to stream time using the currently configured
 539  * segment. The @position value must be between @segment start and
 540  * stop value.
 541  *
 542  * This function is typically used by elements that need to operate on
 543  * the stream time of the buffers it receives, such as effect plugins.
 544  * In those use cases, @position is typically the buffer timestamp or
 545  * clock time that one wants to convert to the stream time.
 546  * The stream time is always between 0 and the total duration of the
 547  * media stream.
 548  *
 549  * Returns: the position in stream_time or -1 when an invalid position
 550  * was given.
 551  */
 552 gint64
 553 gst_segment_to_stream_time (GstSegment * segment, GstFormat format,
 554     gint64 position)
 555 {
 556   gint64 result, start, stop, time;
 557   gdouble abs_applied_rate;
 558
 559   g_return_val_if_fail (segment != NULL, -1);
 560
 561   /* format does not matter for -1 */
 562   if (G_UNLIKELY (position == -1))
 563     return -1;
 564
 565   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 566     segment->format = format;
 567
 568   /* if we have the position for the same format as the segment, we can compare
 569    * the start and stop values, otherwise we assume 0 and -1 */
 570   if (G_LIKELY (segment->format == format)) {
 571     start = segment->start;
 572     stop = segment->stop;
 573     time = segment->time;
 574   } else {
 575     start = 0;
 576     stop = -1;
 577     time = 0;
 578   }
 579
 580   /* outside of the segment boundary stop */
 581   if (G_UNLIKELY (stop != -1 && position > stop))
 582     return -1;
 583
 584   /* before the segment boundary */
 585   if (G_UNLIKELY (position < start))
 586     return -1;
 587
 588   /* time must be known */
 589   if (G_UNLIKELY (time == -1))
 590     return -1;
 591
 592   /* bring to uncorrected position in segment */
 593   result = position - start;
 594
 595   abs_applied_rate = ABS (segment->applied_rate);
 596
 597   /* correct for applied rate if needed */
 598   if (G_UNLIKELY (abs_applied_rate != 1.0))
 599     result *= abs_applied_rate;
 600
 601   /* add or subtract from segment time based on applied rate */
 602   if (G_LIKELY (segment->applied_rate > 0.0)) {
 603     /* correct for segment time */
 604     result += time;
 605   } else {
 606     /* correct for segment time, clamp at 0. Streams with a negative
 607      * applied_rate have timestamps between start and stop, as usual, but have
 608      * the time member starting high and going backwards.  */
 609     if (G_LIKELY (time > result))
 610       result = time - result;
 611     else
 612       result = 0;
 613   }
 614
 615   return result;
 616 }
 617
 618 /**
 619  * gst_segment_to_running_time:
 620  * @segment: a #GstSegment structure.
 621  * @format: the format of the segment.
 622  * @position: the position in the segment
 623  *
 624  * Translate @position to the total running time using the currently configured
 625  * and previously accumulated segments. Position is a value between @segment
 626  * start and stop time.
 627  *
 628  * This function is typically used by elements that need to synchronize to the
 629  * global clock in a pipeline. The runnning time is a constantly increasing value
 630  * starting from 0. When gst_segment_init() is called, this value will reset to
 631  * 0.
 632  *
 633  * This function returns -1 if the position is outside of @segment start and stop.
 634  *
 635  * Returns: the position as the total running time or -1 when an invalid position
 636  * was given.
 637  */
 638 gint64
 639 gst_segment_to_running_time (GstSegment * segment, GstFormat format,
 640     gint64 position)
 641 {
 642   gint64 result;
 643   gint64 start, stop, accum;
 644
 645   g_return_val_if_fail (segment != NULL, -1);
 646
 647   if (G_UNLIKELY (position == -1))
 648     return -1;
 649
 650   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 651     segment->format = format;
 652
 653   /* if we have the position for the same format as the segment, we can compare
 654    * the start and stop values, otherwise we assume 0 and -1 */
 655   if (G_LIKELY (segment->format == format)) {
 656     start = segment->start;
 657     stop = segment->stop;
 658     accum = segment->accum;
 659   } else {
 660     start = 0;
 661     stop = -1;
 662     accum = 0;
 663   }
 664
 665   /* before the segment boundary */
 666   if (G_UNLIKELY (position < start))
 667     return -1;
 668
 669   if (G_LIKELY (segment->rate > 0.0)) {
 670     /* outside of the segment boundary stop */
 671     if (G_UNLIKELY (stop != -1 && position > stop))
 672       return -1;
 673
 674     /* bring to uncorrected position in segment */
 675     result = position - start;
 676   } else {
 677     /* cannot continue if no stop position set or outside of
 678      * the segment. */
 679     if (G_UNLIKELY (stop == -1 || position > stop))
 680       return -1;
 681
 682     /* bring to uncorrected position in segment */
 683     result = stop - position;
 684   }
 685
 686   /* scale based on the rate, avoid division by and conversion to
 687    * float when not needed */
 688   if (G_UNLIKELY (segment->abs_rate != 1.0))
 689     result /= segment->abs_rate;
 690
 691   /* correct for accumulated segments */
 692   result += accum;
 693
 694   return result;
 695 }
 696
 697 /**
 698  * gst_segment_clip:
 699  * @segment: a #GstSegment structure.
 700  * @format: the format of the segment.
 701  * @start: the start position in the segment
 702  * @stop: the stop position in the segment
 703  * @clip_start: the clipped start position in the segment
 704  * @clip_stop: the clipped stop position in the segment
 705  *
 706  * Clip the given @start and @stop values to the segment boundaries given
 707  * in @segment. @start and @stop are compared and clipped to @segment
 708  * start and stop values.
 709  *
 710  * If the function returns FALSE, @start and @stop are known to fall
 711  * outside of @segment and @clip_start and @clip_stop are not updated.
 712  *
 713  * When the function returns TRUE, @clip_start and @clip_stop will be
 714  * updated. If @clip_start or @clip_stop are different from @start or @stop
 715  * respectively, the region fell partially in the segment.
 716  *
 717  * Note that when @stop is -1, @clip_stop will be set to the end of the
 718  * segment. Depending on the use case, this may or may not be what you want.
 719  *
 720  * Returns: TRUE if the given @start and @stop times fall partially or
 721  *     completely in @segment, FALSE if the values are completely outside
 722  *     of the segment.
 723  */
 724 gboolean
 725 gst_segment_clip (GstSegment * segment, GstFormat format, gint64 start,
 726     gint64 stop, gint64 * clip_start, gint64 * clip_stop)
 727 {
 728   g_return_val_if_fail (segment != NULL, FALSE);
 729
 730   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 731     segment->format = format;
 732   else
 733     g_return_val_if_fail (segment->format == format, FALSE);
 734
 735   /* if we have a stop position and a valid start and start is bigger,
 736    * we're outside of the segment */
 737   if (G_UNLIKELY (segment->stop != -1 && start != -1 && start >= segment->stop))
 738     return FALSE;
 739
 740   /* if a stop position is given and is before the segment start,
 741    * we're outside of the segment */
 742   if (G_UNLIKELY (stop != -1 && stop != start && stop <= segment->start))
 743     return FALSE;
 744
 745   if (clip_start) {
 746     if (start == -1)
 747       *clip_start = -1;
 748     else
 749       *clip_start = MAX (start, segment->start);
 750   }
 751
 752   if (clip_stop) {
 753     if (stop == -1)
 754       *clip_stop = segment->stop;
 755     else if (segment->stop == -1)
 756       *clip_stop = MAX (-1, stop);
 757     else
 758       *clip_stop = MIN (stop, segment->stop);
 759
 760     if (segment->duration != -1)
 761       *clip_stop = MIN (*clip_stop, segment->duration);
 762   }
 763
 764   return TRUE;
 765 }
 766
 767 /**
 768  * gst_segment_to_position:
 769  * @segment: a #GstSegment structure.
 770  * @format: the format of the segment.
 771  * @running_time: the running_time in the segment
 772  *
 773  * Convert @running_time into a position in the segment so that
 774  * gst_segment_to_running_time() with that position returns @running_time.
 775  *
 776  * Returns: the position in the segment for @running_time. This function returns
 777  * -1 when @running_time is -1 or when it is not inside @segment.
 778  *
 779  * Since: 0.10.24
 780  */
 781 gint64
 782 gst_segment_to_position (GstSegment * segment, GstFormat format,
 783     gint64 running_time)
 784 {
 785   gint64 result;
 786   gint64 start, stop, accum;
 787
 788   g_return_val_if_fail (segment != NULL, -1);
 789
 790   if (G_UNLIKELY (running_time == -1))
 791     return -1;
 792
 793   if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
 794     segment->format = format;
 795
 796   /* if we have the position for the same format as the segment, we can compare
 797    * the start and stop values, otherwise we assume 0 and -1 */
 798   if (G_LIKELY (segment->format == format)) {
 799     start = segment->start;
 800     stop = segment->stop;
 801     accum = segment->accum;
 802   } else {
 803     start = 0;
 804     stop = -1;
 805     accum = 0;
 806   }
 807
 808   /* this running_time was for a previous segment */
 809   if (running_time < accum)
 810     return -1;
 811
 812   /* start by subtracting the accumulated time */
 813   result = running_time - accum;
 814
 815   /* move into the segment at the right rate */
 816   if (G_UNLIKELY (segment->abs_rate != 1.0))
 817     result = ceil (result * segment->abs_rate);
 818
 819   if (G_LIKELY (segment->rate > 0.0)) {
 820     /* bring to corrected position in segment */
 821     result += start;
 822
 823     /* outside of the segment boundary stop */
 824     if (G_UNLIKELY (stop != -1 && result > stop))
 825       return -1;
 826   } else {
 827     /* cannot continue if no stop position set or outside of
 828      * the segment. */
 829     if (G_UNLIKELY (stop == -1 || result + start > stop))
 830       return -1;
 831
 832     /* bring to corrected position in segment */
 833     result = stop - result;
 834   }
 835   return result;
 836 }
 837
 838
 839 /**
 840  * gst_segment_set_running_time:
 841  * @segment: a #GstSegment structure.
 842  * @format: the format of the segment.
 843  * @running_time: the running_time in the segment
 844  *
 845  * Adjust the start/stop and accum values of @segment such that the next valid
 846  * buffer will be one with @running_time.
 847  *
 848  * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
 849  * returned, @running_time is -1 or not in @segment.
 850  *
 851  * Since: 0.10.24
 852  */
 853 gboolean
 854 gst_segment_set_running_time (GstSegment * segment, GstFormat format,
 855     gint64 running_time)
 856 {
 857   gint64 position;
 858   gint64 start, stop, last_stop;
 859
 860   /* start by bringing the running_time into the segment position */
 861   position = gst_segment_to_position (segment, format, running_time);
 862
 863   /* we must have a valid position now */
 864   if (G_UNLIKELY (position == -1))
 865     return FALSE;
 866
 867   start = segment->start;
 868   stop = segment->stop;
 869   last_stop = segment->last_stop;
 870
 871   if (G_LIKELY (segment->rate > 0.0)) {
 872     /* update the start/last_stop and time values */
 873     start = position;
 874     if (last_stop < start)
 875       last_stop = start;
 876   } else {
 877     /* reverse, update stop */
 878     stop = position;
 879     /* if we were past the position, go back */
 880     if (last_stop > stop)
 881       last_stop = stop;
 882   }
 883   /* and accumulated time is exactly the running time */
 884   segment->time = gst_segment_to_stream_time (segment, format, start);
 885   segment->start = start;
 886   segment->stop = stop;
 887   segment->last_stop = last_stop;
 888   segment->accum = running_time;
 889
 890   return TRUE;
 891 }