ICDecompressPrepareHeader(3mms) — Subroutines

Name

ICDecompressPrepareHeader --- Prepares decompression headers.

Syntax

#include <mme/mme_api.h>
MMRESULT ICDecompressPrepareHeader(HIC hic,
                      LPBITMAPINFOHEADER lpbiFormat,
                      LPVOID lpData,
                      LPBITMAPINFOHEADER lpbi,
                      LPVOID lpBits);

Arguments

HIC hic
Specifies a handle to a decompressor.

LPBITMAPINFOHEADER lpbiFormat
Specifies a pointer to a BITMAPINFOHEADER data structure containing the format of the compressed data. The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICDecompressPrepareHeader function. See the mmeAllocMem(3mms) reference page for more information about allocating memory for data structures.

LPVOID lpData
Specifies a pointer to the input data. The data buffer must be allocated with the mmeAllocBuffer function before being passed to the ICDecompressPrepareHeader function. See the mmeAllocBuffer(3mms) reference page for more information about allocating memory for data buffers.

LPBITMAPINFOHEADER lpbi
Specifies a pointer to a BITMAPINFOHEADER data structure containing the output format.

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICDecompressPrepareHeader function. See the mmeAllocMem(3mms) reference page for more information about allocating memory for data structures.

LPVOID lpBits
Specifies a pointer to a data buffer for the decompressed data. The data buffer must be allocated with the mmeAllocBuffer function before being passed to the ICDecompressPrepareHeader function. See the mmeAllocBuffer(3mms) reference page for more information about allocating memory for data buffers.

Description

The ICDecompressPrepareHeader function prepares buffers for video decompression streaming. If a hardware device requires locked-down memory regions to read and write data, then the standard interface would require a separate lock down and unlock each time a ICDecompress operation was called. This may be highly inefficient for some devices.

This routine allows a large region to be registered and any low level operations may be accomplished once for the entire region, possibly making ICDecompress calls much more efficient.

When the client and server are local to the same machine, memory may be shared between the client, server, and hardware device. ICDecompressPrepareHeader facilitates this sharing. When the client and server are on different machines (not yet supported), then the server has to allocate space for the buffers. ICDecompressPrepareHeader allows the server to allocate all the required space up front reducing the need to allocate space on every ICDecompress call.

This routine must be called after ICDecompressBegin and before ICDecompressEnd. Ideally, this routine is called once to register input and output buffers between the ICDecompressBegin call and the first ICDecompress call.

A buffer can only be prepared once. If the application attempts to register an already registered buffer or a buffer that overlaps with an already registered buffer, the ICDecompressPrepareHeader call will fail. If an application has several compressors and/or decompressors open, the same buffers may not be sharable between compressors and/or decompressors.

Buffers cannot be used for two different purposes. For instance, one memory region can be used to hold multiple input buffers and another memory region can be used to hold multiple output buffers, but the same region cannot be used to hold both input and output buffers since they are used for different purposes.

Extensions

Digital extension to the Microsoft multimedia API specification.

Return Value

Returns ICERR_OK if the function is successful; otherwise, it returns one of the following error codes:

Error Code	Description
ICERR_BADHANDLE	The hic argument is invalid, the decompressor is not open, or the decompressor is not open for decompression.
ICERR_BADFORMAT	The lpbiFormat and lpbi arguments are not acceptable formats.
ICERR_BADIMAGESIZE	The specified image size is invalid.
ICERR_BADPARAM	The lpbiFormat or lpbi, or lpData or lpBits arguments are NULL; or the hardware cannot be properly set up for the operation. The parameters are not the same as those specified in the ICDecompressBegin call (with the exception of the biSizeImage fields).
ICERR_MEMORY	The buffers specified are not valid. Most likely they were not allocated with mmeAllocBuffer or mmeAllocBufferAndGetShminfo.
ICERR_CANTUPDATE	The decompressor is not already in operation, that is, ICDecompressBegin has not yet been called or ICDecompressEnd has been called.
ICERR_INTERNAL	An internal driver error occurred. No more detailed information is available.

Museum

Related Articles