MMPM/2 Device Driver Reference:PDD Sample for MPEG Video Playback Devices

The Developer Connection Device Driver Source Kit for OS/2 provides a sample MPEG Video Playback physical device driver (PDD) to assist in the creation of PDDs for other video playback devices. This sample provides a code base for a new PDD, simplifies development, and illustrates the OS/2 MPEG Video Playback PDD model for a nonshared frame buffer device, also referred to as an overlay device. The ReelMagic card from Sigma Designs, Inc. is an example of such a device.

The code contained in this sample was derived from a working driver. All hardware-specific code and header files have been removed from the sample. Although this device driver was written for a device that uses the split- stream model, it is easily adaptable to the single-stream model.

The split-stream MPEG I/O procedure splits the audio and video packets out of the MPEG file. The audio data packets are passed through the subsystem to the audio DD, and the video data packets are passed through the subsystem to the video DD. As the audio DD returns the buffers that it has played, it also returns the current audio time-which is in turn passed through the subsystem to MPEG hardware compressor/decompressor (CODEC) and from there is sent to the video DD on the next VCAI_PLAY command.

The single-stream MPEG I/O procedure reads the entire MPEG file one buffer at a time-without splitting the video and audio data. As each buffer is read in, it is passed through the subsystem to the video DD. With single stream, every byte in the file is passed to the DD; whereas with split stream, only the video data packets are passed to the video DD. The single- stream video DD and its hardware are then responsible for producing the video and audio along with all synchronization.


 * Note: From the video DD's perspective, the main difference in the single-stream model is that the SCR, PTS, and Audio PTS fields in the VCAI_PLAY contain zero.

Source Code
Source code for the PPD sample is located on the Developer Connection Device Driver Source Kit for OS/2 CD-ROM. Source files include documented headers, which provide detailed descriptions of the programming concepts and routines.

Program Flow
1. The application opens the MPEG Digital Video Device through the media control interface (MCI).

2. The media control device (MCD) finds the PDDnameand VSDname in the MMPM2.INI file and opens the VSD with the PDDname.

3. The VSD opens the PDD, reads in an .INI file, and passes the .INI file to the PDD. The filename is based on the first seven characters of the PDDname with the .INI extension. The .INI file is device-dependent. The types of information in the .INI file may include default key color, video alignment offsets, and video quality adjustments.

4. Through the DevInfo IOCTL, the VSD queries the PDD to determine its capabilities.

5. The application loads an MPEG file through the MCI.


 * a. Through the standard I/O Proc interfaces, the MCD identifies MPGIO as the I/O Proc for the MPEG file.
 * b. Through the standard compressor/decompressor (CODEC) interfaces, the MPEG I/O Proc (MPEGIO) selects the MPEG hardware decompressor (MPEGDC). The MCD tells the VSD handle to the MPEGDC so that it can call the VSD/PDD to play back the compressed Video MPEG data.
 * c. Through the VSD and the PDD, the hardware CODEC MPEGDC loads the device with its DSP/MicroCode from a file whose name matches the results of a query of the VSD/PDD.
 * d. The MCD opens the playback window, queries the VSD/PDD for the transparent/key color, and paints the window with the key color.
 * e. The MCD tells the VSD/PDD the source movie size and window location.
 * f. The MCD tells the VSD/PDD to enable the monitor window and color keying.

6. The application issues a play command through the MCI.

7. The MPEG I/O Proc reads part of the MPEG file.

8. The audio data is sent through the system to the audio PDD.


 * Note: MPEG audio data is passed to the audio device driver via the DDCMD_READWRITE_PARM structure. Field ulParm1 contains the initial audio system clock reference (SCR), and ulParm2 contains the Presentation Time Stamp (PTS).

9. The video data is sent through the system to the MPEG CODEC (MPEGDC). If this data is the first packet in the stream, MPEGDC will issue a VCA_PlayStart IOCtl to the VSD/PDD to set up the device and initialize the stream time. As the data arrives, MPEGDC issues a VCA_PlayData IOCtl to the VSD/PDD.

10. As the audio PDD plays audio buffers, it reports back to the audio stream time, which is eventually sent to MPEGDC.

11. The audio time is passed on the next VCA_PlayData IOCtl to the VSD/PDD.


 * Note: When playing from the beginning of an MPEG file the audio time will begin at zero regardless of the files initial SCR value.

12. Steps 7 through 11 are repeated until the end of the MPEG data/file is reached-at which time, a VCA_PlayStop is issued indicating that the end of the file has been reached.

Audio and Video Synchronization (Split-Stream Model)
The MPEGDC is a decompressor that does not require the MMPM/2 subsystem to control or time the flow of images to the decompressor, whereas the Ultimotion CODEC allows the MMPM/2 subsystem to control the flow of images to the decompressor, which is not called until it is time to display the image. Data is sent to MPEGDC as fast it can be sent by the system. The PDD and its hardware must control the synchronization between audio and video. When the data is arriving too fast (the hardware data buffers are filled), the PDD must suspend processing on the MPEGDC thread until the hardware can accept more data. The hardware may contain over three-fourths of a second of video data waiting to be decompressed. The hardware will decompress the image when its SCR reaches the presentation time stamp (PTS) of the data packet in the hardware buffer. If the SCR is greater than the PTS, the hardware will speed up or skip images until the PTS and SCR match.

To synchronize the audio with the video, the PDD must know the current audio time. Because the audio and video have separate hardware with different clocks, the video PDD will need the audio time to keep the video synchronized with the audio.

As the audio stream plays the audio buffer, it reports back the current audio time. This time is relayed to the MPEGDC. The MPEGDC will pass down the last reported audio time to the PDD on the VCA_PlayData IOCtl. To get the current audio SCR, the PDD multiplies the audio time by 30 to convert from MMTime to the MPEG 90KHz clock and adds the stream's initial SCR from the VCA_PlayStart IOCtl audio time. The PlayStart audio time is the initial stream SCR. It is required because the audio stream times reported by the audio subsystem are zero-based times and the PTSs in the video stream are based on the initial SCR. The PDD compares the hardware video SCR with the calculated audio SCR to determine if the video is ahead of or behind the audio. If the audio is not synchronized with the video hardware, the video SCR must be updated to match the audio SCR.


 * Note: The audio time may contain the same value on subsequent PlayData commands until the audio device driver updates the audio stream time. The audio time can be set to zero, meaning no audio in the MPEG file or no audio PDD. In either case, the audio and video synchronization logic may be skipped.

Running the Sample Device Driver
The easiest way to install and run this sample device driver is to install Sigma Design's ReelMagic through the OS/2 Warp Selective Install and copy this sample device driver over the Sigma Design Reel Magic device driver that has the same name. The file can be found in the MMOS2 subdirectory (usually \MMOS2\VIDRMS1.SYS).

This device driver will not display images on the screen because it contains no hardware-specific code, but it will allow you to see and follow the commands and data to the device driver.

Reboot the computer after installing this sample device driver.