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., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22 #include "gst_private.h"
  23
  24 #include <math.h>
  25
  26 #include "gstutils.h"
  27 #include "gstsegment.h"
  28
  29 /**
  30  * SECTION:gstsegment
  31  * @title: 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  *
  41  *   * performing seeks (handling seek events)
  42  *   * tracking playback regions (handling newsegment events)
  43  *
  44  * The segment is usually configured by the application with a seek event which
  45  * is propagated upstream and eventually handled by an element that performs the seek.
  46  *
  47  * The configured segment is then propagated back downstream with a newsegment event.
  48  * This information is then used to clip media to the segment boundaries.
  49  *
  50  * A segment structure is initialized with gst_segment_init(), which takes a #GstFormat
  51  * that will be used as the format of the segment values. The segment will be configured
  52  * with a start value of 0 and a stop/duration of -1, which is undefined. The default
  53  * rate and applied_rate is 1.0.
  54  *
  55  * The public duration field contains the duration of the segment. When using
  56  * the segment for seeking, the start and time members should normally be left
  57  * to their default 0 value. The stop position is left to -1 unless explicitly
  58  * configured to a different value after a seek event.
  59  *
  60  * The current position in the segment should be set by changing the position
  61  * member in the structure.
  62  *
  63  * For elements that perform seeks, the current segment should be updated with the
  64  * gst_segment_do_seek() and the values from the seek event. This method will update
  65  * all the segment fields. The position field will contain the new playback position.
  66  * If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from
  67  * the position position, possibly with updated flags or rate.
  68  *
  69  * For elements that want to use #GstSegment to track the playback region,
  70  * update the segment fields with the information from the newsegment event.
  71  * 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 the base 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
  84 /* FIXME 2.0: remove unused format parameter.
  85  * Most of the methods in gstsegment.c take and extra GstFormat format, just to
  86  * verify segment->format == format.
  87  * See https://bugzilla.gnome.org/show_bug.cgi?id=788979
  88  */
  89
  90 /**
  91  * gst_segment_copy:
  92  * @segment: (transfer none): a #GstSegment
  93  *
  94  * Create a copy of given @segment.
  95  *
  96  * Free-function: gst_segment_free
  97  *
  98  * Returns: (transfer full): a new #GstSegment, free with gst_segment_free().
  99  */
 100 GstSegment *
 101 gst_segment_copy (const GstSegment * segment)
 102 {
 103   GstSegment *result = NULL;
 104
 105   if (segment) {
 106     result = (GstSegment *) g_slice_copy (sizeof (GstSegment), segment);
 107   }
 108   return result;
 109 }
 110
 111 /**
 112  * gst_segment_copy_into:
 113  * @src: (transfer none): a #GstSegment
 114  * @dest: (transfer none): a #GstSegment
 115  *
 116  * Copy the contents of @src into @dest.
 117  */
 118 void
 119 gst_segment_copy_into (const GstSegment * src, GstSegment * dest)
 120 {
 121   memcpy (dest, src, sizeof (GstSegment));
 122 }
 123
 124 G_DEFINE_BOXED_TYPE (GstSegment, gst_segment,
 125     (GBoxedCopyFunc) gst_segment_copy, (GBoxedFreeFunc) gst_segment_free);
 126
 127 /**
 128  * gst_segment_new:
 129  *
 130  * Allocate a new #GstSegment structure and initialize it using
 131  * gst_segment_init().
 132  *
 133  * Free-function: gst_segment_free
 134  *
 135  * Returns: (transfer full): a new #GstSegment, free with gst_segment_free().
 136  */
 137 GstSegment *
 138 gst_segment_new (void)
 139 {
 140   GstSegment *result;
 141
 142   result = g_slice_new0 (GstSegment);
 143   gst_segment_init (result, GST_FORMAT_UNDEFINED);
 144
 145   return result;
 146 }
 147
 148 /**
 149  * gst_segment_free:
 150  * @segment: (in) (transfer full): a #GstSegment
 151  *
 152  * Free the allocated segment @segment.
 153  */
 154 void
 155 gst_segment_free (GstSegment * segment)
 156 {
 157   g_slice_free (GstSegment, segment);
 158 }
 159
 160 /**
 161  * gst_segment_init:
 162  * @segment: a #GstSegment structure.
 163  * @format: the format of the segment.
 164  *
 165  * The start/position fields are set to 0 and the stop/duration
 166  * fields are set to -1 (unknown). The default rate of 1.0 and no
 167  * flags are set.
 168  *
 169  * Initialize @segment to its default values.
 170  */
 171 void
 172 gst_segment_init (GstSegment * segment, GstFormat format)
 173 {
 174   g_return_if_fail (segment != NULL);
 175
 176   segment->flags = GST_SEGMENT_FLAG_NONE;
 177   segment->rate = 1.0;
 178   segment->applied_rate = 1.0;
 179   segment->format = format;
 180   segment->base = 0;
 181   segment->offset = 0;
 182   segment->start = 0;
 183   segment->stop = -1;
 184   segment->time = 0;
 185   segment->position = 0;
 186   segment->duration = -1;
 187 }
 188
 189 /**
 190  * gst_segment_do_seek:
 191  * @segment: a #GstSegment structure.
 192  * @rate: the rate of the segment.
 193  * @format: the format of the segment.
 194  * @flags: the segment flags for the segment
 195  * @start_type: the seek method
 196  * @start: the seek start value
 197  * @stop_type: the seek method
 198  * @stop: the seek stop value
 199  * @update: (out) (allow-none): boolean holding whether position was updated.
 200  *
 201  * Update the segment structure with the field values of a seek event (see
 202  * gst_event_new_seek()).
 203  *
 204  * After calling this method, the segment field position and time will
 205  * contain the requested new position in the segment. The new requested
 206  * position in the segment depends on @rate and @start_type and @stop_type.
 207  *
 208  * For positive @rate, the new position in the segment is the new @segment
 209  * start field when it was updated with a @start_type different from
 210  * #GST_SEEK_TYPE_NONE. If no update was performed on @segment start position
 211  * (#GST_SEEK_TYPE_NONE), @start is ignored and @segment position is
 212  * unmodified.
 213  *
 214  * For negative @rate, the new position in the segment is the new @segment
 215  * stop field when it was updated with a @stop_type different from
 216  * #GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the
 217  * duration of the segment will be used to update the stop position.
 218  * If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE),
 219  * @stop is ignored and @segment position is unmodified.
 220  *
 221  * The applied rate of the segment will be set to 1.0 by default.
 222  * If the caller can apply a rate change, it should update @segment
 223  * rate and applied_rate after calling this function.
 224  *
 225  * @update will be set to %TRUE if a seek should be performed to the segment
 226  * position field. This field can be %FALSE if, for example, only the @rate
 227  * has been changed but not the playback position.
 228  *
 229  * Returns: %TRUE if the seek could be performed.
 230  */
 231 gboolean
 232 gst_segment_do_seek (GstSegment * segment, gdouble rate,
 233     GstFormat format, GstSeekFlags flags,
 234     GstSeekType start_type, guint64 start,
 235     GstSeekType stop_type, guint64 stop, gboolean * update)
 236 {
 237   gboolean update_stop, update_start;
 238   guint64 position, base;
 239
 240   g_return_val_if_fail (rate != 0.0, FALSE);
 241   g_return_val_if_fail (segment != NULL, FALSE);
 242   g_return_val_if_fail (segment->format == format, FALSE);
 243
 244   update_start = update_stop = TRUE;
 245
 246   position = segment->position;
 247
 248   /* segment->start is never invalid */
 249   switch (start_type) {
 250     case GST_SEEK_TYPE_NONE:
 251       /* no update to segment, take previous start */
 252       start = segment->start;
 253       update_start = FALSE;
 254       break;
 255     case GST_SEEK_TYPE_SET:
 256       /* start holds desired position, map -1 to the start */
 257       if (start == -1)
 258         start = 0;
 259       break;
 260     case GST_SEEK_TYPE_END:
 261       if (segment->duration != -1) {
 262         /* add start to total length */
 263         start = segment->duration + start;
 264       } else {
 265         /* no update if duration unknown */
 266         start = segment->start;
 267         update_start = FALSE;
 268       }
 269       break;
 270   }
 271   /* bring in sane range */
 272   if (segment->duration != -1)
 273     start = MIN (start, segment->duration);
 274   else
 275     start = MAX ((gint64) start, 0);
 276
 277   /* stop can be -1 if we have not configured a stop. */
 278   switch (stop_type) {
 279     case GST_SEEK_TYPE_NONE:
 280       stop = segment->stop;
 281       update_stop = FALSE;
 282       break;
 283     case GST_SEEK_TYPE_SET:
 284       /* stop holds required value */
 285       break;
 286     case GST_SEEK_TYPE_END:
 287       if (segment->duration != -1) {
 288         stop = segment->duration + stop;
 289       } else {
 290         stop = segment->stop;
 291         update_stop = FALSE;
 292       }
 293       break;
 294   }
 295
 296   /* if we have a valid stop time, make sure it is clipped */
 297   if (stop != -1) {
 298     if (segment->duration != -1)
 299       stop = CLAMP ((gint64) stop, 0, (gint64) segment->duration);
 300     else
 301       stop = MAX ((gint64) stop, 0);
 302   }
 303
 304   /* we can't have stop before start */
 305   if (stop != -1) {
 306     if (start > stop) {
 307       GST_WARNING ("segment update failed: start(%" G_GUINT64_FORMAT
 308           ") > stop(%" G_GUINT64_FORMAT ")", start, stop);
 309       g_return_val_if_fail (start <= stop, FALSE);
 310       return FALSE;
 311     }
 312   }
 313
 314   if (flags & GST_SEEK_FLAG_FLUSH) {
 315     /* flush resets the running_time */
 316     base = 0;
 317   } else {
 318     /* make sure the position is inside the segment start/stop */
 319     position = CLAMP (position, segment->start, segment->stop);
 320
 321     /* remember the elapsed time */
 322     base = gst_segment_to_running_time (segment, format, position);
 323     GST_DEBUG ("updated segment.base: %" G_GUINT64_FORMAT, base);
 324   }
 325
 326   if (update_start && rate > 0.0) {
 327     position = start;
 328   }
 329   if (update_stop && rate < 0.0) {
 330     if (stop != -1)
 331       position = stop;
 332     else {
 333       if (segment->duration != -1)
 334         position = segment->duration;
 335       else
 336         position = 0;
 337     }
 338   }
 339
 340   /* set update arg to reflect update of position */
 341   if (update)
 342     *update = position != segment->position;
 343
 344   /* update new values */
 345   /* be explicit about our GstSeekFlag -> GstSegmentFlag conversion */
 346   segment->flags = GST_SEGMENT_FLAG_NONE;
 347   if ((flags & GST_SEEK_FLAG_FLUSH) != 0)
 348     segment->flags |= GST_SEGMENT_FLAG_RESET;
 349   if ((flags & GST_SEEK_FLAG_TRICKMODE) != 0)
 350     segment->flags |= GST_SEGMENT_FLAG_TRICKMODE;
 351   if ((flags & GST_SEEK_FLAG_SEGMENT) != 0)
 352     segment->flags |= GST_SEGMENT_FLAG_SEGMENT;
 353   if ((flags & GST_SEEK_FLAG_TRICKMODE_KEY_UNITS) != 0)
 354     segment->flags |= GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS;
 355   if ((flags & GST_SEEK_FLAG_TRICKMODE_NO_AUDIO) != 0)
 356     segment->flags |= GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO;
 357
 358   segment->rate = rate;
 359   segment->applied_rate = 1.0;
 360
 361   segment->base = base;
 362   if (rate > 0.0)
 363     segment->offset = position - start;
 364   else {
 365     if (stop != -1)
 366       segment->offset = stop - position;
 367     else if (segment->duration != -1)
 368       segment->offset = segment->duration - position;
 369     else
 370       segment->offset = 0;
 371   }
 372
 373   segment->start = start;
 374   segment->stop = stop;
 375   segment->time = start;
 376   segment->position = position;
 377
 378   GST_INFO ("segment updated: %" GST_SEGMENT_FORMAT, segment);
 379
 380   return TRUE;
 381 }
 382
 383 /**
 384  * gst_segment_to_stream_time_full:
 385  * @segment: a #GstSegment structure.
 386  * @format: the format of the segment.
 387  * @position: the position in the segment
 388  * @stream_time: (out): result stream-time
 389  *
 390  * Translate @position to the total stream time using the currently configured
 391  * segment. Compared to gst_segment_to_stream_time() this function can return
 392  * negative stream-time.
 393  *
 394  * This function is typically used by elements that need to synchronize buffers
 395  * against the clock or each other.
 396  *
 397  * @position can be any value and the result of this function for values outside
 398  * of the segment is extrapolated.
 399  *
 400  * When 1 is returned, @position resulted in a positive stream-time returned
 401  * in @stream_time.
 402  *
 403  * When this function returns -1, the returned @stream_time should be negated
 404  * to get the real negative stream time.
 405  *
 406  * Returns: a 1 or -1 on success, 0 on failure.
 407  *
 408  * Since: 1.8
 409  */
 410 gint
 411 gst_segment_to_stream_time_full (const GstSegment * segment, GstFormat format,
 412     guint64 position, guint64 * stream_time)
 413 {
 414   guint64 start, stop, time;
 415   gdouble abs_applied_rate;
 416   gint res;
 417
 418   /* format does not matter for -1 */
 419   if (G_UNLIKELY (position == -1)) {
 420     *stream_time = -1;
 421     return 0;
 422   }
 423
 424   g_return_val_if_fail (segment != NULL, 0);
 425   g_return_val_if_fail (segment->format == format, 0);
 426
 427   stop = segment->stop;
 428
 429   start = segment->start;
 430   time = segment->time;
 431
 432   /* time must be known */
 433   if (G_UNLIKELY (time == -1))
 434     return 0;
 435
 436   abs_applied_rate = ABS (segment->applied_rate);
 437
 438   /* add or subtract from segment time based on applied rate */
 439   if (G_LIKELY (segment->applied_rate > 0.0)) {
 440     if (G_LIKELY (position > start)) {
 441       /* bring to uncorrected position in segment */
 442       *stream_time = position - start;
 443       /* correct for applied rate if needed */
 444       if (G_UNLIKELY (abs_applied_rate != 1.0))
 445         *stream_time *= abs_applied_rate;
 446       /* correct for segment time */
 447       *stream_time += time;
 448       res = 1;
 449     } else {
 450       *stream_time = start - position;
 451       if (G_UNLIKELY (abs_applied_rate != 1.0))
 452         *stream_time *= abs_applied_rate;
 453       if (*stream_time > time) {
 454         *stream_time -= time;
 455         res = -1;
 456       } else {
 457         *stream_time = time - *stream_time;
 458         res = 1;
 459       }
 460     }
 461   } else {
 462     /* correct for segment time. Streams with a negative applied_rate
 463      * have timestamps between start and stop, as usual, but have the
 464      * time member starting high and going backwards.  */
 465     /* cannot continue without a known segment stop */
 466     if (G_UNLIKELY (stop == -1))
 467       return 0;
 468     if (G_UNLIKELY (position > stop)) {
 469       *stream_time = position - stop;
 470       if (G_UNLIKELY (abs_applied_rate != 1.0))
 471         *stream_time *= abs_applied_rate;
 472       if (*stream_time > time) {
 473         *stream_time -= time;
 474         res = -1;
 475       } else {
 476         *stream_time = time - *stream_time;
 477         res = 1;
 478       }
 479     } else {
 480       *stream_time = stop - position;
 481       if (G_UNLIKELY (abs_applied_rate != 1.0))
 482         *stream_time *= abs_applied_rate;
 483       *stream_time += time;
 484       res = 1;
 485     }
 486   }
 487
 488   return res;
 489 }
 490
 491 /**
 492  * gst_segment_to_stream_time:
 493  * @segment: a #GstSegment structure.
 494  * @format: the format of the segment.
 495  * @position: the position in the segment
 496  *
 497  * Translate @position to stream time using the currently configured
 498  * segment. The @position value must be between @segment start and
 499  * stop value.
 500  *
 501  * This function is typically used by elements that need to operate on
 502  * the stream time of the buffers it receives, such as effect plugins.
 503  * In those use cases, @position is typically the buffer timestamp or
 504  * clock time that one wants to convert to the stream time.
 505  * The stream time is always between 0 and the total duration of the
 506  * media stream.
 507  *
 508  * Returns: the position in stream_time or -1 when an invalid position
 509  * was given.
 510  *
 511  * Since: 1.8
 512  */
 513 guint64
 514 gst_segment_to_stream_time (const GstSegment * segment, GstFormat format,
 515     guint64 position)
 516 {
 517   guint64 result;
 518
 519   g_return_val_if_fail (segment != NULL, -1);
 520   g_return_val_if_fail (segment->format == format, -1);
 521
 522   /* before the segment boundary */
 523   if (G_UNLIKELY (position < segment->start)) {
 524     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") < start(%" G_GUINT64_FORMAT
 525         ")", position, segment->start);
 526     return -1;
 527   }
 528   /* after the segment boundary */
 529   if (G_UNLIKELY (segment->stop != -1 && position > segment->stop)) {
 530     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") > stop(%" G_GUINT64_FORMAT
 531         ")", position, segment->stop);
 532     return -1;
 533   }
 534
 535   if (gst_segment_to_stream_time_full (segment, format, position, &result) == 1)
 536     return result;
 537
 538   return -1;
 539 }
 540
 541 /**
 542  * gst_segment_position_from_stream_time_full:
 543  * @segment: a #GstSegment structure.
 544  * @format: the format of the segment.
 545  * @stream_time: the stream-time
 546  * @position: (out): the resulting position in the segment
 547  *
 548  * Translate @stream_time to the segment position using the currently configured
 549  * segment. Compared to gst_segment_position_from_stream_time() this function can
 550  * return negative segment position.
 551  *
 552  * This function is typically used by elements that need to synchronize buffers
 553  * against the clock or each other.
 554  *
 555  * @stream_time can be any value and the result of this function for values outside
 556  * of the segment is extrapolated.
 557  *
 558  * When 1 is returned, @stream_time resulted in a positive position returned
 559  * in @position.
 560  *
 561  * When this function returns -1, the returned @position should be negated
 562  * to get the real negative segment position.
 563  *
 564  * Returns: a 1 or -1 on success, 0 on failure.
 565  *
 566  * Since: 1.8
 567  */
 568 gint
 569 gst_segment_position_from_stream_time_full (const GstSegment * segment,
 570     GstFormat format, guint64 stream_time, guint64 * position)
 571 {
 572   guint64 start, time;
 573   gdouble abs_applied_rate;
 574   gint res;
 575
 576   /* format does not matter for -1 */
 577   if (G_UNLIKELY (stream_time == -1)) {
 578     *position = -1;
 579     return 0;
 580   }
 581
 582   g_return_val_if_fail (segment != NULL, -1);
 583   g_return_val_if_fail (segment->format == format, -1);
 584
 585   start = segment->start;
 586   time = segment->time;
 587
 588   /* time must be known */
 589   if (G_UNLIKELY (time == -1))
 590     return 0;
 591
 592   abs_applied_rate = ABS (segment->applied_rate);
 593
 594   if (G_LIKELY (segment->applied_rate > 0.0)) {
 595     if (G_LIKELY (stream_time > time)) {
 596       res = 1;
 597       *position = stream_time - time;
 598     } else {
 599       res = -1;
 600       *position = time - stream_time;
 601     }
 602     /* correct for applied rate if needed */
 603     if (G_UNLIKELY (abs_applied_rate != 1.0))
 604       *position /= abs_applied_rate;
 605
 606     if (G_UNLIKELY (res == -1)) {
 607       if (*position > start) {
 608         *position -= start;
 609       } else {
 610         *position = start - *position;
 611         res = 1;
 612       }
 613     } else {
 614       *position += start;
 615     }
 616   } else {
 617     GstClockTime stop = segment->stop;
 618     /* cannot continue without a known segment stop */
 619     if (G_UNLIKELY (stop == -1))
 620       return 0;
 621     if (G_UNLIKELY (time > stream_time)) {
 622       res = -1;
 623       *position = time - stream_time;
 624     } else {
 625       res = 1;
 626       *position = stream_time - time;
 627     }
 628     if (G_UNLIKELY (abs_applied_rate != 1.0))
 629       *position /= abs_applied_rate;
 630     if (G_UNLIKELY (stop < *position)) {
 631       if (G_LIKELY (res == 1)) {
 632         *position -= stop;
 633         res = -1;
 634       } else {
 635         *position += stop;
 636         res = 1;
 637       }
 638     } else {
 639       if (G_LIKELY (res == 1)) {
 640         *position = stop - *position;
 641         res = 1;
 642       } else {
 643         *position += stop;
 644         res = 1;
 645       }
 646     }
 647   }
 648
 649   return res;
 650 }
 651
 652 /**
 653  * gst_segment_position_from_stream_time:
 654  * @segment: a #GstSegment structure.
 655  * @format: the format of the segment.
 656  * @stream_time: the stream_time in the segment
 657  *
 658  * Convert @stream_time into a position in the segment so that
 659  * gst_segment_to_stream_time() with that position returns @stream_time.
 660  *
 661  * Returns: the position in the segment for @stream_time. This function returns
 662  * -1 when @stream_time is -1 or when it is not inside @segment.
 663  *
 664  * Since: 1.8
 665  */
 666 guint64
 667 gst_segment_position_from_stream_time (const GstSegment * segment,
 668     GstFormat format, guint64 stream_time)
 669 {
 670   guint64 position;
 671   gint res;
 672
 673   g_return_val_if_fail (segment != NULL, -1);
 674   g_return_val_if_fail (segment->format == format, -1);
 675
 676   res =
 677       gst_segment_position_from_stream_time_full (segment, format, stream_time,
 678       &position);
 679
 680   /* before the segment boundary */
 681   if (G_UNLIKELY (position < segment->start)) {
 682     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") < start(%" G_GUINT64_FORMAT
 683         ")", position, segment->start);
 684     return -1;
 685   }
 686
 687   /* after the segment boundary */
 688   if (G_UNLIKELY (segment->stop != -1 && position > segment->stop)) {
 689     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") > stop(%" G_GUINT64_FORMAT
 690         ")", position, segment->stop);
 691     return -1;
 692   }
 693
 694   if (res == 1)
 695     return position;
 696
 697   return -1;
 698 }
 699
 700 /**
 701  * gst_segment_to_running_time_full:
 702  * @segment: a #GstSegment structure.
 703  * @format: the format of the segment.
 704  * @position: the position in the segment
 705  * @running_time: (out) (allow-none): result running-time
 706  *
 707  * Translate @position to the total running time using the currently configured
 708  * segment. Compared to gst_segment_to_running_time() this function can return
 709  * negative running-time.
 710  *
 711  * This function is typically used by elements that need to synchronize buffers
 712  * against the clock or each other.
 713  *
 714  * @position can be any value and the result of this function for values outside
 715  * of the segment is extrapolated.
 716  *
 717  * When 1 is returned, @position resulted in a positive running-time returned
 718  * in @running_time.
 719  *
 720  * When this function returns -1, the returned @running_time should be negated
 721  * to get the real negative running time.
 722  *
 723  * Returns: a 1 or -1 on success, 0 on failure.
 724  *
 725  * Since: 1.6
 726  */
 727 gint
 728 gst_segment_to_running_time_full (const GstSegment * segment, GstFormat format,
 729     guint64 position, guint64 * running_time)
 730 {
 731   gint res = 0;
 732   guint64 result;
 733   guint64 start, stop, offset;
 734   gdouble abs_rate;
 735
 736   if (G_UNLIKELY (position == -1)) {
 737     GST_DEBUG ("invalid position (-1)");
 738     goto done;
 739   }
 740
 741   g_return_val_if_fail (segment != NULL, 0);
 742   g_return_val_if_fail (segment->format == format, 0);
 743
 744   offset = segment->offset;
 745
 746   if (G_LIKELY (segment->rate > 0.0)) {
 747     start = segment->start + offset;
 748
 749     /* bring to uncorrected position in segment */
 750     if (position < start) {
 751       /* negative value */
 752       result = start - position;
 753       res = -1;
 754     } else {
 755       result = position - start;
 756       res = 1;
 757     }
 758   } else {
 759     stop = segment->stop;
 760
 761     /* cannot continue if no stop position set or invalid offset */
 762     g_return_val_if_fail (stop != -1, 0);
 763     g_return_val_if_fail (stop >= offset, 0);
 764
 765     stop -= offset;
 766
 767     /* bring to uncorrected position in segment */
 768     if (position > stop) {
 769       /* negative value */
 770       result = position - stop;
 771       res = -1;
 772     } else {
 773       result = stop - position;
 774       res = 1;
 775     }
 776   }
 777
 778   if (running_time) {
 779     /* scale based on the rate, avoid division by and conversion to
 780      * float when not needed */
 781     abs_rate = ABS (segment->rate);
 782     if (G_UNLIKELY (abs_rate != 1.0))
 783       result /= abs_rate;
 784
 785     /* correct for base of the segment */
 786     if (res == 1)
 787       /* positive, add base */
 788       *running_time = result + segment->base;
 789     else if (segment->base >= result) {
 790       /* negative and base is bigger, subtract from base and we have a
 791        * positive value again */
 792       *running_time = segment->base - result;
 793       res = 1;
 794     } else {
 795       /* negative and base is smaller, subtract base and remainder is
 796        * negative */
 797       *running_time = result - segment->base;
 798     }
 799   }
 800   return res;
 801
 802 done:
 803   {
 804     if (running_time)
 805       *running_time = -1;
 806     return 0;
 807   }
 808 }
 809
 810 /**
 811  * gst_segment_to_running_time:
 812  * @segment: a #GstSegment structure.
 813  * @format: the format of the segment.
 814  * @position: the position in the segment
 815  *
 816  * Translate @position to the total running time using the currently configured
 817  * segment. Position is a value between @segment start and stop time.
 818  *
 819  * This function is typically used by elements that need to synchronize to the
 820  * global clock in a pipeline. The running time is a constantly increasing value
 821  * starting from 0. When gst_segment_init() is called, this value will reset to
 822  * 0.
 823  *
 824  * This function returns -1 if the position is outside of @segment start and stop.
 825  *
 826  * Returns: the position as the total running time or -1 when an invalid position
 827  * was given.
 828  */
 829 guint64
 830 gst_segment_to_running_time (const GstSegment * segment, GstFormat format,
 831     guint64 position)
 832 {
 833   guint64 result;
 834
 835   g_return_val_if_fail (segment != NULL, -1);
 836   g_return_val_if_fail (segment->format == format, -1);
 837
 838   /* before the segment boundary */
 839   if (G_UNLIKELY (position < segment->start)) {
 840     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") < start(%" G_GUINT64_FORMAT
 841         ")", position, segment->start);
 842     return -1;
 843   }
 844   /* after the segment boundary */
 845   if (G_UNLIKELY (segment->stop != -1 && position > segment->stop)) {
 846     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") > stop(%" G_GUINT64_FORMAT
 847         ")", position, segment->stop);
 848     return -1;
 849   }
 850
 851   if (gst_segment_to_running_time_full (segment, format, position,
 852           &result) == 1)
 853     return result;
 854
 855   return -1;
 856 }
 857
 858 /**
 859  * gst_segment_clip:
 860  * @segment: a #GstSegment structure.
 861  * @format: the format of the segment.
 862  * @start: the start position in the segment
 863  * @stop: the stop position in the segment
 864  * @clip_start: (out) (allow-none): the clipped start position in the segment
 865  * @clip_stop: (out) (allow-none): the clipped stop position in the segment
 866  *
 867  * Clip the given @start and @stop values to the segment boundaries given
 868  * in @segment. @start and @stop are compared and clipped to @segment
 869  * start and stop values.
 870  *
 871  * If the function returns %FALSE, @start and @stop are known to fall
 872  * outside of @segment and @clip_start and @clip_stop are not updated.
 873  *
 874  * When the function returns %TRUE, @clip_start and @clip_stop will be
 875  * updated. If @clip_start or @clip_stop are different from @start or @stop
 876  * respectively, the region fell partially in the segment.
 877  *
 878  * Note that when @stop is -1, @clip_stop will be set to the end of the
 879  * segment. Depending on the use case, this may or may not be what you want.
 880  *
 881  * Returns: %TRUE if the given @start and @stop times fall partially or
 882  *     completely in @segment, %FALSE if the values are completely outside
 883  *     of the segment.
 884  */
 885 gboolean
 886 gst_segment_clip (const GstSegment * segment, GstFormat format, guint64 start,
 887     guint64 stop, guint64 * clip_start, guint64 * clip_stop)
 888 {
 889   g_return_val_if_fail (segment != NULL, FALSE);
 890   g_return_val_if_fail (segment->format == format, FALSE);
 891
 892   /* if we have a stop position and a valid start and start is bigger,
 893    * we're outside of the segment. (Special case) segment start and
 894    * segment stop can be identical. In this case, if start is also identical,
 895    * it's inside of segment */
 896   if (G_UNLIKELY (segment->stop != -1 && start != -1 && (start > segment->stop
 897               || (segment->start != segment->stop && start == segment->stop))))
 898     return FALSE;
 899
 900   /* if a stop position is given and is before the segment start,
 901    * we're outside of the segment. Special case is were start
 902    * and stop are equal to the segment start. In that case we
 903    * are inside the segment. */
 904   if (G_UNLIKELY (stop != -1 && (stop < segment->start || (start != stop
 905                   && stop == segment->start))))
 906     return FALSE;
 907
 908   if (clip_start) {
 909     if (start == -1)
 910       *clip_start = -1;
 911     else
 912       *clip_start = MAX (start, segment->start);
 913   }
 914
 915   if (clip_stop) {
 916     if (stop == -1)
 917       *clip_stop = segment->stop;
 918     else if (segment->stop == -1)
 919       *clip_stop = stop;
 920     else
 921       *clip_stop = MIN (stop, segment->stop);
 922   }
 923
 924   return TRUE;
 925 }
 926
 927 /**
 928  * gst_segment_position_from_running_time:
 929  * @segment: a #GstSegment structure.
 930  * @format: the format of the segment.
 931  * @running_time: the running_time in the segment
 932  *
 933  * Convert @running_time into a position in the segment so that
 934  * gst_segment_to_running_time() with that position returns @running_time.
 935  *
 936  * Returns: the position in the segment for @running_time. This function returns
 937  * -1 when @running_time is -1 or when it is not inside @segment.
 938  *
 939  * Since: 1.8
 940  */
 941 guint64
 942 gst_segment_position_from_running_time (const GstSegment * segment,
 943     GstFormat format, guint64 running_time)
 944 {
 945   guint64 position;
 946   gint res;
 947
 948   g_return_val_if_fail (segment != NULL, -1);
 949   g_return_val_if_fail (segment->format == format, -1);
 950
 951   res =
 952       gst_segment_position_from_running_time_full (segment, format,
 953       running_time, &position);
 954
 955   if (res != 1)
 956     return -1;
 957
 958   /* before the segment boundary */
 959   if (G_UNLIKELY (position < segment->start)) {
 960     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") < start(%" G_GUINT64_FORMAT
 961         ")", position, segment->start);
 962     return -1;
 963   }
 964
 965   /* after the segment boundary */
 966   if (G_UNLIKELY (segment->stop != -1 && position > segment->stop)) {
 967     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") > stop(%" G_GUINT64_FORMAT
 968         ")", position, segment->stop);
 969     return -1;
 970   }
 971
 972   return position;
 973 }
 974
 975 /**
 976  * gst_segment_position_from_running_time_full:
 977  * @segment: a #GstSegment structure.
 978  * @format: the format of the segment.
 979  * @running_time: the running-time
 980  * @position: (out): the resulting position in the segment
 981  *
 982  * Translate @running_time to the segment position using the currently configured
 983  * segment. Compared to gst_segment_position_from_running_time() this function can
 984  * return negative segment position.
 985  *
 986  * This function is typically used by elements that need to synchronize buffers
 987  * against the clock or each other.
 988  *
 989  * @running_time can be any value and the result of this function for values
 990  * outside of the segment is extrapolated.
 991  *
 992  * When 1 is returned, @running_time resulted in a positive position returned
 993  * in @position.
 994  *
 995  * When this function returns -1, the returned @position was < 0, and the value
 996  * in the position variable should be negated to get the real negative segment
 997  * position.
 998  *
 999  * Returns: a 1 or -1 on success, 0 on failure.
1000  *
1001  * Since: 1.8
1002  */
1003 gint
1004 gst_segment_position_from_running_time_full (const GstSegment * segment,
1005     GstFormat format, guint64 running_time, guint64 * position)
1006 {
1007   gint res;
1008   guint64 start, stop, base;
1009   gdouble abs_rate;
1010
1011   if (G_UNLIKELY (running_time == -1)) {
1012     *position = -1;
1013     return 0;
1014   }
1015
1016   g_return_val_if_fail (segment != NULL, 0);
1017   g_return_val_if_fail (segment->format == format, 0);
1018
1019   base = segment->base;
1020
1021   abs_rate = ABS (segment->rate);
1022
1023   start = segment->start;
1024   stop = segment->stop;
1025
1026   if (G_LIKELY (segment->rate > 0.0)) {
1027     /* start by subtracting the base time */
1028     if (G_LIKELY (running_time >= base)) {
1029       *position = running_time - base;
1030       /* move into the segment at the right rate */
1031       if (G_UNLIKELY (abs_rate != 1.0))
1032         *position = ceil (*position * abs_rate);
1033       /* bring to corrected position in segment */
1034       *position += start + segment->offset;
1035       res = 1;
1036     } else {
1037       *position = base - running_time;
1038       if (G_UNLIKELY (abs_rate != 1.0))
1039         *position = ceil (*position * abs_rate);
1040       if (start + segment->offset >= *position) {
1041         /* The TS is before the segment, but the result is >= 0 */
1042         *position = start + segment->offset - *position;
1043         res = 1;
1044       } else {
1045         /* The TS is before the segment, and the result is < 0
1046          * so negate the return result */
1047         *position = *position - (start + segment->offset);
1048         res = -1;
1049       }
1050     }
1051   } else {
1052     if (G_LIKELY (running_time >= base)) {
1053       *position = running_time - base;
1054       if (G_UNLIKELY (abs_rate != 1.0))
1055         *position = ceil (*position * abs_rate);
1056       if (G_UNLIKELY (stop < *position + segment->offset)) {
1057         *position += segment->offset - stop;
1058         res = -1;
1059       } else {
1060         *position = stop - *position - segment->offset;
1061         res = 1;
1062       }
1063     } else {
1064       /* This case is tricky. Requested running time precedes the
1065        * segment base, so in a reversed segment where rate < 0, that
1066        * means it's before the alignment point of (stop - offset).
1067        * Before = always bigger than (stop-offset), which is usually +ve,
1068        * but could be -ve is offset is big enough. -ve position implies
1069        * that the offset has clipped away the entire segment anyway */
1070       *position = base - running_time;
1071       if (G_UNLIKELY (abs_rate != 1.0))
1072         *position = ceil (*position * abs_rate);
1073
1074       if (G_LIKELY (stop + *position >= segment->offset)) {
1075         *position = stop + *position - segment->offset;
1076         res = 1;
1077       } else {
1078         /* Requested position is still negative because offset is big,
1079          * so negate the result */
1080         *position = segment->offset - *position - stop;
1081         res = -1;
1082       }
1083     }
1084   }
1085   return res;
1086 }
1087
1088 /**
1089  * gst_segment_to_position:
1090  * @segment: a #GstSegment structure.
1091  * @format: the format of the segment.
1092  * @running_time: the running_time in the segment
1093  *
1094  * Convert @running_time into a position in the segment so that
1095  * gst_segment_to_running_time() with that position returns @running_time.
1096  *
1097  * Returns: the position in the segment for @running_time. This function returns
1098  * -1 when @running_time is -1 or when it is not inside @segment.
1099  *
1100  * Deprecated: Use gst_segment_position_from_running_time() instead.
1101  */
1102 #ifndef GST_REMOVE_DEPRECATED
1103 guint64
1104 gst_segment_to_position (const GstSegment * segment, GstFormat format,
1105     guint64 running_time)
1106 {
1107   return gst_segment_position_from_running_time (segment, format, running_time);
1108 }
1109 #endif
1110
1111 /**
1112  * gst_segment_set_running_time:
1113  * @segment: a #GstSegment structure.
1114  * @format: the format of the segment.
1115  * @running_time: the running_time in the segment
1116  *
1117  * Adjust the start/stop and base values of @segment such that the next valid
1118  * buffer will be one with @running_time.
1119  *
1120  * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
1121  * returned, @running_time is -1 or not in @segment.
1122  */
1123 gboolean
1124 gst_segment_set_running_time (GstSegment * segment, GstFormat format,
1125     guint64 running_time)
1126 {
1127   guint64 position;
1128   guint64 start, stop;
1129
1130   /* start by bringing the running_time into the segment position */
1131   position =
1132       gst_segment_position_from_running_time (segment, format, running_time);
1133
1134   /* we must have a valid position now */
1135   if (G_UNLIKELY (position == -1))
1136     return FALSE;
1137
1138   start = segment->start;
1139   stop = segment->stop;
1140
1141   if (G_LIKELY (segment->rate > 0.0)) {
1142     /* update the start and time values */
1143     start = position;
1144   } else {
1145     /* reverse, update stop */
1146     stop = position;
1147   }
1148   /* and base time is exactly the running time */
1149   segment->time = gst_segment_to_stream_time (segment, format, start);
1150   segment->start = start;
1151   segment->stop = stop;
1152   segment->base = running_time;
1153
1154   return TRUE;
1155 }
1156
1157 /**
1158  * gst_segment_offset_running_time:
1159  * @segment: a #GstSegment structure.
1160  * @format: the format of the segment.
1161  * @offset: the offset to apply in the segment
1162  *
1163  * Adjust the values in @segment so that @offset is applied to all
1164  * future running-time calculations.
1165  *
1166  * Since: 1.2.3
1167  *
1168  * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
1169  * returned, @offset is not in @segment.
1170  */
1171 gboolean
1172 gst_segment_offset_running_time (GstSegment * segment, GstFormat format,
1173     gint64 offset)
1174 {
1175   g_return_val_if_fail (segment != NULL, FALSE);
1176   g_return_val_if_fail (segment->format == format, FALSE);
1177
1178   if (offset == 0)
1179     return TRUE;
1180
1181   if (offset > 0) {
1182     /* positive offset, we can simply apply to the base time */
1183     segment->base += offset;
1184   } else {
1185     offset = -offset;
1186     /* negative offset, first try to subtract from base */
1187     if (segment->base > offset) {
1188       segment->base -= offset;
1189     } else {
1190       guint64 position;
1191
1192       /* subtract all from segment.base, remainder in offset */
1193       offset -= segment->base;
1194       segment->base = 0;
1195       position =
1196           gst_segment_position_from_running_time (segment, format, offset);
1197       if (position == -1)
1198         return FALSE;
1199
1200       segment->offset = position - segment->start;
1201     }
1202   }
1203   return TRUE;
1204 }
1205
1206 /**
1207  * gst_segment_is_equal:
1208  * @s0: a #GstSegment structure.
1209  * @s1: a #GstSegment structure.
1210  *
1211  * Checks for two segments being equal. Equality here is defined
1212  * as perfect equality, including floating point values.
1213  *
1214  * Since: 1.6
1215  *
1216  * Returns: %TRUE if the segments are equal, %FALSE otherwise.
1217  */
1218 gboolean
1219 gst_segment_is_equal (const GstSegment * s0, const GstSegment * s1)
1220 {
1221   if (s0->flags != s1->flags)
1222     return FALSE;
1223   if (s0->rate != s1->rate)
1224     return FALSE;
1225   if (s0->applied_rate != s1->applied_rate)
1226     return FALSE;
1227   if (s0->format != s1->format)
1228     return FALSE;
1229   if (s0->base != s1->base)
1230     return FALSE;
1231   if (s0->offset != s1->offset)
1232     return FALSE;
1233   if (s0->start != s1->start)
1234     return FALSE;
1235   if (s0->stop != s1->stop)
1236     return FALSE;
1237   if (s0->time != s1->time)
1238     return FALSE;
1239   if (s0->position != s1->position)
1240     return FALSE;
1241   if (s0->duration != s1->duration)
1242     return FALSE;
1243   return TRUE;
1244 }