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  * Conversion parameters:
26  * inFile  = GstClock.html
27  * outPack = gstreamer
28  * outFile = Clock
29  * strct   = GstClock
30  * realStrct=
31  * ctorStrct=
32  * clss    = Clock
33  * interf  = 
34  * class Code: No
35  * interface Code: No
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- gst_clock_
41  * 	- gst_
42  * omit structs:
43  * omit prefixes:
44  * omit code:
45  * omit signals:
46  * imports:
47  * 	- glib.Str
48  * structWrap:
49  * 	- GstClock* -> Clock
50  * module aliases:
51  * local aliases:
52  * overrides:
53  */
54 
55 module gstreamer.Clock;
56 
57 public  import gstreamerc.gstreamertypes;
58 
59 private import gstreamerc.gstreamer;
60 private import glib.ConstructionException;
61 private import gobject.ObjectG;
62 
63 
64 private import glib.Str;
65 
66 
67 
68 private import gstreamer.ObjectGst;
69 
70 /**
71  * Description
72  * GStreamer uses a global clock to synchronize the plugins in a pipeline.
73  * Different clock implementations are possible by implementing this abstract
74  * base class.
75  * The GstClock returns a monotonically increasing time with the method
76  * gst_clock_get_time(). Its accuracy and base time depend on the specific
77  * clock implementation but time is always expressed in nanoseconds. Since the
78  * baseline of the clock is undefined, the clock time returned is not
79  * meaningful in itself, what matters are the deltas between two clock times.
80  * The time returned by a clock is called the absolute time.
81  * The pipeline uses the clock to calculate the stream time. Usually all
82  * renderers synchronize to the global clock using the buffer timestamps, the
83  * newsegment events and the element's base time, see GstPipeline.
84  * A clock implementation can support periodic and single shot clock
85  * notifications both synchronous and asynchronous.
86  * One first needs to create a GstClockID for the periodic or single shot
87  * notification using gst_clock_new_single_shot_id() or
88  * gst_clock_new_periodic_id().
89  * To perform a blocking wait for the specific time of the GstClockID use the
90  * gst_clock_id_wait(). To receive a callback when the specific time is reached
91  * in the clock use gst_clock_id_wait_async(). Both these calls can be
92  * interrupted with the gst_clock_id_unschedule() call. If the blocking wait is
93  * unscheduled a return value of GST_CLOCK_UNSCHEDULED is returned.
94  * Periodic callbacks scheduled async will be repeadedly called automatically
95  * until it is unscheduled. To schedule a sync periodic callback,
96  * gst_clock_id_wait() should be called repeadedly.
97  * The async callbacks can happen from any thread, either provided by the core
98  * or from a streaming thread. The application should be prepared for this.
99  * A GstClockID that has been unscheduled cannot be used again for any wait
100  * operation, a new GstClockID should be created and the old unscheduled one
101  * should be destroyed wirth gst_clock_id_unref().
102  * It is possible to perform a blocking wait on the same GstClockID from
103  * multiple threads. However, registering the same GstClockID for multiple
104  * async notifications is not possible, the callback will only be called for
105  * the thread registering the entry last.
106  * None of the wait operations unref the GstClockID, the owner is responsible
107  * for unreffing the ids itself. This holds for both periodic and single shot
108  * notifications. The reason being that the owner of the GstClockID has to
109  * keep a handle to the GstClockID to unblock the wait on FLUSHING events or
110  * state changes and if the entry would be unreffed automatically, the handle
111  * might become invalid without any notification.
112  * These clock operations do not operate on the stream time, so the callbacks
113  * will also occur when not in PLAYING state as if the clock just keeps on
114  * running. Some clocks however do not progress when the element that provided
115  * the clock is not PLAYING.
116  * When a clock has the GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be
117  * slaved to another GstClock with the gst_clock_set_master(). The clock will
118  * then automatically be synchronized to this master clock by repeadedly
119  * sampling the master clock and the slave clock and recalibrating the slave
120  * clock with gst_clock_set_calibration(). This feature is mostly useful for
121  * plugins that have an internal clock but must operate with another clock
122  * selected by the GstPipeline. They can track the offset and rate difference
123  * of their internal clock relative to the master clock by using the
124  * gst_clock_get_calibration() function.
125  * The master/slave synchronisation can be tuned with the "timeout", "window-size"
126  * and "window-threshold" properties. The "timeout" property defines the interval
127  * to sample the master clock and run the calibration functions.
128  * "window-size" defines the number of samples to use when calibrating and
129  * "window-threshold" defines the minimum number of samples before the
130  * calibration is performed.
131  * Last reviewed on 2006-08-11 (0.10.10)
132  */
133 public class Clock : ObjectGst
134 {
135 	
136 	/** the main Gtk struct */
137 	protected GstClock* gstClock;
138 	
139 	
140 	public GstClock* getClockStruct()
141 	{
142 		return gstClock;
143 	}
144 	
145 	
146 	/** the main Gtk struct as a void* */
147 	protected override void* getStruct()
148 	{
149 		return cast(void*)gstClock;
150 	}
151 	
152 	/**
153 	 * Sets our main struct and passes it to the parent class
154 	 */
155 	public this (GstClock* gstClock)
156 	{
157 		super(cast(GstObject*)gstClock);
158 		this.gstClock = gstClock;
159 	}
160 	
161 	protected override void setStruct(GObject* obj)
162 	{
163 		super.setStruct(obj);
164 		gstClock = cast(GstClock*)obj;
165 	}
166 	
167 	/**
168 	 */
169 	
170 	/**
171 	 * The time master of the master clock and the time slave of the slave
172 	 * clock are added to the list of observations. If enough observations
173 	 * are available, a linear regression algorithm is run on the
174 	 * observations and clock is recalibrated.
175 	 * If this functions returns TRUE, r_squared will contain the
176 	 * correlation coefficient of the interpollation. A value of 1.0
177 	 * means a perfect regression was performed. This value can
178 	 * be used to control the sampling frequency of the master and slave
179 	 * clocks.
180 	 * Params:
181 	 * slave = a time on the slave
182 	 * master = a time on the master
183 	 * rSquared = a pointer to hold the result
184 	 * Returns: TRUE if enough observations were added to run the regression algorithm. MT safe.
185 	 */
186 	public int addObservation(GstClockTime slave, GstClockTime master, out double rSquared)
187 	{
188 		// gboolean gst_clock_add_observation (GstClock *clock,  GstClockTime slave,  GstClockTime master,  gdouble *r_squared);
189 		return gst_clock_add_observation(gstClock, slave, master, &rSquared);
190 	}
191 	
192 	/**
193 	 * Set master as the master clock for clock. clock will be automatically
194 	 * calibrated so that gst_clock_get_time() reports the same time as the
195 	 * master clock.
196 	 * A clock provider that slaves its clock to a master can get the current
197 	 * calibration values with gst_clock_get_calibration().
198 	 * master can be NULL in which case clock will not be slaved anymore. It will
199 	 * however keep reporting its time adjusted with the last configured rate
200 	 * and time offsets.
201 	 * Params:
202 	 * master = a master GstClock
203 	 * Returns: TRUE if the clock is capable of being slaved to a master clock. Trying to set a master on a clock without the GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return FALSE. MT safe.
204 	 */
205 	public int setMaster(Clock master)
206 	{
207 		// gboolean gst_clock_set_master (GstClock *clock,  GstClock *master);
208 		return gst_clock_set_master(gstClock, (master is null) ? null : master.getClockStruct());
209 	}
210 	
211 	/**
212 	 * Get the master clock that clock is slaved to or NULL when the clock is
213 	 * not slaved to any master clock.
214 	 * Returns: a master GstClock or NULL when this clock is not slaved to a master clock. Unref after usage. MT safe.
215 	 */
216 	public Clock getMaster()
217 	{
218 		// GstClock* gst_clock_get_master (GstClock *clock);
219 		auto p = gst_clock_get_master(gstClock);
220 		
221 		if(p is null)
222 		{
223 			return null;
224 		}
225 		
226 		return ObjectG.getDObject!(Clock)(cast(GstClock*) p);
227 	}
228 	
229 	/**
230 	 * Set the accuracy of the clock. Some clocks have the possibility to operate
231 	 * with different accuracy at the expense of more resource usage. There is
232 	 * normally no need to change the default resolution of a clock. The resolution
233 	 * of a clock can only be changed if the clock has the
234 	 * GST_CLOCK_FLAG_CAN_SET_RESOLUTION flag set.
235 	 * Params:
236 	 * resolution = The resolution to set
237 	 * Returns: the new resolution of the clock.
238 	 */
239 	public GstClockTime setResolution(GstClockTime resolution)
240 	{
241 		// GstClockTime gst_clock_set_resolution (GstClock *clock,  GstClockTime resolution);
242 		return gst_clock_set_resolution(gstClock, resolution);
243 	}
244 	
245 	/**
246 	 * Get the accuracy of the clock. The accuracy of the clock is the granularity
247 	 * of the values returned by gst_clock_get_time().
248 	 * Returns: the resolution of the clock in units of GstClockTime. MT safe.
249 	 */
250 	public GstClockTime getResolution()
251 	{
252 		// GstClockTime gst_clock_get_resolution (GstClock *clock);
253 		return gst_clock_get_resolution(gstClock);
254 	}
255 	
256 	/**
257 	 * Gets the current time of the given clock. The time is always
258 	 * monotonically increasing and adjusted according to the current
259 	 * offset and rate.
260 	 * Returns: the time of the clock. Or GST_CLOCK_TIME_NONE when giving wrong input. MT safe.
261 	 */
262 	public GstClockTime getTime()
263 	{
264 		// GstClockTime gst_clock_get_time (GstClock *clock);
265 		return gst_clock_get_time(gstClock);
266 	}
267 	
268 	/**
269 	 * Get a GstClockID from clock to trigger a single shot
270 	 * notification at the requested time. The single shot id should be
271 	 * unreffed after usage.
272 	 * Params:
273 	 * time = the requested time
274 	 * Returns: A GstClockID that can be used to request the time notification. MT safe.
275 	 */
276 	public GstClockID newSingleShotId(GstClockTime time)
277 	{
278 		// GstClockID gst_clock_new_single_shot_id (GstClock *clock,  GstClockTime time);
279 		return gst_clock_new_single_shot_id(gstClock, time);
280 	}
281 	
282 	/**
283 	 * Get an ID from clock to trigger a periodic notification.
284 	 * The periodeic notifications will be start at time start_time and
285 	 * will then be fired with the given interval. id should be unreffed
286 	 * after usage.
287 	 * Params:
288 	 * startTime = the requested start time
289 	 * interval = the requested interval
290 	 * Returns: A GstClockID that can be used to request the time notification. MT safe.
291 	 */
292 	public GstClockID newPeriodicId(GstClockTime startTime, GstClockTime interval)
293 	{
294 		// GstClockID gst_clock_new_periodic_id (GstClock *clock,  GstClockTime start_time,  GstClockTime interval);
295 		return gst_clock_new_periodic_id(gstClock, startTime, interval);
296 	}
297 	
298 	/**
299 	 * Gets the current internal time of the given clock. The time is returned
300 	 * unadjusted for the offset and the rate.
301 	 * Returns: the internal time of the clock. Or GST_CLOCK_TIME_NONE when giving wrong input. MT safe.
302 	 */
303 	public GstClockTime getInternalTime()
304 	{
305 		// GstClockTime gst_clock_get_internal_time (GstClock *clock);
306 		return gst_clock_get_internal_time(gstClock);
307 	}
308 	
309 	/**
310 	 * Converts the given internal clock time to the external time, adjusting for the
311 	 * rate and reference time set with gst_clock_set_calibration() and making sure
312 	 * that the returned time is increasing. This function should be called with the
313 	 * clock's OBJECT_LOCK held and is mainly used by clock subclasses.
314 	 * This function is te reverse of gst_clock_unadjust_unlocked().
315 	 * Params:
316 	 * internal = a clock time
317 	 * Returns: the converted time of the clock.
318 	 */
319 	public GstClockTime adjustUnlocked(GstClockTime internal)
320 	{
321 		// GstClockTime gst_clock_adjust_unlocked (GstClock *clock,  GstClockTime internal);
322 		return gst_clock_adjust_unlocked(gstClock, internal);
323 	}
324 	
325 	/**
326 	 * Converts the given external clock time to the internal time of clock,
327 	 * using the rate and reference time set with gst_clock_set_calibration().
328 	 * This function should be called with the clock's OBJECT_LOCK held and
329 	 * is mainly used by clock subclasses.
330 	 * This function is te reverse of gst_clock_adjust_unlocked().
331 	 * Params:
332 	 * external = an external clock time
333 	 * Returns: the internal time of the clock corresponding to external. Since 0.10.13
334 	 */
335 	public GstClockTime unadjustUnlocked(GstClockTime external)
336 	{
337 		// GstClockTime gst_clock_unadjust_unlocked (GstClock *clock,  GstClockTime external);
338 		return gst_clock_unadjust_unlocked(gstClock, external);
339 	}
340 	
341 	/**
342 	 * Gets the internal rate and reference time of clock. See
343 	 * gst_clock_set_calibration() for more information.
344 	 * internal, external, rate_num, and rate_denom can be left NULL if the
345 	 * caller is not interested in the values.
346 	 * MT safe.
347 	 * Params:
348 	 * internal = a location to store the internal time
349 	 * external = a location to store the external time
350 	 * rateNum = a location to store the rate numerator
351 	 * rateDenom = a location to store the rate denominator
352 	 */
353 	public void getCalibration(out GstClockTime internal, out GstClockTime external, out GstClockTime rateNum, out GstClockTime rateDenom)
354 	{
355 		// void gst_clock_get_calibration (GstClock *clock,  GstClockTime *internal,  GstClockTime *external,  GstClockTime *rate_num,  GstClockTime *rate_denom);
356 		gst_clock_get_calibration(gstClock, &internal, &external, &rateNum, &rateDenom);
357 	}
358 	
359 	/**
360 	 * Adjusts the rate and time of clock. A rate of 1/1 is the normal speed of
361 	 * the clock. Values bigger than 1/1 make the clock go faster.
362 	 * internal and external are calibration parameters that arrange that
363 	 * gst_clock_get_time() should have been external at internal time internal.
364 	 * This internal time should not be in the future; that is, it should be less
365 	 * than the value of gst_clock_get_internal_time() when this function is called.
366 	 * Subsequent calls to gst_clock_get_time() will return clock times computed as
367 	 * Params:
368 	 * internal = a reference internal time
369 	 * external = a reference external time
370 	 * rateNum = the numerator of the rate of the clock relative to its
371 	 *  internal time
372 	 * rateDenom = the denominator of the rate of the clock
373 	 */
374 	public void setCalibration(GstClockTime internal, GstClockTime external, GstClockTime rateNum, GstClockTime rateDenom)
375 	{
376 		// void gst_clock_set_calibration (GstClock *clock,  GstClockTime internal,  GstClockTime external,  GstClockTime rate_num,  GstClockTime rate_denom);
377 		gst_clock_set_calibration(gstClock, internal, external, rateNum, rateDenom);
378 	}
379 	
380 	/**
381 	 * Get the time of the clock ID
382 	 * Params:
383 	 * id = The GstClockID to query
384 	 * Returns: the time of the given clock id. MT safe.
385 	 */
386 	public static GstClockTime idGetTime(GstClockID id)
387 	{
388 		// GstClockTime gst_clock_id_get_time (GstClockID id);
389 		return gst_clock_id_get_time(id);
390 	}
391 	
392 	/**
393 	 * Perform a blocking wait on id.
394 	 * id should have been created with gst_clock_new_single_shot_id()
395 	 * or gst_clock_new_periodic_id() and should not have been unscheduled
396 	 * with a call to gst_clock_id_unschedule().
397 	 * If the jitter argument is not NULL and this function returns GST_CLOCK_OK
398 	 * or GST_CLOCK_EARLY, it will contain the difference
399 	 * against the clock and the time of id when this method was
400 	 * called.
401 	 * Positive values indicate how late id was relative to the clock
402 	 * (in which case this function will return GST_CLOCK_EARLY).
403 	 * Negative values indicate how much time was spent waiting on the clock
404 	 * before this function returned.
405 	 * Params:
406 	 * id = The GstClockID to wait on
407 	 * jitter = A pointer that will contain the jitter, can be NULL.
408 	 * Returns: the result of the blocking wait. GST_CLOCK_EARLY will be returned if the current clock time is past the time of id, GST_CLOCK_OK if id was scheduled in time. GST_CLOCK_UNSCHEDULED if id was unscheduled with gst_clock_id_unschedule(). MT safe.
409 	 */
410 	public static GstClockReturn idWait(GstClockID id, ref GstClockTimeDiff jitter)
411 	{
412 		// GstClockReturn gst_clock_id_wait (GstClockID id,  GstClockTimeDiff *jitter);
413 		return gst_clock_id_wait(id, &jitter);
414 	}
415 	
416 	/**
417 	 * Register a callback on the given GstClockID id with the given
418 	 * function and user_data. When passing a GstClockID with an invalid
419 	 * time to this function, the callback will be called immediatly
420 	 * with a time set to GST_CLOCK_TIME_NONE. The callback will
421 	 * be called when the time of id has been reached.
422 	 * Params:
423 	 * id = a GstClockID to wait on
424 	 * func = The callback function
425 	 * userData = User data passed in the calback
426 	 * Returns: the result of the non blocking wait. MT safe.
427 	 */
428 	public static GstClockReturn idWaitAsync(GstClockID id, GstClockCallback func, void* userData)
429 	{
430 		// GstClockReturn gst_clock_id_wait_async (GstClockID id,  GstClockCallback func,  gpointer user_data);
431 		return gst_clock_id_wait_async(id, func, userData);
432 	}
433 	
434 	/**
435 	 * Cancel an outstanding request with id. This can either
436 	 * be an outstanding async notification or a pending sync notification.
437 	 * After this call, id cannot be used anymore to receive sync or
438 	 * async notifications, you need to create a new GstClockID.
439 	 * MT safe.
440 	 * Params:
441 	 * id = The id to unschedule
442 	 */
443 	public static void idUnschedule(GstClockID id)
444 	{
445 		// void gst_clock_id_unschedule (GstClockID id);
446 		gst_clock_id_unschedule(id);
447 	}
448 	
449 	/**
450 	 * Compares the two GstClockID instances. This function can be used
451 	 * as a GCompareFunc when sorting ids.
452 	 * Params:
453 	 * id1 = A GstClockID
454 	 * id2 = A GstClockID to compare with
455 	 * Returns: negative value if a < b; zero if a = b; positive value if a > b MT safe.
456 	 */
457 	public static int idCompareFunc(void* id1, void* id2)
458 	{
459 		// gint gst_clock_id_compare_func (gconstpointer id1,  gconstpointer id2);
460 		return gst_clock_id_compare_func(id1, id2);
461 	}
462 	
463 	/**
464 	 * Increase the refcount of given id.
465 	 * Params:
466 	 * id = The GstClockID to ref
467 	 * Returns: The same GstClockID with increased refcount. MT safe.
468 	 */
469 	public static GstClockID idRef(GstClockID id)
470 	{
471 		// GstClockID gst_clock_id_ref (GstClockID id);
472 		return gst_clock_id_ref(id);
473 	}
474 	
475 	/**
476 	 * Unref given id. When the refcount reaches 0 the
477 	 * GstClockID will be freed.
478 	 * MT safe.
479 	 * Params:
480 	 * id = The GstClockID to unref
481 	 */
482 	public static void idUnref(GstClockID id)
483 	{
484 		// void gst_clock_id_unref (GstClockID id);
485 		gst_clock_id_unref(id);
486 	}
487 }