VLSETCONNECTION(3dm) VLSETCONNECTION(3dm)
NAME
vlSetConnection - manage the connectivity of a VL path
SYNOPSIS
#include <dmedia/vl.h>
int vlSetConnection(VLServer svr, VLPath path,
VLNode srcnode, VLPort srcport,
VLNode drnnode, VLPort drnport,
VLBoolean preempt);
PARAMETERS
svr Specifies the server handle.
path Specifies the path handle.
srcnode Specifies the source node.
srcport Specified the port on the source node
drnnode Specifies the drain node.
drnport Specifies the port on the drain node
preempt Specifies whether paths may be preempted to establish the
connection
DESCRIPTION
vlSetConnection establishes a connection from (srcnode, srcport) to
(drnnode, drnport) on the indicated path. The connection takes effect
either immediately or at the next vertical interval, depending on the
video device characteristics. If (srcnode, srcport) is capable of
multicasting, then any prior targets of (srcnode, srcport) are
unaffected. Otherwise, the prior targets of (srcnode, srcport) revert to
default inputs.
Use of vlSetConnection is optional in all but the following cases:
The path being setup contains multiple internal nodes.
The connections established by the default routing algorithm are not
suitable for the application.
A node with multiple ports is used, and the default connections to
the ports are not suitable for the application.
The specified connection takes effect within the next vertical interval.
(Note: not all connections may be changed after a path has been setup.
See the documentation pertaining to each node/device.)
If vlSetConnection is not used to explicitly specify the path
Page 1
VLSETCONNECTION(3dm) VLSETCONNECTION(3dm)
connections, a default routing algorithm is applied when vlBeginTransfer
is called.
CONTROL USAGE
The ability to change or establish connections through vlSetConnection is
dependent on the control usage of the path. Paths with control usage
VL_DONE_USING may neither set nor query a connection. Paths with control
usage VL_READ_ONLY may query, but not set, a connection. Paths with
control usage VL_SHARE may both set and get a connection, but may have
the connection changed by other paths with control usage VL_SHARE or
VL_LOCK. Paths with control usage VL_LOCK may set connections and are
guaranteed not to have the connection changed by any other path.
STREAM USAGE AND PREEMPTION
Routing the connection may involve obtaining connectors or other scarce
resources which paths contend for. If the preempt flag is TRUE, then
other paths may be preempted in order to route the connection.
Preemption follows similar rules used for node acquisition during
SetupPaths. Specifically, a path with stream usage VL_LOCK is never
preempted. A path with stream usage VL_SHARE may be preempted by any
other path. Paths with stream usage VL_READ_ONLY are never preempted, as
by definition they never actually use connectors. (Note, however, that
paths with control usage VL_SHARE and stream usage VL_READ_ONLY may
change a connection and thereby cause paths with stream usage VL_SHARE to
be preempted.)
If preempt is FALSE, or the stream usage level is insufficient to obtain
required connectors, then VLNoRoute will be returned if the connection
could not be routed.
DEFAULT VIDEO CONNECTIONS
When a path is first setup, it inherits any connections specified by
other paths operating on the device. vlSetConnection can then be used to
specify the remaining connections or override the inherited connections.
When vlBeginTransfer is called on the path, a default routing algorithm
will be applied if all drains on the path are unconnected. This
maintains compatibility for applications which choose not to explicitly
set connections:
If there are no internal nodes on the path, then the pixel output of
the first source node added to the path is connected to the pixel
input of the first drain node on the path. If the source node is
capable of multicast, then all drain nodes are connected to the
source node.
If there is an internal node on the path, then the pixel output of
the first source node added to the path is connected to the first
pixel input of the internal node, the pixel output of the second
Page 2
VLSETCONNECTION(3dm) VLSETCONNECTION(3dm)
source added to the path is connected to the second pixel input of
the internal node, etc. The pixel output of the internal node is
connected to the first drain node on the path. If the internal node
is capable of multicast, then all drain nodes are connected to the
internal node.
EVENTS
When a connection is set by vlSetConnection, or implicitly by a default
routing algorithm in vlBeginTransfer, a VLStreamChanged event is sent to
all paths of an affected target (node, port). This includes paths using
the new (node, port) specified in vlSetConnection, as well as the prior
(node, port) targets if their connection to the source was broken (i.e.
if the source is not capable of multicast)
RETURN VALUE
If successful, this functions returns zero. A value of -1 indicates an
error, and vlErrno is set to one of the following:
VLBadServer The server parameter is not valid.
VLBadPath The path is not valid.
VLBadNode The source or target node is not a valid node on
the path.
VLBadAccess The path has not been setup, or control usage on
the path is is VL_READ_ONLY.
VLBadAlloc A memory allocation attempt failed.
VLNoRoute The connection could not be routed because
connectors or other required hardware resources are
in use by other paths that cannot be preempted.
VLPathInUse The connection could not be routed because another
path has the connection locked.
VLNotSupported vlSetConnection is not supported on the device.
VLBadImplementation An internal processing error has occurred.
SEE ALSO
vlGetConnection(3dm), vlSetupPaths(3dm), vlBeginTransfer(3dm)
Page 3