VLGETUSTMSCPAIR(3dm)VLGETUSTMSCPAIR(3dm)NAMEvlGetUSTMSCPair - get the time at which a field/frame came in or will go
out
SYNOPSIS
#include <dmedia/vl.h>
int vlGetUSTMSCPair
( VLServer server,
VLPath path,
VLNode jackNode,
VLPort jackPort,
VLNode memNode,
USTMSCpair* returnedPair )
PARAMETERS
server expects the VL server to use
path expects the VL path containing the jack in which you are
interested
jackNode expects the VLNode (usually a VL_VIDEO or VL_SCREEN node)
representing the jack in which you are interested.
jackPort VLPort for that node (VL_ANY for default port)
memNode expects the VL_MEM VLNode representing the buffer for
which you want a UST/MSC pair.
returnedPair expects a pointer to memory in which to return a UST/MSC
pair
DESCRIPTIONvlGetUSTMSCPair(3dm) returns an atomic UST/MSC pair for the specified
jack (electrical input or output of the machine), for a given path that
contains a VL_MEM node.
A "media stream sample" is one item in a VLBuffer or DMbufferpool.
Therefore, if the VL_MEM node in the given path has its VL_CAP_TYPE
control set to VL_CAPTURE_INTERLEAVED (frames), a media stream sample is
a frame. For all other settings of VL_CAP_TYPE, a media stream sample is
a field.
An "MSC" is a counter used to reference particular incoming or outgoing
media stream samples. See vlGetFrontierMSC(3dm) for further information
on MSCs.
The returned pair contains a UST u and an MSC m such that:
1. for a video to memory path, u is the UST at which the media stream
Page 1
VLGETUSTMSCPAIR(3dm)VLGETUSTMSCPAIR(3dm)
sample with MSC m hit the input jack of the machine
2. for a memory to video path, u is the UST at which the media stream
sample with MSC m will hit the output jack of the machine.
3. m is within one second of the media stream sample currently hitting
the jack of the machine.
vlGetUSTMSCPair(3dm) thus accounts for all the latency within the
machine, including any delay due to field buffers internal to the
hardware.
As suggested by #3 above, the returned MSC m is not guaranteed to be the
one currently hitting the jack, nor is it even guaranteed to be the
number of any media stream sample currently in the application's buffer.
In order to relate the returned MSC to a particular item in the
application's buffer, you must use vlGetFrontierMSC(3dm).
See the man page for vlGetFrontierMSC(3dm) for a code example.
This function only returns useful information for a path under the
following circumstances: the path must have a VL_MEM node and a VLBuffer
or DMbufferpool. The path must already be set up (see
vlSetupPaths(3dm)). The path's transfer must already have begun (see
vlBeginTransfer(3dm)).
This function is currently only supported for VL paths in continuous mode
(see vlBeginTransfer(3dm)).
This function is currently only supported for VL paths whose VL_RATE is
the maximum rate as indicated by VL_TIMING.
This function returns a valid UST/MSC pair even if the given path's
buffer is underflowing or overflowing, though its usefulness may be
diminished by this condition (see vlGetFrontierMSC(3dm)).
vlGetUSTMSCPair uses Unadjusted System Time (UST) as its timeline. This
allows it to relate to other media which also use UST. See the man page
for dmGetUST(3dm) for more information on UST.
The returned MSC picks out a particular field or frame. The returned UST
gives the time at which a particular feature of the video waveform for
that field or frame hit the jack of the machine. That feature, known as
the synchronization point, is defined for each video signal format in
videosync(3dm).
RETURN VALUEvlGetUSTMSCPair(3dm) returns VLSuccess on successful completion,
otherwise a value of -1 is returned. In all failure cases,
vlGetErrno(3dm) can be called to return the error code.
Page 2
VLGETUSTMSCPAIR(3dm)VLGETUSTMSCPAIR(3dm)NOTE
Do not confuse the frontier MSC returned by vlGetFrontierMSC(3dm) or the
UST/MSC pair returned by vlGetUSTMSCPair(3dm) with the UST/MSC stamps
contained in a DMbuffer, returned by dmBufferGetUSTMSCpair(3dm) for a
video to memory VLPath. The UST and MSC values returned by
dmBufferGetUSTMSCpair(3dm) refer to that particular buffer, whereas the
frontier MSC and UST/MSC pair returned by vlGetFrontierMSC(3dm) and
vlGetUSTMSCPair(3dm) have different properties, described in their man
pages.
CAVEATS
See vlGetUSTPerMSC(3dm) for an important note about how far you can
extrapolate from the UST in a UST/MSC pair.
For some VL devices, there is a short initial period (up to ten field
times) in the lifetime of a transfer during which no UST/MSC pair is
available. This period begins when the application calls
vlBeginTransfer(3dm) and ends when the device clocks in or out its first
media stream sample from the application's buffer. An attempt to call
vlGetUSTMSCPair(3dm) during this period will block the application until
the end of the period, when a valid UST/MSC pair is available. An
application that does not wish to block may determine whether the period
has ended by watching for the first change in vlGetFilled(3dm) (the first
increment for input or the first decrement for output), or by waiting for
the first VLTransferComplete, VLOddVerticalRetrace,
VLEvenVerticalRetrace, or VLFrameVerticalRetrace event after
vlBeginTransfer(3dm).
SEE ALSOdmGetUST(3dm), vlGetFrontierMSC(3dm), vlGetUSTPerMSC(3dm),
videosync(3dm), vlGetPathDelay(3dm)
Page 3
