vlgetnode(3dm)

NAME
     vlGetNode, vlAddNode, vlRemoveNode - VL node handling routines

SYNOPSIS
     #include <dmedia/vl.h>

     VLNode vlGetNode(VLServer svr, int type, int class, int number);
     int vlAddNode(VLServer svr, VLPath path, VLNode node);
     int vlRemoveNode(VLServer svr, VLPath path, VLNode node);

DESCRIPTION
     vlGetNode returns a handle to a VL node with the specified
     characteristics.  The node handle can be used in subsequent calls to
     vlCreatePath(3dm) or vlSetControl(3dm).  Nodes are used to construct
     paths which tell the system how to interconnect video data streams.  The
     source and drain of a video stream, as well as intermediate filters
     affecting data flowing between them, are types of nodes.  A path may have
     multiple drain nodes, and in some cases, multiple source nodes.  Nodes
     have various controls associated with them which may change the behavior
     of the node or any path containing that node.

     vlAddNode adds node to a path which has been created with
     vlCreatePath(3dm) but not yet instantiated by vlSetupPaths(3dm).
     vlAddNode can be called multiple times for a given path until
     vlSetupPaths is called. Adding multiple nodes of type VL_SRC to a path
     implies that blending is desired, however no blending will take place
     unless a VL_BLENDER node is added to the path. If multiple VL_DRN nodes
     are added to the path, they will all receive the same output.
     vlRemoveNode removes the specified node from the given path.

     Adding a VL_DEVICE node to a path gives that path access to global device
     controls which may affect all paths on the device.

     A node is specified by three parameters, the type, class, and number.
     The type parameter specifies the function of the node in a path.  There
     are four types of nodes:

          VL_SRC       the source from which a video stream will originate.

          VL_DRN       the destination, or drain, where video will be sent.

          VL_INTERNAL  a mid-stream filter such as a blender.

          VL_DEVICE    a special node used to manipulate controls which are
                       global to the video device and shared by all paths.

     The class parameter identifies the type of system resource associated
     with the node.  There are five classes of nodes:

          VL_VIDEO     a hardware video port.  If the type is VL_DRN then the
                       node specifies a video output.  If the type is VL_SRC
                       then the node specifies a video input.  All video
                       devices have at least one of these.

          VL_GFX       specifies a direct connection between a video device
                       and a graphics frame buffer.  Video data may be
                       manipulated in the frame buffer using standard graphics
                       operations.  This class of node is only available with
                       the Sirius Video option.

          VL_MEM       a memory buffer which can be used to send or receive
                       video data.

          VL_SCREEN    specifies a direct connection between a video device
                       and a graphics display device.  This differs from
                       VL_GFX in that the video data does not interact
                       directly with the graphics frame buffer and can not be
                       affected with standard graphics routines.  This class
                       of node is available with the Galileo/IndyVideo or
                       Impact Video options.

          VL_TEXTURE   specifies graphics hardware which can transfer video
                       data directly to or from a texture buffer.  This class
                       of node is available with the Sirius or Impact Video
                       options.

          VL_BLENDER   a filter that can affect data flowing between the
                       source and drain.  Internal nodes are available on some
                       devices to control blending multiple sources.  The type
                       of a blend node should be specified as VL_INTERNAL.

          VL_CSC       a realtime colorspace converter which can be used to
                       convert the video data if the destination requires a
                       different colorspace than the source. Note that source
                       and drain nodes may support some conversions directly,
                       in which case a VL_CSC node may not be necessary in the
                       path. The type of a colorspace converter should be
                       specified as VL_INTERNAL. This class of node is only
                       available with the Impact Video option.

          VL_FB        a frame buffer which can be inserted in the path to
                       freeze the video data. Note that some nodes have an
                       inherent freeze capability, in which case a frame
                       buffer node  may not be necessary on the path. The type
                       of a frame buffer node should be specified as
                       VL_INTERNAL. This class of node is only available with
                       the Impact Video option.

     The number parameter is used to differentiate among multiple instances of
     the same class and type a particular device might support.  The value
     usually corresponds to the numbering of video connectors on the board. If
     VL_ANY is specified for number, the selection will be based on the
     default for that node, which may be changed using videopanel(1).

     Not all classes of nodes are available on all video devices.  The
     complete set of nodes available for a particular device may be determined
     using vlGetDeviceList(3dm).

RETURN VALUE
     Upon successful completion, vlGetNode returns a node handle and vlAddNode
     and vlRemoveNode return VLSuccess. Otherwise, a value of -1 is returned
     and vlErrno is set to indicate the error.

SEE ALSO
     vlCreatePath(3dm), vlRemoveNode(3dm), vlSetControl(3dm),
     vlGetControl(3dm), vlCreateBuffer(3dm), vlGetControlInfo(3dm),
     vlGetDeviceList(3dm)