VLGETPATHDELAY(3dm)VLGETPATHDELAY(3dm)NAMEvlGetPathDelay - get the time delay between two jacks in a VLPath
SYNOPSIS
#include <dmedia/vl.h>
stamp_t vlGetPathDelay(VLServer server, VLPath path,
VLNode node1, VLPort port1,
VLNode node2, VLPort port2);
PARAMETERS
server expects the VL server to use
path expects the VLPath for which you want a path delay
node1 expects the VLNode (usually a VL_VIDEO or VL_SCREEN node)
representing the first jack in which you are interested
port1 VLPort for that node (VL_ANY for default port)
node2 same, for second jack in which you are interested
port2 VLPort for that node (VL_ANY for default port)
DESCRIPTION
For a VLPath involving two jacks, vlGetPathDelay(3dm) returns the average
amount of time between when a signal hits the first jack and when the
corresponding signal hits the second jack. Generally, one jack is an
input jack, and the other jack is an output jack.
The returned value has the same units as the UST clock--nanoseconds (see
dmGetUST(3dm) for more information on UST).
This quantity is useful for applications that need to know the total
latency of a complex path. For example, applications which use the Cosmo
Compress option board in concert with Galileo Video, Indigo2 Video, or
Indy Video often need to know the delay through the video board, so that
they can properly configure a parallel audio path for synchronized
capture or playback.
This function only returns useful information for a path under the
following circumstances: the path must have at least two VLNode/VLPort
pairs representing video jacks (VL_VIDEO or VL_SCREEN). The path must
already be set up (see vlSetupPaths(3dm)).
vlGetPathDelay can be called before the path's transfer is begun (see
vlBeginTransfer(3dm)).
SPECIFICS OF CALCULATION
Because of the variety of different signal types and genlocking
facilities that may be used in a jack-to-jack path in the VL, the
specifics of how this value is calculated are complicated. We anticipate
that this value will be immediately useful to most developers without
knowing the details, but here they are for those who are interested.
Page 1
VLGETPATHDELAY(3dm)VLGETPATHDELAY(3dm)
This function returns the average difference in UST between the
synchronization point of a signal at one jack and the corresponding
synchronization point(s) of a signal at another jack. The
synchronization point for every video signal type supported by SGI
systems is defined in videosync(3dm).
The way in which the value is calculated depends on two factors.
1. Since the two signals may or may not even of be the same signal type,
the first factor is whether there is a nominal one-to-one correspondence
between synchronization points in one signal and synchronization points
in the other, and vice/versa. If this correspondence exists both ways,
then the signals (and the path transferring them) are "one-to-one."
Example: a VLPath from a PAL VL_VIDEO source to a PAL VL_VIDEO drain
would be one-to-one, because there is one input synchronization point
(which is per-field in the case of PAL video) per output synchronization
point, and vice versa. A VLPath from a PAL VL_VIDEO source to a
noninterlaced-72Hz VL_SCREEN drain would not be one-to-one, because the
device has to use some input fields more than once (not only because of
the 50 Hz vs. 72 Hz rate mismatch, but also because the noninterlaced
signal has only one synchronization point per frame, whereas the PAL
signal has one per field).
2. Secondly, regardless of whether the signals are nominally one-to-one,
the two signals may or may not be genlocked. This even applies in paths
from video to screen or vice versa--the graphics system may or may not be
genlocked to the video system.
For one-to-one, genlocked signals, vlGetPathDelay(3dm) returns the
constant time offset between a synchronization point of one signal and
the corresponding synchronization point of the other signal.
For non-one-to-one, genlocked signals, vlGetPathDelay(3dm) returns the
average time offset between the synchronization point of each input
signal and the synchronization point(s) of all corresponding output
signals. If a part of the input signal containing a synchronization
point never makes it to the output jack (ie, decimation), then that
synchronization point is not considered in computing this average figure.
Here is an example of this averaging process:
time 00000000001111111111222222222233333333334444444444
01234567890123456789012345678901234567890123456789
input 1 2 3 4 5 |
output 1 2 3 4 5 6
(6 is the same signal as 5)
The returned delay (in units of "spaces" for the sake of example) is 8.5:
input frame 1 delayed by 10 -> output frame 1
input frame 2 delayed by 9 -> output frame 2
input frame 3 delayed by 8 -> output frame 3
Page 2
VLGETPATHDELAY(3dm)VLGETPATHDELAY(3dm)
input frame 4 delayed by 7 -> output frame 4
input frame 5 delayed by 6 -> output frame 5
input frame 5 delayed by 11 -> output frame 6
weighted average sum/n = 51 / 6 = 8.5 ``spaces'' of delay
For the corresponding non-genlocked signals, the device must perform
timebase correction by dropping or adding fields or frames. The actual
path delay is therefore non-constant over time. For such paths,
vlGetPathDelay(3dm) will attempt to return an average value; this value
may not be constant, but it will stay within a finite upper and lower
bound at all times.
RETURN VALUE
If successful, vlGetPathDelay(3dm) returns a positive value in
nanoseconds representing the delay between the two specified jacks. A
value of (stamp_t)-1 indicates an error, and vlGetErrno(3dm) can be
called to return the error code.
SEE ALSOdmGetUST(3dm), videosync(3dm), vlGetUSTMSCPair(3dm), vlGetUSTPerMSC(3dm)
Page 3
