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 public  import gstreamerc.gstreamertypes;
32 private import gtkd.Loader;
33 
34 
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 public class Segment
84 {
85 	/** the main Gtk struct */
86 	protected GstSegment* gstSegment;
87 	protected bool ownedRef;
88 
89 	/** Get the main Gtk struct */
90 	public GstSegment* getSegmentStruct(bool transferOwnership = false)
91 	{
92 		if (transferOwnership)
93 			ownedRef = false;
94 		return gstSegment;
95 	}
96 
97 	/** the main Gtk struct as a void* */
98 	protected void* getStruct()
99 	{
100 		return cast(void*)gstSegment;
101 	}
102 
103 	/**
104 	 * Sets our main struct and passes it to the parent class.
105 	 */
106 	public this (GstSegment* gstSegment, bool ownedRef = false)
107 	{
108 		this.gstSegment = gstSegment;
109 		this.ownedRef = ownedRef;
110 	}
111 
112 	~this ()
113 	{
114 		if ( Linker.isLoaded(LIBRARY_GSTREAMER) && ownedRef )
115 			gst_segment_free(gstSegment);
116 	}
117 
118 
119 	/** */
120 	public static GType getType()
121 	{
122 		return gst_segment_get_type();
123 	}
124 
125 	/**
126 	 * Allocate a new #GstSegment structure and initialize it using
127 	 * gst_segment_init().
128 	 *
129 	 * Free-function: gst_segment_free
130 	 *
131 	 * Returns: a new #GstSegment, free with gst_segment_free().
132 	 *
133 	 * Throws: ConstructionException GTK+ fails to create the object.
134 	 */
135 	public this()
136 	{
137 		auto p = gst_segment_new();
138 
139 		if(p is null)
140 		{
141 			throw new ConstructionException("null returned by new");
142 		}
143 
144 		this(cast(GstSegment*) p);
145 	}
146 
147 	/**
148 	 * Clip the given @start and @stop values to the segment boundaries given
149 	 * in @segment. @start and @stop are compared and clipped to @segment
150 	 * start and stop values.
151 	 *
152 	 * If the function returns %FALSE, @start and @stop are known to fall
153 	 * outside of @segment and @clip_start and @clip_stop are not updated.
154 	 *
155 	 * When the function returns %TRUE, @clip_start and @clip_stop will be
156 	 * updated. If @clip_start or @clip_stop are different from @start or @stop
157 	 * respectively, the region fell partially in the segment.
158 	 *
159 	 * Note that when @stop is -1, @clip_stop will be set to the end of the
160 	 * segment. Depending on the use case, this may or may not be what you want.
161 	 *
162 	 * Params:
163 	 *     format = the format of the segment.
164 	 *     start = the start position in the segment
165 	 *     stop = the stop position in the segment
166 	 *     clipStart = the clipped start position in the segment
167 	 *     clipStop = the clipped stop position in the segment
168 	 *
169 	 * Returns: %TRUE if the given @start and @stop times fall partially or
170 	 *     completely in @segment, %FALSE if the values are completely outside
171 	 *     of the segment.
172 	 */
173 	public bool clip(GstFormat format, ulong start, ulong stop, out ulong clipStart, out ulong clipStop)
174 	{
175 		return gst_segment_clip(gstSegment, format, start, stop, &clipStart, &clipStop) != 0;
176 	}
177 
178 	/**
179 	 * Create a copy of given @segment.
180 	 *
181 	 * Free-function: gst_segment_free
182 	 *
183 	 * Returns: a new #GstSegment, free with gst_segment_free().
184 	 */
185 	public Segment copy()
186 	{
187 		auto p = gst_segment_copy(gstSegment);
188 
189 		if(p is null)
190 		{
191 			return null;
192 		}
193 
194 		return ObjectG.getDObject!(Segment)(cast(GstSegment*) p, true);
195 	}
196 
197 	/**
198 	 * Copy the contents of @src into @dest.
199 	 *
200 	 * Params:
201 	 *     dest = a #GstSegment
202 	 */
203 	public void copyInto(Segment dest)
204 	{
205 		gst_segment_copy_into(gstSegment, (dest is null) ? null : dest.getSegmentStruct());
206 	}
207 
208 	/**
209 	 * Update the segment structure with the field values of a seek event (see
210 	 * gst_event_new_seek()).
211 	 *
212 	 * After calling this method, the segment field position and time will
213 	 * contain the requested new position in the segment. The new requested
214 	 * position in the segment depends on @rate and @start_type and @stop_type.
215 	 *
216 	 * For positive @rate, the new position in the segment is the new @segment
217 	 * start field when it was updated with a @start_type different from
218 	 * #GST_SEEK_TYPE_NONE. If no update was performed on @segment start position
219 	 * (#GST_SEEK_TYPE_NONE), @start is ignored and @segment position is
220 	 * unmodified.
221 	 *
222 	 * For negative @rate, the new position in the segment is the new @segment
223 	 * stop field when it was updated with a @stop_type different from
224 	 * #GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the
225 	 * duration of the segment will be used to update the stop position.
226 	 * If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE),
227 	 * @stop is ignored and @segment position is unmodified.
228 	 *
229 	 * The applied rate of the segment will be set to 1.0 by default.
230 	 * If the caller can apply a rate change, it should update @segment
231 	 * rate and applied_rate after calling this function.
232 	 *
233 	 * @update will be set to %TRUE if a seek should be performed to the segment
234 	 * position field. This field can be %FALSE if, for example, only the @rate
235 	 * has been changed but not the playback position.
236 	 *
237 	 * Params:
238 	 *     rate = the rate of the segment.
239 	 *     format = the format of the segment.
240 	 *     flags = the segment flags for the segment
241 	 *     startType = the seek method
242 	 *     start = the seek start value
243 	 *     stopType = the seek method
244 	 *     stop = the seek stop value
245 	 *     update = boolean holding whether position was updated.
246 	 *
247 	 * Returns: %TRUE if the seek could be performed.
248 	 */
249 	public bool doSeek(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, ulong start, GstSeekType stopType, ulong stop, ref bool update)
250 	{
251 		int outupdate = (update ? 1 : 0);
252 
253 		auto p = gst_segment_do_seek(gstSegment, rate, format, flags, startType, start, stopType, stop, &outupdate) != 0;
254 
255 		update = (outupdate == 1);
256 
257 		return p;
258 	}
259 
260 	/**
261 	 * Free the allocated segment @segment.
262 	 */
263 	public void free()
264 	{
265 		gst_segment_free(gstSegment);
266 		ownedRef = false;
267 	}
268 
269 	/**
270 	 * The start/position fields are set to 0 and the stop/duration
271 	 * fields are set to -1 (unknown). The default rate of 1.0 and no
272 	 * flags are set.
273 	 *
274 	 * Initialize @segment to its default values.
275 	 *
276 	 * Params:
277 	 *     format = the format of the segment.
278 	 */
279 	public void init(GstFormat format)
280 	{
281 		gst_segment_init(gstSegment, format);
282 	}
283 
284 	/**
285 	 * Checks for two segments being equal. Equality here is defined
286 	 * as perfect equality, including floating point values.
287 	 *
288 	 * Params:
289 	 *     s1 = a #GstSegment structure.
290 	 *
291 	 * Returns: %TRUE if the segments are equal, %FALSE otherwise.
292 	 *
293 	 * Since: 1.6
294 	 */
295 	public bool isEqual(Segment s1)
296 	{
297 		return gst_segment_is_equal(gstSegment, (s1 is null) ? null : s1.getSegmentStruct()) != 0;
298 	}
299 
300 	/**
301 	 * Adjust the values in @segment so that @offset is applied to all
302 	 * future running-time calculations.
303 	 *
304 	 * Params:
305 	 *     format = the format of the segment.
306 	 *     offset = the offset to apply in the segment
307 	 *
308 	 * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
309 	 *     returned, @offset is not in @segment.
310 	 *
311 	 * Since: 1.2.3
312 	 */
313 	public bool offsetRunningTime(GstFormat format, long offset)
314 	{
315 		return gst_segment_offset_running_time(gstSegment, format, offset) != 0;
316 	}
317 
318 	/**
319 	 * Convert @running_time into a position in the segment so that
320 	 * gst_segment_to_running_time() with that position returns @running_time.
321 	 *
322 	 * Params:
323 	 *     format = the format of the segment.
324 	 *     runningTime = the running_time in the segment
325 	 *
326 	 * Returns: the position in the segment for @running_time. This function returns
327 	 *     -1 when @running_time is -1 or when it is not inside @segment.
328 	 *
329 	 * Since: 1.8
330 	 */
331 	public ulong positionFromRunningTime(GstFormat format, ulong runningTime)
332 	{
333 		return gst_segment_position_from_running_time(gstSegment, format, runningTime);
334 	}
335 
336 	/**
337 	 * Translate @running_time to the segment position using the currently configured
338 	 * segment. Compared to gst_segment_position_from_running_time() this function can
339 	 * return negative segment position.
340 	 *
341 	 * This function is typically used by elements that need to synchronize buffers
342 	 * against the clock or each other.
343 	 *
344 	 * @running_time can be any value and the result of this function for values
345 	 * outside of the segment is extrapolated.
346 	 *
347 	 * When 1 is returned, @running_time resulted in a positive position returned
348 	 * in @position.
349 	 *
350 	 * When this function returns -1, the returned @position should be negated
351 	 * to get the real negative segment 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 eachother.
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 eachother.
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 }