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 gstreamerc.gstreamer;
30 public  import gstreamerc.gstreamertypes;
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 should be negated
350 	 * to get the real negative segment position.
351 	 *
352 	 * Params:
353 	 *     format = the format of the segment.
354 	 *     runningTime = the running-time
355 	 *     position = the resulting position in the segment
356 	 *
357 	 * Returns: a 1 or -1 on success, 0 on failure.
358 	 *
359 	 * Since: 1.8
360 	 */
361 	public int positionFromRunningTimeFull(GstFormat format, ulong runningTime, ulong* position)
362 	{
363 		return gst_segment_position_from_running_time_full(gstSegment, format, runningTime, position);
364 	}
365 
366 	/**
367 	 * Convert @stream_time into a position in the segment so that
368 	 * gst_segment_to_stream_time() with that position returns @stream_time.
369 	 *
370 	 * Params:
371 	 *     format = the format of the segment.
372 	 *     streamTime = the stream_time in the segment
373 	 *
374 	 * Returns: the position in the segment for @stream_time. This function returns
375 	 *     -1 when @stream_time is -1 or when it is not inside @segment.
376 	 *
377 	 * Since: 1.8
378 	 */
379 	public ulong positionFromStreamTime(GstFormat format, ulong streamTime)
380 	{
381 		return gst_segment_position_from_stream_time(gstSegment, format, streamTime);
382 	}
383 
384 	/**
385 	 * Translate @stream_time to the segment position using the currently configured
386 	 * segment. Compared to gst_segment_position_from_stream_time() this function can
387 	 * return negative segment position.
388 	 *
389 	 * This function is typically used by elements that need to synchronize buffers
390 	 * against the clock or each other.
391 	 *
392 	 * @stream_time can be any value and the result of this function for values outside
393 	 * of the segment is extrapolated.
394 	 *
395 	 * When 1 is returned, @stream_time resulted in a positive position returned
396 	 * in @position.
397 	 *
398 	 * When this function returns -1, the returned @position should be negated
399 	 * to get the real negative segment position.
400 	 *
401 	 * Params:
402 	 *     format = the format of the segment.
403 	 *     streamTime = the stream-time
404 	 *     position = the resulting position in the segment
405 	 *
406 	 * Returns: a 1 or -1 on success, 0 on failure.
407 	 *
408 	 * Since: 1.8
409 	 */
410 	public int positionFromStreamTimeFull(GstFormat format, ulong streamTime, ulong* position)
411 	{
412 		return gst_segment_position_from_stream_time_full(gstSegment, format, streamTime, position);
413 	}
414 
415 	/**
416 	 * Adjust the start/stop and base values of @segment such that the next valid
417 	 * buffer will be one with @running_time.
418 	 *
419 	 * Params:
420 	 *     format = the format of the segment.
421 	 *     runningTime = the running_time in the segment
422 	 *
423 	 * Returns: %TRUE if the segment could be updated successfully. If %FALSE is
424 	 *     returned, @running_time is -1 or not in @segment.
425 	 */
426 	public bool setRunningTime(GstFormat format, ulong runningTime)
427 	{
428 		return gst_segment_set_running_time(gstSegment, format, runningTime) != 0;
429 	}
430 
431 	/**
432 	 * Convert @running_time into a position in the segment so that
433 	 * gst_segment_to_running_time() with that position returns @running_time.
434 	 *
435 	 * Params:
436 	 *     format = the format of the segment.
437 	 *     runningTime = the running_time in the segment
438 	 *
439 	 * Returns: the position in the segment for @running_time. This function returns
440 	 *     -1 when @running_time is -1 or when it is not inside @segment.
441 	 *
442 	 *     Deprecated. Use gst_segment_position_from_running_time() instead.
443 	 */
444 	public ulong toPosition(GstFormat format, ulong runningTime)
445 	{
446 		return gst_segment_to_position(gstSegment, format, runningTime);
447 	}
448 
449 	/**
450 	 * Translate @position to the total running time using the currently configured
451 	 * segment. Position is a value between @segment start and stop time.
452 	 *
453 	 * This function is typically used by elements that need to synchronize to the
454 	 * global clock in a pipeline. The running time is a constantly increasing value
455 	 * starting from 0. When gst_segment_init() is called, this value will reset to
456 	 * 0.
457 	 *
458 	 * This function returns -1 if the position is outside of @segment start and stop.
459 	 *
460 	 * Params:
461 	 *     format = the format of the segment.
462 	 *     position = the position in the segment
463 	 *
464 	 * Returns: the position as the total running time or -1 when an invalid position
465 	 *     was given.
466 	 */
467 	public ulong toRunningTime(GstFormat format, ulong position)
468 	{
469 		return gst_segment_to_running_time(gstSegment, format, position);
470 	}
471 
472 	/**
473 	 * Translate @position to the total running time using the currently configured
474 	 * segment. Compared to gst_segment_to_running_time() this function can return
475 	 * negative running-time.
476 	 *
477 	 * This function is typically used by elements that need to synchronize buffers
478 	 * against the clock or eachother.
479 	 *
480 	 * @position can be any value and the result of this function for values outside
481 	 * of the segment is extrapolated.
482 	 *
483 	 * When 1 is returned, @position resulted in a positive running-time returned
484 	 * in @running_time.
485 	 *
486 	 * When this function returns -1, the returned @running_time should be negated
487 	 * to get the real negative running time.
488 	 *
489 	 * Params:
490 	 *     format = the format of the segment.
491 	 *     position = the position in the segment
492 	 *     runningTime = result running-time
493 	 *
494 	 * Returns: a 1 or -1 on success, 0 on failure.
495 	 *
496 	 * Since: 1.6
497 	 */
498 	public int toRunningTimeFull(GstFormat format, ulong position, ulong* runningTime)
499 	{
500 		return gst_segment_to_running_time_full(gstSegment, format, position, runningTime);
501 	}
502 
503 	/**
504 	 * Translate @position to stream time using the currently configured
505 	 * segment. The @position value must be between @segment start and
506 	 * stop value.
507 	 *
508 	 * This function is typically used by elements that need to operate on
509 	 * the stream time of the buffers it receives, such as effect plugins.
510 	 * In those use cases, @position is typically the buffer timestamp or
511 	 * clock time that one wants to convert to the stream time.
512 	 * The stream time is always between 0 and the total duration of the
513 	 * media stream.
514 	 *
515 	 * Params:
516 	 *     format = the format of the segment.
517 	 *     position = the position in the segment
518 	 *
519 	 * Returns: the position in stream_time or -1 when an invalid position
520 	 *     was given.
521 	 *
522 	 * Since: 1.8
523 	 */
524 	public ulong toStreamTime(GstFormat format, ulong position)
525 	{
526 		return gst_segment_to_stream_time(gstSegment, format, position);
527 	}
528 
529 	/**
530 	 * Translate @position to the total stream time using the currently configured
531 	 * segment. Compared to gst_segment_to_stream_time() this function can return
532 	 * negative stream-time.
533 	 *
534 	 * This function is typically used by elements that need to synchronize buffers
535 	 * against the clock or eachother.
536 	 *
537 	 * @position can be any value and the result of this function for values outside
538 	 * of the segment is extrapolated.
539 	 *
540 	 * When 1 is returned, @position resulted in a positive stream-time returned
541 	 * in @stream_time.
542 	 *
543 	 * When this function returns -1, the returned @stream_time should be negated
544 	 * to get the real negative stream time.
545 	 *
546 	 * Params:
547 	 *     format = the format of the segment.
548 	 *     position = the position in the segment
549 	 *     streamTime = result stream-time
550 	 *
551 	 * Returns: a 1 or -1 on success, 0 on failure.
552 	 *
553 	 * Since: 1.8
554 	 */
555 	public int toStreamTimeFull(GstFormat format, ulong position, ulong* streamTime)
556 	{
557 		return gst_segment_to_stream_time_full(gstSegment, format, position, streamTime);
558 	}
559 }