vlGetUSTPerMSC(3dm)

NAME
     vlGetUSTPerMSC - get the time spacing of fields/frames in a path


SYNOPSIS
     #include <dmedia/vl.h>

     double vlGetUSTPerMSC(VLServer server, VLPath path, VLNode memNode)

PARAMETERS
     server    expects the VL server to use
     path      expects the VLPath for which you want ust_per_msc
     memNode   expects the VL_MEM VLNode for which you want ust_per_msc

DESCRIPTION
     This function returns the nominal, average amount of UST time elapsed
     between media stream samples in a given VLPath that includes a VL_MEM
     node and a VL_VIDEO or VL_SCREEN node.  It is for use in extrapolating a
     UST/MSC pair as shown in vlGetUSTMSCPair(3dm) and vlGetFrontierMSC(3dm).
     See vlGetFrontierMSC(3dm) for the definition of a "media stream sample."
     The path given must have been set up with vlSetupPaths(3dm).

     This function is currently only supported for VL paths whose VL_RATE is
     the maximum rate as indicated by VL_TIMING.

     This function takes into account the settings of all controls on the
     path's VL_MEM node (such as VL_CAP_TYPE and any relevant device-specific
     controls) and produces an estimate of the amount of UST time elapsed
     between successive items in the path's VLBuffer (assuming no overflow or
     underflow).

     Note that the figure returned is a nominal figure that is constant for a
     given set of control settings; it is not dynamically updated based on the
     actual UST spacing of items in the VLBuffer.  For some applications, it
     may be better to dynamically compute this figure by sampling actual USTs
     and MSCs from vlGetUSTMSCPair(3dm).


RETURN VALUE
     If successful, vlGetUSTPerMSC(3dm) returns a positive floating point
     value.  A negative return value indicates an error, and vlGetErrno(3dm)
     can be called to return the error code.


HINTS
     Be sure to store this value as a double and not a stamp_t, so as to avoid
     any unnecessary roundoff error when using the value to extrapolate from a
     UST/MSC pair.

     Care should be taken not to extrapolate too far from a particular UST in
     a UST/MSC pair.  This advice applies regardless of whether one is using a
     nominal ust_per_msc value (such as the one returned by
     vlGetUSTPerMSC(3dm)), or an empirically determined value (derived from
     watching actual USTs and MSCs in UST/MSC pairs), though it is especially
     important in the former case.  A good rule of thumb is to never
     extrapolate a UST/MSC pair more than one second away from the UST in the
     pair.

     There are two things that can happen if you extrapolate too far from a
     UST/MSC pair:

     1. The crystals which drive real hardware clocks (such as your video
     device's video clock or the UST clock) are not perfect: they tick at a
     rate which may deviate from their nominal rate, typically by up to 100
     parts per million.  When you use vlGetUSTPerMSC(3dm), you get back a
     ratio that is based entirely on the nominal rate of the UST clock and the
     nominal rate of your video device's clock.  As an example, say that your
     UST clock is 100ppm slower than its nominal rate of 1 billion ticks per
     second, and that your video clock is 100ppm faster than its nominal rate
     of 60 fields per second.  If you use vlGetUSTPerMSC(3dm) to extrapolate a
     UST/MSC pair any further than about 2,500 fields (about 42 seconds), then
     you will get a UST that is off by more than half a field.  Most programs
     will never extrapolate more than 1 second, so this is not a problem.

     2. You can totally remove the dependency of your program on nominal
     values by computing an empirical ust_per_msc value instead of using
     vlGetUSTPerMSC(3dm).  This can be done by simply watching the UST and MSC
     of UST/MSC pairs you acquire over time, and computing the ratio based on
     these values.  This method should allow you to extrapolate further if you
     need to, but there is still a caveat: real crystals also have the
     property that their rate can drift over a long period of time.  This can
     occur due to a myriad of factors including temperature.  Therefore it is
     still a good idea to acquire a UST/MSC pair and re-compute your
     ust_per_msc value periodically.


SEE ALSO
     dmGetUST(3dm), vlGetFrontierMSC(3dm), vlGetUSTMSCPair(3dm),
     vlGetPathDelay(3dm)