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