Chapter 2. Programming Sirius Video

Chapter 2. Programming Sirius Video
Prev		Next

The Video Library (VL) contains generic video tools, including simple tools for importing and exporting digital data to and from current and future Silicon Graphics video products, as well as to and from third-party video devices that adhere to the Silicon Graphics architectural model for video equipment.

For example, VL calls enable you to blend computer-generated graphics with frames from videotape or any video source, to present video in a window on the workstation screen, and to digitize and output video data.

This chapter explains

VL basics for Sirius Video
Sirius Video controls
source node controls
drain node controls

Note: Blender node controls are discussed in Chapter 3, "Sirius Video Blending and Keying."
using filters
Sirius Video events and triggering
passing video data through the graphics subsystem

Note: If Sirius Video and Multi-Channel Option are installed on the same graphics pipeline of your system, Sirius Video is not capable of live graphics to video, either directly or pixel-averaged. (You can, however, snap the workstation display, save it as a file, and send the file to video.) Live video input is possible if hinv returns this report:

Sirius Video: unit 0 revision 4 on bus 0 with CPI BOB options

Live video output and input are possible if hinv returns this report:

Sirius Video: unit 0 revision 4 on bus 0 with DGI CPI BOB options

VL Basics for Sirius Video

To run VL, you must

install dmedia_dev option
link with libvl
include vl/vl.h and vl/dev_sirius.h

The client library for VL is /usr/lib/libvl.so. The header files for the VL are in /usr/include/dmedia/vl; the main file is vl.h. This file contains the main definition of the VL API and controls that are common across all hardware.

Note: When building a VL-based program, you must add -lvl to the linking command.

For more information, see Chapter 12, "Getting Started With the Video Library," in the Digital Media Programming Guide (007-1799-040).

This section explains

central VL concepts
VL object classes
VL nodes for Sirius Video
VL data transfer functions

Central VL Concepts

The two central concepts for VL are

path: an abstraction for a way of moving data around
node: an endpoint of the path

The basic nodes are a source (such as a VTR) and a drain (such as graphics). Figure 2-1 diagrams the simplest VL path, with one of each of these two nodes.

Figure 2-1. Simple VL Path

The two other types of node besides source and drain are device node and internal node. Figure 2-2 diagrams a more complex path, a path for a simple blend, which includes two source nodes, a drain node, and an internal (blender) node.

Figure 2-2. VL Blending

VL Object Classes

The VL recognizes five classes of objects:

devices, each including sets of nodes
nodes: sources, drains, and internal nodes (as discussed in the preceding section)
paths, connecting sources and drains (as discussed in the preceding section)
buffers, for sending and receiving frame data to and from host memory

The VL buffers are implemented as ring buffers; each maintains a pointer, a size, and pointers to the head (oldest) and tail (newest) valid data.
controls, or parameters that modify how data flows through nodes; for example:
- video device parameters, such as blanking width, gamma value, horizontal phase, sync source
- video data capture parameters
- blending parameters

VL controls fall into two categories:

device-independent (prefix VL_), which can be used by several Silicon Graphics video products

For details of the device-independent controls, see Chapter 12, "Getting Started With the Video Library," of the Digital Media Programming Guide.
device-dependent (prefix VL_SIR_ for Sirius Video), specific to a particular video device

Both types of VL controls are explained in this chapter with respect to their usage with Sirius Video.

Note: For more detail on VL classes, see Chapter 12, "Getting Started With the Video Library," of the Digital Media Programming Guide.

VL Nodes for Sirius Video

Use vlGetNode() to specify nodes. This call returns the node's handle. Its function prototype is:

VLNode vlGetNode(VLServer vlServer, int type, int kind, int number)

In this prototype, variables are as follows:

VLNode

Handle for the node, used when setting controls or setting up paths.

vlServer

Names the server (as returned by vlOpenVideo()).

type

Specifies the type of node:

VL_SRC: source, such as a tapdeck connected to the Sirius Video breakout box
VL_DRN: drain, such as a window on the workstation graphics monitor
VL_DEVICE: Sirius Video global control, such as trigger, GPI, sync, or genlock voltage level, or default source;Table 2-1 summarizes the values for this type

Note: If you are using VL_DEVICE, the kind (see below) should be set to 0.
VL_INTERNAL: internal node, such as the blend node and chroma key generator node

kind

Specifies the kind of node.

If type is VL_SRC, kind values can be

VL_VIDEO: connection to a video device equipment; for example, a video tape deck or camera

If the type is VL_SRC, values can be

- SIR_SRC_DIGITAL_VIDEO_1 (source node)

- SIR_SRC_DIGITAL_VIDEO_2 (source node)

- SIR_SRC_ANALOG_VIDEO (source node)

These values correspond to input sockets on the Sirius Video breakout box.
VL_GFX: system graphics

Note: Sirius Video uses VL_GFX instead of VL_SCREEN, which is referred to in the section on the Video Library in the Digital Media Programming Guide.
VL_MEM: region of workstation memory
VL_ANY: use any available node (factory setting)

This setting accommodates settings in the control panel vcp, in which input and output parameters can easily changed.

If type is VL_DRN, kind values can be

VL_VIDEO: connection to a video device equipment; for example, a video tape deck or camera
VL_GFX: system graphics
VL_MEM: region of workstation memory
VL_TEXTURE: texture RAM

If type is VL_INTERNAL, kind values can be

VL_BLENDER: a blender node (internal node)
VL_KEYGEN: key generator node (internal node)

number

Number of the node in cases of two or more identical nodes, such as two video source nodes. The default value for all kinds is 0, except VL_VIDEO, which must be SIR_SRC_DIGITAL_VIDEO_1, SIR_SRC_DIGITAL_VIDEO_1, or SIR_SRC_ANALOG_VIDEO.

Besides being a kind value, VL_ANY is also used as a value for number.

The drain nodes VL_TEXTURE and VL_GFX use the same port and cannot both be active at the same time; likewise, the drain nodes VL_VIDEO and VL_MEM use the same port and cannot be active at the same time. Source nodes, however, are independent of each other. Figure 2-3 diagrams this configuration.

Figure 2-3. Sirius Video Source and Drain Nodes

The following fragment creates a digital video input 1 source node and a graphics drain node, and creates the path.

src = vlGetNode(svr, VL_SRC, VL_VIDEO SIR_SRC_DIGITAL_VIDEO_1, VL_ANY);
drn = vlGetNode(svr, VL_DRN, VL_GFX, VL_ANY);
if((path = vlCreatePath(svr, VL_ANY, src, drn)) < 0)
     exit(1);
vlSetupPaths(svr, (VLPathList)&path, 1, VL_SHARE, VL_SHARE);

Note: For details on vlSetupPaths(), see "Displaying Video Data Onscreen," in Chapter 12, "Getting Started With the Video Library," of the Digital Media Programming Guide.

The following fragment illustrates the use of VL_ANY as the default node kind; it allows a program to accept input from whatever video equipment is specified in the video control panel vcp.

src = vlGetNode(svr, VL_SRC, VL_VIDEO, VL_ANY);

It is possible that the actual source or drain node can vary from the source or drain node specified. To discover what the source node is, use the control VL_DEFAULT_SOURCE with vlGetControl() after getting the node handle the normal way. For example:

vlGetControl(svr, path, VL_ANY, VL_DEFAULT_SOURCE, &ctrlval);
nodehandle = vlGetNode(svr, VL_SRC, VL_VIDEO, ctrlval.intVal);

In the second line above, the last argument is a struct that gets the value.

The following fragment adds a video drain node:

VLServer svr;
VLPath path;
VLNode src;
VLNode drn;
VLControlValue timing,format;

drn = vlGetNode(svr, VL_DRN, VL_VIDEO, VL_ANY); /*Get a video drain node */
vlAddNode(svr, path, drn); /* Add node to the exisiting path */

After nodes are specified, the video timing (for example, 525 or CCIR 525) and format (for example S-Video or digital component) must be specified via controls (vlSetControl()). Controls for each node are given in "Source Node Controls" and "Drain Node Controls" later in this chapter and are summarized in Table 2-3.

VL Data Transfer Functions

This section presents a brief summary of VL syntax elements, data transfer categories, and the basic steps of creating an application. For details, please see Chapter 12, "Getting Started With the Video Library," in the Digital Media Programming Guide.

VL syntax elements are as follows:

VL types and constants begin with uppercase VL; for example, VLServer
VL functions begin with lowercase vl; for example, vlOpenVideo()

VL data transfers fall into two categories:

transfers involving memory (video to memory, memory to video), which require setting up a ring buffer
transfers not involving memory (such as video to screen and graphics to video), which do not require a ring buffer

For the two categories of data transfer, based on the VL programming model, the process of creating a VL application consists of these steps:

opening a connection to the video daemon (vlOpenVideo())
specifying nodes on the data path (vlGetNode())
creating the path (vlCreatePath())
optional step: adding more connections to a path (vlAddNode())
setting up the hardware for the path (vlSetupPaths())
specifying path-related events to be captured (vlSelectEvents())
setting input and output parameters (controls) for the nodes on the path (vlSetControl()); video format and timing must be specified
transfers involving memory: creating a ring buffer to hold data for memory transfers (vlGetTransferSize(), vlCreateBuffer())
transfers involving memory: registering the buffer (vlRegisterBuffer())
- starting the data transfer (vlBeginTransfer())
transfers involving memory: getting the data (vlGetNextValid() or vlGetLatestValid(), vlGetActiveRegion(), vlPutFree()) to manipulate frame data
cleanup (vlEndTransfer(), vlDeregisterBuffer(), vlDestroyPath(), vlDestroyBuffer(), vlCloseVideo())

For details on these functions, see Chapter 12, "Getting Started With the Video Library," in the Digital Media Programming Guide.

Sirius Video Controls

To determine the available devices (that is, video options in the workstation, such as Sirius Video) and the nodes available on them, run vlinfo. To determine possible controls for each device, run

vlinfo -l

To set controls for Sirius Video nodes, use vlSetControl(). The following example sets video format and timing on a node:

timing.intVal = VL_TIMING_525_CCIR601;
format.intVal = VL_FORMAT_RGB;

if (vlSetControl(svr, path, drn, VL_TIMING, &timing) <0)
{
     vlPerror("VlSetControl:TIMING");
     exit(1);
}
if (vlSetControl(svr, path, drn, VL_FORMAT, &format) <0)
{
     vlPerror("VlSetControl:FORMAT");
     exit(1);
 }

vlGetControl(svr, path, VL_ANY, VL_DEFAULT_SOURCE, &ctrlval);
nodehandle = vlGetNode(svr, VL_SRC, VL_VIDEO, ctrlval.intVal);

For details on vlSetControl() and vlGetControl(), see Chapter 12, "Getting Started With the Video Library," in the Digital Media Programming Guide.

Tables in this section summarize

device-global controls for Sirius Video
controls for Sirius Video nodes
control values and uses

Table 2-1 summarizes the device-global controls for Sirius Video.

Table 2-1. Device Controls for Sirius Video

Control	Values	Use
VL_DEFAULT_SOURCE	SIR_SRC_DIGITAL_VIDEO_1 SIR_SRC_DIGITAL_VIDEO_2 SIR_SRC_ANALOG_VIDEO SIR_SRC_GRAPHICS SIR_SRC_MEMORY	Determine the source node selected by VL when VL_ANY has been specified as the source node
VL_SIR_SYNC_LEVEL	SIR_SYNC_LEVEL_VIDEO SIR_SYNC_LEVEL_TTL	Sets voltage level at the `SYNC` connector (under `GBRA/YUVA COMPONENT`): 1 V peak-to-peak 4 V peak-to-peak
VL_SIR_GENLOCK_LEVEL	SIR_SYNC_LEVEL_VIDEO SIR_SYNC_LEVEL_TTL	Sets voltage level at the `GENLOCK IN` connector (under `SYNC`): 1 V peak-to-peak 4 V peak-to-peak
VL_SIR_TRIGGER	VL_SIR_TRIGGER_VLAN VL_SIR_TRIGGER_GPI_1 VL_SIR_TRIGGER_GPI_2 VL_SIR_TRIGGER_NONE	Determines whether triggered transfers are triggered on V-LAN, one of two GPI signals, or neither
VL_SIR_VLAN_NODE	Node ID	Associates V-LAN with the node it is genlocked to: a video source or a video drain
VL_SIR_VLAN_CMD	ASCII string containing V-LAN command	Sends V-LAN command string to V-LAN transmitter
VL_SIR_GPI_CHAN1_MODE VL_SIR_GPI_CHAN2_MODE	VL_SIR_GPI_ACTIVE_LOW VL_SIR_GPI_ACTIVE_HIGH	Determines the voltage expected on the GPI (General-Purpose Interface) port on the breakout box: The negative pin is disconnected and internally pulled up. Input is triggered by grounding the positive pin. The negative pin is disconnected and internally grounded. Input is triggered by applying power to the positive pin.
VL_SIR_GPI_OUT_CHAN1 VL_SIR_GPI_OUT_CHAN2	(0,1): 0 = off, 1 = on	Provides trigger information to external devices

Table 2-2 summarizes Sirius Video specific controls and device-independent controls as they apply to Sirius Video.

Table 2-2. Controls for Sirius Video Nodes

Control	Source Nodes				Drain Node
	Digital Video 1, 2	Analog Video	Graphics	Memory	Video	Graphics	Memory	Texture
VL_BRIGHTNESS		X
VL_CAP_TYPE				X			X	X
VL_CONTRAST		X
VL_FORMAT	X	X	X	X	X	X	X	X
VL_H_PHASE	X	X			X
VL_HUE		X
VL_OFFSET (read-only)	X	X	X	X	X	X	X	X
VL_ORIGIN			X
VL_PACKING				X			X	X
VL_RATE (read-only)				X			X
VL_SATURATION		X
VL_SIR_ALPHA_GAIN		X			X
VL_SIR_ALPHA_OFFSET		X
VL_SIR_AUTO_GAIN_CONTROL		X
VL_SIR_BLUE_GAIN		X			X
VL_SIR_BLUE_OFFSET		X
VL_SIR_FIELD_DOMINANCE	X	X			X
VL_SIR_FILTER	X			X	X		X
VL_SIR_GFX_FLICKER			X
VL_SIR_GFX_SIZE			X
VL_SIR_GREEN_GAIN		X			X
VL_SIR_GREEN_OFFSET		X
VL_SIR_H_PHASE_ALPHA	X	X
VL_SIR_LINK_DELAY_A VL_SIR_LINK_DELAY_B	X X
VL_SIR_RED_GAIN		X			X
VL_SIR_RED_OFFSET		X
VL_SIZE (read-only)	X	X	X	X	X	X	X	X
VL_SYNC					X
VL_SYNC_SOURCE		X			X
VL_TIMING	X	X	X	X	X	X	X	X
VL_ZOOM (read-only)	X	X		X	X	X	X	X

Table 2-3 summarizes the values and uses of controls for Sirius Video.

Table 2-3. Sirius Video Control Values and Uses

Control	Values or Range	Use
VL_BRIGHTNESS	(.5, 1,5)	Sets brightness level for composite or YC (S-Video)
VL_CAP_TYPE	Memory or texture drain node: VL_CAPTURE_NONINTERLEAVED VL_CAPTURE_INTERLEAVED Memory source is read-only: VL_CAPTURE_NONINTERLEAVED	Selects type of frame(s) or field(s) to capture
VL_CONTRAST	(0.0, 2.0)	Sets contrast level for composite or YC (S-Video)
VL_FORMAT	VL_FORMAT_RGB (graphics source or drain read-only) VL_FORMAT_BETACAM VL_FORMAT_MII VL_FORMAT_SMPTE_YUV VL_FORMAT_COMPOSITE VL_FORMAT_SVIDEO VL_FORMAT_DIGITAL_COMPONENT VL_FORMAT_DIGITAL_COMPONENT_SERIAL VL_FORMAT_DIGITAL_COMPONENT_DUAL VL_FORMAT_DIGITAL_COMPONENT_DUAL_SERIA L	Sets video format in or out: RGB Betacam MII SMPTE YUV Composite S-Video Parallel 4:2:2:4 Serial 4:2:2:4 Parallel 4:4:4:4 Serial 4:4:4:4
VL_H_PHASE	-32 to +32 pixels	Sets horizontal phase
VL_HUE	-45 to +44 degrees	Sets hue
VL_OFFSET	Read-only; currently set to 0	Sets offset: on video nodes, the offset to the active region of the video; on all other nodes, the offset within the video
VL_ORIGIN	Coordinates; for graphics drain, read-only: 0,0	Sets upper left corner of image in graphics source (usually a window); the offset within the node
VL_PACKING	See Table 2-4 for packing format contents VL_PACKING_RGBA_8 (default, memory source, or memory drain) VL_PACKING_RGB_8 VL_PACKING_YVYU_422_8 VL_PACKING_YUV_444_8 VL_PACKING_YUVA_4444_8 VL_PACKING_ABGR_8 VL_PACKING_AUYV_8 VL_PACKING_A_2_BGR_10 VL_PACKING_A_2_UYV_10 VL_PACKING_AYU_AYV_10 VL_SIR_TEX_PACK_RGB_5 (texture node factory setting) VL_SIR_TEX_PACK_RGBA_4 VL_SIR_TEX_PACK_RGBA_8	Sets packing format for memory source or drain node Sets packing format for texture node
VL_RATE	Read-only; 30 or 60, 25 or 50	Sets transfer rate: fields or frames, depending on the capture type as specified with VL_CAP_TYPE
VL_SATURATION	(0.0, 2.0)	Sets saturation
VL_SIGNAL	VL_SIGNAL_BLACK VL_SIGNAL_REAL_IMAGE Note: Do not use VL_SIGNAL_NOTHING; it returns VLValueOutOfRange.	Sets the video output to black or real image for analog and digital outputs See also VL_SIR_ANALOG_ DRAIN_BLANK_ENABLE and VL_SIR_DIGITAL_ DRAIN_BLANK_ENABLE
VL_SIR_ANALOG_DRAIN_BLANK _ENABLE	VL_SIGNAL_BLACK VL_SIGNAL_REAL_IMAGE	Sets the video output to black or real image for analog outputs only, such as to disable analog output when running digital out; see "Setting Up the Output (Drain)," in Appendix C, "Setting Up Sirius Video for Your Video Hardware," for more information
VL_SIR_AUTO_GAIN_CONTROL	(0,1): 0 = off, 1 = on	For composite or YC (S-Video) source, sets automatic gain adjustment
VL_SIR_DIGITAL_DRAIN_BLANK_ ENABLE	VL_SIGNAL_BLACK VL_SIGNAL_REAL_IMAGE	Sets the video output to black or real image for digital outputs only
VL_SIR_FIELD_DOMINANCE	VL_SIR_F1_IS_DOMINANT VL_SIR_F2_IS_DOMINANT Note: Frames that are output are deinterlaced differently depending on the choice of output field dominance. Deinterlacing is specified in the application; see "Setting Up Analog Source Video," in Appendix C, "Setting Up Sirius Video for Your Video Hardware" for details.	Specifies whether edit occurs on nominal video field boundary (field 1) or on intervening field boundary (field 2); for more information, see "Setting Up Analog Source Video," in Appendix C, "Setting Up Sirius Video for Your Video Hardware"
VL_SIR_FILTER	(0,1): 0 = off, 1 = on	Activates chroma- interpolating filter, converts 4:2:2:4 to 4:4:4:4 on input; converts 4:4:4:4 to 4:2:2:4 on output
VL_SIR_GFX_SIZE	Pixel units	Sets size of graphics on a pixel-by-pixel basis
VL_SIR_GFX_FLICKER	(0,1): 0 = off, 1 = on; default = 0	Reduces flicker in graphics
VL_SIR_H_PHASE_ALPHA	-32 to +32 pixels	Sets horizontal phase on the separate alpha link
VL_SIR_LINK_DELAY_A VL_SIR_LINK_DELAY_B	0 to 3 pixels	When using dual link (two cables) for 4:4:4:4, sets delay to compensate for differing delay on the other link
VL_SIR_RED_GAIN VL_SIR_GREEN_GAIN VL_SIR_BLUE_GAIN VL_SIR_ALPHA_GAIN	(0.0,2.0)	Sets gain for separate inputs or outputs
VL_SIR_RED_OFFSET VL_SIR_GREEN_OFFSET VL_SIR_BLUE_OFFSET VL_SIR_ALPHA_OFFSET	(-1,+1)	Sets offset for separate inputs or outputs
VL_SIR_SYNC_LEVEL	VL_SIR_SYNC_LEVEL_VIDEO VL_SIR_SYNC_LEVEL_TTL	Sets voltage level at the `SYNC` connector (under `GBRA/YUVA COMPONENT`) for video out only: 1 V peak-to-peak 4 V peak-to-peak
VL_SIZE	Coordinates (read-only)	Reads coordinates from input
VL_SYNC	VL_SYNC_INTERNAL VL_SYNC_GENLOCK	Sets sync mode for analog video source or drain; on source, this is set to VL_SYNC_GENLOCK
VL_SYNC_SOURCE	VL_SIR_SYNC_HOUSE VL_SIR_SYNC_GREEN VL_SIR_SYNC_DIGITAL_1 VL_SIR_SYNC_DIGITAL_2 VL_SIR_SYNC_COMPOSITE VL_SIR_SYNC_COMPONENT VL_SIR_SYNC_YC	Sets sync source for analog video source or drain
VL_TIMING	VL_TIMING_525_SQ_PIX VL_TIMING_625_SQ_PIX VL_TIMING_525_CCIR601 VL_TIMING_625_CCIR601	Sets or gets video timing Analog source or drain: 12.27 MHz, 646 x 486 14.75 MHz, 768 x 576 Analog or digital source or drain: 13.50 MHz, 720 x 486 13.50 MHz, 720 x 576
VL_ZOOM	Zoom factor (read-only)	Reads zoom factor of video stream

Note: Blending and keying controls for Sirius Video are explained in Chapter 3, "Sirius Video Blending and Keying," later in this guide. Device-independent controls are discussed in the chapter on VL Blending in Part III of the Digital Media Programming Guide.

Table 2-4 summarizes packing types and their sizes and formats for Sirius Video.

Table 2-4. Sirius Video Packing Type Sizes and Formats

Type	Bits per Pixel	Format MSB------------------------------------------------------------------LSB
VL_PACKING_RGBA_8	32	`AAAAAAAA`₀ `BBBBBBBB`₀ `GGGGGGGG`₀ `RRRRRRRR`₀
VL_PACKING_RGB_8	32	`XXXXXXXX`₀ `BBBBBBBB`₀ `GGGGGGGG`₀ `RRRRRRRR`₀
VL_PACKING_YVYU_422 _8	16	`UUUUUUUU`₀ `YYYYYYYY`₀ `VVVVVVVV`₀ `YYYYYYYY`₁
VL_PACKING_YUV_444_8	32	`XXXXXXXX`₀ `UUUUUUUU`₀ `YYYYYYYY`₀ `VVVVVVVV`₀
VL_PACKING_YUVA_4444_ 8	32	`AAAAAAAA`₀ `UUUUUUUU`₀ `YYYYYYYY`₀ `VVVVVVVV`₀
VL_PACKING_ABGR_8	32	`RRRRRRRR`₀ `GGGGGGGG`₀ `BBBBBBBB`₀ `AAAAAAAA`₀
VL_PACKING_AUYV_8	32	`VVVVVVVV`₀ `YYYYYYYY`₀ `UUUUUUUU`₀ `AAAAAAAA`₀
VL_PACKING_A_2_BGR_10	32	`RRRRRRRR`₀ `RRGGGGGG`₀ `GGGGBBBB`₀ `BBBBBBAA`₀
VL_PACKING_A_2_UYV_10	32	`VVVVVVVV`₀ `VVYYYYYY`₀ `YYYYUUUU`₀ `UUUUUUAA`₀
VL_PACKING_AYU_AYV_1 0	32	Pixels 0, 2, 4, 6: `UUUUUUUUUU`₀ `YYYYYYYYYY`₀ `AAAAAAAAAA`₀ `XX`Pixels 1, 3, 5, 7: `VVVVVVVVVV`₀ `YYYYYYYYYY`₁ `AAAAAAAAAA`₁ `XX`

Note: The subscript in each set indicates the pixel number in the source image.

Table 2-5 summarizes texture node packing types for Sirius Video texture drain nodes.

Table 2-5. Sirius Video Texture Packing Types

Type	Bits per Component
VL_SIR_TEX_PACK_RGB_5	5 (factory setting)
VL_SIR_TEX_PACK_RGBA_4	4
VL_SIR_TEX_PACK_RGBA_8	8

Source Node Controls

This section explains the use of source node controls in separate sections:

digital video
analog video
graphics
memory

Note: For maximum ease of use, set controls in the panel /usr/sbin/vcp. Save the settings as explained in Appendix C, "Setting Up Sirius Video for Your Video Hardware," later in this guide. You do not need to open the panel to put its settings into effect.

Note: Blender node controls are discussed in Chapter 3, "Sirius Video Blending and Keying."

Digital Video Source Node Controls

Select the Digital 1 input node with a statement such as:

src = vlGetNode(svr, VL_SRC, VL_VIDEO, SIR_SRC_DIGITAL_VIDEO_1);

Select the Digital 2 input node with a statement like the following:

src = vlGetNode(svr, VL_SRC, VL_VIDEO, SIR_SRC_DIGITAL_VIDEO_2);

The controls for the VL_SRC nodes SIR_SRC_DIGITAL_VIDEO_1 and SIR_SRC_DIGITAL_VIDEO_2 are as follows:

VL_FORMAT: values are
- parallel 4:2:2:4: VL_FORMAT_DIGITAL_COMPONENT
- serial 4:2:2:4: VL_FORMAT_DIGITAL_COMPONENT_SERIAL
- parallel 4:4:4:4: VL_FORMAT_DIGITAL_COMPONENT_DUAL
- serial 4:4:4:4: VL_FORMAT_DIGITAL_COMPONENT_DUAL_SERIAL
VL_TIMING: either VL_TIMING_525_CCIR601 or VL_TIMING_625_CCIR601

Note: Specify format first, then timing, and then other controls.
VL_H_PHASE, VL_SIR_H_PHASE_ALPHA: the value for each is usually 0
VL_SIR_FILTER
VL_SIR_LINK_DELAY_A, VL_SIR_LINK_DELAY_B
VL_SIR_FIELD_DOMINANCE
VL_SIZE, VL_OFFSET, VL_ZOOM (all three read-only)

For digital video source nodes, set Pixel Format to parallel or serial 4:2:2:4, or to parallel or serial 4:4:4:4, depending on the equipment you have cabled to the Sirius Video breakout box.

In 4:4:4:4 mode, Link A carries Y plus the U and V from even-numbered sample points; Link B carries alpha plus the U and V from odd-numbered sample points.
In 4:2:2:4 mode, Link A carries Y plus the U and V from even-numbered sample points; Link B carries alpha only. If Link B is not connected to external video equipment, the system is 4:2:2 only.

Analog Video Source Node Controls

Select the video input node with a statement such as:

src = vlGetNode(svr, VL_SRC, VL_VIDEO, SIR_SRC_ANALOG_VIDEO);

The controls for VL_SRC node SIR_SRC_ANALOG_VIDEO are as follows:

VL_FORMAT: values are
- VL_FORMAT_RGB
- VL_FORMAT_BETACAM
- VL_FORMAT_MII
- VL_FORMAT_SMPTE_YUV
- VL_FORMAT_COMPOSITE
- VL_FORMAT_SVIDEO
VL_FORMAT determines the color space at which the data goes out; for example, for RGB data, set VL_FORMAT to VL_FORMAT_RGB; for Betacam, set VL_FORMAT to VL_FORMAT_BETACAM.
VL_TIMING: values are
- 525: VL_TIMING_525_SQ_PIX
- 625: VL_TIMING_625_SQ_PIX
- CCIR601 525: VL_TIMING_525_CCIR601
- CCIR601 625: VL_TIMING_625_CCIR601
VL_H_PHASE, VL_SIR_H_PHASE_ALPHA
VL_SIR_RED_GAIN, VL_SIR_GREEN_GAIN, VL_SIR_BLUE_GAIN,VL_SIR_ALPHA_GAIN
VL_SIR_RED_OFFSET, VL_SIR_GREEN_OFFSET,
VL_ SIR_BLUE_OFFSET, VL_SIR_ALPHA_OFFSET
VL_BRIGHTNESS, VL_CONTRAST, VL_SATURATION, VL_HUE
VL_AUTO_GAIN_CONTROL
VL_SIR_FIELD_DOMINANCE
VL_SYNC (read-only), VL_SYNC_SOURCE
VL_SIZE, VL_OFFSET, VL_ZOOM (all three read-only)

The following fragment sets the input sync source:

src = vlGetNode(svr, VL_SRC, VL_VIDEO, SIR_SRC_ANALOG_VIDEO);
vlAddNode(svr, path, src); /* Add node to existing path */

/* Set the input sync src */
syncsrc.intVal = SIR_SYNC_HOUSE;

if (vlSetControl(svr, path, drn, VL_SYNC_SRC, &syncsrc) <0)
{
     vlPerror("VlSetControl:SYNC SRC");
     exit(1);
}

Graphics Source Node Controls

Select the graphics input node with a statement such as:

src = vlGetNode(svr, VL_SRC, VL_GFX, VL_ANY);

Note: If Sirius Video and Multi-Channel Option are installed on the same graphics pipeline of your system, Sirius Video is not capable of live graphics to video. (You can, however, snap the high-resolution display, save it as a file, and send the file to video.)

The controls for VL_SRC node VL_GFX are as follows:

VL_FORMAT (read-only: VL_FORMAT_RGB)
VL_TIMING: values are
- 525: VL_TIMING_525_SQ_PIX
- 625: VL_TIMING_625_SQ_PIX
- CCIR601 525: VL_TIMING_525_CCIR601
- CCIR601 625: VL_TIMING_625_CCIR601
Note: In many situations, CCIR timing gives better results.
VL_ORIGIN, VL_SIR_GFX_SIZE

Note: After setting VL_ORIGIN and VL_SIR_GFX_SIZE with vlSetControl(), immediately use vlGetControl() to determine the actual value set.
VL_SIR_GFX_FLICKER
VL_SIZE, VL_OFFSET (both read-only)

The following fragment sets typical graphics source node controls:

/* Get the first Gfx input */
src = vlGetNode(svr, VL_SRC, VL_GFX, VL_ANY);

/* See what output timing is */
if (vlGetControl(svr,path,drn,VL_TIMING,&timing) < 0 )
{
     vlPerror("vlSetControl");
     exit(1);
}
/* Set the src timing to drn timing */
if (vlSetControl(svr,path,src,VL_TIMING,&timing) < 0 )
{
     vlPerror("vlSetControl");
     exit(1);
}

/* Set the gfx grab origin */
origin.xyVal.x = xcoord;
origin.xyVal.y = ycoord;

/* Set the gfx grab area */
size.xyVal.x = xsize;
size.xyVal.y = ysize;

if (vlSetControl(svr,path,src,VL_SIR_GFX_SIZE,&size) < 0 ) 
{
     vlPerror("vlSetControl");
     exit(1);
}

if (vlSetControl(svr,path,src,VL_ORIGIN,&origin) < 0 )
{
     vlPerror("vlSetControl");
     exit(1);
}

Memory Source Node Controls

Set the memory input node with a statement such as:

src = vlGetNode(svr, VL_SRC, VL_MEM, VL_ANY);

The controls for VL_SRC node VL_MEM are as follows:

VL_FORMAT: this control is always required for memory nodes; default is VL_FORMAT_DIGITAL_COMPONENT

VL_FORMAT determines the color space at which the data comes in:
- for RGB data, set VL_FORMAT to VL_FORMAT_RGB
- for uncompressed YUV, set VL_FORMAT to VL_FORMAT_BETACAM, VL_FORMAT_MII, or VL_FORMAT_SMPTE_YUV
- for CCIR-601-style compressed YUV, set VL_FORMAT to VL_FORMAT_DIGITAL_COMPONENT (the default)
Note: For memory modes, format, timing, and packing are required. You must specify format first, then timing, then packing, and then other controls.
VL_TIMING: this control is always required for memory nodes; values are
- 525: VL_TIMING_525_SQ_PIX
- 625: VL_TIMING_625_SQ_PIX
- CCIR601 525: VL_TIMING_525_CCIR601(the default)
- CCIR601 625: VL_TIMING_625_CCIR601
Note: In many situations, CCIR timing gives better results.
VL_PACKING: factory setting is VL_PACKING_YUVA_RGBA_8

Note: Always set packing to one of the values in Table 2-4.
VL_SIR_FILTER: controls whether the chroma-interpolating filters are used
VL_CAP_TYPE (read-only: VL_CAPTURE_NONINTERLEAVED)
VL_RATE (read-only: either 50 or 59.94 [field only])
VL_SIZE, VL_OFFSET, VL_ZOOM (all three read-only)

Drain Node Controls

This section explains the use of drain node controls in separate sections:

video
graphics
memory
texture

Note: Blender node controls are discussed in Chapter 3, "Sirius Video Blending and Keying."

Video Drain Node Controls

Set the video output node with a statement such as:

drn = vlGetNode(svr, VL_DRN, VL_VIDEO, VL_ANY);

The controls for VL_DRN node VL_VIDEO are as follows:

VL_FORMAT: values are
- VL_FORMAT_RGB
- VL_FORMAT_BETACAM
- VL_FORMAT_MII
- VL_FORMAT_SMPTE_YUV
- VL_FORMAT_COMPOSITE
- VL_FORMAT_SVIDEO
- VL_FORMAT_DIGITAL_COMPONENT (digital 4:2:2:4)
- VL_FORMAT_DIGITAL_COMPONENT_DUAL (digital 4:4:4:4)
Note: As you do for video source node control, always specify format first, then timing, and then other controls.
VL_TIMING: values are
- 525: VL_TIMING_525_SQ_PIX
- 625: VL_TIMING_625_SQ_PIX
- CCIR601 525: VL_TIMING_525_CCIR601
- CCIR601 625: VL_TIMING_625_CCIR601
Note: In many situations, CCIR timing gives better results.
VL_SIGNAL
VL_SIR_ANALOG_DRAIN_BLANK_ENABLE, VL_SIR_DIGITAL_DRAIN_BLANK_ENABLE
VL_SIR_RED_GAIN, VL_SIR_GREEN_GAIN, VL_SIR_BLUE_GAIN,VL_SIR_ALPHA_GAIN
VL_SIR_FILTER
VL_H_PHASE
VL_SYNC, VL_SYNC_SOURCE, VL_SIR_SYNC_LEVEL
VL_SIR_FIELD_DOMINANCE
VL_SIZE, VL_OFFSET, VL_ZOOM (all three read-only)

Graphics Drain Node Controls

Set the video input node with a statement such as:

drn = vlGetNode(svr, VL_DRN, VL_GFX, 0);

The controls for VL_DRN node VL_GFX are as follows:

VL_FORMAT (read-only: VL_FORMAT_RGB)
VL_TIMING (available values are the same as for video drain nodes)
VL_ORIGIN (read-only: 0,0)
VL_OFFSET, VL_SIZE, VL_ZOOM (all three read-only)

Memory Drain Node Controls

Set the video input node with a statement such as:

drn = vlGetNode(svr, VL_DRN, VL_MEM, VL_ANY);

The controls for VL_DRN node VL_MEM are as follows:

VL_FORMAT: this control is always required for memory nodes; default is VL_FORMAT_DIGITAL_COMPONENT

VL_FORMAT determines the color space at which the data goes out; for example, for RGB data, set VL_FORMAT to VL_FORMAT_RGB; for Betacam, set VL_FORMAT to VL_FORMAT_BETACAM.

Note: For memory modes, format, timing, and packing are required. You must specify format first, then timing, then packing, and then other controls.
VL_TIMING: this control is always required for memory nodes; values are the same as for video drain nodes
VL_PACKING: required; factory setting is VL_PACKING_YUVA_4444_8

Note: Always set packing to one of the values in Table 2-4.
VL_SIR_FILTER
VL_CAP_TYPE: values are VL_CAPTURE_NONINTERLEAVED and VL_CAPTURE_INTERLEAVED
VL_OFFSET, VL_SIZE. VL_ZOOM (all three read-only)
VL_RATE (read-only: either 50 or 59.94 [field only])

Texture Drain Node Controls

Set the video input node with a statement such as:

drn = vlGetNode(svr, VL_DRN, VL_TEXTURE, VL_ANY);

The controls for VL_DRN node VL_TEXTURE are as follows:

VL_FORMAT (read-only: VL_FORMAT_RGB)

Note: Always specify format first, then timing, then other controls.
VL_TIMING: values are the same as for video drain nodes
VL_PACKING: required for correct functioning of the texture node; its values are
- VL_SIR_TEX_PACK_RGB_5 (factory setting)
- VL_SIR_TEX_PACK_RGBA_4
- VL_SIR_TEX_PACK_RGBA_8
VL_CAP_TYPE: values are
- VL_CAPTURE_NONINTERLEAVED
- VL_CAPTURE_INTERLEAVED
VL_OFFSET, VL_SIZE, VL_ZOOM (all three read-only)

Using Filters

Digital filters convert video between 4:2:2 and 4:4:4 formats. Digital video and VME sources use interpolating filters; digital video and VME drains use decimating filters.

If you are converting from 4:2:2 to 4:4:4, set the interpolating filter on for the source and off for the drain. If you are converting 4:4:4 to 4:2:2, set the filter off for the source and set the decimating filter on for the drain. For example, if data from a 4:2:2 digital source is to be output as RGB (which is always 4:4:4), the interpolating filter must be turned on for the input. If data from a graphics source (always 4:4:4) is to be output as 4:2:2 digital, the decimating filter must be turned on for the output.

Table 2-6 summarizes these filter settings.

Table 2-6. Setting Filters

Input	On/Off	Output	On/Off
4:2:2	On	4:4:4	Off
4:4:4	Off	4:2:2	On
4:2:2	Off	4:2:2	Off
4:4:4	Off	4:4:4	Off

If you are passing data through in the same format (4:2:2 to 4:2:2, or 4:4:4 to 4:4:4), filters are not needed. If the filters are set on when the source or drain are 4:4:4, the results are not fatal, but image quality is reduced.

Note: For maximum ease of use, set filters and other settings in the panel /usr/sbin/vcp. Save the settings as explained in Appendix C, "Setting Up Sirius Video for Your Video Hardware," later in this guide. You do not need to open the panel to put its settings into effect.

Sirius Video Events and Triggering

The VL provides several ways of handling data stream events, such as completion or failure of data transfer, vertical retrace event, loss of the path to another client, lack of detectable sync, or dropped fields or frames. The method you use depends on the kind of application you're writing:

For a strictly VL application, use:
- vlSelectEvents() to choose the events to which you want the application to respond
- vlCallback() to specify the function called when the event occurs
- your own event loop or a main loop (vlMainLoop()) to dispatch the events
For an application that also accesses another program or device driver, or if you're adding video capability to an existing X or OpenGL application, set up an event loop in the main part of the application and use the IRIX file descriptor (FD) of the event(s) you want to add.

For more information on these functions, see Chapter 14, "VL Event Handling," in the Digital Media Programming Guide.

Table 2-7 summarizes events for Sirius Video. For Sirius Video, this table supersedes the table of events in Chapter 14, "VL Event Handling," in the Digital Media Programming Guide; Sirius Video supports only the events listed in Table 2-7.

Table 2-7. Events Supported by Sirius Video

Event	Use
VL_TRANSFER_COMPLETE	Sent for each field buffer transfer completed
VL_TRANSFER_FAILED	Sent if transfer failed for any reason
VL_STREAM_STARTED	Issued at the beginning of a DMA sequence
VL_STREAM_STOPPED	Issued when the DMA sequence has completed
VL_SEQUENCE_LOST	Issued if the kernel interrupts the DMA for any reason (such as timeout)
VL_SYNC_LOST	Issued if the hardware issues a sync lost interrupt

Note: No VL event is associated with the GPI inputs.

For GPI triggers, the hardware plugged into the GPI port on the Sirius Video breakout box must provide the GPI event, which should match the input level expected by the GPI port as selected by the device control panel or the VL_SIR_GPI_CHAN1_IN_MODE or VL_SIR_GPI_CHAN2_IN_MODE control. See Chapter 4, "Controlling the General-Purpose Interface (GPI)," for full details on GPI triggering.

For V-LAN triggers, issue V-LAN commands to the V-LAN controller so that it generates a coincidence pulse one frame before the point from which you want to grab or lay down an edit clip. See Chapter 5, "Controlling the V-LAN Interface," for full details on V-LAN triggering.

Passing Video Data Through the Graphics Subsystem

Included with Sirius Video system software are four special video output formats (VOFs) for passing video data through the graphics subsystem:

1280x1024_25f
1280x1024_30f
1280x1024_50f
1280x1024_60f

Invoke them with setmon(1G); for example:

setmon -n 1280x1024_25f

Note: You cannot set formats with setmonitor().

These formats configure the workstation display to lock to a video sync source connected to the RealityEngine's genlock input; they automatically select external genlock. If no video sync signal is present, these formats free-run at an inaccurate timebase (for example, 58 Hz..62 Hz for 1280x1024_60f, or 48 Hz..52 Hz for 1280x1024_50f).

In all of these formats, the graphics subsystem runs at twice the input video rate. The difference between the 30/60 or 25/50 versions of the formats is in the rate at which the graphics subsystem executes the swapbuffers() graphics function. The 50/60 versions allow swap buffers to run at twice the video frame rate. The 25/30 versions synchronize the workstation update with the video frame rate.

Use image tools in /usr/sbinizoom (for example, izoom, fromyuv, or snoop) to perform operations on the RGB image files.

Note: To adjust values in the video source, see Appendix C, "Setting Up Sirius Video for Your Video Hardware," later in this guide.

Prev	Table of Contents	Next
Chapter 1. Sirius Video Features and Capabilities		Chapter 3. Sirius Video Blending and Keying