The client-application sends a series of messages to your driver to coordinate decompressing video data. The coordination involves the following activities:
The following messages are used by video compression and decompression drivers for these decompression activities:
Message | Description |
ICM_DECOMPRESS | Decompresses a frame of data into a buffer provided by the client-application. |
ICM_DECOMPRESS_BEGIN | Prepare a driver for decompressing data. |
ICM_DECOMPRESS_END | Cleans up after decompressing. |
ICM_DECOMPRESS_GET_FORMAT | Obtains a suggestion for a good format for the decompressed data. |
ICM_DECOMPRESS_QUERY | Determines if a driver can decompress a specific input format. |
ICM_DECOMPRESS_GET_PALETTE | Returns the color table of the output data structure. |
The video decompressed with these messages is returned to the client-application and it handles the display of data. If you want your driver to control the video timing or directly update the display, use the ICM_DRAW messages explained in "Decompressing Directly to Video Hardware." If you return the decompressed video to the client-application, your driver can decompress data using either software or hardware with the ICM_DECOMPRESS messages.
The client-application restores the driver state by sending ICM_SETSTATE. The client-application recalls the state information from the strd' data chunk of the AVI file. (The information was originally obtained with the ICM_GETSTATE message.) The client-application does not validate any data in the state information. It simply transfers the state information it reads from the 'strd' data chunk to your driver.
The client-application sends the information to your driver in a buffer pointed to by dwParam1. The size of the buffer is specified in dwParam2. The organization of the data in the buffer is driver dependent. If dwParam1 is NULL, your driver should return to its default state.
Note:
All information required for decompressing the image data should be part of the format data. Only optional compression parameters can be included with the state information.
Depending on how the client-application will use the decompressed data, it will send either ICM_DECOMPRESS_GET_FORMAT or ICM_DECOMPRESS_QUERY to specify the input format and determine the decompression format. The client-application sends ICM_DECOMPRESS_GET_FORMAT if it wants your driver to suggest the decompressed format. The client-application sends ICM_DECOMPRESS_QUERY to determine if your driver supports a format it is suggesting.
Both messages send a pointer to a BITMAPINFO data structure in dwParam1. This structure specifies the format of the incoming compressed data. The input format was obtained by the client-application from the 'strf' chunk in the AVI file. While the output format is specified by dwParam2, your driver must use the message to determine how the parameter is defined.
If your driver gets ICM_DECOMPRESS_GET_FORMAT, both dwParam1 and dwParam2 point to BITMAPINFO data structures. The input format data is contained in the dwParam1 structure. Your driver should fill in the dwParam2 BITMAPINFO with information about the format it will use to decompress the data. If your driver can handle the format, return the number of bytes used for the dwParam2 structure as the return value. If your driver cannot handle the input format, or the input format from the 'strf' chunk is incorrect, your driver should return ICERR_BADFORMAT to fail the message.
If you have format information in addition to that specified in the BITMAPINFOHEADER structure, you can add it immediately after this structure. If you do this, update the biSize member to specify the number of bytes used by the structure and your additional information. If a color table is part of the BITMAPINFO information, it follows immediately after your additional information. Return ICERR_OK when your driver has finished updating the data format.
If your driver gets ICM_DECOMPRESS_QUERY, dwParam1 points to a BITMAPINFO data structure containing the input format data. The dwParam2 parameter will either be NULL or contain a pointer to a BITMAPINFO structure describing the decompressed format the client-application wants to use.
If dwParam2 is NULL, your decompression driver can use any output format. In this case, the client-application wants to know if you can decompress the input format and it doesn't care about the output format. If dwParam2 points to a BITMAPINFO structure, the suggested format will be the native or best format for the decompressed data. For example, if playback is on an 8-bit device, the client-application will suggest an 8-bit DIB.
If your driver supports the specified input and output format (which might also include stretching the image), or it supports the specified input with NULL specified for dwParam2, return ICERR_OK to indicate the driver accepts the formats.
Your driver does not have to accept the formats suggested. If you fail the message by returning ICERR_BADFORMAT, the client-application will suggest alternate formats until your driver accepts one. If your driver exhausts the list of formats normally used, the client-application requests a format with ICM_DECOMPRESS_GET_FORMAT.
If you are decompressing to 8-bit data, your driver will also receive the ICM_DECOMPRESS_GET_PALETTE message. Your driver should add a color table to the BITMAPINFO data structure and specify the number of palette entries in the biClrUsed member. The space reserved for the color table will always be 256 colors.
When the client-application is ready, it sends the ICM_DECOMPRESS_BEGIN message to the driver. The client-application sets dwParam1 and dwParam2 to the BITMAPINFO data structures describing the input and output formats. If either of the formats is incorrect, your driver should return ICERR_BADFORMAT. Your driver should create any tables and allocate any memory that it needs to decompress data efficiently. When done, return ICERR_OK.
The client-application sends ICM_DECOMPRESS each time it has an image to decompress. The client-application uses the flags in the file index to ensure the initial frame in a decompression sequence is a key frame.
The ICDECOMPRESS data structure specified in dwParam1 contains the decompression parameters. The value specified in dwParam2 specifies the size of the structure.
The format of the input data is specified in a BITMAPINFOHEADER structure pointed to by the lpbiInput member of ICDECOMPRESS. The input data is in a buffer specified by lpInput member of ICDECOMPRESS. The lpbiOutput and lpOutput members of ICDECOMPRESS contain pointers to the format data and buffer used for the output data.
The client-application sets the ICDECOMPRESS_HURRYUP flag in the dwFlags member of ICDECOMPRESS if it wants your driver to try and decompress the data at a faster rate. The client-application will not display any data decompressed with this flag. This might let your driver avoid decompressing a frame or data, or let it minimally decompress when it needs information from this frame to prepare for decompressing a following frame.
Your driver receives ICM_DECOMPRESS_END when the client-application no longer needs data decompressed. For this message, your driver should free the resources it allocated for the ICM_DECOMPRESS_BEGIN message.
Decompression drivers also receive the ICM_DRAW_START and ICM_DRAW_STOP messages. These messages tell the driver when the client-application starts and stops drawing the images. Most decompression drivers can ignore these messages.
Video for Windows 1.1 adds extended decompression capabilities. These messages let drivers decompress a frame of data directly to the screen, decompress to upside-down DIB, or decompress images described with source and destination rectangles. The following messages are used to obtain these capabilities:
Message | Description |
ICM_DECOMPRESSEX | Decompresses a frame of data into a buffer provided by the client-application. |
ICM_DECOMPRESSEX_BEGIN | Prepare a driver for decompressing data. |
ICM_DECOMPRESSEX_END | Cleans up after decompressing. |
ICM_DECOMPRESSEX_QUERY | Determines if a driver can decompress a specific input format. |
These messages serve the same purpose as the ICM_DECOMPRESS messages except they use the ICDECOMPRESSEX structure. This structure contains the image input format and data, the output format and data, the source rectangle, and the destination rectangle.