gstreamer-0.12.1.2: Binding to the GStreamer open source multimedia framework.

Portability | portable (depends on GHC)
Stability | alpha
Maintainer | gtk2hs-devel@lists.sourceforge.net
Safe Haskell | None

Media.Streaming.GStreamer.Core.Clock

Contents

- Detail
- Types
- Clock Operations
- Clock Properties

Description

Abstract class of global clocks.

Synopsis

- data Clock
- class ObjectClass o => ClockClass o
- castToClock :: GObjectClass obj => obj -> Clock
- gTypeClock :: GType
- type ClockTime = Word64
- clockTimeNone :: ClockTime
- clockTimeIsValid :: ClockTime -> Bool
- second :: ClockTime
- msecond :: ClockTime
- usecond :: ClockTime
- nsecond :: ClockTime
- type ClockTimeDiff = Int64
- data ClockID
- data ClockReturn
  - = ClockOk
  - | ClockEarly
  - | ClockUnscheduled
  - | ClockBusy
  - | ClockBadtime
  - | ClockError
  - | ClockUnsupported
  - | ClockDone
- data ClockFlags
  - = ClockCanDoSingleSync
  - | ClockCanDoSingleAsync
  - | ClockCanDoPeriodicSync
  - | ClockCanDoPeriodicAsync
  - | ClockCanSetResolution
  - | ClockCanSetMaster
- clockGetFlags :: ClockClass clockT => clockT -> IO [ClockFlags]
- clockSetFlags :: ClockClass clockT => clockT -> [ClockFlags] -> IO ()
- clockUnsetFlags :: ClockClass clockT => clockT -> [ClockFlags] -> IO ()
- clockAddObservation :: ClockClass clock => clock -> ClockTime -> ClockTime -> IO (Maybe Double)
- clockSetMaster :: (ClockClass clock, ClockClass master) => clock -> Maybe master -> IO Bool
- clockGetMaster :: ClockClass clock => clock -> IO (Maybe Clock)
- clockSetResolution :: ClockClass clock => clock -> ClockTime -> IO ClockTime
- clockGetResolution :: ClockClass clock => clock -> IO ClockTime
- clockGetTime :: ClockClass clock => clock -> IO ClockTime
- clockNewSingleShotID :: ClockClass clock => clock -> ClockTime -> IO ClockID
- clockNewPeriodicID :: ClockClass clock => clock -> ClockTime -> ClockTime -> IO ClockID
- clockGetInternalTime :: ClockClass clock => clock -> IO ClockTime
- clockGetCalibration :: ClockClass clock => clock -> IO (ClockTime, ClockTime, Ratio ClockTime)
- clockSetCalibration :: ClockClass clock => clock -> ClockTime -> ClockTime -> Ratio ClockTime -> IO ()
- clockIDGetTime :: ClockID -> IO ClockTime
- clockIDWait :: ClockID -> IO (ClockReturn, Maybe ClockTimeDiff)
- clockIDUnschedule :: ClockID -> IO ()
- clockTimeout :: ClockClass clockT => Attr clockT ClockTime
- clockWindowSize :: ClockClass clockT => Attr clockT Int
- clockWindowThreshold :: ClockClass clockT => Attr clockT Int

# Detail

GStreamer uses a global clock to synchronize the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class.

The `Clock` returns a monotonically increasing time with the method `clockGetTime`. Its accuracy and base time depend on the specific clock implementation but time is always expressed in nanoseconds. Since the baseline of the clock is undefined, the clock time returned is not meaningful in itself, what matters are the deltas between two clock times. The time returned by a clock is called the absolute time.

The pipeline uses the clock to calculate the stream time. Usually all renderers synchronize to the global clock using the buffer timestamps, the newsegment events and the element's base time, see GstPipeline.

A clock implementation can support periodic and single shot clock notifications both synchronous and asynchronous.

One first needs to create a `ClockID` for the periodic or single shot notification using `clockNewSingleShotID` or `clockNewPeriodicID`.

To perform a blocking wait for the specific time of the `ClockID` use `clockIDWait`. This calls can be interrupted with the `clockIDUnschedule` call. If the blocking wait is unscheduled a return value of `ClockUnscheduled` is returned.

Periodic callbacks scheduled async will be repeadedly called automatically until it is unscheduled. To schedule a sync periodic callback, `clockIDWait` should be called repeatedly.

The async callbacks can happen from any thread, either provided by the core or from a streaming thread. The application should be prepared for this.

A `ClockID` that has been unscheduled cannot be used again for any wait operation; a new `ClockID` should be created.

It is possible to perform a blocking wait on the same `ClockID` from multiple threads. However, registering the same `ClockID` for multiple async notifications is not possible, the callback will only be called for the thread registering the entry last.

These clock operations do not operate on the stream time, so the callbacks will also occur when not in the playing state as if the clock just keeps on running. Some clocks however do not progress when the element that provided the clock is not playing.

When a clock has the `ClockFlagCanSetMaster` flag set, it can be slaved to another `Clock` with `clockSetMaster`. The clock will then automatically be synchronized to this master clock by repeatedly sampling the master clock and the slave clock and recalibrating the slave clock with `clockSetCalibration`. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the GstPipeline. They can track the offset and rate difference of their internal clock relative to the master clock by using the `clockGetCalibration` function.

The master/slave synchronisation can be tuned with the the `clockTimeout`, `clockWindowSize` and `clockWindowThreshold` properties. The `clockTimeout` property defines the interval to sample the master clock and run the calibration functions. `clockWindowSize` defines the number of samples to use when calibrating and `clockWindowThreshold` defines the minimum number of samples before the calibration is performed.

# Types

data Clock

Instances

Eq Clock |
Ord Clock |
GObjectClass Clock |
ClockClass Clock |
ObjectClass Clock |

class ObjectClass o => ClockClass o

Instances

ClockClass NetClientClock |
ClockClass SystemClock |
ClockClass AudioClock |
ClockClass Clock |

castToClock :: GObjectClass obj => obj -> Clock

gTypeClock :: GType

A time value measured in nanoseconds.

type ClockTime = Word64

A time value in nanoseconds.

The `ClockTime` value representing an invalid time.

clockTimeNone :: ClockTime

The undefined `ClockTime` value.

clockTimeIsValid

Arguments

:: ClockTime

    clockTime

-> Bool | `True` if `clockTime` is valid, `False` otherwise

Returns `True` if the given `ClockTime` is valid, and `False` otherwise.

The `ClockTime` value representing 1 second, i.e. 1e9.

second :: ClockTime

One second as a `ClockTime` value.

The `ClockTime` value representing 1 millisecond, i.e. 1e6.

msecond :: ClockTime

One millisecond as a `ClockTime` value.

The `ClockTime` value representing 1 microsecond, i.e. 1e3.

usecond :: ClockTime

One microsecond as a `ClockTime` value.

The `ClockTime` value representing 1 nanosecond, i.e. 1.

nsecond :: ClockTime

One nanosecond as a `ClockTime` value.

A value holding the difference between two `ClockTime`s.

type ClockTimeDiff = Int64

An opaque identifier for a timer event.

data ClockID

An enumeration type returned by `clockIDWait`.

data ClockReturn

Constructors

ClockOk |
ClockEarly |
ClockUnscheduled |
ClockBusy |
ClockBadtime |
ClockError |
ClockUnsupported |
ClockDone |

Instances

Enum ClockReturn |
Eq ClockReturn |
Show ClockReturn |

The flags a `Clock` may have.

data ClockFlags

The flags that a `Clock` may have.

Constructors

ClockCanDoSingleSync | the clock can do a single sync timeout request
ClockCanDoSingleAsync | the clock can do a single async timeout request
ClockCanDoPeriodicSync | the clock can do periodic sync timeout requests
ClockCanDoPeriodicAsync | the clock can do periodic async timeout requests
ClockCanSetResolution | the clock's resolution can be changed
ClockCanSetMaster | the clock can be slaved to a master clock

Instances

Bounded ClockFlags |
Enum ClockFlags |
Eq ClockFlags |
Show ClockFlags |
Flags ClockFlags |

clockGetFlags

Arguments

:: ClockClass clockT |

=> clockT

    clock

-> IO [ClockFlags] | the flags currently set on the clock

Get the flags set on the clock.

clockSetFlags

Arguments

:: ClockClass clockT |

=> clockT

    clock

-> [ClockFlags] | `flags` - the flags to be set
-> IO () |

Set the given flags on the clock.

clockUnsetFlags

Arguments

:: ClockClass clockT |

=> clockT

    clock

-> [ClockFlags] | `flags` - the flags to be unset
-> IO () |

Unset the given flags on the clock.

# Clock Operations

clockAddObservation :: ClockClass clock => clock -> ClockTime -> ClockTime -> IO (Maybe Double)

The time master of the master clock and the time slave of the slave clock are added to the list of observations. If enough observations are available, a linear regression algorithm is run on the observations and clock is recalibrated.

If a calibration is performed, the correlation coefficient of the interpolation will be returned. A value of 1.0 means the clocks are in perfect sync. This value can be used to control the sampling frequency of the master and slave clocks.

clockSetMaster

Arguments

:: (ClockClass clock, ClockClass master) |

=> clock

    clock

-> Maybe master

    master

-> IO Bool | `True` if `clock` is capable of being slaved to the `master` clock, otherwise `False`

Set `master` as the master clock for `clock`. The `clock` will automatically be calibrated so that `clockGetTime` reports the same time as the `master` clock.

A clock provider that slaves its clock to a master can get the current calibration values with `clockGetCalibration`.

The `master` clock can be `Nothing` in which case `clock` will not be slaved any longer. It will, however, continue to report its time adjusted using the last configured rate and time offsets.

Note that if `clock` does not have the `ClockFlagCanSetMaster` flag set, this function will not succeed and return `False`.

clockGetMaster

Arguments

:: ClockClass clock |

=> clock

    clock

-> IO (Maybe Clock) | the master that `clock` is slaved to, or `Nothing`

Return the master that `clock` is slaved to, or `Nothing` if `clock` is not slaved.

clockSetResolution :: ClockClass clock => clock -> ClockTime -> IO ClockTime

Set the resolution of `clock`. Some clocks have the possibility to operate with different resolution at the expense of more resource usage. There is normally no need to change the default resolution of a clock. The resolution of a clock can only be changed if the clock has the `ClockFlagCanSetResolution` flag set.

clockGetResolution

Arguments

:: ClockClass clock |
=> clock | `clock` -
-> IO ClockTime | the resolution currently set in `clock`

Get the resolution of the `clock`. The resolution of the clock is the granularity of the values returned by `clockGetTime`.

clockGetTime

Arguments

:: ClockClass clock |

=> clock

    clock

-> IO ClockTime | the current time in `clock`

Get the current time stored in `clock`. The time is always monotonically increasing and adjusted according to the current offset and rate.

clockNewSingleShotID

Arguments

:: ClockClass clock |

=> clock

    clock

-> ClockTime

    clockTime

-> IO ClockID | a single shot notification id triggered at `clockTime`

Get a `ClockID` from `clock` to trigger a single shot notification at the requested time.

clockNewPeriodicID

Arguments

:: ClockClass clock |

=> clock

    clock

-> ClockTime

    startTime

-> ClockTime

    interval

-> IO ClockID | a periodic notification id

Get a `ClockID` from `clock` to trigger periodic notifications. The notifications will start at time `startTime` and then be fired at each `interval` after.

clockGetInternalTime

Arguments

:: ClockClass clock |

=> clock

    clock

-> IO ClockTime | the clock's internal time value

Gets the current internal time of `clock`. The time is returned unadjusted in the offset and rate.

clockGetCalibration

Arguments

:: ClockClass clock |

=> clock

    clock

-> IO (ClockTime, ClockTime, Ratio ClockTime) | the clock's internal time, external (adjusted) time, and skew rate

Gets the internal rate and reference time of `clock`. See `clockSetCalibration` for more information.

clockSetCalibration

Arguments

:: ClockClass clock |

=> clock

    clock

-> ClockTime

    internal

-> ClockTime

    external

-> Ratio ClockTime

    rate

-> IO () |

Adjusts the rate and time of clock. A rate of `1 % 1` is the normal speed of the clock. Larger values make the clock go faster.

The parameters `internal` and `external` specifying that `clockGetTime` should have returned `external` when the clock had internal time `internal`. The parameter `internal` should not be in the future; that is, it should be less than the value returned by `clockGetInternalTime` when this function is called.

Subsequent calls to `clockGetTime` will return clock times computed as follows:

     (clock_internal - internal) * rate + external

Note that `clockGetTime` always returns increasing values, so if the clock is moved backwards, `clockGetTime` will report the previous value until the clock catches up.

clockIDGetTime

Arguments

:: ClockID

    clockID

-> IO ClockTime |

Get the time of `clockID`.

clockIDWait

Arguments

:: ClockID

    clockID

-> IO (ClockReturn, Maybe ClockTimeDiff) |

Perform a blocking wait on `clockID`. The parameter `clockID` should have been created with `clockNewSingleShotID` or `clockNewPeriodicID`, and should not been unscheduled with a call to `clockIDUnschedule`.

If second value in the returned pair is not `Nothing`, it will contain the difference against the clock and the time of `clockID` when this method was called. Positive values indicate how late `clockID` was relative to the clock. Negative values indicate how much time was spend waiting on the clock before the function returned.

clockIDUnschedule

Arguments

:: ClockID

    clockID

-> IO () |

Cancel an outstanding request with `clockID`. After this call, `clockID` cannot be used anymore to recieve notifications; you must create a new `ClockID`.

# Clock Properties

clockTimeout :: ClockClass clockT => Attr clockT ClockTime

The amount of time, in nanoseconds, between samples.

clockWindowSize :: ClockClass clockT => Attr clockT Int

The size of the window used to calculate rate and offset.

clockWindowThreshold :: ClockClass clockT => Attr clockT Int

The threshold to start calculating rate and offset.