ftp.microsoft.com

home *** CD-ROM | disk | FTP | other *** search

/ ftp.microsoft.com / 2002-07-02_ftp.microsoft.com.zip / developr / drg / Multimedia / Jumpstart / VfW11e / DK / DEV_KIT.TXT next >

Wrap

Text File | 1994-09-02 | 45KB | 1,291 lines

**************************************************************** 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.