****************************************************************

			 DEV_KIT.TXT
		      
	       VIDEO FOR WINDOWS DEVELOPMENT KIT

****************************************************************

CONTENTS
========

1. INSTALLATION NOTES
2. CONTENTS OF THE VIDEO FOR WINDOWS DEVELOPMENT KIT
3. ONLINE DOCUMENTATION
4. USING AUDIO COMPRESSION MANAGER HELP TOPICS
5. VIDTEST APPLICATION
6. DISTRIBUTION OF RUNTIME FILES
7. DISTRIBUTION OF THIRD-PARTY FILES
8. KNOWN PROBLEMS OR ERRORS
9. UPDATES TO THE PROGRAMMER'S GUIDE


1. INSTALLATION NOTES
=====================
Use the following procedure when installing the Video 
for Windows 1.1 software:

1. Run the Setup program in the \WINVIDEO directory of the 
   development kit disc. This installs the Video for Windows 
   runtime and tools on your system.

2. Run the Setup program in the \VFWDK directory of the 
   development kit disc. This installs the development 
   files on your system.

For information on using the capture and editing tools, 
refer to the individual applications' Help files.

SETTING UP A DEVELOPMENT SYSTEM
-------------------------------

Required Programming Tools
--------------------------
Microsoft C 7.0 or later is required for building the 
C and C++ samples.

Microsoft MASM 5.1 is required for building the assembly 
language modules.

To edit the Visual Basic samples, you must have Visual 
Basic version 2.0 or later. The custom controls (VBX) 
included with the development kit are compatible with 
Visual Basic 1.0 (as well as Visual C++). 

Setting Environment Variables
-----------------------------
The Video for Windows development kit includes header 
and library files needed when using the Video for Window 
programming interfaces. To reference these required 
files, modify your INCLUDE, LIB, and PATH environment
variables as follows:

* The INCLUDE variable must reference the INC subdirectory 
  of the development kit directory.

* The LIB variable must reference the LIB subdirectory 
  of the development kit directory.

In addition, to run the compiled sample files included 
with the development kit, you should modify your PATH 
environment variable to reference the BIN subdirectory 
of the development kit directory.

For example, assuming the development kit is installed 
in the default C:\VFWDK directory, you can set the 
environment variables as follows:

SET INCLUDE=C:\VFWDK\INC;[previous include line]
SET LIB=C:\VFWDK\LIB;[previous lib line]
SET PATH=C:\VFWDK\BIN;[previous path line]

Reading AWM Files Using the Gold Disk File Handler
--------------------------------------------------
To read AWM files using the Gold Disk file handler, 
carry out the following procedure:

1. Add AWMFILE.REG to the registry. To do so, start 
   REGEDIT.EXE, and choose Merge Registration File from 
   the File menu. Choose the AWMFILE.REG file, which is 
   contained in the MISC directory.

2. Make sure the AWMFILE.DLL, AWMFILE2.DLL, and 
   AWMFILE3.TSK files are contained in the SYSTEM directory 
   of your Windows directory.

3. In your WIN.INI file, add the following line to 
   the [MCI EXTENSIONS] section:

   awmfile=AVIVideo

To play AWM files using MPlayer or any AVI player:

1. Run REGEDIT with the /v switch and choose Add Key from 
   the Edit menu. Specify .AWM for the key and MPlayer 
   for the value.


2. CONTENTS OF THE VIDEO FOR WINDOWS DEVELOPMENT KIT
====================================================

DIRECTORIES ON THE CD
---------------------
The Video for Windows disc includes the following 
directories:

Directory       Contents
---------       -------------------------------------------
MULTILNG        Contains a sample AVI file with multiple
		audio streams. Media Player or any other 
		AVI player can play the English audio track.
		Use the sample application LangPlay to play
		it with the other audio tracks. (Setup will
		add a LangPlay icon to your VFW 1.1 DK 
		Program Manager group.)

RUNTIME         Contains the files needed to play back 
		Video for Windows clips. These files 
		include the set of drivers, DLLs, and 
		applications that are installed on an 
		end-user's system. This directory also 
		includes the source files for the
		runtime setup application.

VFWDK           Contains the Video for Windows development 
		kit.

WINVIDEO        Contains the Video for Windows runtime and 
		tools (video capture and editing).


DIRECTORIES INSTALLED ON YOUR SYSTEM
------------------------------------
By default, the Setup routine for the Video for Windows 
runtime and tools creates a C:\WINVIDEO directory on your 
system. This directory contains VidCap and VidEdit. The 
Video for Windows runtime files are installed in your 
Windows SYSTEM directory.

By default, the Setup routine for the development kit 
creates a C:\VFWDK directory on your system. This directory 
contains the following subdirectories:

Subdirectory    Contents
------------    -------------------------------------------
ACMHELP         Contains ACM help files that you can build 
		into your application's help file. For more 
		information, see section 4, USING AUDIO 
		COMPRESSION MANAGER HELP TOPICS.

BIN             Contains compiled versions of the 
		programming samples, along with system 
		files (VBX, DLL) required to run the samples.

DOC             Contains a Microsoft Multimedia Viewer 
		title, the Programmer's Guide. Also 
		contains documentation on custom stream 
		handlers. For more information on the
		Programmer's Guide, see section 3, ONLINE 
		DOCUMENTATION.

TOOLS           Contains the following useful tools:

		* RIFFWALK, an MS-DOS utility that displays 
		  the contents of a RIFF file, with special
		  support for AVI and WAV files. Type 
		  RIFFWALK -f [filename] to  display AVI or
		  WAV headers. Type RIFFWALK to display the
		  program's full syntax and parameters.

		* UUIDGEN, an MS-DOS OLE 2.0 utility that
		  generates globally unique IDs for AVIFile
		  handlers.

		* DDTEST, a Windows application for testing
		  DrawDib functions, display drivers, and 
		  installable video codecs.

		The DEBUG subdirectory contains debugging
		versions of MSVIDEO.DLL, MSVIDEO.SYM, 
		MSACM.DLL and MSACM.SYM.

INC             Contains C header files.

LIB             Contains C import libraries.

MISC            Contains drivers, custom controls, and
		other useful utilities for Video for
		Windows developers. For information on the
		contents of this directory, see CONTENTS 
		OF THE MISC DIRECTORY below.

SAMPLES         Contains a series of programming samples.
		For information on the samples, see 
		SAMPLE APPLICATIONS below.


CONTENTS OF THE MISC DIRECTORY
------------------------------
The MISC subdirectory of the Video for Windows development
kit contains a collection of drivers, custom controls, 
file handlers, and other useful tools. The following 
sections describe these files.


MCI Drivers
-----------
The MISC directory includes the following MCI drivers,
which you can install using the Drivers option of the 
Control Panel.

Driver          Description
------------    --------------------------------------
MCIPIONR.DRV    MCI driver for the Pioneer laserdisc 
		player.

MCIPANAS.DRV    MCI driver for the Panasonic laserdisc 
		player.

MCIVISCA.DRV    MCI drivers for Sony VISCA devices (VCRs).
		For more information about this driver, 
		consult the documentation for the 
		development kit.

To install these drivers, use the Drivers option of the 
Control Panel for adding an unlisted or updated driver.


Visual Basic Custom Controls
----------------------------
The MISC directory contains the following Visual Basic 
custom controls (VBXs):

Control         Description
------------    -------------------------------------------
MCIWNDX.VBX     Custom control for playing MCI devices. 
		Provides better support for windowed video 
		devices than the MCI.VBX included with 
		Visual Basic.

CAPWNDX.VBX     Custom control for capturing AVI sequences.

These custom controls support Visual Basic versions 1.0 
through 3.0, as well as Microsoft Visual C++. For more 
information on these custom controls, consult the 
documentation for the development kit.


MCI Command Tables
------------------
The MISC directory contains the following Media Control 
Interface (MCI) command tables:

File            Description
----            -------------------------------------------
DIGITALV.MCI    MCI command-table resource for digital 
		video devices.

DIGITALV.RC     Resource script for using the digital video
		command table in a digital-video MCI driver.

VCR.MCI         MCI command-table resource for VCR devices.

VCR.RC          Resource script for using the VCR command 
		table in a VCR MCI driver.


File Handlers Used with AVIFile
-------------------------------
The MISC directory contains the following file handlers 
which are used as part of the AVIFile interfaces:

File            Description
----            -------------------------------------------
AWMFILE.DLL     Animation Works Interactive file handler.
AWMFILE.REG     These files are developed and supported by
AWMFILE2.DLL    Gold Disk.
AWMFILE3.TSK

FLIFILE.DLL     File handler for Autodesk Animator files.


SAMPLE APPLICATIONS
-------------------
The development kit includes the following programming
samples:

Sample          Description
---------       -------------------------------------------
ACMAPP          Displays wave file format, and plays, 
		records, and converts wave files.

AVICLIP         Reads frame data and copies it onto 
		the Clipboard.

AVIEDIT         Simple AVI editing application using the 
		editing APIs in AVIFile.

AVIVIEW         Simple AVI viewing application using the 
		read/write APIs in      AVIFile.

BRAVADO         Sample capture driver for the Truevision 
		Bravado board.

CAPCPP          Sample Visual C++ capture application that
		uses the AVICap capture window class and 
		MCIWnd window class for playback.

CAPTEST         Sample capture application that uses the 
		AVICap capture window class.

DSEQFILE        AVIFile file handler for DIB sequences. 
		Implemented in C++.

ICMAPP          Shows how to call the ICM APIs.

ICSAMPLE        Sample of an installable compressor. Good 
		starting point for creating a codec.

ICWALK          Sample application that shows all the 
		codecs installed on the system. Uses the
		ICM APIs.

IMAADPCM        Sample ACM codec driver.

LANGPLAY        Plays back multi-audio stream AVI files.

MCIPLAY         Simple video playback application. 
		Uses MCIWnd.

MCIPUZZL        Application lets you make a 15-square
		puzzle of a playing video sequence. Shows
		how to use installable draw procedures.

MCIVISCA        Sample MCI driver for the VCR command set.

MOVPLAY         Simple application for playing movies using
		MCI. Builds two versions, one using 
		mciSendCommand and another
		using mciSendString.

MPLAY           Simple AVI playback application. Includes 
		a subset of the features in Media Player 
		and uses the MCIWnd window class.

MSFILTER        Audio filter for ACM.

MSRLEC          Example of an installable compressor.
		Uses the RLE compression technique.

PALMAP          Stream handler that translates video
		streams into new streams of a different
		bit depth--for example, it can  translate 
		from 24-bit to 8-bit.

TXTOUT          Text stream draw renderer for rendering 
		text data in AVI files.

VBCAPTST        Sample capture application implemented 
		using Visual Basic      and the CAPWNDX.VBX 
		custom control.

VBMCITST        Sample playback application implemented 
		using Visual Basic      and the MCIWNDX.VBX
		custom control.

WAVEFILE        Sample AVIFile file handler for waveform
		audio files. 

WRITEAVI        Example showing how to use the AVIFILE 
		interface to write files such as those 
		that AVIView reads.


3. ONLINE DOCUMENTATION
=======================

Programming documentation for the development kit is
provided in a Microsoft Multimedia Viewer title, the 
Programmer's Guide.

The Setup routine for the development kit installs an icon
for this title in Program Manager, in the Video for Windows
1.1 DK group. For information on browsing the titles, 
see the following sections.

Navigating Through the Table of Contents
----------------------------------------
At any time, you can return to the opening screen: just
choose the Contents button.

From the opening screen, click on one of the headings 
to display a table of contents for that topic.

From the topic table of contents, click a name 
to display a list of subtopics. Then click
on a subtopic name to display the information.

To move up one level in the hierarchy, choose the Up
button.

Navigating Among Topics 
-----------------------
To move from topic to topic, choose the browse left << and
browse right >> buttons.

To display a list of related topics, choose the See Also
button. Then, click a topic name to jump to that topic.

To return to the last topic viewed, choose the Go Back
button.

To display a list of topics viewed, choose the History
button. You can double-click a topic name to jump to that
topic.

Displaying an Index of API Elements
-----------------------------------
To display a list of all functions, messages, and data 
structures, choose the Index button. To jump to the topic,
double-click the API element name. You can scroll the API
list or type a partial API name in the dialog box.

Searching the Title
-------------------
To perform a full-text search on the title, use the
following procedure:

1. Choose the Search button.

2. In Search by Word, type the word or phrase you're
   looking for.

   For information on using wildcards, Boolean operators,
   and phrases, choose the Hints button.

3. Choose OK.

4. A Search Results window is displayed listing the results
   of the search. To jump to a found topic, select the 
   topic name, then choose the Go To button.


4. USING AUDIO COMPRESSION MANAGER HELP TOPICS
==============================================
Setup installs the Audio Compression Manager help files
in the ACMHELP directory. The help project file is 
ACMHELP.HPJ, and the RTF source files are ACMHELP.RTF, 
FILTSRC.RTF, and CHOOSSRC.RTF. The ACMHELP.RTF file 
contains information on using the help topics. The 
FILTSRC.RTF and CHOOSSRC.RTF files contain the help 
information for the filter and chooser topics.

You can use the RTF help topics in your application's help
file. For example, you could include the three RTF files
under the [FILES] entry in your application's help project
file. That way, ACM help topics will be built into your
application's help file when you compile it.   

5. VIDTEST APPLICATION
======================

The Samples disc includes a multimedia performance testing
application called VidTest. You can use VidTest to test the
performance of multimedia components on your system, 
including the CD-ROM drive, audio hardware, and video
hardware. To allow your customers to obtain useful metrics
on the performance of their multimedia systems, you can 
distribute the VidTest application with your product. 

VidTest only works with this version (1.1) of Video for
Windows. It does not work with Video for Windows 1.0.


LOCATION OF VIDTEST
-------------------
VidTest is located on the Video for Windows Samples disc, 
in the \VIDTEST directory. The application includes a set
of sample AVI and files which are stored in the same
directory.


RUNNING VIDTEST
---------------
You can run VidTest directly from the Samples disc. Use 
Program Manager or File Manager to start VIDTEST.EXE from
the \VIDTEST directory. For information on using the
application, choose the Help button.


DISTRIBUTING VIDTEST
--------------------
If you distribute VidTest with your product, you can use
one of the following setup options:

* You can leave VidTest (and the its sample files)
  on your distribution disc. Your users can run VidTest
  directly from the disc, in the same way you can run 
  VidTest from the Video for Windows samples disc.

* You can install VidTest (and, optionally, the 
  accompanying sample files) on your user's system.


Leaving VidTest on the Distribution Disc
----------------------------------------
With this option, you must create a directory on your 
distribution disc containing the same set of files 
stored in the \VIDTEST directory on the Video for Windows
sample disc. No further modifications are needed.


Installing VidTest on the User's System
---------------------------------------
If you install VidTest on your user's system, you must make
the necessary changes to your Setup routine to install the
files. You can install the complete set of VidTest files 
on the user's system, or you can just install the following
files:

* VIDTEST.EXE
* VIDTEST.HLP
* PERFTEST.DLL
* VIDTEST.INI

In either case, you must make the following changes to the
VIDTEST.INI file:

* In the VOLUMELABLE= entry, enter the label of the disk on
  which the sample AVI and WAV files are stored.

* In the VOLUMENAME= entry, enter the name of the disc.
  This text is displayed in a prompt if VidTest fails to 
  find the specified disc.

* In the file= entries (rlefile=, msvc8file=, msvc16file=,
  indeofile=, and cinepakfile=), change the value to 
  specify the full path name (without the drive letter) for
  the sample AVI files used with VidTest. For example, if 
  you place the VidTest samples in a TESTFILE directory, 
  your RLEFILE= entry would read as follows:

  rlefile=\testfile\rlefile.avi

When searching for the VIDTEST.INI file, VidTest first 
looks in the directory containing VIDTEST.EXE. If the
VIDTEST.INI file is not there, VidTest looks in the Windows
directory. You should install VIDTEST.INI in the same 
directory as VIDTEST.EXE.


6. DISTRIBUTION OF RUNTIME FILES
================================

The RUNTIME directory on the Video for Windows development
kit CD contains the complete Video for Windows runtime
files. You may distribute the runtime files with your 
product. 


CONTENTS OF THE RUNTIME DIRECTORY
---------------------------------

The RUNTIME directory contains the following subdirectories:

Subdirectory    Description
------------    -------------------------------------------
DISKS           Contains disk images of the runtime files.
		The DISKS subdirectory contains USA, FRN, 
		and GER subdirectories containing the 
		English, French, and German versions of
		the runtime files. 
		

SETUPSRC        Contains the source files for the runtime
		setup application. Using the Setup Toolkit
		included with the Microsoft Windows 
		Software Development Kit, you can modify 
		these source files to customize Setup to
		install your own product along with the 
		Video for Windows runtime.


USING THE DISK IMAGES
---------------------

You can use the disk images in the DISKS subdirectory to
create a Video for Windows setup disk to distribute with
your product. Simply copy the contents of the appropriate
DISK1 subdirectory to your Video for Windows setup disk. 


CUSTOMIZING THE RUNTIME SETUP PROGRAM
-------------------------------------

The SETUPSRC directory contains the source files for the
Video for Windows Setup program. Using the Setup Toolkit
included with the Microsoft Windows 3.1 SDK, you can modify
the Setup script and layout to accommodate your own 
product files. For example, you can create an integrated
Setup program that installs  your hardware specific drivers
along with the Video for Windows files. To customize Setup,
you must become familiar with the Setup Toolkit; for 
additional information, see the Setup Toolkit for Windows 
manual in the Windows 3.1 SDK. The SETUPSRC directory 
contains the following items:

Contents        Description
--------        -----------
MKRTIME.BAT     Batch file that compresses all files and 
		creates a series of disk images in the 
		DISKS subdirectory. Before running 
		MKRTIME.BAT, you must follow the 
		procedure described later in this section.

FILES           Subdirectory containing the uncompressed 
		Video for Windows files. Add your own files 
		to this subdirectory.

LAYOUT          Subdirectory containing the SETUP.LYT 
		file. This file describes the attributes 
		of the files stored in the FILES
		subdirectory. The disk-layout utility
		included with the Setup Toolkit uses this
		file. For each file you add to the FILES 
		subdirectory you must make a corresponding 
		entry in the SETUP.LYT file. For 
		information on layout files, see the 
		documentation for the Setup Toolkit.

SCRIPT          Subdirectory containing the setup script
		file SETUP.MST. If you add files to the
		FILES subdirectory, use the SETUP.MST file
		to tell Setup when and where to copy the
		files on the end user's machine (using the 
		AddSectionFilesToCopyList function). The 
		SETUP.MST file also tells SETUP what 
		changes (if any) to make to the WIN.INI 
		and SYSTEM.INI files.

To customize a Setup script:

1. Obtain the Setup Toolkit and read the accompanying
   documentation. Make sure that both DSKLAYT.EXE and
   DSKLAYT2.EXE are in your path.

2. Use the MS-DOS XCOPY command to copy the SETUPSRC
   directory and all its subdirectories to your hard disk.
	
3. Copy your product files to the FILES subdirectory. The
   Video for Windows runtime files are already in this
   subdirectory.

4. Run the DSKLAYT.EXE program and load the SETUP.LYT file
   from the LAYOUT subdirectory. Enter in the Source
   Directory dialog box the full path to location of your 
   files. Then add entries for your product files by
   selecting filenames from the Source Directory list and
   selecting other options from lists in the dialog box.

5. If necessary, modify the setup script file stored in
   the SCRIPT subdirectory. 

6. Run MKRTIME.BAT. This batch file compresses the files in
   the FILES subdirectory and creates a COMP temporary 
   directory with the compressed files and a DISK directory
   containing the disk images. 

Once you've finished editing your setup script, test it
thoroughly, varying the installation options and system
configurations. You can verify results of the setup by
examining contents of the target directories for a 
correct set of files (with correct date and time stamps)
and by checking the WIN.INI and SYSTEM.INI files for
correct alterations.

After you successfully complete your tests, create your
master disks by copying the disk images to floppy disks.

7. DISTRIBUTION OF THIRD-PARTY FILES
====================================

The MISC directory of the Video for Windows Development
Kit contains the Panasonic laser disc driver MCIPANAS.DRV.
Panasonic developed and provided this driver for use with
this version of the Development Kit.  For support or
distribution rights to the driver, please contact:

Panasonic Technical Support:
201-392-4357
Outside of New Jersey:  1-800-524-1448
Inside of New Jersey:   1-800-624-1746

The MISC directory contains the following Gold Disk file
handlers: AWMFILE.DLL, AWMFILE.REG, AWMFILE2.DLL,
AWMFILE3.TSK. Gold Disk developed and provided these files
for use with this version of the Development Kit. Please 
see the GOLDDISK.TXT for specific licensing information.
For support or distribution rights to the driver, please
contact:

Gold Disk Technical Support:
905-602-5292
5155 Spectrum Way
Building 5
Mississauga, ON L4W5A1


8. KNOWN PROBLEMS OR ERRORS 
===========================

1. If you send data through the wave mapper with a mapped
   format and with looping enabled, the looping is still
   ignored.

2. This version of the Video for Windows Development Kit
   includes IMA ADPCM codec version 2.2. Although waveform 
   audio files created with previous versions of Microsoft's
   IMA ADPCM codec will be recognized by this new release, 
   the decompression of older files will not be performed 
   correctly. A common symptom of an incompatible waveform 
   audio file is a "popping" sound during playback. If you 
   notice the "popping" sound during playback, please 
   recompress the original uncompressed source file with 
   this new release of the IMA ADPCM codec.

3. In the sample code found in the ACMAPP example, 
   there is a discrepancy between the user interface
   and the code to implement these features. The dialog 
   box for the ACM Drivers command on the View menu does 
   not implement the Filters button correctly. Also, the 
   dialog box for Formats does not implement the Details
   button correctly.

4. Versions of ATI's video accelerator prior to 2.1 do not
   work well with Video for Windows version 1.1. Installing 
   the accelerator software after installing Video for 
   Windows can overwrite Video for Windows version 1.1 
   components with components from the previous version.
   Avoid installing any version of the video accelerator 
   unless it is specifically noted to be compatible 
   with Video for Windows version 1.1.

   The vidc.rlec=ativdacc.drv entry in the [installable 
   compressors] section of the SYSTEM.INI file can cause
   problems when playing large RLE-compressed movies. 
   Remove this entry from the SYSTEM.INI file.

   For update drivers, contact ATI Technologies Inc.


9. UPDATES TO THE PROGRAMMER'S GUIDE
====================================

The following information updates the information in the 
Video for Windows Programmer's Guide.

WORKING WITH THE DRAWDIB FUNCTIONS
----------------------------------

1. DrawDibBegin/DrawDibEnd

   DrawDib changes the state of the DDF_ANIMATE flag only
   if other parameters change for the DrawDibBegin 
   function. To make sure that DrawDib uses the state you
   want, reset the state of the DDF_ANIMATE flag with 
   DrawDibEnd and use DrawDibBegin to specify the desired
   state.

2. DrawDibDraw

   When  you call DrawDibDraw, use the biSizeImage member 
   of the BITMAPINFOHEADER structure to specify the number
   of bytes contained in the image data pointed to by 
   lpBits.

   If you open an old RLE file and get the first frame, 
   it might be returned to you as RGB data and not RLE. 
   This can be easily checked because the size of the 
   frame will be equal to the width (DWORD aligned) 
   times the height of the frame. When this happens, 
   set the compression to 0 (RGB) before you draw it. 
   All subsequent frames will be normal RLE frames.

   The DDF_KEYFRAME flag has not been implemented. Using
   the DDF_NOTKEYFRAME is still recommended for drawing
   nonkeyframes.

3. DrawDibChangePalette

   If you have not specified DDF_ANIMATE in DrawDibBegin or 
   DrawDibDraw prior to calling DrawDibChangePalette,  
   DrawDibRealize or a re-draw doesn't change the color of
   the bitmap. In this case, set the color table values 
   from the values of the palette entry values used in 
   DrawDibChangePalette. For example, if lppe is the
   pointer to the PALETTEENTRY array containing the new
   colors, and lpbi is the LPBITMAPINFOHEADER structure
   used in the DrawDibBegin or DrawDibDraw, the following
   fragment updates the DIB color table:

   //call to change color
   DrawDibChangePalette(hDD, iStart, iLen, lppe);
      
   // Update DIB color table now
   LPRGBQUAD lpColors = (LPRGBQUAD)((LPBYTE)lpbi 
			+ lpbi->biSize) ;
   for (i = iStart ; i < iStart+iLen ; i++) {
       lpColors[i].rgbRed   = lppe[i].peRed ;
       lpColors[i].rgbGreen = lppe[i].peGreen ;
       lpColors[i].rgbBlue  = lppe[i].peBlue ;
   }

4. DrawDibGetBuffer

   The DrawDibGetBuffer function returns a pointer to a
   buffer if DrawDib is being used to draw compressed data.
   For example, if drawing RGB DIBs, this function returns
   NULL. Your application should always be prepared to
   handle NULL returns from DrawDibGetBuffer. 

READING AND WRITING AVI FILES
-----------------------------

1. AVIFile/AVIStream Functions

   The AVIFile and AVIStream functions should have HRESULT
   return values rather than LONG return values.

2. AVIStreamGetFrame
 
   The buffer referenced by the pointer returned for
   AVIStreamGetFrame should not be modified. This buffer 
   is owned by AVIFile. 

3. AVIStreamRead

   If the number of samples to read is specified as zero
   for AVIStreamRead, it reads data until the buffer is
   full.

   If the number of samples to read is specified as 
   AVISTREAMREAD_CONVENIENT for AVIStreamRead, it reads
   a convenient number of data samples. For example, it
   reads until the end of a chunk in an interleaved file. 

4. AVISTREAMINFO Flags

   The AVISF_DISABLED flag for the AVISTREAMINFO structure 
   should be listed as AVISTREAMINFO_DISABLED.

   The AVISF_VIDEO_PALCHANGES flag for the AVISTREAMINFO 
   structure should be listed as AVISTREAMINFO_FORMATCHANGES.

5. AVIFILEINFO Flags

   The AVIF_ flags for the AVIFILEINFO structure should
   be listed as AVIFILEINFO_ flags:

   AVIFILEINFO_HASINDEX
   AVIFILEINFO_ISINTERLEAVED
   AVIFILEINFO_MUSTUSEINDEX
   AVIFILEINFO_WASCAPTUREFILE
   AVIFILEINFO_COPYRIGHTED

WORKING WITH THE INSTALLABLE COMPRESSION MANAGER
------------------------------------------------

1. ICInfo/ICGetInfo

   Use ICGetInfo to obtain complete information about
   a compressor. ICInfo only returns basic information 
   about a compressor.

WORKING WITH THE AUDIO COMPRESSION MANAGER
------------------------------------------

1. acmFormatChoose/acmFilterChoose

   The following flags are not defined for acmFormatChoose
   and acmFilterChoose:

   FORMATCHOOSE_FORMAT_ADD
   FORMATCHOOSE_FORMATTAG_ADD
   FILTERCHOOSE_FORMAT_ADD
   FILTERCHOOSE_FORMATTAG_ADD

CONTROLLING MCI DEVICES USING THE MCIWND WINDOW CLASS
-----------------------------------------------------

1. MCIWndCan Macros

   The MCIWndCanConfig, MCIWndCanEject, MCIWndCanPlay, 
   MCIWndCanRecord, MCIWndCanSave, and MCIWndCanWindow 
   return type is BOOL rather than LRESULT.

2. MCIWndCreate

   The MCIWndCreate macro also has the MCIWNDF_NOOPEN
   style. This style creates a popup window that excludes
   the open menu item.

3. MCIWndGetMode

   The MCIWndGetMode macro can return the following MCI
   modes: MCI_MODE_STOP, MCI_MODE_PAUSE, MCI_MODE_PLAY, 
   MCI_MODE_OPEN, MCI_MODE_RECORD, and MCI_MODE_SEEK. 

4. MCIWndOpenInterface

   The MCIWndOpenInterface macro opens a file or stream
   interface.

   MCIWndOpenInterface(hwnd, pUnk)

   hwnd
     Specifies a window handle.

   pUnk
     Specifies a handle to a file or stream interface.

   This macro is defined using the MCIWNDM_OPENINTERFACE
   message.

5. MCIWndPutDest/MCIWndPutSource 

   The RECT argument for MCIWndPutDest and MCIWndPutSource
   should be an LPRECT data type.

CAPTURING AVI FILES USING THE AVICAP WINDOW CLASS
-------------------------------------------------

1. Optimizing AVICap Performance

   The following fragment sets parameters for optimizing
   AVICap performance. Capturing to extended memory
   provides the best performance if the entire captured 
   sequence can fit in memory. If the sequence will not 
   fit in memory, capturing to disk using memory below 
   1 megabyte gives better performance than capturing to 
   disk using extended memory. 

   CAPTUREPARMS CapParms;
   ... 
   if (fCaptureToDisk) {
      // Capture to disk
      // Writes from DOS memory give the best disk 
      // performance. So attempt to use 10 buffers 
      // below 1 megabyte.
      // If DOS buffers are unavailable, AVICAP 
      // automatically attempts to allocate 10 buffers from
      // extended memory. Only if zero buffers are
      // allocated, will the capture abort.
      CapParms.wNumVideoBuffers = 10;
      CapParms.fUsingDOSMemory = TRUE;
   } else {
      // Capture to Memory
      // Try to allocate 1000 buffers above 1 megabyte.
      // The actual number of buffers allocated will
      // depend on available physical memory.
      // Only if zero buffers are allocated,
      // will the capture abort.
      CapParms.wNumVideoBuffers = 1000;
      CapParms.fUsingDOSMemory = FALSE;
   }

2. CAPDRIVERCAPS 

   The CAPDRIVERCAPS data structure has the following 
   additional members:

   HVIDEO  hVideoIn;         // Driver In channel
   HVIDEO  hVideoOut;        // Driver Out channel
   HVIDEO  hVideoExtIn;      // Driver Ext. In channel
   HVIDEO  hVideoExtOut;     // Driver Ext. Out channel

  Existing programs do not need to be recompiled for this 
  expanded structure.  


3. CAPTUREPARMS

   The CAPTUREPARMS structure has the following additional
   members:

   DWORD dwAudioBufferSize;   // Size of audio buffers 
			      // (0 = default)
   BOOL  fDisableWriteCache;  // Attempt to disable write
			      // cache

   Existing programs do not need to be recompiled for this 
   expanded structure.  

   The default value for the fUsingDOSMemory member of the
   CAPTUREPARMS data structure has been changed to FALSE.

5. videoGetErrorText

   If the wSize parameter is zero, videoGetErrorText
   returns DV_ERR_SIZEFIELD and nothing is copied to the
   return buffer.

6. capGetMCIDevice

   The capGetMCIDevice reference in the AVI Capture Macros
   reference table should be capGetMCIDeviceName.

PLAYING AVI FILES USING MCI
---------------------------

1. Dialog Box for the Configure String Command.

   The Don't Buffer Offscreen checkbox has been removed
   from the Configure dialog box.

MCI VCR SERVICES
----------------

1. Enabling and Disabling Tracks with the VISCA Driver

   When operating in insert mode, the VISCA device driver
   cannot turn tracks on or off individually. It sets 
   both the video and audio tracks in combination
   simultaneously. To change the setting of both the audio
   and video tracks in the insert mode, use the SETAUDIO 
   command immediately followed by the SETVIDEO command. 
   An error message will result from the first command 
   which you can ignore. The VISCA driver changes both
   tracks to their new state when it receives the second
   command.

2. MCI VCR String Command Reference

   Change the "set pause (timeout)" command to 
   "set pause timeout (timeout)".

   The references to "status clock increment rate" should 
   be "capability clock increment rate".

MULTIMEDIA COMPRESSION, DECOMPRESSION, AND RENDERING DRIVERS
------------------------------------------------------------

1. ICM Draw Handlers

   Returning a value other than ICERR_OK for the 
   ICM_DRAW_WINDOW message in a draw handler prevents 
   subsequent ICM_DRAW_WINDOW messages from being sent to
   a draw handler. In this case, moving a playback window
   will not update the window.


NEW PERFORMANCE APIS 
------------------------------------------------- 

1. Changes to AVICAP
    The WM_CAP_SET_CALLBACK_CAPCONTROL 
    message has been added to allow capture applications frame 
    accurate control over the starting and stopping points of video capture.  
    Applications can now preroll and postroll.

2. Changes to MSVIDEO
    The videoStreamAllocHdrAndBuffer and 
    videoStreamFreeHdrAndBuffer and corresponding driver messages 
    DVM_STREAM_ALLOCHDRANDBUFFER and 
    DVM_STREAM_FREEHDRANDBUFFER have been added.  These 
    messages are used by AVICap.dll to let capture drivers allocate image 
    buffers from memory located on-board.  These on-board buffers are then 
    written directly to disk, improving capture performance.

3. The new ICM_DECOMPRESS_SET_PALETTE message was added.  
    The lParam1 is a pointer to a BITMAPINFOHEADER structure.  
    This message tells the codec that the application wishes it to use 
    a particular palette for 8-bit decompression if possible.  The colors to use 
    are the color table of the DIB that is passed in.

    This message will be sent after the ICM_OPEN message, and before any 
    ICM_DECOMPRESS_GET_FORMAT or 
    ICM_DECOMPRESS_GET_PALETTE messages.  A codec is allowed to 
    ignore this message, and return ICERR_UNSUPPORTED.
    A possible implementation by the codec is if this message is received, 
    remember the colors given.  Then, whenever decoding to 8-bit, rather than 
   dithering to a standard palette, use a palette containing the colors passed in, 
    and return the set of colors you're using as appropriate from the 
    ICM_DECOMPRESS_GET_FORMAT or 
    ICM_DECOMPRESS_GET_PALETTE message.

4.  API Specifics

    WM_CAP_SET_CALLBACK_CAPCONTROL
    ----------------
    This message sets a callback procedure in the client application allowing it 
    precise recording control.

    Parameters
	wParam	
		Not used.
	lParam
		Specifies NULL or a FARPROC address of the callback 
		procedure. NULL disables a previously installed callback 
		procedure. Use MakeProcInstance to create the instance 
		address, and export the callback in the application's .DEF 
		file.
    Return Value	
	Returns TRUE on success, or FALSE if streaming capture is in progress 
	or if a single frame capture session is in progress.
    Comments
	A single control callback is used to give the client application precise 
	control over the moment that streaming capture begins and completes.  
	The AVICap window first calls the procedure with nState set to 	CONTROLCALLBACK_PREROLL after all buffers have been 
	allocated and all other capture preparations have finished. This 
	gives the client application the ability to preroll video sources, 
	returning from the callback at the exact moment recording is to begin. 
	A return value from the callback of TRUE continues capture, and 
	FALSE stops capture. Once capture has begun, this callback will 
	be called frequently with nState set to 
	CONTROLCALLBACK_CAPTURING to allow the client application 
	to halt capture by returning FALSE.
    Example
	The capSetCallbackOnCapControl macro is defined using this 
	message. The capSetCallbackOnCapControl macro has the following syntax:
	capSetCallbackOnCapControl(hwnd, fpProc)



    The following example uses a macro to install an audio stream callback:
    FARPROC fpCapControlCallback;

    LRESULT FAR PASCAL MyCapControlCallback (HWND hwnd, int nState)
    {
	if (nState == CONTROLCALLBACK_PREROLL) { 
		// if waiting to begin capture
		while (!fPreRollDone)  
			... // Hang here waiting for preroll to complet
		return (LRESULT) TRUE; // Begin capture NOW!
	}
	else if (nState == CONTROLCALLBACK_CAPTURING) {
		//if capturing
		if (!fTimeToQuit)  
			return (LRESULT) TRUE; // Continue capture
		else
			return (LRESULT) FALSE; // Stop capture
	}
    }

    fpCapControlCallback = MakeProcInstance ((FARPROC)MyCapControlCallback, 
    hInst);
    capSetCallbackOnCapControl (hwndCapture, fpCapControlCallback);

 
    videoStreamAllocHdrAndBuffer
    ----------------
    This function is used to allow drivers to optionally allocate video buffers.  
    Normally, the client application is responsible for allocating buffer memory, 
    but devices which have on-board memory may optionally allocate headers 
    and buffers using this function. Generally, this will avoid an additional 
    data copy, resulting in faster capture rates.

    DWORD videoStreamAllocHdrAndBuffer(HVIDEO hVideo, LPVIDEOHDR 
    FAR * plpvideoHdr, DWORD dwSize)

    Parameters
	hVideo
		Specifies a handle to the video device channel.
	plpvideoHdr
		Specifies a pointer to the address of a VIDEOHDR structure.  
		The driver saves the buffer address in this location, or NULL 
		if it cannot allocate a buffer.
	dwSize
		Specifies the size of the VIDEOHDR structure and associated 
		video buffer in bytes.
   Return Value
	Returns zero if the function was successful. Otherwise, it returns an 
	error number. 
	The following errors are defined:
		DV_ERR_INVALHANDLE
			Indicates the specified device handle is invalid.
		DV_ERR_NOMEM
			Indicates the device is unable to allocate or lock 
			memory.
		DV_ERR_NOTSUPPORTED
			Indicates the driver does not have on-board 
			memory.
    Comments
	If the driver allocates buffers via this method, the 
	videoStreamPrepareHeader and videoStreamUnprepareHeader 
	functions should not be used. The buffer allocated must be
	accessible for DMA by the host.
    See Also
	videoStreamPrepareHeader


    videoStreamFreeHdrAndBuffer
    ----------------
    This function is used to free buffers allocated by the driver using the 
    videoStreamAllocHdrAndBuffer function.

    DWORD videoStreamFreeHdrAndBuffer(HVIDEO hVideo, 
    LPVIDEOHDR lpvideoHdr)

    Parameters
	hVideo
		Specifies a handle to the video device channel.
	lpvideoHdr
		Specifies a pointer to the VIDEOHDR structure and 
		associated buffer to be freed.
    Return Value
	Returns zero if the function was successful. Otherwise, it returns 
	an error number. 
	The following errors are defined:
		DV_ERR_INVALHANDLE
			Indicates the specified device handle is invalid.
		DV_ERR_NOTSUPPORTED
			Indicates the driver does not have on-board memory.
    Comments
	If the driver allocates buffers via this method, the 
	videoStreamPrepareHeader and videoStreamUnprepareHeader 
	functions should not be used.
    See Also
	videoStreamPrepareHeader

    DVM_STREAM_ALLOCHDRANDBUFFER
    ----------------
    This video capture message requests the video driver to attempt allocation 
    of a capture buffer.  Normally, only devices which provide substantial 
    on-board memory, which is not part of the system heap, should respond to 
    this message. Responding to this message allows capture to proceed with 
    fewer data copy operations.  Generally, this will result in faster capture rates.

    Parameters
	dwParam1
		Specifies a far pointer to the address of a VIDEOHDR 
		structure identifying the buffer.  The address of the 
		allocated buffer must be stored in this location by the 
		driver if it responds without error to this message.
	dwParam2
		Specifies the size of the VIDEOHDR structure plus 
		the size of the associated image buffer.
    Return Value
	Returns DV_ERR_OK if the message was successful. Otherwise, 
	it returns an error number. The following errors are defined:
		DV_ERR_INVALHANDLE
			Indicates the specified device handle is invalid.
		DV_ERR_NOMEM
			Indicates the device is unable to allocate or lock 
			memory.
		DV_ERR_NOTSUPPORTED
			Indicates the driver does not have on-board 
			memory.
    Comments
	If the driver allocates buffers via this method, the 
	DVM_STREAM_PREPAREHEADER message will not be received, 
	since the buffer is assumed to be continuously available.
	The buffer allocated must be accessible for DMA by the host.


    DVM_STREAM_FREEHDRANDBUFFER
    ----------------
    This video capture message is used to free data buffers allocated on 
    the capture device using the DVM_STREAM_ALLOCHDRANDBUFFER 
    message.

    Parameters
	dwParam1
		Specifies a far pointer to a VIDEOHDR structure 
		identifying the buffer.
	dwParam2
		Not used.
    Return Value
	Returns DV_ERR_OK if the message was successful. Otherwise, 
	it returns an error number. The following errors are defined:
		DV_ERR_INVALHANDLE
			Indicates the specified device handle is invalid.
		DV_ERR_NOTSUPPORTED
			Indicates the driver does not have on-board memory.
    Comments
	If the driver allocates buffers via this method, the 
	DVM_STREAM_UNPREPAREHEADER message will not be 
	received, since the buffer is assumed to be continuously available.



