Compaq Multimedia Services
for OpenVMS Alpha
Programmer's Guide
Previous Contents Index

ICClose

 Name ICClose --- Close a compressor or decompressor Syntax 


#include <mme/mme_api.h> 
 
MMRESULT ICClose(HIC hic)
Arguments HIC hic
Specifies a handle to a compressor or decompressor.

Description

The ICClose function closes a compressor or decompressor.
Extensions None.

Return Values

1
Returns ICERR_OK if the function is successful; otherwise, it returns the following error code:
Error Code Description
ICERR_BADHANDLE The hic argument is invalid, or the compressor has already been closed.
See Also ICLocate , ICOpen

ICCompress

 Name ICCompress --- Compress a single video image Syntax 


#include <mme/mme_api.h> 
 
DWORD ICCompress(HIC hic, 
                 DWORD dwflags, 
                 LPBITMAPINFOHEADER lpbiOutput, 
                 LPVOID lpdata, 
                 LPBITMAPINFOHEADER lpbiInput, 
                 LPVOID lpBits, 
                 LPDWORD lpckid, 
                 LPDWORD lpdwFlags, 
                 LONG lFrameNum, 
                 DWORD dwFrameSize, 
                 DWORD dwQuality, 
                 LPBITMAPINFOHEADER lpbiPrev, 
                 LPVOID lpPrev);
Arguments HIC hic
Specifies a handle to a compressor.

DWORD dwFlags
Specifies flags for compression. The following flag is defined:

ICM_COMPRESS_KEYFRAME
Indicates that the compressor should make this frame a key frame.

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 ICCompress function. See Chapter 2 for more information about the memory allocation functions.

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 ICCompress function. See Chapter 2 for more information about the memory allocation functions.

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 ICCompress function. See Chapter 2 for more information about the memory allocation functions.

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 ICCompress function. See Chapter 2 for more information about the memory allocation functions.

LPDWORD lpckid
Specifies a pointer to a DWORD used to hold a chunk ID for data in the AVI file. This argument is filled in by the compressor. The lpckid argument must be allocated with the mmeAllocMem function before being passed to the ICCompress function. See Chapter 2 for more information about the memory allocation functions.

LPDWORD lpdwFlags
Specifies a pointer to a DWORD holding the return flags used in the AVI index. This argument is filled in by the compressor. The following flag is defined:

AVIIF_KEYFRAME
Indicates that this frame is a key frame.

The lpdwFlags argument must be allocated with the mmeAllocMem function before being passed to the ICCompress function. See Chapter 2 for more information about the memory allocation functions.

LONG lFrameNum
Specifies the frame number.

DWORD dwFrameSize
Specifies the requested frame size in bytes. If set to zero, the compressor chooses the frame size.

DWORD dwQuality
Specifies the requested quality value for the frame. This value ranges from 0 to 10000. The value 10000 denotes the best quality. See Chapter 7 for information about quality settings and see Appendix B for restrictions.

LPBITMAPINFOHEADER lpbiPrev
Specifies a pointer to a BITMAPINFOHEADER data structure holding the previous frame's format.

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompress function. See Chapter 2 for more information about the memory allocation functions.

LPVOID lpPrev
Specifies a pointer to the previous frame's data buffer. The data buffer must be allocated with the mmeAllocBuffer function before being passed to the ICCompress function. See Chapter 2 for more information about the memory allocation functions.

Description

The ICCompress function compresses a single video image.

The size of the data buffer pointed to by the lpData argument must be large enough to hold the compressed frame. Use the ICCompressGetSize function to obtain the size of this buffer.

Set the dwFrameSize argument to a requested frame size only if the compressor returns the VIDCF_CRUNCH flag in response to a call to the ICGetInfo function. Without the VIDCF_CRUNCH flag, set the parameter to zero.

Set the dwQuality argument to a quality value only if the compressor returns the VIDCF_QUALITY flag in response to a call to the ICGetInfo function. Without the VIDCF_QUALITY flag, set the parameter to zero.

The lpbiPrev and lpPrev arguments are relevant only when using temporal compression (the dwFlags field in the ICINFO data structure is VIDCF_TEMPORAL). Otherwise, they can be set to NULL.

If changes are made to any of the fields in the BITMAPINFOHEADER data structures passed to this function, call the ICCompressEnd function followed by the ICCompressBegin function to reconfigure the compression device.

Note
Some video devices may check compression parameters, detect a change, and reconfigure themselves. In these cases, the ICCompress function can return error codes associated with the ICCompressEnd and ICCompressBegin functions.
Extensions None.

Return Values

1
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 compressor is not open, or the compressor is not open for compression.
ICERR_BADFORMAT The lpbiOutput and lpbiInput arguments are not acceptable formats.
ICERR_BADPARAM The lpbiOutput or lpbiInput, or lpData or lpBits arguments are NULL; or the hardware cannot be properly set up for the operation.
See Also ICCompressBegin , ICCompressEnd , ICCompressGetSize , ICGetInfo

ICCompressBegin

 Name ICCompressBegin --- Prepare a compressor for compressing data Syntax 


#include <mme/mme_api.h> 
 
MMRESULT ICCompressBegin(HIC hic, 
                         LPBITMAPINFOHEADER lpbiInput, 
                         LPBITMAPINFOHEADER lpbiOutput);
Arguments HIC hic
Specifies a handle to a compressor.

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

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompressBegin function. See Chapter 2 for more information about the memory allocation functions.

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 ICCompressBegin function. See Chapter 2 for more information about the memory allocation functions.

Description

The ICCompressBegin function prepares a compressor for compressing data. Call this function before calling the ICCompress function.
Extensions None.

Return Values

1
Returns ICERR_OK if the specified compression is supported; otherwise, it returns one of the following error codes:
Error Code Description
ICERR_BADHANDLE The hic argument is invalid, the compressor is not open, or the compressor is not open for compression.
ICERR_BADFORMAT The lpbiOutput and lpbiInput arguments are not acceptable formats.
ICERR_BADPARAM The lpbiOutput argument, lpbiInput argument, or both are NULL.
See Also ICCompress , ICCompressEnd , ICDecompressBegin

ICCompressEnd

 Name ICCompressEnd --- End compression Syntax 


#include <mme/mme_api.h> 
 
MMRESULT ICCompressEnd(HIC hic)
Arguments HIC hic
Specifies a handle to a compressor.

Description

The ICCompressEnd function ends compression by a compressor.
Extensions None.

Return Values

1
Returns ICERR_OK if the function is successful; otherwise, it returns the following error code:
Error Code Description
ICERR_BADHANDLE The hic argument is invalid, the compressor is not open, or the compressor is not open for compression.
See Also ICCompressBegin , ICCompress , ICDecompressEnd

ICCompressGetFormat

 Name ICCompressGetFormat --- Determine the default output of a compressor Syntax 


#include <mme/mme_api.h> 
 
MMRESULT ICCompressGetFormat(HIC hic, 
                             LPBITMAPINFOHEADER lpbiInput, 
                             LPBITMAPINFOHEAER lpbiOutput);
Arguments HIC hic
Specifies a handle to a compressor.

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

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompressGetFormat function. See Chapter 2 for more information about the memory allocation functions.

LPBITMAPINFOHEADER lpbiOutput
Specifies a pointer to a BITMAPINFOHEADER data structure used to return the default output of the compressor.

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompressGetFormat function. See Chapter 2 for more information about the memory allocation functions.

Description

The ICCompressGetFormat function determines the default output of a compressor.
Extensions None.

Return Values

1
Returns the size of the default output format structure in bytes 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 compressor is not open, or the compressor is not open for compression.
ICERR_BADFORMAT The lpbiOutput and lpbiInput arguments are not acceptable formats.
See Also ICCompressGetFormatSize

ICCompressGetFormatSize

 Name ICCompressGetFormatSize --- Obtain the maximum required size of the output structure for the compressor Syntax 


#include <mme/mme_api.h> 
 
MMRESULT ICCompressGetFormatSize(HIC hic, 
                                 LPBITMAPINFOHEADER lpbi);
Arguments HIC hic
Specifies a handle to a compressor.

LPBITMAPINFOHEADER lpbi
Specifies a pointer to a BITMAPINFOHEADER data structure indicating the format of the input data.

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompressGetFormatSize function. See Chapter 2 for more information about the memory allocation functions.

Description

The ICCompressGetFormatSize function obtains the maximum required size in bytes of the output data structure for the compressor. Use the ICCompressGetFormatSize function to determine the size of the default output data structure (the lpbiOutput argument) that must be allocated for the ICCompressGetFormat function.
Extensions None.

Return Values

1
Returns the maximum required size of the output structure for the compressor 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 compressor is not open, or the compressor is not open for compression.
ICERR_BADFORMAT The lpbi argument is not an acceptable format.
See Also ICCompressGetFormat

ICCompressGetSize

 Name ICCompressGetSize --- Obtain the maximum data buffer size that is expected to be used for the compressed data Syntax 


#include <mme/mme_api.h> 
 
MMRESULT ICCompressGetSize(HIC hic, 
                           LPBITMAPINFOHEADER lpbiInput, 
                           LPBITMAPINFOHEADER lpbiOutput);
Arguments HIC hic
Specifies a handle to a compressor.

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

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompressGetSize function. See Chapter 2 for more information about the memory allocation functions.

LPBITMAPINFOHEADER lpbiOutput
Specifies a pointer to a BITMAPINFOHEADER data structure indicating the output format.

The BITMAPINFOHEADER data structure must be allocated with the mmeAllocMem function before being passed to the ICCompressGetSize function. See Chapter 2 for more information about the memory allocation functions.

Description

The ICCompressGetSize function obtains the maximum data buffer size in bytes that is expected to be used for the compressed data.
Extensions None.

Return Values

1
Returns the maximum data buffer size expected to be used 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 compressor is not open, or the compressor is not open for compression.
ICERR_BADFORMAT The lpbiOutput and lpbiInput arguments are not acceptable formats.
See Also ICCompress , ICCompressGetFormat , ICCompressQuery

ICCompressPrepareHeader

 Name ICCompressPrepareHeader --- Prepare 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 Chapter 2 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 Chapter 2 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 Chapter 2 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 Chapter 2 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 example, 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 The ICCompressPrepareHeader function is a Compaq extension to the Microsoft multimedia API specification.

Compaq has extended the Microsoft video and ICM (Installable Compression Manager) interfaces to provide for memory optimization. See Section 1.5.8 for more information.

Return Values

1
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 compressor is not open, or the compressor is not open for compression.
ICERR_BADFORMAT The lpbiFormat and lpbi arguments are not acceptable formats.
ICERR_BADIMAGESIZE The specified image size is invalid.
ICERR_BADPARAM The lpbiInput or lpbiOutput, 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 ICCompressBegin 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 compressor is not already in operation, that is, ICCompressBegin has not yet been called or ICCompressEnd has been called.
ICERR_INTERNAL An internal driver error occurred. No more detailed information is available.
See Also ICCompressBegin , ICCompressEnd , ICCompressUnprepareHeader

Previous Next Contents Index