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
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT

use glib::object::Cast;
use glib::object::ObjectType as ObjectType_;
use glib::signal::connect_raw;
use glib::signal::SignalHandlerId;
use glib::translate::*;
use glib::StaticType;
use glib::ToValue;
use std::boxed::Box as Box_;
use std::mem::transmute;

glib::wrapper! {
    /// GstTestClock is an implementation of [`crate::gst::Clock`] which has different
    /// behaviour compared to [`crate::gst::SystemClock`]. Time for [`crate::gst::SystemClock`] advances
    /// according to the system time, while time for [`crate::TestClock`] changes only
    /// when [`Self::set_time()`] or [`Self::advance_time()`] are
    /// called. [`crate::TestClock`] provides unit tests with the possibility to
    /// precisely advance the time in a deterministic manner, independent of the
    /// system time or any other external factors.
    ///
    /// ## Advancing the time of a [`crate::TestClock`]
    ///
    ///
    /// ```C
    ///   #include <gst/gst.h>
    ///   #include <gst/check/gsttestclock.h>
    ///
    ///   GstClock *clock;
    ///   GstTestClock *test_clock;
    ///
    ///   clock = gst_test_clock_new ();
    ///   test_clock = GST_TEST_CLOCK (clock);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   gst_test_clock_advance_time ( test_clock, 1 * GST_SECOND);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   g_usleep (10 * G_USEC_PER_SEC);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   gst_test_clock_set_time (test_clock, 42 * GST_SECOND);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   ...
    /// ```
    ///
    /// [`crate::gst::Clock`] allows for setting up single shot or periodic clock notifications
    /// as well as waiting for these notifications synchronously (using
    /// [`crate::gst::Clock::id_wait()`]) or asynchronously (using [`crate::gst::Clock::id_wait_async()`] or
    /// [`crate::gst::Clock::id_wait_async()`]). This is used by many GStreamer elements,
    /// among them `GstBaseSrc` and `GstBaseSink`.
    ///
    /// [`crate::TestClock`] keeps track of these clock notifications. By calling
    /// [`Self::wait_for_next_pending_id()`] or
    /// [`Self::wait_for_multiple_pending_ids()`] a unit tests may wait for the
    /// next one or several clock notifications to be requested. Additionally unit
    /// tests may release blocked waits in a controlled fashion by calling
    /// [`Self::process_next_clock_id()`]. This way a unit test can control the
    /// inaccuracy (jitter) of clock notifications, since the test can decide to
    /// release blocked waits when the clock time has advanced exactly to, or past,
    /// the requested clock notification time.
    ///
    /// There are also interfaces for determining if a notification belongs to a
    /// [`crate::TestClock`] or not, as well as getting the number of requested clock
    /// notifications so far.
    ///
    /// N.B.: When a unit test waits for a certain amount of clock notifications to
    /// be requested in [`Self::wait_for_next_pending_id()`] or
    /// [`Self::wait_for_multiple_pending_ids()`] then these functions may block
    /// for a long time. If they block forever then the expected clock notifications
    /// were never requested from [`crate::TestClock`], and so the assumptions in the code
    /// of the unit test are wrong. The unit test case runner in gstcheck is
    /// expected to catch these cases either by the default test case timeout or the
    /// one set for the unit test by calling tcase_set_timeout\(\).
    ///
    /// The sample code below assumes that the element under test will delay a
    /// buffer pushed on the source pad by some latency until it arrives on the sink
    /// pad. Moreover it is assumed that the element will at some point call
    /// [`crate::gst::Clock::id_wait()`] to synchronously wait for a specific time. The first
    /// buffer sent will arrive exactly on time only delayed by the latency. The
    /// second buffer will arrive a little late (7ms) due to simulated jitter in the
    /// clock notification.
    ///
    /// ## Demonstration of how to work with clock notifications and [`crate::TestClock`]
    ///
    ///
    /// ```C
    ///   #include <gst/gst.h>
    ///   #include <gst/check/gstcheck.h>
    ///   #include <gst/check/gsttestclock.h>
    ///
    ///   GstClockTime latency;
    ///   GstElement *element;
    ///   GstPad *srcpad;
    ///   GstClock *clock;
    ///   GstTestClock *test_clock;
    ///   GstBuffer buf;
    ///   GstClockID pending_id;
    ///   GstClockID processed_id;
    ///
    ///   latency = 42 * GST_MSECOND;
    ///   element = create_element (latency, ...);
    ///   srcpad = get_source_pad (element);
    ///
    ///   clock = gst_test_clock_new ();
    ///   test_clock = GST_TEST_CLOCK (clock);
    ///   gst_element_set_clock (element, clock);
    ///
    ///   GST_INFO ("Set time, create and push the first buffer\n");
    ///   gst_test_clock_set_time (test_clock, 0);
    ///   buf = create_test_buffer (gst_clock_get_time (clock), ...);
    ///   gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
    ///
    ///   GST_INFO ("Block until element is waiting for a clock notification\n");
    ///   gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
    ///   GST_INFO ("Advance to the requested time of the clock notification\n");
    ///   gst_test_clock_advance_time (test_clock, latency);
    ///   GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
    ///   processed_id = gst_test_clock_process_next_clock_id (test_clock);
    ///   g_assert (processed_id == pending_id);
    ///   g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
    ///   gst_clock_id_unref (pending_id);
    ///   gst_clock_id_unref (processed_id);
    ///
    ///   GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
    ///   g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
    ///   buf = get_buffer_pushed_by_element (element, ...);
    ///   g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, latency);
    ///   gst_buffer_unref (buf);
    ///   GST_INFO ("Check that element does not wait for any clock notification\n");
    ///   g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
    ///
    ///   GST_INFO ("Set time, create and push the second buffer\n");
    ///   gst_test_clock_advance_time (test_clock, 10 * GST_SECOND);
    ///   buf = create_test_buffer (gst_clock_get_time (clock), ...);
    ///   gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
    ///
    ///   GST_INFO ("Block until element is waiting for a new clock notification\n");
    ///   (gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
    ///   GST_INFO ("Advance past 7ms beyond the requested time of the clock notification\n");
    ///   gst_test_clock_advance_time (test_clock, latency + 7 * GST_MSECOND);
    ///   GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
    ///   processed_id = gst_test_clock_process_next_clock_id (test_clock);
    ///   g_assert (processed_id == pending_id);
    ///   g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
    ///   gst_clock_id_unref (pending_id);
    ///   gst_clock_id_unref (processed_id);
    ///
    ///   GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
    ///   g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
    ///   buf = get_buffer_pushed_by_element (element, ...);
    ///   g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==,
    ///       10 * GST_SECOND + latency + 7 * GST_MSECOND);
    ///   gst_buffer_unref (buf);
    ///   GST_INFO ("Check that element does not wait for any clock notification\n");
    ///   g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
    ///   ...
    /// ```
    ///
    /// Since [`crate::TestClock`] is only supposed to be used in unit tests it calls
    /// `g_assert()`, `g_assert_cmpint()` or `g_assert_cmpuint()` to validate all function
    /// arguments. This will highlight any issues with the unit test code itself.
    ///
    /// # Implements
    ///
    /// [`trait@gst::prelude::ClockExt`], [`trait@gst::prelude::ObjectExt`], [`trait@glib::object::ObjectExt`]
    pub struct TestClock(Object<ffi::GstTestClock, ffi::GstTestClockClass>) @extends gst::Clock, gst::Object;

    match fn {
        type_ => || ffi::gst_test_clock_get_type(),
    }
}

impl TestClock {
    /// Creates a new test clock with its time set to zero.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// a [`crate::TestClock`] cast to [`crate::gst::Clock`].
    #[doc(alias = "gst_test_clock_new")]
    pub fn new() -> TestClock {
        assert_initialized_main_thread!();
        unsafe { gst::Clock::from_glib_full(ffi::gst_test_clock_new()).unsafe_cast() }
    }

    /// Creates a new test clock with its time set to the specified time.
    ///
    /// MT safe.
    /// ## `start_time`
    /// a [`crate::gst::ClockTime`] set to the desired start time of the clock.
    ///
    /// # Returns
    ///
    /// a [`crate::TestClock`] cast to [`crate::gst::Clock`].
    #[doc(alias = "gst_test_clock_new_with_start_time")]
    #[doc(alias = "new_with_start_time")]
    pub fn with_start_time(start_time: gst::ClockTime) -> TestClock {
        assert_initialized_main_thread!();
        unsafe {
            gst::Clock::from_glib_full(ffi::gst_test_clock_new_with_start_time(
                start_time.into_glib(),
            ))
            .unsafe_cast()
        }
    }

    /// Advances the time of the `self` by the amount given by `delta`. The
    /// time of `self` is monotonically increasing, therefore providing a
    /// `delta` which is negative or zero is a programming error.
    ///
    /// MT safe.
    /// ## `delta`
    /// a positive [`crate::gst::ClockTimeDiff`] to be added to the time of the clock
    #[doc(alias = "gst_test_clock_advance_time")]
    pub fn advance_time(&self, delta: gst::ClockTimeDiff) {
        unsafe {
            ffi::gst_test_clock_advance_time(self.to_glib_none().0, delta);
        }
    }

    /// A "crank" consists of three steps:
    /// 1: Wait for a [`crate::gst::ClockID`] to be registered with the [`crate::TestClock`].
    /// 2: Advance the [`crate::TestClock`] to the time the [`crate::gst::ClockID`] is waiting, unless
    ///  the clock time is already passed the clock id (Since: 1.18).
    /// 3: Release the [`crate::gst::ClockID`] wait.
    /// A "crank" can be though of as the notion of
    /// manually driving the clock forward to its next logical step.
    ///
    /// # Returns
    ///
    /// [`true`] if the crank was successful, [`false`] otherwise.
    ///
    /// MT safe.
    #[doc(alias = "gst_test_clock_crank")]
    pub fn crank(&self) -> bool {
        unsafe { from_glib(ffi::gst_test_clock_crank(self.to_glib_none().0)) }
    }

    /// Retrieve the requested time for the next pending clock notification.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// a [`crate::gst::ClockTime`] set to the time of the next pending clock
    /// notification. If no clock notifications have been requested
    /// `GST_CLOCK_TIME_NONE` will be returned.
    #[doc(alias = "gst_test_clock_get_next_entry_time")]
    #[doc(alias = "get_next_entry_time")]
    pub fn next_entry_time(&self) -> gst::ClockTime {
        unsafe {
            from_glib(ffi::gst_test_clock_get_next_entry_time(
                self.to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "gst_test_clock_has_id")]
    //pub fn has_id(&self, id: /*Ignored*/gst::ClockID) -> bool {
    //    unsafe { TODO: call ffi:gst_test_clock_has_id() }
    //}

    /// Determine the number of pending clock notifications that have been
    /// requested from the `self`.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// the number of pending clock notifications.
    #[doc(alias = "gst_test_clock_peek_id_count")]
    pub fn peek_id_count(&self) -> u32 {
        unsafe { ffi::gst_test_clock_peek_id_count(self.to_glib_none().0) }
    }

    //#[doc(alias = "gst_test_clock_peek_next_pending_id")]
    //pub fn peek_next_pending_id(&self, pending_id: /*Ignored*/&mut gst::ClockID) -> bool {
    //    unsafe { TODO: call ffi:gst_test_clock_peek_next_pending_id() }
    //}

    //#[cfg(any(feature = "v1_18", feature = "dox"))]
    //#[cfg_attr(feature = "dox", doc(cfg(feature = "v1_18")))]
    //#[doc(alias = "gst_test_clock_process_id")]
    //pub fn process_id(&self, pending_id: /*Ignored*/gst::ClockID) -> bool {
    //    unsafe { TODO: call ffi:gst_test_clock_process_id() }
    //}

    //#[doc(alias = "gst_test_clock_process_id_list")]
    //pub fn process_id_list(&self, pending_list: /*Ignored*/&[&gst::ClockID]) -> u32 {
    //    unsafe { TODO: call ffi:gst_test_clock_process_id_list() }
    //}

    //#[doc(alias = "gst_test_clock_process_next_clock_id")]
    //pub fn process_next_clock_id(&self) -> /*Ignored*/Option<gst::ClockID> {
    //    unsafe { TODO: call ffi:gst_test_clock_process_next_clock_id() }
    //}

    /// Sets the time of `self` to the time given by `new_time`. The time of
    /// `self` is monotonically increasing, therefore providing a `new_time`
    /// which is earlier or equal to the time of the clock as given by
    /// [`crate::gst::prelude::ClockExt::get_time()`] is a programming error.
    ///
    /// MT safe.
    /// ## `new_time`
    /// a [`crate::gst::ClockTime`] later than that returned by [`crate::gst::prelude::ClockExt::get_time()`]
    #[doc(alias = "gst_test_clock_set_time")]
    pub fn set_time(&self, new_time: gst::ClockTime) {
        unsafe {
            ffi::gst_test_clock_set_time(self.to_glib_none().0, new_time.into_glib());
        }
    }

    //#[cfg(any(feature = "v1_16", feature = "dox"))]
    //#[cfg_attr(feature = "dox", doc(cfg(feature = "v1_16")))]
    //#[doc(alias = "gst_test_clock_timed_wait_for_multiple_pending_ids")]
    //pub fn timed_wait_for_multiple_pending_ids(&self, count: u32, timeout_ms: u32, pending_list: /*Unimplemented*/Vec<gst::ClockID>) -> bool {
    //    unsafe { TODO: call ffi:gst_test_clock_timed_wait_for_multiple_pending_ids() }
    //}

    //#[doc(alias = "gst_test_clock_wait_for_multiple_pending_ids")]
    //pub fn wait_for_multiple_pending_ids(&self, count: u32, pending_list: /*Unimplemented*/Vec<gst::ClockID>) {
    //    unsafe { TODO: call ffi:gst_test_clock_wait_for_multiple_pending_ids() }
    //}

    //#[doc(alias = "gst_test_clock_wait_for_next_pending_id")]
    //pub fn wait_for_next_pending_id(&self, pending_id: /*Ignored*/&mut gst::ClockID) {
    //    unsafe { TODO: call ffi:gst_test_clock_wait_for_next_pending_id() }
    //}

    /// Blocks until at least `count` clock notifications have been requested from
    /// `self`. There is no timeout for this wait, see the main description of
    /// [`crate::TestClock`].
    ///
    /// # Deprecated
    ///
    /// use [`Self::wait_for_multiple_pending_ids()`] instead.
    /// ## `count`
    /// the number of pending clock notifications to wait for
    #[doc(alias = "gst_test_clock_wait_for_pending_id_count")]
    pub fn wait_for_pending_id_count(&self, count: u32) {
        unsafe {
            ffi::gst_test_clock_wait_for_pending_id_count(self.to_glib_none().0, count);
        }
    }

    #[doc(alias = "clock-type")]
    pub fn clock_type(&self) -> gst::ClockType {
        unsafe {
            let mut value = glib::Value::from_type(<gst::ClockType as StaticType>::static_type());
            glib::gobject_ffi::g_object_get_property(
                self.as_ptr() as *mut glib::gobject_ffi::GObject,
                b"clock-type\0".as_ptr() as *const _,
                value.to_glib_none_mut().0,
            );
            value
                .get()
                .expect("Return Value for property `clock-type` getter")
        }
    }

    #[doc(alias = "clock-type")]
    pub fn set_clock_type(&self, clock_type: gst::ClockType) {
        unsafe {
            glib::gobject_ffi::g_object_set_property(
                self.as_ptr() as *mut glib::gobject_ffi::GObject,
                b"clock-type\0".as_ptr() as *const _,
                clock_type.to_value().to_glib_none().0,
            );
        }
    }

    #[doc(alias = "start-time")]
    pub fn start_time(&self) -> u64 {
        unsafe {
            let mut value = glib::Value::from_type(<u64 as StaticType>::static_type());
            glib::gobject_ffi::g_object_get_property(
                self.as_ptr() as *mut glib::gobject_ffi::GObject,
                b"start-time\0".as_ptr() as *const _,
                value.to_glib_none_mut().0,
            );
            value
                .get()
                .expect("Return Value for property `start-time` getter")
        }
    }

    //#[doc(alias = "gst_test_clock_id_list_get_latest_time")]
    //pub fn id_list_get_latest_time(pending_list: /*Ignored*/&[&gst::ClockID]) -> gst::ClockTime {
    //    unsafe { TODO: call ffi:gst_test_clock_id_list_get_latest_time() }
    //}

    #[doc(alias = "clock-type")]
    pub fn connect_clock_type_notify<F: Fn(&TestClock) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_clock_type_trampoline<
            F: Fn(&TestClock) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstTestClock,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::clock-type\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_clock_type_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl Default for TestClock {
    fn default() -> Self {
        Self::new()
    }
}

unsafe impl Send for TestClock {}
unsafe impl Sync for TestClock {}