---

Using Video Digitizer Components

This section describes how you can control a video digitizer component. It is divided into the following topics:

• “Specifying Destinations” discusses how you tell the digitizer where to put the converted video data.

• “Starting and Stopping the Digitizer” discusses how you control digitization.

• “Multiple Buffering” describes a technique for improving performance.

• “Obtaining an Accurate Time of Frame Capture” tells how the sequence grabber usually supplies video digitizers with a time base. This time base lets your application get an accurate time for the capture of any specified frame.

In this section:

Specifying Destinations
Setting Video Destinations
Starting and Stopping the Digitizer
Controlling Digitization
Multiple Buffering
Obtaining an Accurate Time of Frame Capture

Specifying Destinations

Video digitizer components provide several functions that allow applications to specify the destination for the digitized video stream produced by the digitizer component. You have two options for specifying the destination for the video data stream in your application.

• The first option requires that the video be digitized as RGB pixels and placed into a destination pixel map. This option allows the video to be placed either onscreen or offscreen, depending upon the placement of the pixel map. Your application can use the VDSetPlayThruDestination function to set the characteristics for this option. Your application can use the VDPreflightDestination function to determine the capabilities of the digitizer. All video digitizer components must support this option.

• The second option uses a global boundary rectangle to define the destination for the video. This option always results in onscreen images and is useful with digitizers that support hardware direct memory access (DMA) across multiple screens. The digitizer component is responsible for any required color depth conversions, image clipping and resizing, and so on. Your application can use the VDSetPlayThruGlobalRect function to set the characteristics for this option. Your application can use the VDPreflightGlobalRect function to determine the capabilities of the digitizer. Not all video digitizer components support this option.

Setting Video Destinations

Video digitizer components provide several functions that allow applications to specify the destination for the digitized video stream produced by the digitizer component. Applications have two options for specifying the destination for the video data stream:

• The first option requires that the video be digitized as RGB pixels and placed into a destination pixel map. This option allows the video to be placed either onscreen or offscreen, depending upon the placement of the pixel map. You can use the VDSetPlayThruDestination function in your application to set the characteristics for this option. The VDPreflightDestination function lets you determine the capabilities of the digitizer in your application. All video digitizer components must support this option. The VDGetPlayThruDestination function lets you get data about the current video destination.

• The second option uses a global boundary rectangle to define the destination for the video. This option is useful only with digitizers that support hardware DMA. You can use the VDSetPlayThruGlobalRect function in your application to set the characteristics for this option. You can use the VDPreflightGlobalRect function in your application to determine the capabilities of the digitizer. Not all video digitizer components support this option.

The VDGetMaxAuxBuffer function returns information about a buffer that may be located on some special hardware.

Starting and Stopping the Digitizer

You can control digitization on a frame-by-frame basis in your application. The VDGrabOneFrame function digitizes a single video frame. All video digitizer components support this function.

Alternatively, you can use the VDSetPlayThruOnOff function to enable or disable digitization. When digitization is enabled, the video digitizer component places video into the specified destination continuously. The application stops the digitizer by disabling digitization. This function can be used with both destination options. However, not all video digitizer components support this function.

Controlling Digitization

This section describes the video digitizer component functions that allow applications to control video digitization.

Video digitizer components allow applications to start and stop the digitizing process. Your application can request continuous digitization or single-frame digitization. When a digitizer component is operating continuously, it automatically places successive frames of digitized video into the specified destination. When a digitizer component works with a single frame at a time, the application and other software, such as an image compressor component, control the speed at which the digitized video is processed.

You can use the VDSetPlayThruOnOff function in your application to enable or disable digitization. When digitization is enabled, the video digitizer component places digitized video frame into the specified destination continuously. The application stops the digitizer by disabling digitization. This function can be used with both destination options.

Alternatively, your application can control digitization on a frame-by-frame basis. The VDGrabOneFrame and VDGrabOneFrameAsync functions digitize a single video frame; VDGrabOneFrame works synchronously, returning control to your application when it has obtained a complete frame, while VDGrabOneFrameAsync works asynchronously. The VDDone function helps you to determine when the VDGrabOneFrameAsync function is finished with a video frame. Your application can define the buffers for use with asynchronous digitization by calling the VDSetupBuffers function. Free the buffers by calling the VDReleaseAsyncBuffers function.

The VDSetFrameRate function allows applications to control the digitizer’s frame rate. The VDGetDataRate function returns the digitizer’s current data rate.

Multiple Buffering

You can improve the performance of frame-by-frame digitization by using multiple destination buffers for the digitized video. Your application defines a number of destination buffers to the video digitizer component and specifies the order in which those buffers are to be used. The digitizer component then fills the buffers, allowing you to switch between the buffers more quickly than your application otherwise could. In this manner, you can grab a video sequence at a higher rate with less chance of data loss. This technique can be used with both destination options.

You define the buffers to the digitizer by calling the VDSetupBuffers function. The VDGrabOneFrameAsync function starts the process of grabbing a single video frame. The VDDone function allows you to determine when the digitizer component has finished a given frame.

Obtaining an Accurate Time of Frame Capture

The sequence grabber typically gives video digitizers a time base so your application can obtain an accurate time for the capture of any given frame. Applications can set the digitizer’s time base by calling the VDSetTimeBase function.

---