vlgetcontrol(3dm)

NAME
     vlGetControl, vlSetControl - get or set control VL value

SYNOPSIS
     #include <dmedia/vl.h>

     int vlGetControl(VLServer svr, VLPath path, VLNode node,
               VLControlType type, VLControlValue *value);
     int vlSetControl(VLServer svr, VLPath path, VLNode node,
               VLControlType type, VLControlValue *value);

PARAMETERS
     svr      The handle for the video server to use.

     path     Specifies a handle to the path.

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

     value    Specifies a pointer the control's values or return values.

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

DESCRIPTION
     vlGetControl immediately gets the specified control's value and stores
     the result in the VLControlValue struct pointed to by value.

     vlSetControl immediately sets the specified control's value using the
     values specified in the VLControlValue struct.

     The following is the list of device independent controls defined in the
     VL. Devices may not support all controls.

          VL_DEFAULT_SOURCE(int)
               returns the node number of the current default video source
               node.  This is the node number which will be used when VL_ANY
               is specified as the node number in vlGetNode(3v). This control
               is read-only.

          VL_TIMING(int)
               specifies the video timing which will be used by a video node.

          VL_ORIGIN(x,y)
               specifies the location of the upper left corner of the active
               video. This control applies to screen nodes.

          VL_OFFSET(x,y)
               specifies the location of the upper left corner of video with
               respect to the active video region. The dimensions of the
               active video region are timing and device dependent.
          VL_SIZE(x,y)
               specifies the size of the active video region on video nodes,
               and the clipped size of video on other nodes.

          VL_RATE(fract)
               specifies rate of data transfer in frames or fields per second,
               depending on the setting of VL_CAP_TYPE. Note that most VL
               devices will return an approximated rate of 30/1 or 60/1 when
               they are in actuality performing 30000/1001 or 60000/1001
               fields or frames per second (i.e. the full field or frame rate
               for NTSC). For these devices, fractional field or frame rates
               are affected as well. A field rate of 15/1 is in reality
               15000/1001, for example.

          VL_ZOOM(fract)
               specifies a zoom factor where 1.0 is nominal.

          VL_CAP_TYPE(int)
               specifies whether transfer should be frame or field based, and
               whether fields should be interleaved. This control affects
               buffer size, and if needed, should be set before the buffer is
               created.

          VL_PACKING(int)
               specifies the pixel packing.

          VL_WINDOW(uint)
               specifies the X window id of the window to be associated with a
               screen drain.

          VL_BRIGHTNESS(int)
               specifies brightness factor.

          VL_CONTRAST(int)
               specifies contrast.

          VL_HUE(int)
               specifies hue.

          VL_SATURATION(int)
               specifies saturation.

          VL_FREEZE(boolean)
               causes data transfer to continually send the same frame.

          VL_MUXSWITCH(int)
               specifies the connector to be used on video nodes which have
               multiple inputs. For example, an analog video node may have
               both RCA composite connectors and svideo connectors.

          VL_FORMAT(int)
               specifies the video data format for a video node.

          VL_SYNC(int)
               specifies the sync mode.

          VL_SYNC_SOURCE(int)
               specifies which video node is to be used as the timing source.
               This control should be used in conjunction with VL_SYNC.

          VL_LAYOUT(int)
               specifies the video data layout for a video node.

     Control values are control- and device-dependent.  See the manual for
     detailed descriptions of the values for each control.

     Various controls affect buffer creation, and should be set, if needed,
     prior to calling vlCreateBuffer(3dm). In particular, frame size is
     dependent on the controls VL_CAP_TYPE, VL_PACKING, VL_SIZE, VL_ZOOM,
     VL_OFFSET and VL_TIMING. In general, control settings should be completed
     before the buffer is created.

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 from vlSetControl, the VL had to adjust the
     value passed in before using it. In this case the user should always
     check to see what the value was set to using vlGetControl.  If other
     errors are returned, the value should also be checked.  VLBadValue means
     that the value was not set. VLBadControl means that the control does not
     exist on the specified node or path.

SEE ALSO
     vlGetControlInfo(3dm), vlGetControlList(3dm)