VLGETUSTPERMSC(3dm)VLGETUSTPERMSC(3dm)NAMEvlGetUSTPerMSC - 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
Page 1
VLGETUSTPERMSC(3dm)VLGETUSTPERMSC(3dm)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 ALSOdmGetUST(3dm), vlGetFrontierMSC(3dm), vlGetUSTMSCPair(3dm),
vlGetPathDelay(3dm)
Page 2
