SGI TPL (IRIX 5.3: Developer/Ind2Vid_PG - Chapter 3. Using VL Controls)

IRIX 5.3 » Books » Developer »
Indigo2 Video for Indigo2 IMPACT Programmer's Guide
(document number: 007-2917-001 / published: 1995-09-22) table of contents | additional info | download
find in page

Chapter 3. Using VL Controls
Prev		Next

Chapter 3. Using VL Controls

VL controls enable you to:

specify data transfer parameters, such as the frame rate or count
specify the capture region and decimation, or output window
specify video format and timing
adjust signal parameters, such as hue, brightness, vertical sync, and horizontal sync
specify sync source

This chapter explains

VL control type and values
VL control fraction ranges
VL control classes
VL control groupings

Device-independent controls are documented in /usr/include/dmedia/vl.h. Device-dependent controls for the Indigo² Video board for Indigo² IMPACT are documented in the header file /usr/include/media/vl_ev1.h).

Table 3-1 lists device-independent VL controls alphabetically, along with their values or ranges.

Table 3-1. Device-Independent VL Controls

Control	Purpose	Comments
VL_BLEND_A	Input source for foreground (channel A) image	VLNode type derived from vlGetNode(); must be one of the source nodes
VL_BLEND_B	Input source for background (channel B) image	VLNode type derived from vlGetNode(); must be one of the source nodes
VL_BLEND_A_ALPHA	Input source for foreground (channel A) alpha
VL_BLEND_B_ALPHA	Input source for background (channel B) alpha
VL_BLEND_A_FCN	Blend function that controls mixing of foreground (channel A) signals	VL_BLDFCN_ZERO VL_BLDFCN_ONE VL_BLDFCN_A_ALPHA: foreground_alpha/255 VL_BLDFCN_MINUS_A_ALPHA: 1 - (foreground_alpha/255)
VL_BLEND_B_FCN	Blend function that controls mixing of background (channel B) signals	VL_BLDFCN_ZERO VL_BLDFCN_ONE VL_BLDFCN_B_ALPHA: background_alpha/255 VL_BLDFCN_MINUS_B_ALPHA: 1 - (background_alpha/255)
VL_BLEND_A_NORMALIZE		1 = on; off is not supported
VL_BLEND_B_NORMALIZE	Follows Porter-Duff model (background [channel A]' pixels premultiplied by their corresponding alphas before blending); premultiplies foreground (channel B) by alpha	0 = off 1 = on
VL_BLEND_OUT_NORMALIZE		Not supported
VL_BRIGHTNESS	Brightness
VL_CAP_TYPE	Type of frame(s) or field(s) to capture; see “Interlacing” in Appendix A
VL_CONTRAST
VL_DEFAULT_SOURCE	Default source for the video path
VL_FORMAT	Video format
VL_FREEZE	Data transfer freeze; suspends transfer at the drain node, with no picture regeneration	0 = off 1 = on
VL_H_PHASE	Horizontal phase
VL_HUE	Hue; the control panel `vcp` calculates numerator and denominator
VL_MUXSWITCH	Switch between inputs on a single path, corresponding to the physical connector to the option	Y/C (RCA jacks) set 0 Y/C (S-Video connector): set 1 Composite input 1: set 3; input 2: set 4
VL_OFFSET	On VL_VIDEO nodes, the offset to the active region of the video; on all other nodes, the offset within the video Because the default is 0,0, use negative values to get blanking data
VL_ORIGIN	Upper left corner of image in drain (usually a window); the offset within the node;	Coordinates; default is 0,0
VL_PACKING	Packing of video data at source or drain
VL_RATE	Transfer rate in fields or frames
VL_SIGNAL		N/A
VL_SIZE	On VL_VIDEO nodes, the size of the video; on all other nodes, the clipped size of the video
VL_SYNC	Sync mode	VL_SYNC_INTERNAL VL_SYNC_GENLOCK VL_SYNB_SLAVE
VL_SYNC_SOURCE	Sets sync source for analog breakout box	Composite 1: set 0 Composite 2: set 2
VL_TIMING	Video timing
VL_V_PHASE	Vertical phase	Integer
VL_WINDOW	Window ID for video in a window (screen node only)	Integer
VL_ZOOM	Zoom factor for video stream; fractions greater than 1 expand the picture, fractions less than one reduce the picture	4/1, 2/1, 1/1, 1/2, 1/3, 1/4, 1/5, 1/6, 1/7, 1/8

Note: For information on controls for keying, blending, or wipes, see Chapter 5, “Blending, Keying, and Transitions.”

For detailed information on using VL_CAP_TYPE, VL_FORMAT, VL_MUXSWITCH, VL_OFFSET, VL_PACKING, VL_RATE, VL_SIZE, VL_TIMING, and VL_ZOOM, see “Setting Parameters for Data Transfer to or From Memory” in Chapter 2.

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. WINDOW, HUE, BRIGHTNESS */
    VLControlClass ctlClass; /* SLIDER, DETENT, KNOB, BUTTON */
    VLControlGroup group;    /* BLEND, 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 the 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 info 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 VLProgressionType 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)))

to 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 char NameString[80];
#define VL_CTL_GROUP_PATH     9    /* Path Controls */

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

Table 3-2 summarizes the VL control groupings.

Table 3-2. VL Control Groupings

Grouping	Includes controls for...
VL_CTL_GROUP_BLENDING	Blending; for example, VL_BLEND_B
VL_CTL_GROUP_VISUALQUALITY	Visual quality of sources or drains; for example, VL_H_PHASE or VL_V_PHASE
VL_CTL_GROUP_SIGNAL	Signal of sources or drains; for example, VL_MUXSWITCH or VL_HUE
VL_CTL_GROUP_CODING	Encoding or decoding sources or drains; for example, VL_TIMING or VL_FORMAT
VL_CTL_GROUP_SYNC	Synchronizing video sources or drains; for example, VL_SYNC
VL_CTL_GROUP_ORIENTATION	Orientation or placement of video signals; for example, VL_ORIGIN
VL_CTL_GROUP_SIZING	Setting the size of the video signal; for example, VL_SIZE
VL_CTL_GROUP_RATES	Setting the rate of the video signal; for example, VL_RATE
VL_CTL_GROUP_WS	Specifying the windowing system of the workstation; for example, VL_WINDOW
VL_CTL_GROUP_PATH	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
VL_CTL_GROUP_SIGNAL_ALL	Specifying properties of all signals
VL_CTL_GROUP_SIGNAL_COMPOSITE	Specifying properties of composite signals
VL_CTL_GROUP_SIGNAL_CLUT_COMPOSITE	Specifying properties of composite color lookup table (CLUT) controls
VL_CTL_GROUP_KEYING	Specifying properties of chroma or luma keying controls, such as VL_KEYER_FG_OPACITY
VL_CTL_GROUP_PRO	Specifying values not commonly found on the front panel of a real-world video device; for example, a wipe control
VL_CTL_GROUP_MASK	Masking optional bits to extract only the control group

Prev	Table of Contents	Next
Chapter 2. Creating Video Programs With the Video Library		Chapter 4. VL Event Handling

Indigo2 Video for Indigo2 IMPACT Programmer's Guide
(document number: 007-2917-001 / published: 1995-09-22)    table of contents  |  additional info  |  download

    Front Matter
    About This Guide
    Chapter 1. Features of the Indigo2 Video Option for Indigo2 IMPACT
    Chapter 2. Creating Video Programs With the Video Library
    Chapter 3. Using VL Controls
    Chapter 4. VL Event Handling
    Chapter 5. Blending, Keying, and Transitions
    Appendix A. Video Basics
    Glossary
    Index

home/search | what's new | help