gstsegment.c 23.5 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
/* GStreamer
 * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
 *
 * gstsegment.c: GstSegment subsystem
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */


#include "gst_private.h"

#include "gstutils.h"
#include "gstsegment.h"

/**
 * SECTION:gstsegment
 * @short_description: Structure describing the configured region of interest
 *                     in a media file.
 * @see_also: #GstEvent
 *
 * This helper structure holds the relevant values for tracking the region of
35
 * interest in a media file, called a segment. 
36
 *
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 * The structure can be used for two purposes:
 * <itemizedlist>
 *   <listitem><para>performing seeks (handling seek events)</para></listitem>
 *   <listitem><para>tracking playback regions (handling newsegment events)</para></listitem>
 * </itemizedlist>
 *
 * The segment is usually configured by the application with a seek event which 
 * is propagated upstream and eventually handled by an element that performs the seek.
 *
 * The configured segment is then propagated back downstream with a newsegment event.
 * This information is then used to clip media to the segment boundaries.
 *
 * A segment structure is initialized with gst_segment_init(), which takes a #GstFormat
 * that will be used as the format of the segment values. The segment will be configured
 * 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
55
 *
 * If the segment is used for managing seeks, the segment duration should be set with
 * gst_segment_set_duration(). The public duration field contains the duration of the
56
57
58
 * segment. When using the segment for seeking, the start and time members should 
 * normally be left to their default 0 value. The stop position is left to -1 unless
 * explicitly configured to a different value after a seek event.
59
60
61
62
63
64
 *
 * The current position in the segment should be set with the gst_segment_set_last_stop().
 * The public last_stop field contains the last set stop position in the segment.
 *
 * For elements that perform seeks, the current segment should be updated with the
 * 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
 *
Wim Taymans's avatar
Wim Taymans committed
69
 * For elements that want to use #GstSegment to track the playback region, use
70
71
72
73
74
75
 * gst_segment_set_newsegment() to update the segment fields with the information from
 * the newsegment event. The gst_segment_clip() method can be used to check and clip
 * the media data to the segment boundaries.
 *
 * For elements that want to synchronize to the pipeline clock, gst_segment_to_running_time()
 * can be used to convert a timestamp to a value that can be used to synchronize
76
77
 * to the clock. This function takes into account all accumulated segments as well as
 * any rate or applied_rate conversions.
78
79
80
81
82
 *
 * For elements that need to perform operations on media data in stream_time, 
 * gst_segment_to_stream_time() can be used to convert a timestamp and the segment
 * info to stream time (which is always between 0 and the duration of the stream).
 *
83
 * Last reviewed on 2007-05-17 (0.10.13)
84
85
 */

86
87
88
89
/**
 * gst_segment_copy:
 * @segment: a #GstSegment
 *
90
91
92
 * Create a copy of given @segment.
 *
 * Returns: a new #GstSegment, free with gst_segment_free().
93
94
95
96
 *
 * Since: 0.10.20
 */
GstSegment *
97
98
99
100
101
gst_segment_copy (GstSegment * segment)
{
  GstSegment *result = NULL;

  if (segment) {
102
    result = (GstSegment *) g_slice_copy (sizeof (GstSegment), segment);
103
  }
104
  return result;
105
106
107
108
109
110
111
}

GType
gst_segment_get_type (void)
{
  static GType gst_segment_type = 0;

112
  if (G_UNLIKELY (gst_segment_type == 0)) {
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
    gst_segment_type = g_boxed_type_register_static ("GstSegment",
        (GBoxedCopyFunc) gst_segment_copy, (GBoxedFreeFunc) gst_segment_free);
  }

  return gst_segment_type;
}

/**
 * gst_segment_new:
 *
 * Allocate a new #GstSegment structure and initialize it using 
 * gst_segment_init().
 *
 * Returns: a new #GstSegment, free with gst_segment_free().
 */
GstSegment *
gst_segment_new (void)
{
  GstSegment *result;

133
  result = g_slice_new0 (GstSegment);
134
135
136
137
138
139
140
141
142
143
144
145
146
147
  gst_segment_init (result, GST_FORMAT_UNDEFINED);

  return result;
}

/**
 * gst_segment_free:
 * @segment: a #GstSegment
 *
 * Free the allocated segment @segment.
 */
void
gst_segment_free (GstSegment * segment)
{
148
  g_slice_free (GstSegment, segment);
149
150
}

151
152
153
154
155
/**
 * gst_segment_init:
 * @segment: a #GstSegment structure.
 * @format: the format of the segment.
 *
156
157
158
159
160
 * The start/last_stop positions are set to 0 and the stop/duration
 * fields are set to -1 (unknown). The default rate of 1.0 and no
 * flags are set.
 *
 * Initialize @segment to its default values.
161
162
163
164
165
166
167
 */
void
gst_segment_init (GstSegment * segment, GstFormat format)
{
  g_return_if_fail (segment != NULL);

  segment->rate = 1.0;
168
  segment->abs_rate = 1.0;
169
  segment->applied_rate = 1.0;
170
171
172
173
174
175
  segment->format = format;
  segment->flags = 0;
  segment->start = 0;
  segment->stop = -1;
  segment->time = 0;
  segment->accum = 0;
176
  segment->last_stop = 0;
177
178
179
180
181
182
183
  segment->duration = -1;
}

/**
 * gst_segment_set_duration:
 * @segment: a #GstSegment structure.
 * @format: the format of the segment.
184
 * @duration: the duration of the segment info or -1 if unknown.
185
186
187
 *
 * Set the duration of the segment to @duration. This function is mainly
 * used by elements that perform seeking and know the total duration of the
188
 * segment. 
189
 * 
Wim Taymans's avatar
Wim Taymans committed
190
 * This field should be set to allow seeking requests relative to the
191
 * duration.
192
193
194
195
196
197
 */
void
gst_segment_set_duration (GstSegment * segment, GstFormat format,
    gint64 duration)
{
  g_return_if_fail (segment != NULL);
198

199
  if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
200
201
202
    segment->format = format;
  else
    g_return_if_fail (segment->format == format);
203
204
205
206

  segment->duration = duration;
}

207
208
209
210
211
212
213
/**
 * gst_segment_set_last_stop:
 * @segment: a #GstSegment structure.
 * @format: the format of the segment.
 * @position: the position 
 *
 * Set the last observed stop position in the segment to @position.
Wim Taymans's avatar
Wim Taymans committed
214
215
216
 *
 * This field should be set to allow seeking requests relative to the
 * current playing position.
217
218
219
220
221
222
 */
void
gst_segment_set_last_stop (GstSegment * segment, GstFormat format,
    gint64 position)
{
  g_return_if_fail (segment != NULL);
223

224
  if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
225
226
227
    segment->format = format;
  else
    g_return_if_fail (segment->format == format);
228

229
  segment->last_stop = MAX (segment->start, position);
230
231
}

232
233
234
235
236
237
/**
 * gst_segment_set_seek:
 * @segment: a #GstSegment structure.
 * @rate: the rate of the segment.
 * @format: the format of the segment.
 * @flags: the seek flags for the segment
238
239
 * @start_type: the seek method
 * @start: the seek start value
240
241
 * @stop_type: the seek method
 * @stop: the seek stop value
242
 * @update: boolean holding whether last_stop was updated.
243
 *
244
245
 * Update the segment structure with the field values of a seek event (see
 * gst_event_new_seek()).
246
 *
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 * After calling this method, the segment field last_stop and time will
 * contain the requested new position in the segment. The new requested
 * position in the segment depends on @rate and @start_type and @stop_type. 
 *
 * For positive @rate, the new position in the segment is the new @segment
 * start field when it was updated with a @start_type different from
 * #GST_SEEK_TYPE_NONE. If no update was performed on @segment start position
 * (#GST_SEEK_TYPE_NONE), @start is ignored and @segment last_stop is
 * unmodified.
 *
 * For negative @rate, the new position in the segment is the new @segment
 * stop field when it was updated with a @stop_type different from
 * #GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the
 * duration of the segment will be used to update the stop position.
 * If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE),
 * @stop is ignored and @segment last_stop is unmodified.
263
264
265
266
 *
 * The applied rate of the segment will be set to 1.0 by default.
 * If the caller can apply a rate change, it should update @segment
 * rate and applied_rate after calling this function.
267
268
269
270
 *
 * @update will be set to TRUE if a seek should be performed to the segment 
 * last_stop field. This field can be FALSE if, for example, only the @rate
 * has been changed but not the playback position.
271
272
273
274
 */
void
gst_segment_set_seek (GstSegment * segment, gdouble rate,
    GstFormat format, GstSeekFlags flags,
275
    GstSeekType start_type, gint64 start,
276
    GstSeekType stop_type, gint64 stop, gboolean * update)
277
278
{
  gboolean update_stop, update_start;
279
  gint64 last_stop;
280
281
282

  g_return_if_fail (rate != 0.0);
  g_return_if_fail (segment != NULL);
283

284
  if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
285
    segment->format = format;
286

287
  update_start = update_stop = TRUE;
288

289
  /* segment->start is never invalid */
290
  switch (start_type) {
291
    case GST_SEEK_TYPE_NONE:
292
      /* no update to segment, take previous start */
293
      start = segment->start;
294
295
296
      update_start = FALSE;
      break;
    case GST_SEEK_TYPE_SET:
297
298
299
      /* start holds desired position, map -1 to the start */
      if (start == -1)
        start = 0;
300
301
      /* start must be 0 or the formats must match */
      g_return_if_fail (start == 0 || segment->format == format);
302
303
      break;
    case GST_SEEK_TYPE_CUR:
304
305
      g_return_if_fail (start == 0 || segment->format == format);
      /* add start to currently configured segment */
306
      start = segment->start + start;
307
308
309
      break;
    case GST_SEEK_TYPE_END:
      if (segment->duration != -1) {
310
        g_return_if_fail (start == 0 || segment->format == format);
311
312
        /* add start to total length */
        start = segment->duration + start;
313
314
      } else {
        /* no update if duration unknown */
315
        start = segment->start;
316
317
318
319
320
321
        update_start = FALSE;
      }
      break;
  }
  /* bring in sane range */
  if (segment->duration != -1)
322
    start = CLAMP (start, 0, segment->duration);
323
  else
324
    start = MAX (start, 0);
325
326
327
328
329
330
331
332

  /* stop can be -1 if we have not configured a stop. */
  switch (stop_type) {
    case GST_SEEK_TYPE_NONE:
      stop = segment->stop;
      update_stop = FALSE;
      break;
    case GST_SEEK_TYPE_SET:
333
334
335
      /* stop holds required value, if it's not -1, it must be of the same
       * format as the segment. */
      g_return_if_fail (stop == -1 || segment->format == format);
336
337
      break;
    case GST_SEEK_TYPE_CUR:
338
339
340
      if (segment->stop != -1) {
        /* only add compatible formats or 0 */
        g_return_if_fail (stop == 0 || segment->format == format);
341
        stop = segment->stop + stop;
342
      } else
343
344
345
        stop = -1;
      break;
    case GST_SEEK_TYPE_END:
346
347
348
      if (segment->duration != -1) {
        /* only add compatible formats or 0 */
        g_return_if_fail (stop == 0 || segment->format == format);
349
        stop = segment->duration + stop;
350
      } else {
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
        stop = segment->stop;
        update_stop = FALSE;
      }
      break;
  }

  /* if we have a valid stop time, make sure it is clipped */
  if (stop != -1) {
    if (segment->duration != -1)
      stop = CLAMP (stop, 0, segment->duration);
    else
      stop = MAX (stop, 0);
  }

  /* we can't have stop before start */
  if (stop != -1)
367
    g_return_if_fail (start <= stop);
368
369
370

  segment->rate = rate;
  segment->abs_rate = ABS (rate);
371
  segment->applied_rate = 1.0;
372
  segment->flags = flags;
373
  segment->start = start;
374
375
376
  segment->stop = stop;
  segment->time = start;

377
  last_stop = segment->last_stop;
378
  if (update_start && rate > 0.0) {
379
    last_stop = start;
380
381
  }
  if (update_stop && rate < 0.0) {
382
    if (stop != -1)
383
      last_stop = stop;
384
385
    else {
      if (segment->duration != -1)
386
        last_stop = segment->duration;
387
      else
388
        last_stop = 0;
389
    }
390
  }
391
392
393
394
395
  /* set update arg to reflect update of last_stop */
  if (update)
    *update = last_stop != segment->last_stop;

  /* update new position */
396
  segment->last_stop = last_stop;
397
398
399
400
401
402
403
404
405
406
407
408
}

/**
 * gst_segment_set_newsegment:
 * @segment: a #GstSegment structure.
 * @update: flag indicating a new segment is started or updated
 * @rate: the rate of the segment.
 * @format: the format of the segment.
 * @start: the new start value
 * @stop: the new stop value
 * @time: the new stream time
 *
409
410
411
412
 * Update the segment structure with the field values of a new segment event and
 * with a default applied_rate of 1.0.
 *
 * Since: 0.10.6
413
414
415
416
 */
void
gst_segment_set_newsegment (GstSegment * segment, gboolean update, gdouble rate,
    GstFormat format, gint64 start, gint64 stop, gint64 time)
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
{
  gst_segment_set_newsegment_full (segment, update, rate, 1.0, format, start,
      stop, time);
}

/**
 * gst_segment_set_newsegment_full:
 * @segment: a #GstSegment structure.
 * @update: flag indicating a new segment is started or updated
 * @rate: the rate of the segment.
 * @applied_rate: the applied rate of the segment.
 * @format: the format of the segment.
 * @start: the new start value
 * @stop: the new stop value
 * @time: the new stream time
 *
 * Update the segment structure with the field values of a new segment event.
 */
void
gst_segment_set_newsegment_full (GstSegment * segment, gboolean update,
    gdouble rate, gdouble applied_rate, GstFormat format, gint64 start,
    gint64 stop, gint64 time)
439
{
440
  gint64 duration, last_stop;
441
442

  g_return_if_fail (rate != 0.0);
443
  g_return_if_fail (applied_rate != 0.0);
444
  g_return_if_fail (segment != NULL);
445

446
447
448
449
450
451
  GST_DEBUG ("configuring segment update %d, rate %lf, format %s, "
      "start %" G_GINT64_FORMAT ", stop %" G_GINT64_FORMAT ", position %"
      G_GINT64_FORMAT, update, rate, gst_format_get_name (format), start,
      stop, time);
  GST_DEBUG ("old segment was: %" GST_SEGMENT_FORMAT, segment);

452
  if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
453
454
    segment->format = format;

455
456
457
458
459
460
461
462
463
464
  /* any other format with 0 also gives time 0, the other values are
   * invalid in the format though. */
  if (format != segment->format && start == 0) {
    format = segment->format;
    if (stop != 0)
      stop = -1;
    if (time != 0)
      time = -1;
  }

465
466
467
  g_return_if_fail (segment->format == format);

  if (update) {
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
    if (segment->rate > 0.0) {
      /* an update to the current segment is done, elapsed time is
       * difference between the old start and new start. */
      if (start > segment->start)
        duration = start - segment->start;
      else
        duration = 0;
    } else {
      /* for negative rates, the elapsed duration is the diff between the stop
       * positions */
      if (stop != -1 && stop < segment->stop)
        duration = segment->stop - stop;
      else
        duration = 0;
    }
483
484
485
486
487
488
489
    /* update last_stop to be a valid value in the updated segment */
    if (start > segment->last_stop)
      last_stop = start;
    else if (stop != -1 && stop < segment->last_stop)
      last_stop = stop;
    else
      last_stop = segment->last_stop;
490
491
492
493
  } else {
    /* the new segment has to be aligned with the old segment.
     * We first update the accumulated time of the previous
     * segment. the accumulated time is used when syncing to the
494
     * clock. */
495
    if (segment->stop != -1) {
496
      duration = segment->stop - segment->start;
497
    } else if (segment->last_stop != -1) {
498
      /* else use last seen timestamp as segment stop */
499
      duration = segment->last_stop - segment->start;
500
    } else {
501
502
503
      /* else we don't know and throw a warning.. really, this should
       * be fixed in the element. */
      g_warning ("closing segment of unknown duration, assuming duration of 0");
504
505
      duration = 0;
    }
506
507
508
509
510
511
    /* position the last_stop to the next expected position in the new segment,
     * which is the start or the stop of the segment */
    if (rate > 0.0)
      last_stop = start;
    else
      last_stop = stop;
512
513
  }
  /* use previous rate to calculate duration */
514
515
516
517
518
  if (segment->abs_rate != 1.0)
    duration /= segment->abs_rate;

  /* accumulate duration */
  segment->accum += duration;
519

520
521
522
  /* then update the current segment */
  segment->rate = rate;
  segment->abs_rate = ABS (rate);
523
  segment->applied_rate = applied_rate;
524
  segment->start = start;
525
  segment->last_stop = last_stop;
526
527
528
529
530
531
532
533
534
535
536
  segment->stop = stop;
  segment->time = time;
}

/**
 * gst_segment_to_stream_time:
 * @segment: a #GstSegment structure.
 * @format: the format of the segment.
 * @position: the position in the segment
 *
 * Translate @position to stream time using the currently configured 
537
538
 * segment. The @position value must be between @segment start and
 * stop value. 
539
540
541
 *
 * This function is typically used by elements that need to operate on
 * the stream time of the buffers it receives, such as effect plugins.
542
543
 * In those use cases, @position is typically the buffer timestamp or 
 * clock time that one wants to convert to the stream time.
544
 * The stream time is always between 0 and the total duration of the 
545
 * media stream. 
546
 *
547
548
 * Returns: the position in stream_time or -1 when an invalid position
 * was given.
549
550
551
552
553
 */
gint64
gst_segment_to_stream_time (GstSegment * segment, GstFormat format,
    gint64 position)
{
554
  gint64 result, start, stop, time;
555
  gdouble abs_applied_rate;
556

557
  g_return_val_if_fail (segment != NULL, -1);
558

559
  /* format does not matter for -1 */
560
  if (G_UNLIKELY (position == -1))
561
562
    return -1;

563
  if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
564
    segment->format = format;
565
566
567
568
569
570
571
572
573
574
575
576

  /* if we have the position for the same format as the segment, we can compare
   * the start and stop values, otherwise we assume 0 and -1 */
  if (segment->format == format) {
    start = segment->start;
    stop = segment->stop;
    time = segment->time;
  } else {
    start = 0;
    stop = -1;
    time = 0;
  }
577

578
  /* outside of the segment boundary stop */
579
  if (G_UNLIKELY (stop != -1 && position > stop))
580
    return -1;
581

582
  /* before the segment boundary */
583
  if (G_UNLIKELY (position < start))
584
585
586
    return -1;

  /* time must be known */
587
  if (G_UNLIKELY (time == -1))
588
589
590
    return -1;

  /* bring to uncorrected position in segment */
591
  result = position - start;
592
593
594
595
596
597
598
599
600
601

  abs_applied_rate = ABS (segment->applied_rate);

  /* correct for applied rate if needed */
  if (abs_applied_rate != 1.0)
    result *= abs_applied_rate;

  /* add or subtract from segment time based on applied rate */
  if (segment->applied_rate > 0.0) {
    /* correct for segment time */
602
    result += time;
603
  } else {
604
605
606
    /* correct for segment time, clamp at 0. Streams with a negative
     * applied_rate have timestamps between start and stop, as usual, but have
     * the time member starting high and going backwards.  */
607
608
    if (time > result)
      result = time - result;
609
610
611
    else
      result = 0;
  }
612
613
614
615
616
617
618
619
620
621
622

  return result;
}

/**
 * gst_segment_to_running_time:
 * @segment: a #GstSegment structure.
 * @format: the format of the segment.
 * @position: the position in the segment
 *
 * Translate @position to the total running time using the currently configured 
623
624
 * and previously accumulated segments. Position is a value between @segment
 * start and stop time.
625
626
 *
 * This function is typically used by elements that need to synchronize to the
627
 * global clock in a pipeline. The runnning time is a constantly increasing value
Wim Taymans's avatar
Wim Taymans committed
628
629
 * starting from 0. When gst_segment_init() is called, this value will reset to
 * 0.
630
 *
631
632
633
634
 * This function returns -1 if the position is outside of @segment start and stop.
 *
 * Returns: the position as the total running time or -1 when an invalid position
 * was given.
635
636
637
638
639
640
 */
gint64
gst_segment_to_running_time (GstSegment * segment, GstFormat format,
    gint64 position)
{
  gint64 result;
641
  gint64 start, stop, accum;
642

643
  g_return_val_if_fail (segment != NULL, -1);
644

645
  if (G_UNLIKELY (position == -1))
646
647
    return -1;

648
  if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
649
    segment->format = format;
650
651
652
653
654
655
656
657
658
659
660
661

  /* if we have the position for the same format as the segment, we can compare
   * the start and stop values, otherwise we assume 0 and -1 */
  if (segment->format == format) {
    start = segment->start;
    stop = segment->stop;
    accum = segment->accum;
  } else {
    start = 0;
    stop = -1;
    accum = 0;
  }
662

663
  /* before the segment boundary */
664
  if (G_UNLIKELY (position < start))
665
666
667
668
    return -1;

  if (segment->rate > 0.0) {
    /* outside of the segment boundary stop */
669
    if (G_UNLIKELY (stop != -1 && position > stop))
670
671
672
      return -1;

    /* bring to uncorrected position in segment */
673
    result = position - start;
674
675
676
  } else {
    /* cannot continue if no stop position set or outside of
     * the segment. */
677
    if (G_UNLIKELY (stop == -1 || position > stop))
678
679
680
      return -1;

    /* bring to uncorrected position in segment */
681
    result = stop - position;
682
683
684
685
686
687
688
689
  }

  /* scale based on the rate, avoid division by and conversion to 
   * float when not needed */
  if (segment->abs_rate != 1.0)
    result /= segment->abs_rate;

  /* correct for accumulated segments */
690
  result += accum;
691
692
693
694
695
696
697
698
699
700
701
702
703
704

  return result;
}

/**
 * gst_segment_clip:
 * @segment: a #GstSegment structure.
 * @format: the format of the segment.
 * @start: the start position in the segment
 * @stop: the stop position in the segment
 * @clip_start: the clipped start position in the segment
 * @clip_stop: the clipped stop position in the segment
 *
 * Clip the given @start and @stop values to the segment boundaries given
705
706
 * in @segment. @start and @stop are compared and clipped to @segment 
 * start and stop values.
707
 *
Wim Taymans's avatar
Wim Taymans committed
708
709
710
711
712
713
714
 * If the function returns FALSE, @start and @stop are known to fall
 * outside of @segment and @clip_start and @clip_stop are not updated.
 *
 * When the function returns TRUE, @clip_start and @clip_stop will be
 * updated. If @clip_start or @clip_stop are different from @start or @stop
 * respectively, the region fell partially in the segment.
 *
715
716
717
 * Note that when @stop is -1, @clip_stop will be set to the end of the
 * segment. Depending on the use case, this may or may not be what you want.
 *
Wim Taymans's avatar
Wim Taymans committed
718
719
720
 * Returns: TRUE if the given @start and @stop times fall partially or 
 *     completely in @segment, FALSE if the values are completely outside 
 *     of the segment.
721
722
723
724
725
726
 */
gboolean
gst_segment_clip (GstSegment * segment, GstFormat format, gint64 start,
    gint64 stop, gint64 * clip_start, gint64 * clip_stop)
{
  g_return_val_if_fail (segment != NULL, FALSE);
727

728
  if (G_UNLIKELY (segment->format == GST_FORMAT_UNDEFINED))
729
730
731
    segment->format = format;
  else
    g_return_val_if_fail (segment->format == format, FALSE);
732

733
734
  /* if we have a stop position and a valid start and start is bigger, 
   * we're outside of the segment */
735
  if (G_UNLIKELY (segment->stop != -1 && start != -1 && start >= segment->stop))
736
737
738
739
    return FALSE;

  /* if a stop position is given and is before the segment start,
   * we're outside of the segment */
740
  if (G_UNLIKELY (stop != -1 && stop != start && stop <= segment->start))
741
742
    return FALSE;

743
744
745
746
747
748
  if (clip_start) {
    if (start == -1)
      *clip_start = -1;
    else
      *clip_start = MAX (start, segment->start);
  }
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763

  if (clip_stop) {
    if (stop == -1)
      *clip_stop = segment->stop;
    else if (segment->stop == -1)
      *clip_stop = MAX (-1, stop);
    else
      *clip_stop = MIN (stop, segment->stop);

    if (segment->duration != -1)
      *clip_stop = MIN (*clip_stop, segment->duration);
  }

  return TRUE;
}