vltransfer(3dm)

NAME
     vlBeginTransfer, vlEndTransfer, vlGetTransferSize - begin and end
     transfer on video path

SYNOPSIS
     #include <dmedia/vl.h>

     int vlBeginTransfer(VLServer svr, VLPath path, int count,
                   VLTransferDescriptor *xferDesc);
     int vlEndTransfer(VLServer svr, VLPath path);
     int vlGetTransferSize(VLServer svr, VLPath path);

PARAMETERS
     svr       Specifies the video server.

     path      Specifies the path.

     count     Specifies the number of transfer descriptors in the array
               passed. If count = 0 then the continuous mode transfer
               operations are used.  Transfers will continue using ring
               buffers, if necessary,  until vlEndTransfer is called.

     xferDesc  If count is non-zero, then xferDesc is an array of transfer
               descriptors.  Each element of the array can specify a discrete,
               continuous, or automatic transfer. The contents of a descriptor
               are described below.

DESCRIPTION
     vlBeginTransfer immediately begins a continuous transfer of video data on
     the specified path if count is set to zero.  If count is non-zero, then
     vlBeginTransfer initiates a series of transfers on the specified path
     using the fields of each descriptor as follows.

     trigger An event to trigger the transfer on.  VLTriggerImmediate means
             that the transfer will start as soon as the daemon is able to
             start.  VLDeviceEvent is generally used to indicate an external
             triggering mechanism, such as the GPI input.

     delay   A count of frames to wait after the trigger is received. In the
             case of VLTriggerImmediate,
             this may be ignored.

     count   The count of frames to transfer.

     mode    There are three current values for the mode:

             VL_TRANSFER_MODE_DISCRETE
                  means that a single transfer of count frames is executed.

             VL_TRANSFER_MODE_CONTINUOUS
                  means that a single transfer of undetermined length is
                  started, and will not end until vlEndTransfer is called.
             VL_TRANSFER_MODE_AUTOTRIGGER
                  means that every trigger received will cause a transfer of
                  count frames.  In this case if delay plus count is greater
                  than the time between triggers, undetermined behavior may
                  result.

     The following events may be delivered once vlBeginTransfer has been
     called:

          VLTransferComplete
               events are delivered for each frame transfer on paths which use
               buffers.

          VLTransferFailed
               events are delivered to indicate an error condition preventing
               data transfer.

     vlEndTransfer ends the transfer of video data on the specified path.

     vlGetTransferSize returns the number of bytes of space required for a
     transfer on the server specified, using the path specified, for one frame
     or field of data. For this information to be useful, all controls that
     can effect the size of the data should be set before this call.

     The user is responsible for multiplying the returned value by the number
     of frames to get the buffer's size.

     There are several controls that affect the transfer of data.  See the
     documentation for the particular controls of a device that affect the
     data transfer, such as rate, addresses, field or frame mode, depth,
     format, sizes, etc.

RETURN VALUE
     If successful, vlBeginTransfer and vlEndTransfer return zero.  A value of
     -1 indicates an error, and vlGetErrno(3v) can be called to return the
     error code.

SEE ALSO
     vlCreateBuffer(3dm), vlRegisterBuffer(3dm)