vlsetconnection(3dm)
vlSetConnection - manage the connectivity of a VL path
Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.
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 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 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)