Use vlCreatePath() to create the video data transfer path. Its function prototype is

VLPath vlCreatePath ( VLServer svr, VLDev dev, VLNode source, VLNode drain )

You can create a path using any available node by specifying the generic value VL_ANY for the device. This code fragment creates a path if the device is unknown:

if ((path = vlCreatePath(vlSvr, VL_ANY, src, drn)) < 0) {
    vlPerror(_progName);
    exit(1);
}

This code fragment creates a path that uses a device specified by parsing a devlist:

if ((path = vlCreatePath(vlSvr, devlist.devices[devicenum].dev, src,
    drn)) < 0) {
    vlPerror(_progName);
    exit(1);
}

---

Note: If the path contains one or more invalid nodes, vlCreatePath() returns VLBadNode.

---

If you specify VL_ANY as the device when you create the path, use vlGetDevice() to discover the device ID selected. Its function prototype is

VLDev vlGetDevice ( VLServer vlSvr, VLPath path )

For example:

devicenum = vlGetDevice(vlSvr, path);
deviceName = devlist.devices[devicenum].name;
printf("Device is: %s/n", deviceName);

You can add nodes to an existing path to provide additional processing or I/O capabilities. For this optional step, use vlAddNode(). Its function prototype is

int vlAddNode ( VLServer vlSvr, VLPath vlPath, VLNodeId node )

where

Path attributes specify usage rules for video controls and data transfers. Even though the names are the same, the intent and function of the usage attributes depend on whether they specify control or stream (data) usage.

Control usage attributes are

Stream (data) usage attributes are

Once the path has been created and usage attributes assigned, its settings do not go into effect until the path is set up with vlSetupPaths(). Its function prototype is

int vlSetupPaths ( VLServer vlSvr, VLPathList paths,
                   u_int count, VLUsageType ctrlusage,
                   VLUsageType streamusage )

where

This example fragment sets up a path with shared controls and a locked stream:

if (vlSetupPaths(vlSvr, (VLPathList)&path, 1, VL_SHARE,
    VL_LOCK) < 0)
{
    vlPerror(_progName);
    exit(1);
}

---

Note: The Video Library infers the connections on a path if vlBeginTransfer() is called and no drain nodes have been connected using vlSetConnection() (implicit routing). To specify a path that does not use the default connections, use vlSetConnection() (explicit routing).

---

---

Note: Do not combine implicit and explicit routing.

---

VL_DEFAULT_SOURCE specifies which of the input nodes is to be considered the “default” input. This is automatically set up when the video driver is loaded according to Table 4-1, which indicates which input signal(s) is active.

For example, if a VCR is connected to the S-Video input and it is powered on, then it is the default input.

When the VL_DEFAULT_SOURCE is changed, a VLDefaultSource event is sent to all processes that have this event enabled in their vlEventMask.

The VL_FORMAT control on the video source node is usually set using the Video Control Panel. It is often of no concern to a vid-to-mem application, except with Sirius Video^™, where it is used to determine color space conversion.

VL_FORMAT selects the input video format (use VL_MUXSWITCH if there is more than one to select):

The VL_TIMING control on the video source node is usually set from the Video Control Panel. The input source timing also affects the value returned by the VL_SIZE control on the video source node.

Use VL_TIMING to determine whether the input source timing is PAL or NTSC, and whether the input pixels are square or not. Knowing whether the input signal is PAL or NTSC timing is useful for setting the VL_RATE control on the memory drain node. (For Sirius Video, it is also used to determine the value for the VL_TIMING control on the memory drain node.) An easy way to set the VL_TIMING value for the memory node is to read the value of the VL_TIMING control from the video source node, and then set that value into the VL_TIMING control for the memory node.

The VL_TIMING control is an integer value that adjusts the video filter for different video standards.

The 525 (NTSC) or 625 (PAL) timing standards are specified, and the pixels are considered to be in the accepted video aspect ratio for those standards (also known as “non-square”) for VL_TIMING_525_CCIR601 and VL_TIMING_625_CCIR601.

The 525 (NTSC) or 625 (PAL) timing standards are specified and, depending on the VL video device and the connector type, a non-square-to-square pixel filter can be engaged so that in memory, the pixels are in a 1:1 aspect ratio (which is compatible with OpenGL) for VL_TIMING_525_SQ_PIX and VL_TIMING_625_SQ_PIX.

When these timings are applied to a path that has a standard digital camera attached, then the 525 (NTSC) or 625 (PAL) timing standards are interpreted to mean that the external pixels are in a 1:1 aspect ratio, and there is no non-square format available for the internal pixels.The pixel conversion applies a ratio of 11/10 for NTSC, and a ratio of 11/12 for PAL.

---

Note: The application program should always check the default VL_SIZE after a timing change to determine the size of the resultant images.

---

The VL_SIZE control on the video source node is a read-only control. The x and y values returned by this control are affected by the setting of the VL_TIMING control on the video source node. The x and y values of this control are not, in general, affected by the settings of any controls in the memory drain node, including VL_ZOOM, VL_SIZE, and VL_CAP_TYPE.

The x component value of this control reveals the width, in pixels, of the unzoomed, unclipped video input images (in fields or frames, depending on the VL_CAP_TYPE). The meaning of the y component value of the video source node's VL_SIZE control depends on the video device. On Sirius, the y value is the number of pixel rows in each field, and includes the count of rows of pixel samples taken from the field's Vertical Retrace Interval. On EV1 and VINO, the y value is the number of pixel rows in each frame (pair of fields), and does not include any pixel rows from the Vertical Retrace Interval.

A vid-to-mem application chooses the color space (that is, the set of components that make up each pixel–for example–RGB, RGBA, YUV, YCrCb, Y, YIQ) and the particular packing of those pixel components into memory using the VL_PACKING control (on all video devices) and also with the VL_FORMAT control on Sirius video.

On all VL video devices except Sirius, VL_FORMAT is not applicable to memory drain nodes, and VL_PACKING is used to select the color space as well as the packing. Packings that imply RGB or RGBA color spaces select those spaces. Packings that imply Y, YUV, or YCrCb color spaces select one of those spaces.

On all VL video devices except Sirius, the capture mode can be set by the application. Its setting determines whether the images in the buffers returned by the VL are individual fields, interleaved frames, or pairs of non-interleaved fields.

VL_CAP_TYPE specifies the capture mode:

There is no single VL_CAP_TYPE that is available, and implemented in the same way, on all VL video devices. VL_CAPTURE_NONINTERLEAVED is available on all devices, but has different meanings on different platforms. VL_CAPTURE_INTERLEAVED, VL_CAPTURE_EVEN_FIELDS, and VL_CAPTURE_ODD_FIELDS are available and common to all VL video devices except Sirius.

On Sirius Video, VL_CAP_TYPE is read-only, and is permanently set to VL_CAPTURE_NONINTERLEAVED. Each captured buffer contains exactly one field, unclipped, unzoomed, with n leading pixel rows of samples from the Vertical Retrace Interval.

EV1 implements VL_CAPTURE_NONINTERLEAVED differently from all other VL video devices. On all VL video devices except EV1, when VL_CAP_TYPE is set to VL_CAPTURE_NONINTERLEAVED, each image buffer that the VL gives to the application contains one field, either F1 or F2, and VL_RATE (the rate at which these buffers are returned) is in fields per second, not frames per second. But on EV1 video devices, when VL_CAP_TYPE is set to VL_CAPTURE_NONINTERLEAVED, each image buffer contains two non-interleaved fields, and VL_RATE is in frames per second.

On all VL video devices except Sirius, VL_RATE sets the target rate (upper bound) of image buffers per second to be captured and returned to the application. The VL does not deliver more buffers per second than the rate you specify, but it can deliver less.

The contents of each image buffer is either a frame or a field, as determined by the VL_CAP_TYPE control. Accordingly, VL_RATE is in units of fields per second or frames per second, as determined by the VL_CAP_TYPE control.

VL_RATE is effective on a pair of fields, though it is still interpreted as a field rate. What this means is that if a field is to be dropped because of the effects of VL_RATE, then both fields are dropped (for output, if the VL_RATE causes some fields to be dropped, then the preceding fields are repeated). Also, changing from interleaved to non-interleaved mode doubles the VL_RATE.

VL_RATE is expressed as a fractional value (an integer numerator divided by an integer denominator) and ranges from the maximum rate (60/1 for NTSC, 50/1 for PAL, and half of each value for VL_CAPTURE_INTERLEAVED) down to 1/0xffff in any increment. Both the numerator and denominator must be specified. The usual value for the denominator is 1. Some devices convert the fraction to an integer number of images per second by truncating rather than rounding, so using values that are equivalent to integer values is the safest thing to do. Because VL_RATE is a fraction, vlGetControlInfo() cannot be used to obtain the minimum or maximum values for VL_RATE.

Acceptable values are determined from the following list of devices:

VINO's VL_RATE cannot be set to a value less than 5/1.

This section discusses the VL_SIZE control and the VL_OFFSET control on the memory drain node.

The VL_SIZE control on the memory drain node determines the number of rows of pixels, and the number of pixels in each row, in each image buffer (field or frame) that the VL returns to the application. If zooming (decimation) is being done, the VL_SIZE control on the memory drain node specifies the size of the image after it has been decimated.

The VL_SIZE control on the memory drain node can be used to “clip” a region out of an image by setting the x and/or y components to values that are smaller than the size of the captured (and decimated, if applicable) image.

When the (possibly decimated) image is being clipped, the clipped region does not have to come from the upper left hand corner of the (possibly decimated) source image. The VL_OFFSET control on the memory drain node determines the number of top pixel rows to skip and the number of leading pixels to skip in each row to find the first pixel in the (possibly decimated) image to place in the image buffer, the first pixel of the clipping region.

When zooming (decimation) is being used, VL_OFFSET is always in coordinates of the zoomed image. It is as if the entire source image is decimated down, and then the clipping function is applied to the decimated image. In practice, the hardware usually clips before decimating, but the VL API always specifies the VL_OFFSET in the coordinates of the decimated (virtual) image.

On all VL devices except Sirius, the vertical (y) component of VL_OFFSET may be specified with a negative value. This causes the clipping region to include row of samples taken before the top of the image, for example, rows from the Vertical Retrace Interval. This feature is usually used with VL_ZOOM of 1/1, since the information in the Vertical Retrace Interval isn't an image and doesn't make sense to decimate or average, at least not in the vertical direction.

The VL imposes these requirements on the values of VL_OFFSET and VL_SIZE:

Both VL_OFFSET and VL_SIZE cannot be set in one atomic operation. A change in either component of either control could violate one of the rules, especially after VL_ZOOM is set to a smaller fraction. It may be necessary to alternately and repeatedly set VL_OFFSET and VL_SIZE until no VLValueOutOfRange errors are reported.

Every VL video device places additional limitations on the range of acceptable values of VL_SIZE and VL_OFFSET. Each device has different limitations.

VL_ZOOM controls the expansion or decimation of the video image. Values greater than 1 expand the video; values less than 1 perform decimation. The only value of VL_ZOOM that works on all VL devices is 1/1. Acceptable values for vid-to-mem applications follow.

VINO may exhibit the following effects at these decimation factors: 1/4, 1/5, 1/6, 1/7, and 1/8:

As a workaround, the VINO driver implements decimation by 1/4 and 1/6 by decimating in hardware by 1/2 or 1/3, and then decimating by an additional factor of 1/2 in software. This produces acceptable looking images, but at significant cost in CPU time. The three other VL_ZOOM factors, 1/5, 1/7, and 1/8, also exhibit the green image effect.

For example, the listed zoom factors on VINO may behave as follows:

For example, the listed zoom factors on EV1 may behave as follows:

---

Note: Sirius and Galileo 1.5 accept only a 1/1 zoom factor (Sirius and Galileo 1.5 don't zoom).

---

VL_ZOOM specifies the decimation of the input video to a fraction of its original size. Scaling from 1/1 down to 1/256 is available; the actual increments are: 256 to 1/256. The actual zoom value is affected by VL_ASPECT.

---

Note: VL_ZOOM is available only on the VL_DRN/VL_MEM (input) node.

---

VL_SYNC selects the type of sync used for video output. The choices are:

VL_LAYOUT specifies the pixel layout (same as DM_IMAGE_LAYOUT):

When you modify digitized video data or synthesize new video data, the result must consist of fields with all the same properties, but temporally offset and spatially disjointed. This may not be trivial to implement in a typical renderer without wasting a lot of rendering resources (rendering 50/60 images a second, throwing out unneeded lines in each field) unless the developer has fields in mind from the start.

You might think that you can generate synthetic video by taking the output of a frame-based renderer at 25/30 frames per second and pulling two fields out of each frame image. This does not work well: the motion in the resulting sequence on an interlaced video monitor noticeably stutters, due to the fact that the two fields are scanned out at different times, yet represent an image from a single time. Your renderer must know that it is rendering 50/60 temporally distinct images per second.

Two relatively easy tasks to do with frame-based data, such as movies, are playing it slowly (by outputting some frames more than once) or dealing with frames that are missing in the input stream by duplicating previous frames. There are more elaborate ways to generate better-looking results in these cases, and they, too, are not difficult to implement on frame-based data.

Suppose you are playing a video sequence, and run up against a missing field, as shown in Figure 4-5 (the issues discussed here also come up when you want to play back video slowly).

Figure 4-5. Dropped Frame

To keep the playback rate of the video sequence constant, put some video data in that slot. Which field do you choose?

Suppose you choose to duplicate the previously displayed field (field 2), as shown in Figure 4-6.

Figure 4-6. Field Duplication

You can also try duplicating field 4 or interpolating between 2 and 4, but with all of these methods there is a crucial problem: The surrounding fields contain data from a different spatial location than the missing field. If you view the resulting video, you immediately notice that the image visually jumps up and down at this point. This is a large-scale version of the same problem that made the 2-pixel-high line jump up and down: Your eye is very good at picking up on the vertical “motion” caused by an image being drawn to the lines of one field, then being drawn again one picture line higher, into the lines of the other field. You would see this even if the ball was not in motion.

Suppose instead you choose to fill in the missing field with the last non-missing field that occupies the same spatial locations, as shown in Figure 4-7.

Figure 4-7. Field Replacement

Now you have a more obvious problem: You are displaying the images temporally out of order. The ball appears to fly down, fly up again for a bit, and then fly down. Clearly, this method is not good for video that contains motion. But for video containing little or no motion, it works pretty well, and does not suffer the up-and-down jittering of the previous approach.

Which of these two methods is best thus depends on the video being used. For general-purpose video where motion is common, you'd be better off using the first technique, the “temporally correct” technique. For certain situations such as computer screen capture or video footage of still scenes, however, you can often get guarantees that the underlying image is not changing, and the second technique, the “spatially correct” technique, is best.

As with de-interlacing methods, there are many more elaborate methods for interpolating fields that use more of the input data. For example, you can interpolate fields 2 and 4 and then interpolate the result of that vertically to guess at the content of the other field's lines. Depending on the situation, these techniques may or may not be worth the effort.

The problem of getting a good still frame from a video input has a counterpart in video output. Suppose you have a digitized video sequence and you want to pause playback of the sequence. Either you, the video driver, or the video hardware must continue to output video fields even though the data stream has stopped, so which fields do you output?

If you choose the “temporally correct” method and repeatedly output one field (effectively giving you the “line-doubled” look), then you get an image with reduced vertical resolution. But you also get another problem: As soon as you pause, the image appears to jump up or down, because your eye picks up on an image being drawn into the lines of one field, and then being drawn one picture line higher or lower, into the lines of another field. Depending on the monitor and other factors, the paused image may appear to jump up and down constantly or it may appear to jump only when you enter and exit pause.

If you choose the “spatially correct” method and repeatedly output a pair of fields, then if there is any motion at the instant where you pause, you see that motion happening back and forth, 60 times a second. This can be very distracting.

There are, of course, more elaborate heuristics that can be used to produce good looking pauses. For example, vertically interpolating an F1 to make an F2 or vice versa works well for slow-motion, pause, and vari-speed play. In addition, vertical interpolation can be combined with inter-field interpolation for “super slow-motion” effects.

alReadFrames() reads a specified number of sample frames from an input port to a sample data buffer, blocking until the requested number of sample frames have been read from the port. Its function prototype is

int alReadFrames ( const ALport port, void *samples, const int framecount )

where

To prevent blocking, framecount must be less than the return value of alGetFilled().

When 4-channel data is input on systems that do not support 4 line-level electrical connections, that is, when setting AL_CHANNEL_MODE to AL_4CHANNEL is not possible, alReadFrames() provides 4 sample frames per frame, but the second pair of sample frames is set to 0.

Table 4-4 shows the input conversions that are applied when reading mono, stereo, and 4-channel input in stereo mode (default) and in 4-channel mode hardware configurations. Each entry in the table represents a sample frame.

---

Note: If the summed signal is greater than the maximum allowed by the audio system, it is clipped (limited) to that maximum, as indicated by the Clip function.

---

Sample frames placed in an output queue are played by the audio hardware after a specific amount of time, which is equal to the number of sample frames that were present in the queue before the new sample frames were written, divided by the (sample rate × number of channels) settings of the ALport.

alWriteFrames() writes a specified number of sample frames to an output port from a sample data buffer, blocking until the requested number of sample frames have been written to the port. Its function prototype is

int alWriteFrames ( ALport port, void *samples, long framecount )

where

Table 4-5 shows the output conversions that are applied when writing mono, stereo, and 4-channel data to stereo mode (default) and 4-channel mode hardware configurations.