The entry-point function, DriverProc, processes messages sent by the system to the driver as the result of an application call to a video compression and decompression function. For example, when an application opens a video compression and decompression driver, the system sends the specified driver a DRV_OPEN message. The driver's DriverProc function receives and processes this message. Your DriverProc should return ICERR_UNSUPPORTED for any messages that it does not handle.
Note:
Your driver should respond to all system messages. If supplemental information is not provided for them in this chapter, use the definitions provided in the Microsoft Win32 Programmer's Reference.
Like other installable drivers, client applications must open a video compression and decompression driver before using it, and they must close it when finished using it so the driver will be available to other applications. When a driver receives an open request, it returns a value that the system will use for dwDriverID sent with subsequent messages. When your driver receives other messages, it can use this value to identify instance data needed for operation. Your drivers can use this data to maintain information related to the client that opened the driver.
Compression and decompression drivers should support more than one client simultaneously. If you do this, though, remember to check the dwDriverID parameter to determine which client is being accessed.
If the driver is opened for configuration by the Drivers option of the Control Panel, lParam2 contains zero. When opened this way, your driver should respond to the DRV_CONFIGURE and DRV_QUERYCONFIGURE messages.
If opened for compression or decompression services, lParam2 contains a far pointer to an ICOPEN data structure. The fccType member of ICOPEN specifies a four-character code representing the type of stream being compressed or decompressed. For video streams, this will be 'vidc'.
Because video capture drivers can rely on video compression and decompression drivers for efficient operation, a single driver can handle both video capture, and video compression and decompression services. Video capture drivers use the VIDEO_OPEN_PARMS data structure when it is opened. This structure has the same member definitions as the ICOPEN structure. By examining the fccType member, a combined driver can determine whether it is being opened as a video capture driver or a video compression and decompression driver. Video capture devices contain the four-character code 'vcap' in this member. For more information on video capture drivers, see .
Other drivers that require close coordination with video compression and decompression drivers can also be combined with video compression and decompression drivers if they use a similar interface.
The fccHandler member of ICOPEN specifies a four-character code identifying a specific compressor. The client-application obtains the four-character code from the entry in the SYSTEM.INI file used to open your driver. Your driver should not fail the open if it does not recognize the four-character code.
The dwVersion member of ICOPEN specifies the version of the compressor interface used to open the driver. Your driver can use this information to determine the capabilities of the system software when future versions of it are available.
The dwFlags member of ICOPEN contains a constant indicating the function of the driver. The following functions are defined for video compression drivers: compressing data, decompressing data, interrogation, and decompressing and draw directly to hardware.
The ICMODE_COMPRESS, ICMODE_DECOMPRESS, and ICMODE_DRAW flags indicate your driver is opened to compress or decompress data. Depending on the flag, your driver should prepare to handle ICM_COMPRESS, ICM_DECOMPRESS, ICM_DECOMPRESSEX, or ICM_DRAW messages. Your driver should also prepare to handle all messages used to configure and interrogate your driver.
The ICMODE_QUERY flag indicates your driver is opened to obtain information. It should prepare to handle the ICM_ABOUT, ICM_GETINFO, and ICM_GETDEFAULTQUALITY messages.
Video compression and decompression drivers can receive a series of configuration messages. System configuration messages are typically sent by the Drivers option of the Control Panel to configure the hardware. Video compression and decompression specific configuration messages are typically initiated by the client-application or from dialog boxes displayed by your driver. Your driver should use these messages to configure the driver.
Installable drivers can supply a configuration dialog box for users to access through the Drivers option in the Control Panel. If your driver supports different options, it should allow user configuration. Any hardware-related settings should be stored in a section with the same name as the driver in the user's SYSTEM.INI file.
Like other installable drivers, your driver will receive DRV_CONFIGURE and DRV_QUERYCONFIGURE messages from the Drivers option of the Control Panel. If your driver controls hardware that needs to be configured, it should return a non-zero value for the DRV_QUERYCONFIGURE system message and display a hardware configuration dialog box for the DRV_CONFIGURE system message.
The video compression and decompression specific configuration messages are typically initiated by the client-application or from dialog boxes displayed by your driver. Your driver should use these messages to configure the driver.
If your driver is configurable, it should support the ICM_CONFIGURE message for driver configuration. In addition, it should also use this message to set parameters for compression or decompression. Any options the user selects in the dialog box displayed for ICM_CONFIGURE should be saved as part of the state information referenced by the ICM_GETSTATE and ICM_SETSTATE messages.
The ICM_GETSTATE and ICM_SETSTATE messages query and set the internal state of your compression or decompression driver. State information is device dependent and your driver must define its own data structure for it. While the client-application reserves a memory block for the information, it will obtain the size needed for the memory block from your driver. If your driver receives ICM_GETSTATE with a NULL pointer for dwParam1, the client-application is requesting that your driver return the size of its state information. Conversely, if your driver receives ICM_GETSTATE with dwParam1 pointing to a block of memory, and dwParam2 specifying the size of the memory block, the client-application is requesting that your driver transfer the state information to the memory block.
When your driver receives ICM_SETSTATE with dwParam1 pointing to a block of memory, and dwParam2 specifying the size of the memory block, the client-application is requesting that your driver restore its configuration from the state information contained in the memory block. Before setting the state, your driver should verify the state information applies to your driver. One technique for verifying the data is to reserve the first DWORD in the state data structure for the four-character code used to identify your driver. If you set this DWORD for data returned for ICM_GETSTATE, you can use it to verify the data supplied with ICM_SETSTATE. If ICM_SETSTATE has a NULL pointer for dwParam1, it indicates that your driver should return to its default state.
State information should not contain any data that is absolutely required for data decompression-any such data should be part of the format you return for the ICM_DECOMPRESS_GET_FORMAT message. For information on the ICM_DECOMPRESS_GET_FORMAT message, see .
The client-application sends the ICM_ABOUT message to display your driver's about box. If the client-application sets dwParam1 to -1, it wants to know if your driver supports display of an about box. Your driver returns ICERR_OK if it does, and it returns ICERR_UNSUPPORTED if it does not. Your driver should only display an about box if the client-application specifies a window handle in dwParam1. The window handle indicates the parent of the dialog box.
The client-application uses the ICM_GETINFO message to obtain a description of your driver. Your driver should respond to this message by filling in the ICINFO structure it receives with the message. The flags your driver sets in the structure tells the client-application what capabilities the driver supports.
For the video compression and decompression interface, quality is indicated by an integer ranging from 0 to 10,000. A quality level of 7,500 typically indicates an acceptable image quality. A quality level of 0 typically indicates a very low quality level (possibly even a totally black image). As the quality level moves from an acceptable level to low quality, the image might have a loss of color as the colors in the color table are merged, or as the color resolution of each pixel decreases. If your driver supports temporal compression (it needs information from the previous frame to decompress the current frame), low and high quality might imply how much this type of compression can degrade image quality. For example, your driver might limit the compression of a high quality image to preserve sharp detail and color fidelity. Conversely, your driver might sacrifice these qualities to obtain very compressed output files.
If your driver supports quality values, it maps the values to its internal definitions used by the compression algorithms. Thus, the definition of image quality will vary from driver to driver, and, quite possibly, from compression algorithm to compression algorithm. Even though the values are not definitive, your driver should support as many individual values as possible.
The client-application obtains the capabilities for compression quality with the ICM_GETDEFAULTQUALITY and ICM_GETQUALITY messages. If your driver supports quality levels, it should respond to the ICM_GETDEFAULTQUALITY message by returning a value between 0 and 10,000 that corresponds to a good default quality level for your compressor. Your should return the current quality level for the ICM_GETQUALITY message.
The client-application sends the ICM_SETQUALITY message to set the quality level of your driver. Your driver should pass the quality value directly to the compression routine.
If your driver supports quality levels, it should set the VIDCF_QUALITY flag when it responds to the ICM_GETINFO message.
The client-application uses ICM_GETDEFAULTKEYFRAMERATE to obtain the drivers recommendation for the key frame spacing for compressing data. (A key frame is a frame in a video sequence that does not require information from a previous frame for decompression.) If the client-application does not specify another value, this value determines how frequently the client-application sends an uncompressed image to your driver with the ICM_COMPRESS_KEYFRAME flag set. If your driver supports this option, it should specify the key frame rate in the DWORD pointed to by dwParam1 and return ICERR_OK. If it does not support this option, return ICERR_UNSUPPORTED.
The client-application uses ICM_GETBUFFERSWANTED to determine if your driver wants to maintain a queue of buffers. Your driver might maintain a queue of buffers if it renders the decompressed data and it wants to keep its hardware pipelines full. If your driver supports this option, it should specify the number of buffers in the DWORD pointed to by dwParam1 and return ICERR_OK. If it does not support this option, return ICERR_UNSUPPORTED.