`
`Microsoft Video for Windows
`Development Kit
`
`
`
`
`For the Microsoft Windows Operating System
`
`Microsoft Corporation
`
`
`
`1
`
`SAMSUNG 1007
`
`
`
`
`
`Information in this document is subject to change without notice. Companies, names, and data used in
`examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or
`transmitted in any form or by any means, electronic or mechanical, for any purpose, without the
`express written permission of Microsoft Corporation.
`
`©1992, 1993 Microsoft Corporation. All rights reserved.
`
`
`Microsoft, MS, and MS-DOS are registered trademarks, Windows and Visual Basic are trademarks
`of Microsoft Corporation in the USA and other countries.
`
`
`U.S. Patent No. 4955066
`
`IBM is a registered trademark of International Business Machines Corporation.
`Intel is a registered trademark of Intel Corporation.
`ToolBook is a registered trademark of Asymetrix Corp.
`
`
`
`Printed in the United States of America.
`
`
`
`2
`
`
`
`
`
`
`
`Contents
`
`
`
`
`
`Chapter 1 Introduction and Installation . . . . . . . . . . . . . . . . . . . . . . . 1 - 1
`Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 - 2
`Documentation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 - 2
`Chapter 2 Using the Installable Compression Manager . . . . . . . . 2 - 1
`Video Compression and Decompression Header Files . . . . . . . . . . . . . . . . . . . . 2 -1
`ICM Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -1
`Using ICM Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -2
`Error Returned from the ICM Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -2
`Locating and Opening Compressors and Decompressors . . . . . . . . . . . . . . . 2 -2
`Installing and Removing Compressors and Decompressors . . . . . . . . . . . . . 2 -5
`Configuring Compressors and Decompressors . . . . . . . . . . . . . . . . . . . . . . . 2 -7
`Getting Information about Compressors and Decompressors. . . . . . . . . . . . 2 -8
`Compressing Image Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -11
`Specifying the Input Format and Determining
` the Compression Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -11
`Initialization for the Compression Sequence . . . . . . . . . . . . . . . . . . . . . 2 -13
`Compressing the Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -13
`Decompressing Image Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -15
`Specifying the Input Format and Determining
` the Decompression Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -16
`Initialization for the Decompression Sequence . . . . . . . . . . . . . . . . . . . 2 -17
`Decompressing the Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -18
`Using Hardware Drawing Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -19
`Specifying the Input Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -20
`Preparing to Decompress Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -20
`Decompressing the Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -21
`Controlling Drawing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 -23
`Video Compression and Decompression Function Reference . . . . . . . . . . . . . 2 -23
`Video Compression and Decompression Functions . . . . . . . . . . . . . . . . . . 2 -26
`Video Compressor and Decompressor Data Structure Reference . . . . . . . . . . 2 -45
`
`
`
`3
`
`
`
`
`
` Video for Windows Programmer's Guide
`
`
`
`ii
`
`
`
`
`Chapter 3 Using the DrawDib Functions . . . . . . . . . . . . . . . . . . . . . . 3 - 1
`Drawing With the DrawDib Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1
`Supporting Palettes for the DrawDib Functions . . . . . . . . . . . . . . . . . . . . . . 3 - 3
`Manipulating Palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3
`Optimizing DrawDibDraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 4
`Profiling the Display Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 5
`DrawDib Application Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 5
`DrawDib Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 5
`Chapter 4 AVI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1
`AVI RIFF Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1
`Data Structures for AVI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3
`The Main AVI Header LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3
`The Stream Header (“strl”) Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 5
`The LIST “movi” Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 7
`The “idx1” Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 8
`Other Data Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 9
`Special Information for Interleaved Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 9
`Using VidEdit With AVI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 10
`Example Code for Writing AVI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 10
`An Outline for Writing AVI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 10
`Creating the File and “AVI ” Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 11
`Creating the LIST “hdrl ” and “avih” Chunks . . . . . . . . . . . . . . . . . . . . . . . 4 - 11
`Creating the “strl”, “strh”, “strf”, and “strd” Chunks . . . . . . . . . . . . . . . . . 4 - 12
`Creating the LIST “movi” and “rec ” Chunks . . . . . . . . . . . . . . . . . . . . . . . 4 - 12
`Creating the “idx1” Chunk and Ascending From the “AVI ” Chunk . . . . 4 - 13
`AVI RIFF File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 14
`Chapter 5 DIB Format Extensions for Microsoft Windows . . . . . . 5 - 1
`Windows Compression Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 1
`Existing Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 2
`Extensions to the BI_RGB Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 2
`Formats Using BI_BITFIELDS and Color Masks . . . . . . . . . . . . . . . . . . . . . 5 - 3
`Custom Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 4
`Determining Display Driver Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 5
`Inverted DIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 6
`Definition of the Flags and Escape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 6
`Chapter 6 Playing AVI Files With MCI . . . . . . . . . . . . . . . . . . . . . . . . 6 - 1
`MCI Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 1
`Using the MCI Command Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 2
`Using the MCI String Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3
`Choosing the mciSendCommand or mciSendString Interface . . . . . . . . . . . 6 - 5
`
`02/10/93
`
`4
`
`
`
`
`
`
`iii
`
`Contents
`Handling MCI Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 6
`Playing AVI files with MCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 7
`Opening an AVI File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 7
`Setting up the Playback Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 8
`Playing the AVI Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 10
`Changing the Playback State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 10
`Obtaining Playback Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 12
`Closing the AVI File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 12
`Chapter 7 MCI Command Strings for MCIAVI . . . . . . . . . . . . . . . . . . 7 - 1
`About the MCIAVI.DRV Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 1
`Custom Commands and Flags for MCIAVI.DRV . . . . . . . . . . . . . . . . . . . . . . . . 7 - 1
`MCI Command Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 2
`Chapter 8 MCI Command Messages for MCIAVI . . . . . . . . . . . . . . . 8 - 1
`MCI Command Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 1
`Chapter 9 Video Capture Application Reference . . . . . . . . . . . . . . . 9 - 1
`Video Capture Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 1
`Video Capture Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 1
`Video Capture Function Alphabetic Reference . . . . . . . . . . . . . . . . . . . . . . . 9 - 3
`Video Capture Data Structure Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 16
`Video Capture Data Structure Alphabetic Reference . . . . . . . . . . . . . . . . . 9 - 16
`Chapter 10 Video Compression and Decompression Drivers . 1 0 - 1
`Architecture of a Video Compression and Decompression Driver . . . . . . . . 1 0- 1
`The ICSAMPLE Example Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 3
`The Structure of a Video Compression and Decompression Driver . . . . . . . 1 0- 3
`Video Compression and Decompression Header Files . . . . . . . . . . . . . . . 1 0- 3
`Naming Video Compression and Decompression Drivers . . . . . . . . . . . . 1 0- 3
`SYSTEM.INI Entries for Video Compression and
` Decompression Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 4
`The Module-Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 5
`The Module Name Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 5
`The Installable Driver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 6
`An Example DriverProc Entry-Point Function . . . . . . . . . . . . . . . . . . . . . 1 0- 6
`Handling the DRV_OPEN and DRV_CLOSE Messages . . . . . . . . . . . . . 1 0- 8
`Compressor Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 9
`Configuration Messages Sent by the System . . . . . . . . . . . . . . . . . . . . 1 0- 9
`Messages for Configuring the Driver State . . . . . . . . . . . . . . . . . . . . . 1 0- 10
`Messages Used to Interrogate the Driver . . . . . . . . . . . . . . . . . . . . . . 1 0- 11
`Configuration Messages for Compression Quality . . . . . . . . . . . . . . . . . 1 0- 12
`Configuration Messages for Key Frame Rate and Buffer Queue . . . . . . 1 0- 13
`
`02/10/93
`
`5
`
`
`
`
`
` Video for Windows Programmer's Guide
`
`
`
`iv
`
`
`Video Compression and Decompression Messages . . . . . . . . . . . . . . . . . . . 1 0- 14
`About the AVI File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 14
`Identifying Compression Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 16
`Decompressing Video Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 17
`Setting the Driver State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 18
`Specifying the Input Format and Determining
` the Decompression Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 18
`Preparing to Decompress Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 19
`Decompressing the Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 19
`Ending Decompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 20
`Other Messages Received During Decompression . . . . . . . . . . . . . . 1 0- 20
`Compressing Video Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 20
`Obtaining the Driver State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 21
`Specifying the Input Format and Determining
` the Compression Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 21
`Initialization for the Compression Sequence . . . . . . . . . . . . . . . . . . . 1 0- 23
`Compressing the Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 23
`Ending Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 24
`Decompressing Directly to Video Hardware . . . . . . . . . . . . . . . . . . . . . . 1 0- 25
`Setting the Driver State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 25
`Specifying the Input Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 25
`Preparing to Decompress Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 26
`Decompressing the Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 27
`Ending Decompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 28
`Rendering the Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 0- 28
`Using Installable Compressors for Non-video Data . . . . . . . . . . . . . . . . . . . 1 0- 29
`Testing Video Compression and Decompression Drivers . . . . . . . . . . . . . . 1 0- 30
`Video Compression and Decompression Driver Reference . . . . . . . . . . . . . 1 0- 30
`Video Compression and Decompression Driver Message Reference . . 1 0- 30
`Video Compression and Decompression Driver Messages . . . . . . . . . . . . . 1 0- 33
`Chapter 11 Video Capture Device Drivers . . . . . . . . . . . . . . . . . . . 1 1 - 1
`Architecture of a Video Capture Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 1
`Video Capture Device Driver Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 2
`The Video Capture Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 3
`Sample Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 3
`The Structure of a Video Capture Device Driver . . . . . . . . . . . . . . . . . . . . . . 1 1- 3
`Combining Video Capture and Video
` Compression/Decompression Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 4
`Video Capture Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 4
`Naming Video Capture Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 4
`SYSTEM.INI Entries for Video Capture Device Drivers . . . . . . . . . . . . . 1 1- 4
`
`02/10/93
`
`6
`
`
`
`
`
`
`v
`
`Contents
`The Module-Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 6
`The Module Name Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 6
`The Module Description Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 6
`Considerations for Interrupt-Driven Drivers . . . . . . . . . . . . . . . . . . . . . . . 1 1- 7
`Fixing Code and Data Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 7
`Allocating and Using Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 7
`Calling Windows Functions at Interrupt Time . . . . . . . . . . . . . . . . . . . 1 1- 8
`The Installable Driver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 8
`An Example DriverProc Entry-Point Function . . . . . . . . . . . . . . . . . . . . . 1 1- 8
`Handling the DRV_OPEN and DRV_CLOSE Messages . . . . . . . . . . . . 1 1- 10
`Handling the DRV_ENABLE and DRV_DISABLE Messages . . . . . . . 1 1- 14
`Driver Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 15
`Video Capture Driver Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 15
`Configuring the Channels of a Video Capture Driver . . . . . . . . . . . . . . . 1 1- 15
`Setting and Obtaining Video Capture Format . . . . . . . . . . . . . . . . . . . . . 1 1- 17
`Setting and Obtaining the Video Source and Destination Rectangles . . 1 1- 19
`Determining Channel Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 21
`Setting and Obtaining a Video Capture Palette . . . . . . . . . . . . . . . . . . . . 1 1- 22
`Obtaining the Device Driver Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 25
`Transferring Data From the Frame Buffer . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 25
`Streaming Video Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 26
`The Data Transfer Model For Streaming Video Input . . . . . . . . . . . . . . 1 1- 26
`Initializing the Data Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 28
`Preparing Data Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 28
`Starting and Stopping Streaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 29
`Ending Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 29
`Additional Stream Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 30
`Video Capture Device Driver Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 31
`Video Capture Device Driver Message Reference . . . . . . . . . . . . . . . . . 1 1- 31
`Message Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 32
`Video Capture Device Driver Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1- 33
`Video Capture Device Driver Data Structure Reference . . . . . . . . . . . . 1 1- 47
`
`02/10/93
`
`7
`
`
`
`
`
`C H A P T E R 1
`
`Introduction and Installation
`
`
`
`The Microsoft® Video for WindowsDevelopment Kit provides the resources you need
`to write applications that use the following services:
` Video Capture—These functions give your application easy access to video capture
`drivers. Your application can use these functions to obtain video sequences that you
`can use in AVI movies and in other applications using Video for Windows.
` Video Compression and Decompression—These functions give your application the
`ability to access video compressors and decompressors that use industry standard
`compression formats.
` AVI Playback with MCI—The MCI commands let your application use the AVI MCI
`driver to play AVI movies and manage the playback window.
` Extended Display Services—These services augment the standard video services to
`provide access to video decompressors, provide improved dithering of true-color
`images to 256 colors, and dither 8-bit images to 16-color VGA displays.
` Read and Write AVI Files—The AVI file examples and information let you develop
`routines to read and write AVI files.
`This development kit also provides the resources needed by people developing video
`capture device drivers, and video compression and decompression drivers.
`The software support supplied in this development kit includes:
` A collection of sample applications and drivers that use and provide Video for
`Windows services
` Header files defining the messages, data structures, and functions
` Documentation describing the features of the components of the development kit
`
`8
`
`
`
`Error! Main Document Only.-2
`
`
`Installing the Software
`
` Video for Windows Programmer's Guide
`
`The distribution disks included with the development kit use a batch file to install the
`software. The following procedure describes the installation process.
`
`Û To install the Video for Windows Development Software:
` 1. From the MS-DOS command prompt, change to the floppy drive you are installing
`from and run the INSTALL batch file. The INSTALL batch file has the following
`syntax:
`INSTALL C:\VFWDK
`
`Replace C:\VFWDK with disk and path for the destination of the files.
` 2. When installation is complete, change your INCLUDE and LIB environment variables
`to include the INC and LIB directories in your destination path. For example, if you
`used C:\VFWDK as the path during installation, you could use the following:
`SET INCLUDE=[previous include line];C:\VFWDK\INC
`
`SET LIB=[previous lib line];C:\VFWDK\LIB
`
`For these examples, replace [previous include line] and [previous lib line] with any
`existing paths for these statements.
` 3. You might also want to add the BIN directory to your PATH variable. The following
`example shows the template for modifying your PATH statement to include the Video
`for Windows BIN directory:
`SET PATH=[previous path line];C:\VFWDK\BIN
`
`As in the previous examples, replace [previous path line] with any existing path
`statements.
`
`Documentation Overview
`
`The chapters included in this guide describe the development of applications accessing
`Video for Windows services and development of drivers providing video capture, and
`video compression and decompression services. This guide contains the following
`chapters:
` Chapter 1, “Introduction and Installation,” provides background information about the
`contents of this guide.
` Chapter 2, “Using the Installable Compression Manager,” describes how applications
`use the Installable Compression Manager (ICM) functions for compressing or
`decompressing video image data. The chapter also contains a reference to the ICM
`functions.
` Chapter 3, “Using the DrawDib Functions,” describes how applications can use the
`DrawDib functions to access ICM services, and obtain improved support of low-end
`VGA display adapters. These functions significantly improve the speed and quality of
`displaying such images on display adapters with limited capabilities.
`
`02/10/93
`
`9
`
`
`
`
`
`
`Error! Main Document Only.-3
`
`Introduction and Installation
` Chapter 4, “AVI Files,” describes the AVI RIFF file format. The information in this
`chapter applies to applications and drivers that use this file format.
` Chapter 5, “DIB Format Extensions for Microsoft Windows,” describes the DIB
`format extensions for Microsoft Windows that add new compression formats, custom
`compression formats, and inverted DIBs. Information in this chapter applies to both
`applications and video drivers.
` Chapter 6, “Playing AVI Files With MCI,” describes how to play AVI files using the
`MCI interface for Video for Windows.
` Chapter 7, “MCI Command Strings for MCIAVI,” describes the MCI command strings
`for the Microsoft MCI video driver (MCIAVI.DRV) that you can use with applications
`that support the MCI command-string interface.
` Chapter 8, “MCI Command Messages for MCIAVI,” describes the MCI command
`messages for the Microsoft MCI video driver (MCIAVI.DRV) that you can use with
`applications that support the MCI command-message interface.
` Chapter 9, “Video Capture Application Reference,” describes functions available for
`video capture.
` Chapter 10, “Video Compression and Decompression Drivers,” describes the
`installable driver interface used by video compressors and decompressors. This
`information applies to developers creating these types of drivers. This chapter also
`contains an alphabetical reference to the messages and data structures used to write
`video compression and decompression drivers.
` Chapter 11, “Video Capture Drivers,” describes the installable driver interface used by
`video capture drivers. This information applies to developers creating these types of
`drivers. This chapter also contains an alphabetical reference to the messages and data
`structures used to write video capture drivers.
`
`
`
`02/10/93
`
`10
`
`
`
`
`
`C H A P T E R 2
`
`Using the Installable
`Compression Manager
`
`
`
`The Installable Compression Manager (ICM) provides services for applications that want
`to compress or decompress video image data stored in AVI files. This chapter explains the
`programming techniques used to access these services. It covers the following topics:
` General information about the ICM and the Video for Windows architecture
` Information on how to compress and decompress video image data from your
`application
` An alphabetic reference to the ICM functions and data structures
`Before reading this chapter, you should be familiar with the video services available with
`Windows. For information about these Windows topics, see the Microsoft Windows
`Programmer’s Reference.
`Video Compression and Decompression Header
`Files
`
`The function prototypes, constants, flags, and data structures applications use to access
`the ICM services are defined in COMPMAN.H and COMPDDK.H.
`
`ICM Architecture
`
`The ICM is used by the Video for Windows editing tool (VidEdit) and the playback
`engine (MCIAVI) to handle compression and decompression of image data. ICM is the
`intermediary between the application and the actual video compression and
`decompression drivers. It is the video compression/decompression drivers that do the real
`work of compressing and decompressing individual frames of data.
`This chapter covers the ICM and the functions a video editing or playback application
`uses to communicate with it. For information on the video compression and
`decompression drivers, see Chapter 10, Video Compression and Decompression Drivers.
`As the application makes calls to the ICM to compress or decompress data, the ICM
`translates this to a message to be sent to the appropriate compressor or decompressor
`which does the work of compressing or decompressing the data. The ICM gets the return
`from the driver and then returns back to the application.
`
`
`
`11
`
`
`
` Video for Windows Programmer's Guide
`Error! Main Document Only.-2
`
`The ICMAPP sample application illustrates routines that compress data, decompress data,
`and display a dialog box. You might find the helper functions defined in ICM.C useful in
`developing your application.
`
`Using ICM Services
`
`In general, an application performs the following tasks to use ICM services:
` Locate, open, or install the appropriate compressor or decompressor
` Configures or obtains configuration information about the compressor or
`decompressor
` Uses a series of functions to compress, decompress, and (for decompressors with
`drawing capabilities) draw the data
`These tasks are covered in the following sections. The sample application, ICMApp,
`shows how to use the ICM services to do all of the above functions to compress and
`decompress images.
`Error Returned from the ICM Functions
`For most ICM functions, return values of less than zero indicate an error. Your application
`should check these return values to see if the ICM function encounters an error. To keep
`the example fragments in this chapter simple, many of them do not check for errors. For
`more complete examples, see the ICMAPP and ICM examples included with the
`development kit.
`Locating and Opening Compressors and Decompressors
`To use ICM, an application must open a compressor or decompressor. If your application
`does not know about the compressors or decompressors installed on a system, it must find
`a suitable compressor to open. Once your application finishes with a compressor or
`decompressor, it closes it to free any resources used for compression or decompression.
`Your application can use the following functions for finding compressors and
`decompressors, and opening and closing them:
`
`ICInfo
`This function obtains information about compressor or decompressor.
`ICOpen
`This function opens a compressor or decompressor.
`ICClose
`This function closes a compressor or decompressor.
`ICLocate
`This function locates a specific type of compressor or decompressor.
`
`
`If your application knows the compressor or decompressor it needs, it can open the
`compressor with the ICOpen function. Your application uses the handle returned by this
`function to identify the opened compressor or decompressor when it uses other ICM
`functions. The ICOpen function has the following syntax:
`
`02/10/93
`
`12
`
`
`
`
`
`
`
`
`Error! Main Document Only.-3
`
`Using the Installable Compression Manager
`BOOL ICOpen(fccType, fccHandler, wMode)
`The fccType and fccHandler parameters are four character codes used to describe the type
`and handler type for the compressor. Compressor and decompressors are identified by two
`four-character codes. Applications open a specific compressor or decompressor by using
`the four-character codes for the type and handler. The first four-character code describes
`the type of the compressor or decompressor. For video compressors and decompressors,
`this is always 'vidc'. The second four-character code identifies the specific compression
`handler type. For example, this value is 'msvc' for the Video 1 compressor. Your
`application can use NULL if it does not know this four-character code.
`
`Note:
`In an AVI file, the stream header contains information about the stream type and
`the specific handler for that stream. For video streams, the stream type is 'vidc' and the
`handler type is the appropriate handler four-character code. As in the previous example,
`Video 1 compressed streams use 'msvc'.
`
`The wMode parameter specifies flags passed to the compressor or decompressor. For
`ICOpen, these flags let the compressor or decompressor know why it is opened and they
`can prepare for subsequent operation. The following flags are defined:
`
`ICMODE_COMPRESS
`Advises a compressor it is opened for compression.
`ICMODE_DECOMPRESS
`Advises a decompressor it is opened for decompression.
`ICMODE_DRAW
`Advises a decompressor it is opened to decompress an image and draw it directly to
`hardware.
`ICMODE_QUERY
`Advises a compressor or decompressor it is opened to obtain information.
`
`
`If your application does not know which compressors and deompressors are installed on a
`system, it can use ICInfo to enumerate them. This function has the following syntax:
`BOOL ICInfo(fccType, fccHandler, lpicinfo)
`The fccType parameter specifies a four-character code indicating the type of compressor
`or decompressor. To enumerate the compressors or decompressors, your application
`specifies an integer for fccHandler. Your application receives return information for
`integers between 0 and the number of installed compressors or decompressors of the type
`specified for fccType. The compressor or decompressor returns information about itself in
`a ICINFO data structure pointed to by lpicinfo. The ICInfo function returns TRUE if it
`can locate the specified compressor or decompressor.
`The following example enumerates the compressors or decompressors in the system to
`find one that can handle the format of its images. (The example uses ICCompressQuery
`and ICDecompressQuery to determine if a compressor or decompressor supports the
`image format. The use of these functions is described in “Compressing Image Data” and
`“Decompressing Image Data.”)
`
`02/10/93
`
`13
`
`
`
` Video for Windows Programmer's Guide
`Error! Main Document Only.-4
`
`for (i=0; ICInfo(p->fccTyp