Name

ICCompressPrepareHeader --- Prepares compression headers. 

Syntax

#include <mme/mme_api.h>
MMRESULT ICCompressPrepareHeader(HIC hic,
                 LPBITMAPINFOHEADER lpbiOutput,
                 LPVOID lpdata,
                 LPBITMAPINFOHEADER lpbiInput,
                 LPVOID lpBits);

Arguments

HIC hic
Specifies a handle to a compressor.

LPBITMAPINFOHEADER lpbiOutput
Specifies a pointer to a BITMAPINFOHEADER data structure holding the output format.  The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompressPrepareHeader function.  See the mmeAllocMem(3mms) reference page for more information about allocating memory for data structures. 

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

LPBITMAPINFOHEADER lpbiInput
Specifies a pointer to a BITMAPINFOHEADER data structure containing the input format. 

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

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

Description

The ICCompressPrepareHeader function prepares buffers for video compression 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 ICCompress 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 ICCompress 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. ICCompressPrepareHeader 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. ICCompressPrepareHeader allows the server to allocate all the required space up front reducing the need to allocate space on every ICCompress call. 

This routine must be called after ICCompressBegin and before ICCompressEnd. Ideally, this routine is called once to register input and output buffers between the ICCompressBegin call and the first ICCompress 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 ICCompressPrepareHeader 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:

See Also

ICCompressBegin(3mms), ICCompressEnd(3mms), ICCompressUnprepareHeader(3mms),