1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Segment;
26 
27 private import glib.ConstructionException;
28 private import gobject.ObjectG;
29 private import gstreamer.c.functions;
30 public  import gstreamer.c.types;
31 private import gtkd.Loader;
32 
33 
34 /**
35  * This helper structure holds the relevant values for tracking the region of
36  * interest in a media file, called a segment.
37  * 
38  * The structure can be used for two purposes:
39  * 
40  * * performing seeks (handling seek events)
41  * * tracking playback regions (handling newsegment events)
42  * 
43  * The segment is usually configured by the application with a seek event which
44  * is propagated upstream and eventually handled by an element that performs the seek.
45  * 
46  * The configured segment is then propagated back downstream with a newsegment event.
47  * This information is then used to clip media to the segment boundaries.
48  * 
49  * A segment structure is initialized with gst_segment_init(), which takes a #GstFormat
50  * that will be used as the format of the segment values. The segment will be configured
51  * with a start value of 0 and a stop/duration of -1, which is undefined. The default
52  * rate and applied_rate is 1.0.
53  * 
54  * The public duration field contains the duration of the segment. When using
55  * the segment for seeking, the start and time members should normally be left
56  * to their default 0 value. The stop position is left to -1 unless explicitly
57  * configured to a different value after a seek event.
58  * 
59  * The current position in the segment should be set by changing the position
60  * member in the structure.
61  * 
62  * For elements that perform seeks, the current segment should be updated with the
63  * gst_segment_do_seek() and the values from the seek event. This method will update
64  * all the segment fields. The position field will contain the new playback position.
65  * If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from
66  * the position position, possibly with updated flags or rate.
67  * 
68  * For elements that want to use #GstSegment to track the playback region,
69  * update the segment fields with the information from the newsegment event.
70  * The gst_segment_clip() method can be used to check and clip
71  * the media data to the segment boundaries.
72  * 
73  * For elements that want to synchronize to the pipeline clock, gst_segment_to_running_time()
74  * can be used to convert a timestamp to a value that can be used to synchronize
75  * to the clock. This function takes into account the base as well as
76  * any rate or applied_rate conversions.
77  * 
78  * For elements that need to perform operations on media data in stream_time,
79  * gst_segment_to_stream_time() can be used to convert a timestamp and the segment
80  * info to stream time (which is always between 0 and the duration of the stream).
81  */
82 public class Segment
83 {
84 	/** the main Gtk struct */
85 	protected GstSegment* gstSegment;
86 	protected bool ownedRef;
87 
88 	/** Get the main Gtk struct */
89 	public GstSegment* getSegmentStruct(bool transferOwnership = false)
90 	{
91 		if (transferOwnership)
92 			ownedRef = false;
93 		return gstSegment;
94 	}
95 
96 	/** the main Gtk struct as a void* */
97 	protected void* getStruct()
98 	{
99 		return cast(void*)gstSegment;
100 	}
101 
102 	/**
103 	 * Sets our main struct and passes it to the parent class.
104 	 */
105 	public this (GstSegment* gstSegment, bool ownedRef = false)
106 	{
107 		this.gstSegment = gstSegment;
108 		this.ownedRef = ownedRef;
109 	}
110 
111 	~this ()
112 	{
113 		if ( Linker.isLoaded(LIBRARY_GSTREAMER) && ownedRef )
114 			gst_segment_free(gstSegment);
115 	}
116 
117 
118 	/** */
119 	public static GType getType()
120 	{
121 		return gst_segment_get_type();
122 	}
123 
124 	/**
125 	 * Allocate a new #GstSegment structure and initialize it using
126 	 * gst_segment_init().
127 	 *
128 	 * Free-function: gst_segment_free
129 	 *
130 	 * Returns: a new #GstSegment, free with gst_segment_free().
131 	 *
132 	 * Throws: ConstructionException GTK+ fails to create the object.
133 	 */
134 	public this()
135 	{
136 		auto __p = gst_segment_new();
137 
138 		if(__p is null)
139 		{
140 			throw new ConstructionException("null returned by new");
141 		}
142 
143 		this(cast(GstSegment*) __p);
144 	}
145 
146 	/**
147 	 * Clip the given @start and @stop values to the segment boundaries given
148 	 * in @segment. @start and @stop are compared and clipped to @segment
149 	 * start and stop values.
150 	 *
151 	 * If the function returns %FALSE, @start and @stop are known to fall
152 	 * outside of @segment and @clip_start and @clip_stop are not updated.
153 	 *
154 	 * When the function returns %TRUE, @clip_start and @clip_stop will be
155 	 * updated. If @clip_start or @clip_stop are different from @start or @stop
156 	 * respectively, the region fell partially in the segment.
157 	 *
158 	 * Note that when @stop is -1, @clip_stop will be set to the end of the
159 	 * segment. Depending on the use case, this may or may not be what you want.
160 	 *
161 	 * Params:
162 	 *     format = the format of the segment.
163 	 *     start = the start position in the segment
164 	 *     stop = the stop position in the segment
165 	 *     clipStart = the clipped start position in the segment
166 	 *     clipStop = the clipped stop position in the segment
167 	 *
168 	 * Returns: %TRUE if the given @start and @stop times fall partially or
169 	 *     completely in @segment, %FALSE if the values are completely outside
170 	 *     of the segment.
171 	 */
172 	public bool clip(GstFormat format, ulong start, ulong stop, out ulong clipStart, out ulong clipStop)
173 	{
174 		return gst_segment_clip(gstSegment, format, start, stop, &clipStart, &clipStop) != 0;
175 	}
176 
177 	/**
178 	 * Create a copy of given @segment.
179 	 *
180 	 * Free-function: gst_segment_free
181 	 *
182 	 * Returns: a new #GstSegment, free with gst_segment_free().
183 	 */
184 	public Segment copy()
185 	{
186 		auto __p = gst_segment_copy(gstSegment);
187 
188 		if(__p is null)
189 		{
190 			return null;
191 		}
192 
193 		return ObjectG.getDObject!(Segment)(cast(GstSegment*) __p, true);
194 	}
195 
196 	/**
197 	 * Copy the contents of @src into @dest.
198 	 *
199 	 * Params:
200 	 *     dest = a #GstSegment
201 	 */
202 	public void copyInto(Segment dest)
203 	{
204 		gst_segment_copy_into(gstSegment, (dest is null) ? null : dest.getSegmentStruct());
205 	}
206 
207 	/**
208 	 * Update the segment structure with the field values of a seek event (see
209 	 * gst_event_new_seek()).
210 	 *
211 	 * After calling this method, the segment field position and time will
212 	 * contain the requested new position in the segment. The new requested
213 	 * position in the segment depends on @rate and @start_type and @stop_type.
214 	 *
215 	 * For positive @rate, the new position in the segment is the new @segment
216 	 * start field when it was updated with a @start_type different from
217 	 * #GST_SEEK_TYPE_NONE. If no update was performed on @segment start position
218 	 * (#GST_SEEK_TYPE_NONE), @start is ignored and @segment position is
219 	 * unmodified.
220 	 *
221 	 * For negative @rate, the new position in the segment is the new @segment
222 	 * stop field when it was updated with a @stop_type different from
223 	 * #GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the
224 	 * duration of the segment will be used to update the stop position.
225 	 * If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE),
226 	 * @stop is ignored and @segment position is unmodified.
227 	 *
228 	 * The applied rate of the segment will be set to 1.0 by default.
229 	 * If the caller can apply a rate change, it should update @segment
230 	 * rate and applied_rate after calling this function.
231 	 *
232 	 * @update will be set to %TRUE if a seek should be performed to the segment
233 	 * position field. This field can be %FALSE if, for example, only the @rate
234 	 * has been changed but not the playback position.
235 	 *
236 	 * Params:
237 	 *     rate = the rate of the segment.
238 	 *     format = the format of the segment.
239 	 *     flags = the segment flags for the segment
240 	 *     startType = the seek method
241 	 *     start = the seek start value
242 	 *     stopType = the seek method
243 	 *     stop = the seek stop value
244 	 *     update = boolean holding whether position was updated.
245 	 *
246 	 * Returns: %TRUE if the seek could be performed.
247 	 */
248 	public bool doSeek(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, ulong start, GstSeekType stopType, ulong stop, ref bool update)
249 	{
250 		int outupdate = (update ? 1 : 0);
251 
252 		auto __p = gst_segment_do_seek(gstSegment, rate, format, flags, startType, start, stopType, stop, &outupdate) != 0;
253 
254 		update = (outupdate == 1);
255 
256 		return __p;
257 	}
258 
259 	/**
260 	 * Free the allocated segment @segment.
261 	 */
262 	public void free()
263 	{
264 		gst_segment_free(gstSegment);
265 		ownedRef = false;
266 	}
267 
268 	/**
269 	 * The start/position fields are set to 0 and the stop/duration
270 	 * fields are set to -1 (unknown). The default rate of 1.0 and no
271 	 * flags are set.
272 	 *
273 	 * Initialize @segment to its default values.
274 	 *
275 	 * Params:
276 	 *     format = the format of the segment.
277 	 */
278 	public void init(GstFormat format)
279 	{
280 		gst_segment_init(gstSegment, format);
281 	}
282 
283 	/**
284 	 * Checks for two segments being equal. Equality here is defined
285 	 * as perfect equality, including floating point values.
286 	 *
287 	 * Params:
288 	 *     s1 = a #GstSegment structure.
289 	 *
290 	 * Returns: %TRUE if the segments are equal, %FALSE otherwise.
291 	 *
292 	 * Since: 1.6
293 	 */
294 	public bool isEqual(Segment s1)
295 	{
296 		return gst_segment_is_equal(gstSegment, (s1 is null) ? null : s1.getSegmentStruct()) != 0;
297 	}
298 
299 	/**
300 	 * Adjust the values in @segment so that @offset is applied to all
301 	 * future running-time calculations.
302 	 *
303 	 * Params:
304 	 *     format = the format of the segment.
305 	 *     offset = the offset to apply in the segment
306 	 *
307 	 * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
308 	 *     returned, @offset is not in @segment.
309 	 *
310 	 * Since: 1.2.3
311 	 */
312 	public bool offsetRunningTime(GstFormat format, long offset)
313 	{
314 		return gst_segment_offset_running_time(gstSegment, format, offset) != 0;
315 	}
316 
317 	/**
318 	 * Convert @running_time into a position in the segment so that
319 	 * gst_segment_to_running_time() with that position returns @running_time.
320 	 *
321 	 * Params:
322 	 *     format = the format of the segment.
323 	 *     runningTime = the running_time in the segment
324 	 *
325 	 * Returns: the position in the segment for @running_time. This function returns
326 	 *     -1 when @running_time is -1 or when it is not inside @segment.
327 	 *
328 	 * Since: 1.8
329 	 */
330 	public ulong positionFromRunningTime(GstFormat format, ulong runningTime)
331 	{
332 		return gst_segment_position_from_running_time(gstSegment, format, runningTime);
333 	}
334 
335 	/**
336 	 * Translate @running_time to the segment position using the currently configured
337 	 * segment. Compared to gst_segment_position_from_running_time() this function can
338 	 * return negative segment position.
339 	 *
340 	 * This function is typically used by elements that need to synchronize buffers
341 	 * against the clock or each other.
342 	 *
343 	 * @running_time can be any value and the result of this function for values
344 	 * outside of the segment is extrapolated.
345 	 *
346 	 * When 1 is returned, @running_time resulted in a positive position returned
347 	 * in @position.
348 	 *
349 	 * When this function returns -1, the returned @position was < 0, and the value
350 	 * in the position variable should be negated to get the real negative segment
351 	 * position.
352 	 *
353 	 * Params:
354 	 *     format = the format of the segment.
355 	 *     runningTime = the running-time
356 	 *     position = the resulting position in the segment
357 	 *
358 	 * Returns: a 1 or -1 on success, 0 on failure.
359 	 *
360 	 * Since: 1.8
361 	 */
362 	public int positionFromRunningTimeFull(GstFormat format, ulong runningTime, out ulong position)
363 	{
364 		return gst_segment_position_from_running_time_full(gstSegment, format, runningTime, &position);
365 	}
366 
367 	/**
368 	 * Convert @stream_time into a position in the segment so that
369 	 * gst_segment_to_stream_time() with that position returns @stream_time.
370 	 *
371 	 * Params:
372 	 *     format = the format of the segment.
373 	 *     streamTime = the stream_time in the segment
374 	 *
375 	 * Returns: the position in the segment for @stream_time. This function returns
376 	 *     -1 when @stream_time is -1 or when it is not inside @segment.
377 	 *
378 	 * Since: 1.8
379 	 */
380 	public ulong positionFromStreamTime(GstFormat format, ulong streamTime)
381 	{
382 		return gst_segment_position_from_stream_time(gstSegment, format, streamTime);
383 	}
384 
385 	/**
386 	 * Translate @stream_time to the segment position using the currently configured
387 	 * segment. Compared to gst_segment_position_from_stream_time() this function can
388 	 * return negative segment position.
389 	 *
390 	 * This function is typically used by elements that need to synchronize buffers
391 	 * against the clock or each other.
392 	 *
393 	 * @stream_time can be any value and the result of this function for values outside
394 	 * of the segment is extrapolated.
395 	 *
396 	 * When 1 is returned, @stream_time resulted in a positive position returned
397 	 * in @position.
398 	 *
399 	 * When this function returns -1, the returned @position should be negated
400 	 * to get the real negative segment position.
401 	 *
402 	 * Params:
403 	 *     format = the format of the segment.
404 	 *     streamTime = the stream-time
405 	 *     position = the resulting position in the segment
406 	 *
407 	 * Returns: a 1 or -1 on success, 0 on failure.
408 	 *
409 	 * Since: 1.8
410 	 */
411 	public int positionFromStreamTimeFull(GstFormat format, ulong streamTime, out ulong position)
412 	{
413 		return gst_segment_position_from_stream_time_full(gstSegment, format, streamTime, &position);
414 	}
415 
416 	/**
417 	 * Adjust the start/stop and base values of @segment such that the next valid
418 	 * buffer will be one with @running_time.
419 	 *
420 	 * Params:
421 	 *     format = the format of the segment.
422 	 *     runningTime = the running_time in the segment
423 	 *
424 	 * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
425 	 *     returned, @running_time is -1 or not in @segment.
426 	 */
427 	public bool setRunningTime(GstFormat format, ulong runningTime)
428 	{
429 		return gst_segment_set_running_time(gstSegment, format, runningTime) != 0;
430 	}
431 
432 	/**
433 	 * Convert @running_time into a position in the segment so that
434 	 * gst_segment_to_running_time() with that position returns @running_time.
435 	 *
436 	 * Deprecated: Use gst_segment_position_from_running_time() instead.
437 	 *
438 	 * Params:
439 	 *     format = the format of the segment.
440 	 *     runningTime = the running_time in the segment
441 	 *
442 	 * Returns: the position in the segment for @running_time. This function returns
443 	 *     -1 when @running_time is -1 or when it is not inside @segment.
444 	 */
445 	public ulong toPosition(GstFormat format, ulong runningTime)
446 	{
447 		return gst_segment_to_position(gstSegment, format, runningTime);
448 	}
449 
450 	/**
451 	 * Translate @position to the total running time using the currently configured
452 	 * segment. Position is a value between @segment start and stop time.
453 	 *
454 	 * This function is typically used by elements that need to synchronize to the
455 	 * global clock in a pipeline. The running time is a constantly increasing value
456 	 * starting from 0. When gst_segment_init() is called, this value will reset to
457 	 * 0.
458 	 *
459 	 * This function returns -1 if the position is outside of @segment start and stop.
460 	 *
461 	 * Params:
462 	 *     format = the format of the segment.
463 	 *     position = the position in the segment
464 	 *
465 	 * Returns: the position as the total running time or -1 when an invalid position
466 	 *     was given.
467 	 */
468 	public ulong toRunningTime(GstFormat format, ulong position)
469 	{
470 		return gst_segment_to_running_time(gstSegment, format, position);
471 	}
472 
473 	/**
474 	 * Translate @position to the total running time using the currently configured
475 	 * segment. Compared to gst_segment_to_running_time() this function can return
476 	 * negative running-time.
477 	 *
478 	 * This function is typically used by elements that need to synchronize buffers
479 	 * against the clock or each other.
480 	 *
481 	 * @position can be any value and the result of this function for values outside
482 	 * of the segment is extrapolated.
483 	 *
484 	 * When 1 is returned, @position resulted in a positive running-time returned
485 	 * in @running_time.
486 	 *
487 	 * When this function returns -1, the returned @running_time should be negated
488 	 * to get the real negative running time.
489 	 *
490 	 * Params:
491 	 *     format = the format of the segment.
492 	 *     position = the position in the segment
493 	 *     runningTime = result running-time
494 	 *
495 	 * Returns: a 1 or -1 on success, 0 on failure.
496 	 *
497 	 * Since: 1.6
498 	 */
499 	public int toRunningTimeFull(GstFormat format, ulong position, out ulong runningTime)
500 	{
501 		return gst_segment_to_running_time_full(gstSegment, format, position, &runningTime);
502 	}
503 
504 	/**
505 	 * Translate @position to stream time using the currently configured
506 	 * segment. The @position value must be between @segment start and
507 	 * stop value.
508 	 *
509 	 * This function is typically used by elements that need to operate on
510 	 * the stream time of the buffers it receives, such as effect plugins.
511 	 * In those use cases, @position is typically the buffer timestamp or
512 	 * clock time that one wants to convert to the stream time.
513 	 * The stream time is always between 0 and the total duration of the
514 	 * media stream.
515 	 *
516 	 * Params:
517 	 *     format = the format of the segment.
518 	 *     position = the position in the segment
519 	 *
520 	 * Returns: the position in stream_time or -1 when an invalid position
521 	 *     was given.
522 	 *
523 	 * Since: 1.8
524 	 */
525 	public ulong toStreamTime(GstFormat format, ulong position)
526 	{
527 		return gst_segment_to_stream_time(gstSegment, format, position);
528 	}
529 
530 	/**
531 	 * Translate @position to the total stream time using the currently configured
532 	 * segment. Compared to gst_segment_to_stream_time() this function can return
533 	 * negative stream-time.
534 	 *
535 	 * This function is typically used by elements that need to synchronize buffers
536 	 * against the clock or each other.
537 	 *
538 	 * @position can be any value and the result of this function for values outside
539 	 * of the segment is extrapolated.
540 	 *
541 	 * When 1 is returned, @position resulted in a positive stream-time returned
542 	 * in @stream_time.
543 	 *
544 	 * When this function returns -1, the returned @stream_time should be negated
545 	 * to get the real negative stream time.
546 	 *
547 	 * Params:
548 	 *     format = the format of the segment.
549 	 *     position = the position in the segment
550 	 *     streamTime = result stream-time
551 	 *
552 	 * Returns: a 1 or -1 on success, 0 on failure.
553 	 *
554 	 * Since: 1.8
555 	 */
556 	public int toStreamTimeFull(GstFormat format, ulong position, out ulong streamTime)
557 	{
558 		return gst_segment_to_stream_time_full(gstSegment, format, position, &streamTime);
559 	}
560 }