The video daemon /usr/etc/videod, which has device-dependent and device-independent portions, handles video device management and status information.

Management that the video daemon performs includes

Status information for which the video daemon is responsible includes

The generic video tools include

The vlinfo, vidtomem, and memtovid tools are command-line tools. In addition to their reference pages, these tools have explanations in the Media Control Panels User's Guide. Similar applications are supplied in source-code form as examples in the directories /usr/share/src/dmedia/video/vl and /usr/share/src/dmedia/video/vl/OpenGL).

The node is an endpoint or internal processing element of the path, such as a video source like a VTR, video drain (such as to the OCTANE screen), a device (video), or the blender in which video sources are combined for output to a drain.

The path is an abstraction for a way of moving data around. A path is a set of nodes with video routes (connections) between the ports on the nodes. A path defines the useful connections between video sources and video drains. Figure 3-2 shows a simple path in which a frame from a videotape is displayed in a workstation window.

Figure 3-2. Simple VL Path

Figure 3-3 shows a more complex path with two video sources: a frame from a videotape and a computer-generated image are blended and output to a workstation window. This path is set up in stages.

Figure 3-3. Simple VL Blending

The port is an entity on a node that produces or consumes video data.

Most nodes have only one port, such as the video in or video out nodes. Each internal node has at least two ports, input (drain) and output (source). The blend node has several ports (A alpha in, A pixel in, B alpha in, B pixel in, pixel out, alpha out).

Ports have several attributes:

Ports produce or consume various types of data: pixel, alpha, or dual-link data. The identification of the port as pixel or alpha may cause the video stream to be treated differently. For example, alpha data, which can be supplied to OCTANE video in the CCIR range only, is internally expanded to full range before it is used. No range expansion is performed for pixel data. Dual-link channels carry both alpha and pixel data, although one data type may be ignored depending on the format.

Ports have generic names; for example:

For the symbolic names for ports, see /usr/include/dmedia/dev_impact.h. Appendix A, “Video Library Controls and Compression Library Parameters for the OCTANE Compression Option,” gives the ports associated with each node.

The connections between ports on nodes determine the topology of a path. Single-link ports can be connected to single-link ports only; dual-link ports can be connected to double-link ports only.

Data flows from a source port to a drain port. It is not permissible to connect a source port to another source port, or a drain port to another drain port.

Connections obey stream-usage levels set with vlSetupPaths(). Usage is drain-centric: the usage levels of the path(s) using the drain node serve as the usage level of the connection.

The functions vlSetConnection() and vlGetConnection() manipulate connections:

The OCTANE Compression board translates video signals into a form usable by the Indigo² workstation. It also does the reverse, translating memory buffers into video signals.

Table 3-1 summarizes the formats that the OCTANE Compression board supports.

Timing type expresses the timing of video presented to a source or drain. Table 3-5 summarizes dimensions for VL_TIMING.

To specify video input and output formats of the video signal on the physical connector, use VL_FORMAT. Table 3-6 summarizes the options.

A video packing describes how a video signal is stored in memory, in contrast to a video format, which describes the characteristics of the video signal.

Packings are specified through the VL_PACKING control on the memory nodes. This control also converts one video output format to another in memory, within the limits of the nodes.

Packing types for eight bits per component are summarized in Table 3-7.

In the VL, VL_ZOOM controls the expansion or decimation of the video image. For OCTANE Compression, VL_ZOOM is used in this way:

Figure 3-4 illustrates decimation.

Figure 3-4. Decimation

VL_ZOOM takes a nonzero fraction as its argument; do not use negative values. For example, this fragment captures half-size decimation video to the screen:

val.fractVal.numerator = 1;
val.fractVal.denominator = 2;
if (vlSetControl(server, screen_path, screen_drain_node, VL_ZOOM, &val)){
   vlPerror("Unable to set zoom");
   exit(1);
}

---

Note: For a source, decimation takes place before blending; for a drain, blending takes place before decimation.

---

This fragment captures half-size decimation video to the screen, with clipping to 320 × 243 (NTSC size minus overscan):

val.fractVal.numerator = 1;
val.fractVal.denominator = 2;
if (vlSetControl(server,screen_path, screen_drain_node,
VL_ZOOM, &val))
{
    vlPerror("Unable to set zoom");
    exit(1);
}
val.xyVal.x = 320;
val.xyVal.y = 243;
if (vlSetControl(server, screen_path, screen_drain_node,
VL_SIZE, &val))
{
    vlPerror("Unable to set size");
    exit(1);
}

This fragment captures xsize × ysize video with as much decimation as possible, assuming the size is smaller than the video stream:

if (vlGetControl(server, screen_path, screen_source, VL_SIZE, &val))
{
   vlPerror("Unable to get size");
   exit(1);
}
if (val.xyVal.x/xsize < val.xyVal.y/ysize)
   zoom_denom = (val.xyVal.x + xsize - 1)/xsize;
else
   zoom_denom = (val.xyVal.y + ysize - 1)/ysize;
val.fractVal.numerator = 1;
val.fractVal.denominator = zoom_denom;
if (vlSetControl(server, screen_path, screen_drain_node, VL_ZOOM, &val))
{
   /* allow this error to fall through */
   vlPerror("Unable to set zoom");
}
val.xyVal.x = xsize;
val.xyVal.y = ysize;
if (vlSetControl(server, screen_path, screen_drain_node,
VL_SIZE, &val))
{
   vlPerror("Unable to set size");
   exit(1);
}

VL_SIZE controls how much of the image sent to the drain is used, that is, how much clipping takes place. This control operates on the zoomed image; for example, when the image is zoomed to half size, the limits on the size control change by a factor of 2. Figure 3-5 illustrates clipping.

Figure 3-5. Clipping an Image

For example, to display PAL video in a 320 × 243 space, clip the image to that size, as shown in the following fragment:

VLControlValue value;

value.xyval.x=320;
value.xyval.y=243;
vlSetControl(vlSvr, path, drn, VL_SIZE, &value); 

---

Note: Because this control is device-dependent and interacts with other controls, always check the error returns. For example, if offset is set before size and an error is returned, set size before offset.

---

VL_OFFSET puts the upper left corner of the video data at a specific position; it sets the beginning position for the clipping performed by VL_SIZE. The values you enter are relative to the origin.

This example places the data ten pixels down and ten pixels in from the left:

VLControlValue value;

value.xyval.x=10; 
value.xyval.y=10; 
vlSetControl(vlSvr, path, drn, VL_OFFSET, &value); 

To capture the blanking region, set offset to a negative value.

Figure 3-6 shows the relationships between the source and drain size, and offset.

---

Note: For memory nodes, VL_OFFSET and VL_SIZE in combination define the active region of video that is transferred to or from memory.

---

Figure 3-6. Zoom (Decimation), Size, and Offset

An application can request that OCTANE Compression capture or play back a video stream in a number of ways. For example, the application can request that each field be placed in its own buffer, that each buffer contain an interleaved frame, or that only odd or even fields be captured. This section enumerates the capture types that OCTANE Compression supports.

A field mask is useful for identifying which fields will be captured and played back and which fields will be dropped. A field mask is a bit mask of 60 bits for NTSC or 50 bits for PAL (two fields per frame). A numeral 1 in the mask indicates that a field is captured or played back, while a zero indicates that no action occurs.

For example, the following field mask indicates that every other field will be captured or played back:

10101010101010101010...

Capture types are as follows:

VL_RATE determines the data transfer rate by field or frame, depending on the capture type as specified by VL_CAP_TYPE, as shown in Table 3-8.

---

Note: Not all rates are supported on all memory nodes; see Appendix A, “VL Controls and CL Parameters for the OCTANE Compression Option,” for details. The buffer size must be set in accordance with the capture type, as listed in Table 3-10 in this chapter.

---

The VL_CAPTURE_NONINTERLEAVED capture type specifies that frame-size units are captured noninterleaved. Each field is placed in its own buffer, with the dominant field in the first buffer. If one of the fields of a frame is dropped, all fields are dropped. Consequently, an application is guaranteed that the field order is maintained; no special synchronization is necessary to ensure that fields from different frames are mixed.

The rate (VL_RATE) for noninterleaved capture is in terms of fields and must be even. For NTSC, the capture rate may be from 2 to 60 fields per second, and for PAL, from 2 to 50 fields per second. Because a frame is always captured as a whole, a rate of 30 fields per second results in the following field mask:

1100110011001100...

The first bit in the field mask corresponds to the dominant field of a frame. OCTANE Digital Video waits for a dominant field before it starts the transfer.

If VL_CAPTURE_NONINTERLEAVED is specified for playback, similar guarantees apply as for capture. If one field is lost during playback, it is not possible to “take back” the field. OCTANE Digital Video resynchronizes on the next frame boundary, although black or “garbage” video might be present between the erring field and the frame boundary.

The rate during playback also follows the rules for capture. For each 1 in the mask above, a field from the VL buffer is output. During the 0 fields, the previous frame is repeated. Note that the previous frame is output, not just the last field. If there are a pair of buffers, the dominant field is placed in the first buffer.

Interleaved capture interleaves the two fields of a frame and places them in a single buffer; the order of the frames depends on the value set for VL_MGV_DOMINANCE_FIELD (see Table A-3 or Table A-4 in Appendix A for details). OCTANE Digital Video guarantees that the interleaved fields are from the same frame: if one field of a frame is dropped, then both are dropped.

The rate for interleaved frames is in frames per second: 1-30 frames per second for NTSC and 1-25 frames per second for PAL. A rate of 15 frames per second results in every other frame being captured. Expressed as a field mask, the following sequence is captured:

1100110011001100....

As with VL_CAPTURE_NONINTERLEAVED, OCTANE Digital Video begins processing the field mask when a dominant field is encountered.

During playback, a frame is deinterleaved and output as two consecutive fields, with the dominant field output first. If one of the fields is lost, OCTANE Digital Video resynchronizes to a frame boundary before playing the next frame. During the resynchronization period, black or “garbage” data may be displayed.

Rate control follows similar rules as for capture. For each 1 in the mask above, a field from the interleaved frame is output. During 0 periods, the previous frame is repeated.

In the VL_CAPTURE_EVEN_FIELDS capture type, only even (F2) fields are captured, with each field placed in its own buffer. Expressed as a field mask, the captured fields are

1010101010101010...

OCTANE Digital Video begins processing this field mask when an even field is encountered.

The rate for this capture type is expressed in even fields. For NTSC, the range is 1-30 fields per second, and for PAL 1-25 fields per second. A rate of 15 fields per second (NTSC) indicates that every other even field is captured, yielding a field mask of

1000100010001000...

During playback, the even field is repeated as both the F1 and F2 fields, until it is time to output the next buffer. If a field is lost during playback, black or “garbage” data might be displayed until the next buffer is scheduled to be displayed.

The VL_CAPTURE_ODD_FIELDS capture type works the same way as VL_CAPTURE_EVEN_FIELDS, except that only odd (F1) fields are captured, with each field placed in its own buffer. The rate for this capture type is expressed in odd fields. A rate of 15 fields per second (NTSC) indicates that every other odd field is captured. Field masks are the same as for VL_CAPTURE_EVEN_FIELDS.

The VL_CAPTURE_FIELDS capture type captures both even and odd fields and places each in its own buffer. Unlike VL_CAPTURE_NONINTERLEAVED, there is no guarantee that fields are dropped in frame units. Field synchronization can be performed by examining the UST, the MSC, or the dmedia info sequence number associated with each field.

The rate for this capture type is expressed in fields. For NTSC, the range is
1-60 fields per second, and for PAL 1-50 fields per second. A rate of 30 fields per second (NTSC) indicates that every other field is captured, resulting in the following field mask:

101010101010101010...

Contrast this with the rate of 30 for VL_CAPTURE_NONINTERLEAVED, which captures every other frame.

Field mask processing begins on the first field after the transfer is started; field dominance, evenness, oddness play no role in this capture type.

---

Note: The OCTANE Digital Video can make use of the Unadjusted System Time (UST)/Media Stream Count (MSC) feature. See Chapter 2 of the OCTANE Digital Video Programmer's Guide for information.

---

Use the control VL_MGC_DOMINANCE_FIELD to set the field dominance mode, which determines the order in which the fields are read from memory. This control applies only to the frame-oriented capture types VL_CAPTURE_INTERLEAVED and VL_CAPTURE_NONINTERLEAVED.

The values for the control VL_MGC_DOMINANCE_FIELD are VL_MGC_DOMINANCE_F1 (the default) and VL_MGC_DOMINANCE_F2. Figure 3-7 diagrams the field dominance values.

Figure 3-7. Field Dominance

You can set field dominance independently for each DMA channel.

OCTANE Compression has hardware acceleration for shrinking images that have an original size of up to 1000 × 1000 pixels. Original sizes with height or width larger than 1000 pixels are sized (and optionally converted to the RGB color space) by software on the host CPU.

Table 3-9 lists controls you can use to pad and scale images on capture.

For examples, see /usr/share/src/dmedia/video/vl/OpenGL/contcapt.c.

Use vlGetNextValid() to read all the frames in the buffer or get a valid frame of data. Its function prototype is

VLInfoPtr vlGetNextValid(VLServer vlSvr, VLBuffer vlBuffer)

Use vlGetLatestValid() to read only the most current frame in the buffer, discarding the rest. Its function prototype is

VLInfoPtr vlGetLatestValid(VLServer vlSvr, VLBuffer vlBuffer) 

After removing interesting data, return the buffer for use with vlPutFree() (video to memory). Its function prototype is

int vlPutFree(VLServer vlSvr, VLBuffer vlBuffer)

Use vlGetNextFree() to get a free buffer to which to write data. Its function prototype is

VLInfoPtr vlGetNextFree(VLServer vlSvr, VLBuffer vlBuffer,
      int size)

After filling the buffer with the data you want to send to video output, use vlPutValid() to put a frame into the valid list for output to video (memory to video). Its function prototype is

int vlPutValid(VLServer vlSvr, VLBuffer vlBuffer)

---

Caution: These calls do not have count or block arguments; appropriate calls in the application must deal with a NULL return in cases of no data being returned.

---

Use vlGetActiveRegion() to get a pointer to the active buffer. Its function prototype is

void * vlGetActiveRegion(VLServer vlSvr, VLBuffer vlBuffer,
     VLInfoPtr ptr)

Use vlGetDMediaInfo() to get a pointer to the DMediaInfo structure associated with a frame. This structure contains timestamp and field count information. The function prototype for this call is

DMediaInfo * vlGetDMediaInfo(VLServer vlSvr,
   VLBuffer vlBuffer, VLInfoPtr ptr)

Use vlGetImageInfo() to get a pointer to the DMImageInfo structure associated with a frame. This structure contains image size information. The function prototype for this call is

DMImageInfo * vlGetImageInfo(VLServer vlSvr,
   VLBuffer vlBuffer, VLInfoPtr ptr)