Streaming Data Transfer

Waveform and video streams involve the continuous flow of real-time audio and video data. Typically, these streams involve a high data-transfer rate and require significant processor time.

The data-transfer model for streaming audio and video input is similar. If you have worked with waveform or video-capture device drivers, many of the concepts you already understand apply to the other type of driver.

The following sequence of operations occurs when streaming waveform or video data between a device driver and a client application:

1. The client allocates the memory buffers for the audio or video data.
2. If required, the client initializes the data stream.
3. The client requests that the driver prepare the data buffers.
4. The client sends the empty data buffers to the driver.
5. The driver puts the data buffers in its input queue.
6. When the streaming operation begins, the driver fills a data buffer and sets the done bit for the data buffer. The driver then releases the buffer from its queue and proceeds to fill the next buffer.
7. When the client is ready for data, it uses the done bit or a callback to see if the data in the buffer is ready.
8. After the client empties the buffer, it resets the done bit and sends the empty buffer back to the driver for it to add to its queue.

Once the stream starts, the client application and the audio and video device driver do not communicate directly. The device driver fills the data buffers at the data rate specified by the client application. It fills the buffers without waiting for any synchronization signal from the application, as long as buffers are available and it is not paused or stopped by the application. The buffers are filled in the order that the driver receives them from the application. (If the device driver runs out of buffers, it should set an error flag. A client video application can use the DVM_STREAM_GETERROR message to test for this condition.)

The client application expects the buffers back in the order that it sends them to the device driver. When it is ready for more data, it checks the done bit of the next buffer it expects to receive from the device driver. If the done bit is set, the application continues operation with that buffer. If the done bit is not set, the application periodically checks the done bit while it waits for the buffer.

Streaming continues until it is stopped by the application. The following sequence of operations occurs when the application has finished capturing data:

• When the client stops the streaming operation, the driver stops filling buffers.
• If the client wants to restart streaming, it sends a message to restart streaming. If the client is finished streaming, it requests that the driver unprepare the data buffers.
• The client releases the data stream and frees the memory allocated for the data.

Preparing Data Buffers

Because audio and video data buffers must be accessed at interrupt time, the memory allocated for them is subject to the requirements mentioned in . Rather than have the client application prepare the memory before sending data blocks to the driver, the client requests that the driver make the preparations.

This request involves two messages, in the form of _PREPARE and _UNPREPARE. Most drivers can respond to these messages by returning a MMSYSERR_NOTSUPPORTED error. Then, MMSYSTEM prepares the data block by page-locking it so the driver can access it at interrupt time. For example, most drivers can respond to the DVM_STREAM_PREPAREHEADER and DVM_STREAM_UNPREPAREHEADER messages by returning a DV_ERR_UNSUPPORTED error. When a driver returns the DV_ERR_UNSUPPORTED error, MMSYSTEM prepares the data block by page-locking the header and data sections so the driver can access them at interrupt time.

If a device driver does not need page-locked data (for example, if the application immediately copies the data to an on-card buffer) or if the buffer requires additional preparation, the application can respond to these messages directly instead of letting MMSYSTEM handle them. An application should respond to both messages, or to neither.

The following table identifies the drivers that use these messages, and the name of the prepare and unprepare messages.