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     if (stop == -1 && segment->duration != -1)
 762       stop = segment->start + segment->duration;
 763
 764     /* cannot continue if no stop position set or invalid offset */
 765     g_return_val_if_fail (stop != -1, 0);
 766     g_return_val_if_fail (stop >= offset, 0);
 767
 768     stop -= offset;
 769
 770     /* bring to uncorrected position in segment */
 771     if (position > stop) {
 772       /* negative value */
 773       result = position - stop;
 774       res = -1;
 775     } else {
 776       result = stop - position;
 777       res = 1;
 778     }
 779   }
 780
 781   if (running_time) {
 782     /* scale based on the rate, avoid division by and conversion to
 783      * float when not needed */
 784     abs_rate = ABS (segment->rate);
 785     if (G_UNLIKELY (abs_rate != 1.0))
 786       result /= abs_rate;
 787
 788     /* correct for base of the segment */
 789     if (res == 1)
 790       /* positive, add base */
 791       *running_time = result + segment->base;
 792     else if (segment->base >= result) {
 793       /* negative and base is bigger, subtract from base and we have a
 794        * positive value again */
 795       *running_time = segment->base - result;
 796       res = 1;
 797     } else {
 798       /* negative and base is smaller, subtract base and remainder is
 799        * negative */
 800       *running_time = result - segment->base;
 801     }
 802   }
 803   return res;
 804
 805 done:
 806   {
 807     if (running_time)
 808       *running_time = -1;
 809     return 0;
 810   }
 811 }
 812
 813 /**
 814  * gst_segment_to_running_time:
 815  * @segment: a #GstSegment structure.
 816  * @format: the format of the segment.
 817  * @position: the position in the segment
 818  *
 819  * Translate @position to the total running time using the currently configured
 820  * segment. Position is a value between @segment start and stop time.
 821  *
 822  * This function is typically used by elements that need to synchronize to the
 823  * global clock in a pipeline. The running time is a constantly increasing value
 824  * starting from 0. When gst_segment_init() is called, this value will reset to
 825  * 0.
 826  *
 827  * This function returns -1 if the position is outside of @segment start and stop.
 828  *
 829  * Returns: the position as the total running time or -1 when an invalid position
 830  * was given.
 831  */
 832 guint64
 833 gst_segment_to_running_time (const GstSegment * segment, GstFormat format,
 834     guint64 position)
 835 {
 836   guint64 result;
 837
 838   g_return_val_if_fail (segment != NULL, -1);
 839   g_return_val_if_fail (segment->format == format, -1);
 840
 841   /* before the segment boundary */
 842   if (G_UNLIKELY (position < segment->start)) {
 843     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") < start(%" G_GUINT64_FORMAT
 844         ")", position, segment->start);
 845     return -1;
 846   }
 847   /* after the segment boundary */
 848   if (G_UNLIKELY (segment->stop != -1 && position > segment->stop)) {
 849     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") > stop(%" G_GUINT64_FORMAT
 850         ")", position, segment->stop);
 851     return -1;
 852   }
 853
 854   if (gst_segment_to_running_time_full (segment, format, position,
 855           &result) == 1)
 856     return result;
 857
 858   return -1;
 859 }
 860
 861 /**
 862  * gst_segment_clip:
 863  * @segment: a #GstSegment structure.
 864  * @format: the format of the segment.
 865  * @start: the start position in the segment
 866  * @stop: the stop position in the segment
 867  * @clip_start: (out) (allow-none): the clipped start position in the segment
 868  * @clip_stop: (out) (allow-none): the clipped stop position in the segment
 869  *
 870  * Clip the given @start and @stop values to the segment boundaries given
 871  * in @segment. @start and @stop are compared and clipped to @segment
 872  * start and stop values.
 873  *
 874  * If the function returns %FALSE, @start and @stop are known to fall
 875  * outside of @segment and @clip_start and @clip_stop are not updated.
 876  *
 877  * When the function returns %TRUE, @clip_start and @clip_stop will be
 878  * updated. If @clip_start or @clip_stop are different from @start or @stop
 879  * respectively, the region fell partially in the segment.
 880  *
 881  * Note that when @stop is -1, @clip_stop will be set to the end of the
 882  * segment. Depending on the use case, this may or may not be what you want.
 883  *
 884  * Returns: %TRUE if the given @start and @stop times fall partially or
 885  *     completely in @segment, %FALSE if the values are completely outside
 886  *     of the segment.
 887  */
 888 gboolean
 889 gst_segment_clip (const GstSegment * segment, GstFormat format, guint64 start,
 890     guint64 stop, guint64 * clip_start, guint64 * clip_stop)
 891 {
 892   g_return_val_if_fail (segment != NULL, FALSE);
 893   g_return_val_if_fail (segment->format == format, FALSE);
 894
 895   /* if we have a stop position and a valid start and start is bigger,
 896    * we're outside of the segment. (Special case) segment start and
 897    * segment stop can be identical. In this case, if start is also identical,
 898    * it's inside of segment */
 899   if (G_UNLIKELY (segment->stop != -1 && start != -1 && (start > segment->stop
 900               || (segment->start != segment->stop && start == segment->stop))))
 901     return FALSE;
 902
 903   /* if a stop position is given and is before the segment start,
 904    * we're outside of the segment. Special case is were start
 905    * and stop are equal to the segment start. In that case we
 906    * are inside the segment. */
 907   if (G_UNLIKELY (stop != -1 && (stop < segment->start || (start != stop
 908                   && stop == segment->start))))
 909     return FALSE;
 910
 911   if (clip_start) {
 912     if (start == -1)
 913       *clip_start = -1;
 914     else
 915       *clip_start = MAX (start, segment->start);
 916   }
 917
 918   if (clip_stop) {
 919     if (stop == -1)
 920       *clip_stop = segment->stop;
 921     else if (segment->stop == -1)
 922       *clip_stop = stop;
 923     else
 924       *clip_stop = MIN (stop, segment->stop);
 925   }
 926
 927   return TRUE;
 928 }
 929
 930 /**
 931  * gst_segment_position_from_running_time:
 932  * @segment: a #GstSegment structure.
 933  * @format: the format of the segment.
 934  * @running_time: the running_time in the segment
 935  *
 936  * Convert @running_time into a position in the segment so that
 937  * gst_segment_to_running_time() with that position returns @running_time.
 938  *
 939  * Returns: the position in the segment for @running_time. This function returns
 940  * -1 when @running_time is -1 or when it is not inside @segment.
 941  *
 942  * Since: 1.8
 943  */
 944 guint64
 945 gst_segment_position_from_running_time (const GstSegment * segment,
 946     GstFormat format, guint64 running_time)
 947 {
 948   guint64 position;
 949   gint res;
 950
 951   g_return_val_if_fail (segment != NULL, -1);
 952   g_return_val_if_fail (segment->format == format, -1);
 953
 954   res =
 955       gst_segment_position_from_running_time_full (segment, format,
 956       running_time, &position);
 957
 958   if (res != 1)
 959     return -1;
 960
 961   /* before the segment boundary */
 962   if (G_UNLIKELY (position < segment->start)) {
 963     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") < start(%" G_GUINT64_FORMAT
 964         ")", position, segment->start);
 965     return -1;
 966   }
 967
 968   /* after the segment boundary */
 969   if (G_UNLIKELY (segment->stop != -1 && position > segment->stop)) {
 970     GST_DEBUG ("position(%" G_GUINT64_FORMAT ") > stop(%" G_GUINT64_FORMAT
 971         ")", position, segment->stop);
 972     return -1;
 973   }
 974
 975   return position;
 976 }
 977
 978 /**
 979  * gst_segment_position_from_running_time_full:
 980  * @segment: a #GstSegment structure.
 981  * @format: the format of the segment.
 982  * @running_time: the running-time
 983  * @position: (out): the resulting position in the segment
 984  *
 985  * Translate @running_time to the segment position using the currently configured
 986  * segment. Compared to gst_segment_position_from_running_time() this function can
 987  * return negative segment position.
 988  *
 989  * This function is typically used by elements that need to synchronize buffers
 990  * against the clock or each other.
 991  *
 992  * @running_time can be any value and the result of this function for values
 993  * outside of the segment is extrapolated.
 994  *
 995  * When 1 is returned, @running_time resulted in a positive position returned
 996  * in @position.
 997  *
 998  * When this function returns -1, the returned @position was < 0, and the value
 999  * in the position variable should be negated to get the real negative segment
1000  * position.
1001  *
1002  * Returns: a 1 or -1 on success, 0 on failure.
1003  *
1004  * Since: 1.8
1005  */
1006 gint
1007 gst_segment_position_from_running_time_full (const GstSegment * segment,
1008     GstFormat format, guint64 running_time, guint64 * position)
1009 {
1010   gint res;
1011   guint64 start, stop, base;
1012   gdouble abs_rate;
1013
1014   if (G_UNLIKELY (running_time == -1)) {
1015     *position = -1;
1016     return 0;
1017   }
1018
1019   g_return_val_if_fail (segment != NULL, 0);
1020   g_return_val_if_fail (segment->format == format, 0);
1021
1022   base = segment->base;
1023
1024   abs_rate = ABS (segment->rate);
1025
1026   start = segment->start;
1027   stop = segment->stop;
1028
1029   if (G_LIKELY (segment->rate > 0.0)) {
1030     /* start by subtracting the base time */
1031     if (G_LIKELY (running_time >= base)) {
1032       *position = running_time - base;
1033       /* move into the segment at the right rate */
1034       if (G_UNLIKELY (abs_rate != 1.0))
1035         *position = ceil (*position * abs_rate);
1036       /* bring to corrected position in segment */
1037       *position += start + segment->offset;
1038       res = 1;
1039     } else {
1040       *position = base - running_time;
1041       if (G_UNLIKELY (abs_rate != 1.0))
1042         *position = ceil (*position * abs_rate);
1043       if (start + segment->offset >= *position) {
1044         /* The TS is before the segment, but the result is >= 0 */
1045         *position = start + segment->offset - *position;
1046         res = 1;
1047       } else {
1048         /* The TS is before the segment, and the result is < 0
1049          * so negate the return result */
1050         *position = *position - (start + segment->offset);
1051         res = -1;
1052       }
1053     }
1054   } else {
1055     if (G_LIKELY (running_time >= base)) {
1056       *position = running_time - base;
1057       if (G_UNLIKELY (abs_rate != 1.0))
1058         *position = ceil (*position * abs_rate);
1059       if (G_UNLIKELY (stop < *position + segment->offset)) {
1060         *position += segment->offset - stop;
1061         res = -1;
1062       } else {
1063         *position = stop - *position - segment->offset;
1064         res = 1;
1065       }
1066     } else {
1067       /* This case is tricky. Requested running time precedes the
1068        * segment base, so in a reversed segment where rate < 0, that
1069        * means it's before the alignment point of (stop - offset).
1070        * Before = always bigger than (stop-offset), which is usually +ve,
1071        * but could be -ve is offset is big enough. -ve position implies
1072        * that the offset has clipped away the entire segment anyway */
1073       *position = base - running_time;
1074       if (G_UNLIKELY (abs_rate != 1.0))
1075         *position = ceil (*position * abs_rate);
1076
1077       if (G_LIKELY (stop + *position >= segment->offset)) {
1078         *position = stop + *position - segment->offset;
1079         res = 1;
1080       } else {
1081         /* Requested position is still negative because offset is big,
1082          * so negate the result */
1083         *position = segment->offset - *position - stop;
1084         res = -1;
1085       }
1086     }
1087   }
1088   return res;
1089 }
1090
1091 /**
1092  * gst_segment_to_position:
1093  * @segment: a #GstSegment structure.
1094  * @format: the format of the segment.
1095  * @running_time: the running_time in the segment
1096  *
1097  * Convert @running_time into a position in the segment so that
1098  * gst_segment_to_running_time() with that position returns @running_time.
1099  *
1100  * Returns: the position in the segment for @running_time. This function returns
1101  * -1 when @running_time is -1 or when it is not inside @segment.
1102  *
1103  * Deprecated: Use gst_segment_position_from_running_time() instead.
1104  */
1105 #ifndef GST_REMOVE_DEPRECATED
1106 guint64
1107 gst_segment_to_position (const GstSegment * segment, GstFormat format,
1108     guint64 running_time)
1109 {
1110   return gst_segment_position_from_running_time (segment, format, running_time);
1111 }
1112 #endif
1113
1114 /**
1115  * gst_segment_set_running_time:
1116  * @segment: a #GstSegment structure.
1117  * @format: the format of the segment.
1118  * @running_time: the running_time in the segment
1119  *
1120  * Adjust the start/stop and base values of @segment such that the next valid
1121  * buffer will be one with @running_time.
1122  *
1123  * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
1124  * returned, @running_time is -1 or not in @segment.
1125  */
1126 gboolean
1127 gst_segment_set_running_time (GstSegment * segment, GstFormat format,
1128     guint64 running_time)
1129 {
1130   guint64 position;
1131   guint64 start, stop;
1132
1133   /* start by bringing the running_time into the segment position */
1134   position =
1135       gst_segment_position_from_running_time (segment, format, running_time);
1136
1137   /* we must have a valid position now */
1138   if (G_UNLIKELY (position == -1))
1139     return FALSE;
1140
1141   start = segment->start;
1142   stop = segment->stop;
1143
1144   if (G_LIKELY (segment->rate > 0.0)) {
1145     /* update the start and time values */
1146     start = position;
1147   } else {
1148     /* reverse, update stop */
1149     stop = position;
1150   }
1151   /* and base time is exactly the running time */
1152   segment->time = gst_segment_to_stream_time (segment, format, start);
1153   segment->start = start;
1154   segment->stop = stop;
1155   segment->base = running_time;
1156
1157   return TRUE;
1158 }
1159
1160 /**
1161  * gst_segment_offset_running_time:
1162  * @segment: a #GstSegment structure.
1163  * @format: the format of the segment.
1164  * @offset: the offset to apply in the segment
1165  *
1166  * Adjust the values in @segment so that @offset is applied to all
1167  * future running-time calculations.
1168  *
1169  * Since: 1.2.3
1170  *
1171  * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
1172  * returned, @offset is not in @segment.
1173  */
1174 gboolean
1175 gst_segment_offset_running_time (GstSegment * segment, GstFormat format,
1176     gint64 offset)
1177 {
1178   g_return_val_if_fail (segment != NULL, FALSE);
1179   g_return_val_if_fail (segment->format == format, FALSE);
1180
1181   if (offset == 0)
1182     return TRUE;
1183
1184   if (offset > 0) {
1185     /* positive offset, we can simply apply to the base time */
1186     segment->base += offset;
1187   } else {
1188     offset = -offset;
1189     /* negative offset, first try to subtract from base */
1190     if (segment->base > offset) {
1191       segment->base -= offset;
1192     } else {
1193       guint64 position;
1194
1195       /* subtract all from segment.base, remainder in offset */
1196       offset -= segment->base;
1197       segment->base = 0;
1198       position =
1199           gst_segment_position_from_running_time (segment, format, offset);
1200       if (position == -1)
1201         return FALSE;
1202
1203       segment->offset = position - segment->start;
1204     }
1205   }
1206   return TRUE;
1207 }
1208
1209 /**
1210  * gst_segment_is_equal:
1211  * @s0: a #GstSegment structure.
1212  * @s1: a #GstSegment structure.
1213  *
1214  * Checks for two segments being equal. Equality here is defined
1215  * as perfect equality, including floating point values.
1216  *
1217  * Since: 1.6
1218  *
1219  * Returns: %TRUE if the segments are equal, %FALSE otherwise.
1220  */
1221 gboolean
1222 gst_segment_is_equal (const GstSegment * s0, const GstSegment * s1)
1223 {
1224   if (s0->flags != s1->flags)
1225     return FALSE;
1226   if (s0->rate != s1->rate)
1227     return FALSE;
1228   if (s0->applied_rate != s1->applied_rate)
1229     return FALSE;
1230   if (s0->format != s1->format)
1231     return FALSE;
1232   if (s0->base != s1->base)
1233     return FALSE;
1234   if (s0->offset != s1->offset)
1235     return FALSE;
1236   if (s0->start != s1->start)
1237     return FALSE;
1238   if (s0->stop != s1->stop)
1239     return FALSE;
1240   if (s0->time != s1->time)
1241     return FALSE;
1242   if (s0->position != s1->position)
1243     return FALSE;
1244   if (s0->duration != s1->duration)
1245     return FALSE;
1246   return TRUE;
1247 }