vlsetcontroltrigger(3dm)

NAME
     vlSetControlTrigger, vlSetControlInLine - frame-accurate setting of
     control VL values

SYNOPSIS
     #include <dmedia/vl.h>

     int vlSetControlTrigger(VLServer svr, VLPath path, VLNode targetNode,
                       VLTriggerType triggerType, VLTriggerData *triggerData,
                       VLControlType controlType, VLControlValue *value);
     int vlSetControlInLine(VLServer svr, VLPath path, VLNode targetNode,
                       VLNode refNode, VLControlType type, VLControlValue *value);

PARAMETERS
     svr      The handle for the video server to use.

     path     Specifies a handle to the path.

     targetNode
              Specifies the node on which the control resides (VL_ANY
              specifies any node)

     triggerType
              Specifies the type of trigger used to trigger the control
              change.

     triggerData
              Specifies data specific to the given triggerType used to trigger
              the control change.

     refNode  Specifies the memory node which provides the source of video
              fields

     type     Specifies the control type, as defined in <dmedia/vl.h>

     value    Specifies a pointer the control's values.

DESCRIPTION
     vlSetControlTrigger sets the specified control value at an exact point in
     the video stream defined by the associated trigger. The following types
     of triggers are currently defined:

     VL_TRIGGER_MSC
          The control value is set based on a specified MSC (media stream
          counter - see vlGetFrontierMSC(3dm)).  The corresponding triggerData
          fields are:

          val.msc
               The control takes effect on the media stream sample whose MSC
               is val.msc. Specifying an MSC of 0 causes the control to be set
               before the first media stream sample, but not before
               vlBeginTransfer() is called. Because the MSC continues to
               increment during underflow/overflow on the path (see
               vlGetFrontierMSC(3dm)), the occurrence of overflow/underflow
               can cause the control to be set on a media stream sample other
               than that intended. If a control change is specified at an MSC
               which has already occurred, it takes effect immediately and a
               VLAdvanceMissed event is generated.

          param.refNode
               The memory node with respect to which the MSCs are defined.

     VL_TRIGGER_VITC
          The control value is set based on a specified Vertical Interval Time
          Code (VITC) value.  The corresponding triggerData field is:

          val.vitc
               The control takes effect on the media stream sample whose VITC
               value is val.vitc (a DMtimecode structure - see
               <dmedia/dm_timecode.h>).

     VL_TRIGGER_GPI
          The control value is set based on the occurrence of an external
          trigger (GPI).  The corresponding triggerData field is:

          val.instance
               The control is set between the media stream sample during which
               an external trigger occurs on the specified trigger input
               (val.instance) and the following sample.

     vlSetControlInLine sets a control value between two media stream samples
     flowing from a memory src node. The point at which the control is to be
     set is specified implicitly by the order of execution of the
     vlSetControlInLine() call with respect to the order of calls to enqueue
     samples on the memory buffer associated with refNode.  Thus, for example,
     in the following code fragment:

          err = vlDMBufferPutValid(svr, path, refNode, buf1);
          err = vlSetControlInLine(svr, path, node, refNode, type, value);
          err = vlDMBufferPutValid(svr, path, refNode, buf2);

     the control is set between the sample contained in buf1 and the sample
     contained in buf2.  vlSetControlInLine works with both DMbuffers and
     vlBuffers. Making a vlSetControlInLine() call before the first sample is
     enqueued, causes the control to be set before the first sample, but not
     before vlBeginTransfer() is called.

     The following statements apply to all frame-accurate control changes.
     Prior to issuing a control change request, vlSetupPaths(3dm)) must be
     called.  A VLControlChanged event is generated and the new control value
     becomes visible to the application when the control is actually set - not
     when the control change request returns.  Some validity checking for a
     control change request may not occur until the time arrives to actually
     set the control. If validity checks fail at this time, the request is not
     executed and the application is notified via a VLInvalidControl event.
     All pending control change requests are flushed when the path chages
     state from VL_SHARE or VL_LOCK to VL_DONE_USING or VL_READ_ONLY.

RETURN VALUE
     If successful, these functions return zero.  A value of -1 indicates an
     error, and vlErrno is set to the correct error number. If an error of
     VLValueOutOfRange is returned the VL had to adjust the value passed in
     before using it.  VLBadValue means that the value was not set.
     VLBadControl means that the control does not exist on the specified node
     or path.  VLNotSupported means that setting the specified control in a
     frame-accurate manner is not supported on the specified device.

SEE ALSO
     vlSetControl(3dm), vlGetFrontierMSC(3dm)