VLSETCONTROLTRIGGER(3dm)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
Page 1
VLSETCONTROLTRIGGER(3dm)VLSETCONTROLTRIGGER(3dm)
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
Page 2
VLSETCONTROLTRIGGER(3dm)VLSETCONTROLTRIGGER(3dm)
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 ALSOvlSetControl(3dm), vlGetFrontierMSC(3dm)
Page 3
