Chapter 6. Using VL Controls

Video Library (VL) controls enable you to

This chapter explains

Device-independent controls are documented in /usr/include/dmedia/vl.h. Device-dependent controls for the OCTANE Personal Video option are documented in the header file /usr/include/dmedia/vl_evo.h (linked to /usr/include/vl/dev_evo.h).

Note: For information on the controls used for specific nodes, see Appendix B, “OCTANE Personal Video Nodes and Their Controls.” For detailed information on using controls such as VL_CAP_TYPE, VL_FORMAT, VL_TIMING, and so on, see Chapter 3, “Setting Parameters for Data Transfer.”.

VL Control Type and Values

The type of VL controls is

typedef long VLControlType;

Common types used by the VL to express the values returned by the controls are

typedef struct __vlControlInfo {
    char name[VL_NAME_SIZE]; /* name of control */
    VLControlType type;      /* e.g. HUE, BRIGHTNESS */ 
    VLControlClass ctlClass; /* SLIDER, DETENT, KNOB, BUTTON */
    VLControlGroup group;    /* VISUAL QUALITY, SIGNAL, SYNC */ 
    VLNode node;             /* associated node */
    VLControlValueType valueType;       /* what kind of data do we have */
    int valueCount;             /* how many data items do we have */
    int numFractRanges;     /* number of ranges to describe control */
    VLFractionRange *ranges; /* range of values of control */

    int numItems;               /* number of enumerated items */
    VLControlItem *itemList;    /* the actual enumerations */
} VLControlInfo;

To store the value of different controls, libvl.a uses this struct:

typedef union {
    VLFraction  fractVal;
    VLBoolean   boolVal;
    int         intVal;
    VLXY        xyVal;
    char        stringVal[96];  /* beware of trailing NULLs! */
    float       matrixVal[3][3];        
    uint        pad[24];        /* reserved */
} VLControlValue;

typedef struct {
    int numControls;
    VLControlInfo *controls;
} VLControlList;

The control info structure is returned by a vlGetControlInfo() call, and it contains many of the items discussed above.

VLControlInfo.number is the number of the VLControlInfo.node that the information pertains to. There may be several controls of the same type on a particular node, but usually there is just one.

VLControlInfo.numFractRanges is the number of fraction ranges for a particular control. The names correspond 1-to-1 with the rangeNames, up to the number of range names, numRangeNames. That is, there may be fewer names than ranges, but never more.

VL Control Fraction Ranges

The VL uses fraction ranges to represent the values possible for a control. A VLFractionRange generated by the VL is guaranteed never to generate a fraction with a zero denominator, or a fractional numerator or denominator.

For a range type of VL_LINEAR, numerator.increment and denominator.increment are guaranteed to be greater than zero, and the limit is always guaranteed to be {numerator,denominator}.base, plus some integral multiple of {numerator,denominator}.increment.

The type definition for fraction types in the header file is

typedef struct {
    VLRange numerator;
    VLRange denominator;
} VLFractionRange;

VL Control Classes

The VL defines control classes for user-interface developers. The classes are hints only; they are the VL developer's idea of how the control is commonly represented in the real world.

#define VL_CLASS_NO_UI            0
#define VL_CLASS_SLIDER           1
#define VL_CLASS_KNOB             2
#define VL_CLASS_BUTTON           3
#define VL_CLASS_TOGGLE           4
#define VL_CLASS_DETENT_KNOB      5
#define VL_CLASS_LIST             6

In the list above, VL_CLASS_NO_UI is often used for controls that have no user-interface metaphor and are not displayed in the video control panel or saved in the defaults file.

The VL controls can be read-only, write-only, or both. The VL includes these macros:

#define VL_CLASS_RDONLY         0x8000  /* control is read-only */
#define VL_CLASS_WRONLY         0x4000  /* control is write-only */
#define VL_CLASS_NO_DEFAULT     0x2000  /* don't save in default files */

#define VL_IS_CTL_RDONLY(x)     ((x)->ctlClass & VL_CLASS_RDONLY)
#define VL_IS_CTL_WRONLY(x)     ((x)->ctlClass & VL_CLASS_WRONLY)
#define VL_IS_CTL_RW(x)         (!(VL_IS_CTL_RDONLY(x) || VL_IS_CTL_WRONLY(x)))

The macros test these conditions:

#define VL_CLASS_MASK        0xfff

typedef unsigned long VLControlClass; /* from list above */

VL Control Groupings

Like control class, control grouping is an aid for the user-interface developer. The groupings are the VL developer's idea of how the controls would be grouped in the real world. These groupings are implemented in the video control panel vcp.

The type definition for groupings is

typedef unsigned int VLControlGroup;

The maximum length of a control or range name is VL_NAME_SIZE.

Table 6-1 summarizes the VL control groupings.

Table 6-1. VL Control Groupings


Includes controls for...


Visual quality of sources or drains; for example, VL_H_PHASE


Signal of sources or drains; for example, VL_HUE


Encoding or decoding sources or drains; for example, VL_TIMING or VL_FORMAT


Synchronizing video sources or drains; for example, VL_SYNC


Orientation or placement of video signals; for example, VL_ORIGIN


Setting the size of the video signal; for example, VL_SIZE


Setting the rate of the video signal; for example, VL_RATE


Specifying the data path through the system; these controls, often marked with the VL_CLASS_NO_UI, are often internal to the VL, with no direct access for the user


Specifying properties of all signals


Specifying properties of composite signals


Specifying properties of composite color lookup table (CLUT) controls


Specifying values not commonly found on the front panel of a real-world video device; for example, filter quality selections


Masking optional bits to extract only the control group