vlsetuppaths(3dm)

NAME
     vlSetupPaths - setup VL paths

SYNOPSIS
     #include <dmedia/vl.h>

     int vlSetupPaths(VLServer svr, VLPathList paths, uint count,
               VLUsageType ctrlUsage, VLUsageType streamUsage);

PARAMETERS
     svr           Specifies the server.

     paths         Specifies paths.

     count         Specifies number of paths.

     ctrlUsage     Specifies usage of controls.

     streamUsage   Specifies usage of streams.

DESCRIPTION
     vlSetupPaths is the function that sets up the hardware to enable
     exclusive or shared usage, and prepares the hardware for the intended use
     by establishing connections and switches within the device.

     Paths must be from a single device and single server.  If paths from
     multiple devices are specified, the function returns -1, and vlErrno is
     set to the reason.

     This means that any inter-device or inter-server video data transfer must
     be done by the application.

     Transfer requiring CPU intervention are not started until the
     vlBeginTransfer function is called.

     Call vlSetupPaths again to change the usage on a set of paths.  If the
     requested change in usage fails, the old usage, if any, is retained.  For
     example, if exclusive use was requested, but unavailable, the old usage
     would be retained.

          typedef VLPath VLPathList[];

          typedef enum VLTypeUsage
              { VL_DONE_USING, VL_READ_ONLY, VL_SHARE, VL_LOCK } VLUsageType;

     Streamusage may be set to the following values:

          VL_DONE_USING
               the application is finished using this path, and the hardware
               resources may be released. The path is not destroyed, but it
               cannot be used for transfers until it's usage is changed to
               either VL_SHARE or VL_LOCK.
          VL_READ_ONLY
               the application will be using the path, but will not be doing
               data transfers.

          VL_SHARE
               the path will be used for transfers, but can be preempted by
               other paths. When using VL_SHARE, the application should pay
               attention to VLStreamPreempted events.

          VL_LOCK
               the path will be used for transfers and cannot be preempted.
               When this path is setup, it may preempt other paths.

     Controlusage may be set to the following values:

          VL_DONE_USING
               the application is finished using this path, and the hardware
               resources may be released.

          VL_READ_ONLY
               controls can be read, but not set. No data transfers can occur.

          VL_SHARE
               controls can be read and set, and VLControlChanged events
               should be watched to reflect the activities of other paths.

          VL_LOCK
               prevents other paths from setting controls which reflect shared
               hardware resources.

RETURN VALUE
     If successful, this function returns zero.  A value of -1 indicates an
     error.

SEE ALSO
     vlCreatePath(3dm), vlAddNode(3dm), vlRemoveNode(3dm),
     vlBeginTransfer(3dm), vlEndTransfer(3dm)