vlGetUSTMSCPair(3dm)

NAME
     vlGetUSTMSCPair - 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

DESCRIPTION
     vlGetUSTMSCPair(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
     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 VALUE
     vlGetUSTMSCPair(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.

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 ALSO
     dmGetUST(3dm), vlGetFrontierMSC(3dm), vlGetUSTPerMSC(3dm),
     videosync(3dm), vlGetPathDelay(3dm)