| Previous | Contents | Index |
Once an application selects a decompressor that can handle the input and
output formats required, it can prepare the decompressor for
decompression. An application uses the
ICDecompressBegin
function to initialize the decompressor.
5.2.4.5 Decompressing the Video
The
ICDecompress
function does the actual decompression.
An application must use this function repeatedly, once for each frame
of data, until all the frames are decompressed.
5.2.4.6 Ending Decompression
After an application has decompressed its data, it uses the ICDecompressEnd function to notify the decompressor that the decompression is complete. To restart decompression after using this function, an application must reinitialize the decompressor by calling the ICDecompressBegin function again.
Example 5-3 shows how an application can initialize a decompressor, decompress a frame sequence, and terminate decompression.
| Example 5-3 Initializing, Decompressing, and Terminating Decompression | |||
|---|---|---|---|
LPBITMAPINFOHEADER lpbiIn, lpbiOut;
LPVOID lpIn, lpOut;
LONG lNumFrames, lFrameNum;
/* Assume lpbiIn and lpbiOut are initialized to the input and output format */
/* and that the structures were allocated with the mmeAllocMem function. */
/* Also assume that lpIn and lpOut are pointing to data buffers that were */
/* allocated with the mmeAllocBuffer function. */
if (ICDecompressBegin(hic, lpbiIn, lpbiOut) == ICERR_OK) {
for (lFrameNum = 0; lFrameNum < lNumFrames; lFrameNum++) {
getNextFrame(lpIn);
if (ICDecompress(hic, NULL, lpbiIn, lpIn, lpbiOut, lpOut) == ICERR_OK) {
/* frame decompressed OK so we can process it as required */
} else {
/* handle decompression error */
}
}
ICDecompressEnd(hic);
} else {
/* handle error for decompression initialization */
}
|
The following attributes are used to modify uncompressed rendered images. These attributes apply only when decompressing an image to 8-bit X image format. Setting these attributes for compression will have no effect. Also, they do not apply when decompressing an image into 24-bit X image or YUV format.
See the descriptions of these function in Section 5.6 for more
information.
5.3 Video Compression and Decompression Header Files
The function prototypes, constants, flags, and data structures that
applications can use to access the video compression and decompression
services are defined in the
mme_api.h
header file provided with Multimedia Services for OpenVMS. Include this
header file in all application programs that use video compression and
decompression functions.
5.4 Video Compression and Decompression Data Structures
This section contains the data structures used by the video compression and decompression functions. The structures are defined, followed by a description of each field.
All video compression and decompression data structures must be allocated using the mmeAllocMem function. All video compression and decompression data buffers must be allocated using the mmeAllocBuffer or the mmeAllocBufferAndGetShminfo function. See Chapter 2 for more information about these memory allocation functions. |
The ICINFO data structure is filled by a video compressor or decompressor. The ICGetInfo and ICInfo functions use the ICINFO data structure to return information about the specified compressor or decompressor.
Example 5-4 shows the ICINFO data structure definition.
| Example 5-4 ICINFO Data Structure Definition | |||
|---|---|---|---|
typedef struct {
DWORD dwSize; /* size of the data structure */
DWORD fccType; /* type of stream */
DWORD fccHandler; /* specific device */
DWORD dwFlags; /* capabilities of the compressor */
DWORD dwVersion; /* version number of the compressor */
DWORD dwVersionICM; /* version number of the ICM */
char szName[16]; /* short name of the compressor */
char szDescription[128]; /* long name of the compressor */
char szDriver[128]; /* module containing the compressor */
} ICINFO;
|
The ICINFO data structure has the following fields:
dwSize
Specifies the size (in bytes) of the ICINFO data
structure.
fccType
Specifies a four-character code representing the type of stream to be
compressed or decompressed. Set to
'vidc'
(or ICTYPE_VIDEO) for video streams.
fccHandler
Specifies a four-character code identifying a specific compressor or
decompressor. The following shows available options and their values:
| Option | Value |
|---|---|
| FullVideo Supreme JPEG | " J321 " |
| FullVideo Supreme | " J301 " |
| Software JPEG CODEC | " SJPG " |
dwFlags
Specifies flags indicating the capabilities of a compressor. The
following flags are defined:
VIDCF_QUALITY
Indicates that the compressor supports quality.
VIDCF_CRUNCH
Indicates that the compressor supports crunching to a frame size.
VIDCF_TEMPORAL
Indicates that the compressor supports interframe compression.
VIDCF_DRAW
Indicates that the compressor supports drawing.
VIDCF_FASTTEMPORAL
Indicates that the compressor supports temporal compression and does not need the previous frame.
dwVersion
Specifies the version number of the compressor.
dwVersionICM
Specifies the version of the ICM supported by this compressor. Set to
ICVERSION.
szName[16]
Specifies the short name for the compressor. The name is null
terminated.
szDescription[128]
Specifies a null-terminated string containing the long name for the
compressor.
szDriver[128]
Specifies a null-terminated string for the module that contains the
compressor.
5.5 Video Compression and Decompression Function Overview
Table 5-1 provides a summary of the video compression and decompression functions.
| Application Function | Description |
|---|---|
| Callback services: | |
| ICCallbackProc | Registers a callback procedure for streaming video compression or decompression |
| Functions for compressing video data: | |
| ICCompress | Compresses a single video image |
| ICCompressBegin | Prepares a compressor for compressing data |
| ICCompressEnd | Tells a compressor to end compression |
| ICCompressGetFormat | Determines the output format of a compressor |
| ICCompressGetFormatSize | Obtains the size of the output format data |
| ICCompressGetSize | Obtains the size of the compressed data |
| ICCompressPrepareHeader | Prepares compression headers |
| ICCompressQuery | Determines if a compressor can compress a specific format |
| ICCompressUnprepareHeader | Unprepares compression headers |
| Functions for decompressing video data: | |
| ICDecompress | Decompresses a single video image |
| ICDecompressBegin | Prepares a decompressor for decompressing data |
| ICDecompressEnd | Tells a decompressor to end decompression |
| ICDecompressGetFormat | Determines the output format of a decompressor |
| ICDecompressGetFormatSize | Obtains the size (in bytes) of the output format data |
| ICDecompressGetPalette | Obtains the palette for the output format of a decompression |
| ICDecompressPrepareHeader | Prepares decompression headers |
| ICDecompressQuery | Determines if a decompressor can decompress data with a specific format |
| ICDecompressUnprepareHeader | Unprepares decompression headers |
| Functions for obtaining information about a compressor or decompressor: | |
| ICGetInfo | Obtains information about a compressor or decompressor |
| ICInfo | Returns information about a specific installed compressor, or enumerates the compressors installed |
| ICGetDefaultKeyFrameRate | Obtains the default key frame rate value |
| Functions for setting and retrieving state information about a compressor or decompressor: | |
| ICGetState | Obtains the state of a compressor |
| ICGetStateSize | Obtains the size of the state data used by a compressor |
| ICSetState | Sets the state of a compressor |
| Functions for locating, opening, and closing a compressor or decompressor: | |
| ICOpen | Opens a compressor or decompressor |
| ICClose | Closes a compressor or decompressor |
| ICLocate | Locates and opens a compressor or decompressor |
| Functions for modifying the rendering attributes of uncompressed rendered images: | |
| ICGetBrightness | Obtains the current brightness value |
| ICGetContrast | Obtains the current contrast value |
| ICGetDefaultQuality | Obtains the default quality setting used for compression |
| ICGetMirror | Obtains the current mirroring value |
| ICGetSaturation | Obtains the current saturation value |
| ICGetSharpening | Obtains the current sharpening value |
| ICSetBrightness | Sets the brightness value |
| ICSetContrast | Sets the contrast value |
| ICSetMirror | Sets the current mirroring value |
| ICSetSaturation | Sets the saturation value |
| ICSetSharpening | Sets the sharpening value |
This section contains an alphabetical listing of the functions an application uses to manage compression and decompression of video data. These functions are prefixed with IC.
#include <mme/mme_api.h>
MMRESULT ICCallbackProc(HIC hic,
void (*CallbackProc)(),
DWORD dwInstance);
|
void (*CallbackProc) ()
Specifies a callback procedure to use.
DWORD dwInstance
Specifies the user instance data that the compressor will pass back to
the callback procedure.
This function registers a callback procedure. Once a callback procedure is registered, ICCompress and ICDecompress routines are no longer blocking routines. Instead, they return data asynchronously to the registered callback.Extensions The ICCallbackProc function is a Compaq extension to the Microsoft multimedia API specification.If the CallbackProc is NULL, then a previously registered CallbackProc is deregistered and operations return to synchronous behavior.
The registration must occur before compression or decompression begins. A new callback procedure may be registered after compression or decompression has ended but before a new sequence has begun.
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. |
| ICERR_BADPARAM | The registration fails due to resource limitations. |
| ICERR_CANTUPDATE | The registration is occurring while compression or decompression operations are in progress. |
| ICERR_UNSUPPORTED | The compressor or decompressor does not support streaming. |
#include <mme/mme_api.h>
void CALLBACK icmFunc(HIC hic,
DWORD wMsg,
DWORD dwInstance,
LPARAM * lParam1,
DWORD errorFlags);
|
DWORD wMsg
Specifies the ICM streaming message. The following messages are defined:
ICM_CB_COMP_DATA
Sent when the compressor has completed the compression operation.
ICM_CB_DCMP_DATA
Sent when the decompressor has completed the decompression operation.
DWORD dwInstance
Specifies the data passed to the
ICCallbackProc
.
LPARAM lParam1
Specifies either a pointer to a ICCOMPRESSDATA data
structure or a pointer to the decompressed output image buffer,
depending on whether the message is ICM_CB_COMP_DATA or
ICM_CB_DCMP_DATA, respectively. The ICCOMPRESSDATA
data structure is only valid while the callback function is executing.
DWORD errorFlags
Specifies ICERR_OK on success or an error that occurred during the
operation.
If an error is specified, the lpOutput pointer will still be the pointer originally specified to ICCompress or ICDecompress for the application's reference.
For compression, if an error is specified, the biSizeImage field will be set to 0.
Error flags are the same as those returned from ICCompress or ICDecompress .
Callback Description for Compression
The ICCOMPRESSDATA data structure is allocated by the mmeserver . The ICCOMPRESSDATA data structure is defined as follows:
typedef struct {
DWORD lpdwFlags;
DWORD biSizeImage;
LPARAM lpOutput;
} ICCOMPRESSDATA;
|
DWORD lpdwFlags
Specifies the return flags for the AVI index. See the
lpdwFlags parameter of
ICCompress
for further details. Note that while the name of the field is
lpdwFlags to match that in the lpdwFlags parameter of
the
ICCompress
function, this field is not a pointer.
DWORD biSizeImage
Specifies the size of the data in the lpOutput buffer. This will be 0
on an error. See the lpbiOutput.biSizeImage parameter of
ICCompress
for further details.
LPARAM lpOutput
Specifies a pointer to the buffer where the compressed data has been
written, if no error occurred. See the lpData parameter of
ICCompress
for further details.
Callback Description for Decompression
For decompression, the callback lParam1 field specifies:
LPARAM lpOutput
Specifies a pointer to the buffer where the decompressed data has been
written, if no error occurred. See the lpBits parameter of
ICDecompress
.
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. |
| ICERR_BADPARAM | The registration fails due to resource limitations. |
| ICERR_CANTUPDATE | The registration is occurring while compression or decompression operations are in progress. |
| ICERR_UNSUPPORTED | The compressor or decompressor does not support bitstreaming. |
| Previous | Next | Contents | Index |