
Table of Contents:      

I.	Contents of the floppy
	Introduction
II.	How to Install DCI
III.	How to verify DCI is enabled
IV.	How to run the tests
V.	Release Notes
VI.	DCISAMP.DRV
VII.	DCISVGA.DRV
VIII.	How to modify VfW SETUP program to install 
	your DCI provider.
IX.	How to overwrite offscreen profiling information
X.	How to report problems


I. CONTENTS of the DCI DEVELOPER'S KIT
	DISK1-Developer's Kit
	DISK2-Test Applications   
	DISK3-Video for Windows Run-time 1.1D      

DISK1 - DCI Developer's Kit

\DEVKIT

 README.TXT	This file
 SPEC1560.DOC	DCI Interface Specification Version 
		1.6 in Word for Windows v. 6.0 format
\DEVKIT\LIB

 DCIMAN.LIB     DCI Manager static library for DCI clients

\DEVKIT\INC    

 DCIMAN.H       Include file for DCIMAN functions
 DCIDDI.H       Include file for DCI providers
 COMPDDK.H      Include file update since VfW v1.1 DK
	
\DEVKIT\SAMPLE		
		Source code for sample DCI Provider --
		this includes a routine to convert IF09 
		(Indeo format)to YUY2 
       
REDISTRIBUTABLE FILES              

\DEVKIT\BIN    
 DCISAMP.DRV    Sample DCI Provider that supports the ATI Mach32
 MSVIDEO.DLL    Updated MSVIDEO.DLL that uses DCI primary surfaces
 DVA.386	VFlatD, frame buffer linearizer
 ICCVID.DRV     Cinepak(tm) video codec
 DCISVGA.DRV    General SVGA Primary Surface support Driver
 IR32.DLL       New Indeo(tm) video codec - This DLL will encode only 
		the new,3.2 bitstream (desginated by the FOURCC IV32), 
		but will decode both the 3.2 and the 3.1 bitstream. 
 UDH.DLL        Universal Draw Handler--uses only offscreen surfaces
 DCIMAN.DLL     DCI Manager, used by offscreen providers

DISK2 - Tests

TMCIAVI.EXE    Test for movie playback
TDCITEST.EXE   Test for DCI Providers
LOADBMP.DLL    Support DLL for YUV Conversion in TDCITEST


DISK3 - Video for Windows Run-Time 1.1D
The SETUP.EXE program of VfW run-time can be modified to add 
your DCI provider when installing VfW 1.1D. 
Refer to instructions later in this file.

WARNING:DCI is a driver's extension interface. 
DCI is NOT to be used by software application packages. 
If an application wants to use DCI, they should write to 
Video for Windows, WinG and other client software packages.
DCI support for Winodws NT is not available at this time.



INTRODUCTION

The Display Control Interface (DCI) for the Microsoft Windows 
operating system is a driver-level software interface which 
provides access to display devices while maintaining compatibility 
with Windows GDI.  
It works with the upcoming version of Windows (code-named Chicago) 
and in Windows 3.1.  DCI provides a device-independent way for 
Windows subsystem software such as 3-D graphics packages, games 
interface packages, or digital video codecs to access display 
device-dependent features.  
In the case of digital video codecs, additional support is provided
so that any codec that already supports the ICM_DECOMPRESSEX message, 
as specified by the Video for Windows Installable Codec Interface, 
automatically takes advantage of DCI capabilities, if these 
capabilities are available.
For more details of the DCI functionality, please consult the DCI 
Specification (SPEC16.DOC) included in the Developer's Disk.
	
Primary surface support is done via the MSVIDEO.DLL. 
The Universal Draw Handler is used for offscreen surface support only.
	
The Indeo codec has been updated.  The Indeo codec encodes only
the new IV32 bitstream, but will decode both the IV31 and IV32 
bitstreams.

The sample DCI provider--DCISAMP.DRV supports primary and offscreen 
surfaces.
	
	
II. How to Install DCI on your system:

DCI comes with a Video for Windows 1.1.D run-time version.
You MUST install this new version of VfW prior to installing 
your DCI DDK.

After installing Video for Windows, manually install the 
DCI Driver Developer's Kit.

1) TO INSTALL Video for Windows 1.1D Run-Time 
	Insert the Video for Windows 1.1D run-time disk, and 
	run setup.

2) TO INSTALL DCI Driver Developer's Kit
	After installing VfW, insert the DCI Developer's Disk 
	and copy DCIMAN.DLL and UDH.DLL files in the \DEVKIT\BIN 
	directory of the floppy disk to your WINDOWS\SYSTEM 
	directory.
	DCISVGA.DRV, DVA.386, and the IR32.DLL,ICCVID.DRV codecs are 
	automatically copied by the VfW Run-time setup to your 
	WINDOWS\SYSTEM directory. 
	
3)  Add the following line to the [Drivers] section of your 
	SYSTEM.INI:
	VIDS.DRAW=udh.dll

4)  Install one of the enclosed DCI providers:
	
a)  If you want to test primary DCI support on a supported SVGA card, 
	add the following line to the [Drivers] section of your 
	SYSTEM.INI file:
	DCI=dcisvga

b)  If you wish to test your own provider, follow the same procedure:
	DCI=<path>\<driver name>

c)  If you have a graphics card with the ATI Mach32 graphics chip,
	you can run the sample DCI provider adding the following line:
		DCI=<path>\dcisamp
					
5)  Open and play an AVI file recorded in a bitstream whose codec
    supports the ICM_DECOMPRESSEX interface.  
	Examples: Indeo(tm) Video R3.1, Cinepak, MSVideo.


Without Video for Windows v. 1.1, it is still possible to 
install DCI in your system. However, you will need a DCI Client 
to make use of the installed DCI Provider.


1)  To install one of the enclosed DCI providers:
	
a)  If you want to test a supported SVGA card, add the following line
	    to the [Drivers] section of your SYSTEM.INI file:

		DCI=<path>\dcisvga

b)  If you wish to test your own provider, follow the same procedure:

		DCI=<path>\<driver name>

c)  If you have a graphics card with the ATI Mach32 graphics chip, you
	    can use the sample provider in the \devkit\bin directory:
	
		DCI=<path>\dcisamp
 

2) Copy all the files in the \DEVKIT\BIN directory to your 
	\WINDOWS\SYSTEM directory.
		

III. HOW TO VERIFY THAT DCI IS ENABLED

a) For DCI primary surfaces:
	Run WPS (from the WIndows SDK) and check to see that the 
	DCI primary surface provider is loaded and the MSVIDEO.DLL 
	in this release is loaded. 

b) For DCI offscreen surfaces:

	Run WPS and check to see that the DCI offscreen surface 
	provider, UDH, and DCIMAN are loaded.

	After bringing up the movie, check in your Windows directory 
	for a file called DCI.INI.  If there is a section headed by 
	[<FOURCC>DCIColors] where <FOURCC> corresponds to the AVI 
	file you just opened, and there is a DCIColors entry in 
	that section, then your DCI offscreen surface is enabled 
	and being used.

	If you suspect that DCI is not enabled in your system, one 
	of two things could be wrong.  
	First, verify the installation was successful(see section II).
	Then if all files are present, check that your provider 
	indeed supports your installed graphics card.

		
IV. HOW TO RUN THE TESTS

A.  How to run TMCIAVI

TMCIAVI.EXE uses MCI strings to manipulate and play *.AVI files.  
This is a good test for DCI providers to ensure that the providers 
function correctly with the Universal Draw Handler under the Video 
for Windows environment.TMCIAVI.EXE exercises the installed DCI 
provider and MSVIDEO.DLL or the UDH.DLL.
		
To run TMCIAVI.EXE, set up a directory with *.AVI files that you wish
to use during test.

0 - Make sure the DCI client and/or DCI provider that you wish to 
	test are correctly installed in your machine.
		
1 - Bring up TMCIAVI.EXE, at the "Element Ext" entry, enter 
	the *.AVI path you set up and the name of an AVI file 
	you wish to use.

2 - Note down the "Random Seed" entry.  You will need this if
	you wish to repeat the exact test in a later time.

3 - Check the "Random" checkbox in the Flags list box.  
	Hit the "OK" button.

4 - Under the Tests option, choose "Set Input/Output Paths..."  
	Enter the path that contains your AVI files.
	At the "Resource/Input Path" edit box.  Enter
	a path name for "Output Path."  Hit the "OK" button.
		
5 - Under the Options menu, choose the "Set Logging" option and
	enter a path and file name for the log file.  Make sure
	you use "Terse" as the level of log.  Hit the "OK" button.

6 - Under the Tests menu, choose the "Select Tests" option and 
	choose the "Add All Cases" option.  Hit the "OK" button.

7 - Under the Tests menu, choose the "Run Tests" option and testing
	shall begin.

8 - Watch the screen for misplaced draws and any other errors during
	testing.

9 - The length of the test depends on the number of .AVI files in
	the path you chose, as well as the length of the .AVI files 
	used for testing.  This test can take anywhere from an hour 
	to a few days.
	The first time you use this test, it is best to try it with 
	a directory with only one .AVI file.

10 - To stop TMCIAVI.EXE during a test, hit Ctrl-Break and then 
	the ESC key.  If that does not stop the test, you may be 
	running a test that cannot be stopped, in which case, 
	either wait until the test is complete or press 
	ctrl-alt-del to force your way out.

11 - Once the test is complete, the logging information is stored
	in the file you specified in step #5 above.  In addition, this
	information is also displayed in the TMCIAVI.EXE client area.   

12 - Should you find a failure and wish to reproduce it, make sure
	you use the exact Random Seed that was used when the failure 
	occurred.
	This Random Seed should appear at the beginning of the test 
	case in the log file.  Note down the failed test case.  
	To reproduce it, follow the above steps, with the exception 
	of using only the failed test case during the Select Tests 
	step, instead of running all test cases again.
	Also enter the random seed from the log file.

B.  How to run TDCITEST

TDCITEST.EXE is essentially a DCI Client that uses various DCI 
calls and callbacks to exercise the DCI provider under test.  
TDCITEST focuses on the DCI provider's primary and offscreen 
services.  TDCITEST is especially effective in validating the 
error handling capabilities of a DCI provider.  
While a DCI provider is expected to remain simple, it is also 
expected that a DCI provider be able to handle error conditions 
gracefully.  
During testing, TDCITEST acts as a misbehaving DCI client, 
and exercises the various error handling capabilities in 
the provider under test.

TDCITEST uses the accompanying LOADBMP.DLL to perform color 
conversion and drawing to the screen.  
LOADBMP.DLL supports the following color formats:  

RGB 8, RGB 16 - 555 and 565, RGB 24, YUY2, YVYU, UYVY,
VYUY, Y211 and Y411

At the time of this release, only RGB 8 and RGB 16 formats 
have been verified to be working due to limited availability 
of DCI providers.  If your provider supports color formats 
other than those listed above, the accompanying LOADBMP.DOC 
describes the interfaces necessary to create a .DLL similar 
to LOADBMP so that you may use TDCITEST to test your 
DCI provider.

Please pay attention to the following:

1 - Ensure you have a clean environment before you run 
	TDCITEST and exit out of Windows after you are done 
	with TDCITEST, before running anything else.

3 - During testing, pay attention to failures that are caused 
	by the DCI provider. While TDCITEST is capable of 
	handling errors returned by the DCI provider, any error 
	returned by the provider would result in a failure status 
	in TDCITEST.

4 - If you are using LOADBMP.DLL and your provider does not 
	support one of the above color formats, please provide 
	your own LOADBMP.DLL before running TDCITEST.

5 - During testing, please do not resize or clip the test windows.

6 - If you have DBWIN invoked, please make sure the "Always On Top" 
	option is NOT selected.

To run TDCITEST, 

0 - Bring up DBWIN.EXE and resize it to a small window.

1 - Bring up TDCITEST.EXE, under the Options menu, choose the
	"Set Logging" option and enter a path and file name 
	for the log file.  Make sure you use "Terse" as the 
	level of log.  Hit the "OK" button.

2 - Under the Tests menu, choose the "Select Tests" option and 
	choose the "Add All Cases" option.  Hit the "OK" button.

3 - Under the Tests menu, choose the "Run Tests" option and testing
	shall begin.

4 - The test takes approximately 20 minutes to complete.  
	While most of the test are automated, you must watch 
	the screen for misplaced draws and any other error 
	during testing.

5 - If you must stop TDCITEST during a test, hit the ESC
	key.  If that does not stop the test, you may be running 
	a test that cannot be stopped, in which case, either wait 
	until the test is complete or press ctrl-alt-del to 
	force your way out.

6 - Once the test is complete, the logging information is stored
	in the file you specified in step #1 above.  In addition, this
	information is also displayed in the TDCITEST.EXE client area.          

7 - Should you find a failure and wish to reproduce it, make sure
	you use the exact Random Seed that was used when the failure 
	occurred.
	This Random Seed should appear at the beginning of the test 
	case in the log file.  Note down the failed test case.  
	To reproduce it, follow the above steps, with the exception 
	of using only the failed test case during the Select Tests 
	step, instead of running all test cases again.  
	Under the "Parameters" option, manually enter in the 
	Random Seed before reproducing the error.

		
V. RELEASE NOTES

	UDH will refuse to draw after receiving a return code from 
	SetClipList() which is not DCI_OK.  
	This also applies to the SetDestination() callback.    
    
	UDH will not support a codec that does not support the 
	ICM_DECOMPRESS_SET_PALETTE message when the surface is a 
	palettized surface.

	The MSVIDEO.DLL in this release will give priority to the 
	UDH; i.e., if the DCI provider supports both primary and 
	offscreen surfaces and the UDH is installed, then the UDH 
	will be used for playback.  As a result, to test a primary 
	surface, it is necessary to comment out the VIDS.DRAW 
	entry to allow drawing to default to MSVIDEO if the DCI 
	provider supports both a primary as well as offscreen 
	surfaces.

	Currently, if the UDH detects more than one offscreen 
	surface, it will decide which surface to use by running a 
	quick profiling test. During profiling, a set of test images 
	are encoded using the codec that will be used to play the 
	opened movie.  As a result, if the codec does not support 
	encoding, no profiling will be done and the first offscreen 
	surface returned by the DCI provider will be used 
	for playback.  

VI. DCISAMP.DRV

DCISAMP.DRV is a sample DCI Provider that supports the ATI 
Mach32 graphics chip.

DCISAMP.DRV will provide Primary surface access for RGB 8 
and RGB 16 (555 & 565) bitdepths.  In addition, DCISAMP also 
provides two OffScreen surfaces.  If the display is in RGB 8 
bits per pixel mode, DCISAMP will allow creation of an RGB 8bpp 
surface that simulates arbitrary stretching hardware by performing 
stretching on the host.  If the display is in RGB 16 bits per 
pixel mode, DCISAMP will allow the creation of an OffScreen surface 
of FOURCC type IF09.  This surface is not provided for purposes of 
display.  It is provided to utilize the CONVERT.ASM routine 
described below.

The DEVKIT\SAMPLE directory also contains a file called 
CONVERT.ASM which is supplied to aid Provider writers to support 
the Indeo Video intermediate format, IF09.  The file contains a 
routine which will convert an IF09 bitmap into a YUY2 bitmap.  
IF09 is the only YUV format supported by the IR32.DLL contained 
in this kit.  
	
The goal is for providers which support YUV through Offscreen surfaces
to support IF09 and perform any necessary conversion at Draw callback
time.  Since All Indeo Video codecs will support IF09, a Provider that
supports IF09 will accelerate all Indeo bitstreams.  The supplied 
routine can be easily modified to support all byte orderings of 
YUV 4:2:2 and YUV 4:1:1, or any other YUV format.
	
VII.  DCISVGA.DRV

DCISVGA.DRV provides basic DCI primary surface support for several 
popular SVGA graphics chips/cards.  The following graphics 
chips/cards are supported by DCISVGA.DRV:
	
		TSENG ET4000
		Video Seven HT208, HT209
		Video Seven VRAM
		Cirrus GD5424, GD5426, GD5428
		ATI Wonder
		Western Digital 90C30, 90C31
		S3 86C801
		ATI 68800
		older cards from Oak, and Trident 
				
If you have one of the above graphics chips/cards, you may try 
using DCISVGA.DRV as the DCI primary surface provider.  

If you do not have one of the above graphics chips/cards, please 
do not use DCISVGA.DRV; instead, please contact your graphics 
vendor for a DCI provider that is appropriate to your chip/card.


VIII.   How to modify VfW SETUP program to install your DCI provider

The Video for Windows 1.1D runtime, provides primary DCI support, 
through MSVIDEO.DLL, DVA.386 and DCISVGA.DRV.
To modify the VfW SETUP program you will have to edit the SETUP.INF 
file to copy UDH.DLL, DCIMAN.DLL and your DCI provider to the 
\WINDOWS\SYSTEM directory.
If you need space,to fit all your files in one floppy, you can 
remove the DCISVGA.DRV file from the INF list and from the disk.
	
In addition, SETUP should add the following line to the [Drivers] 
section of your SYSTEM.INI:

		VIDS.DRAW=udh.dll

and to install your own provider, follow the same procedure:

		DCI=<path>\<driver name>


IX. How to Override UDH profiling information

To override the surface the UDH has selected through profiling, 
do the following:
	
1 - Select the offscreen surface you wish to use by browsing
	through the recorded surfaces in DCI.INI

2 - Enter the chosen surface, in the exact format recorded
	in the DCI.INI file at the following entry in the
	[DCIOverrides] section:

	IWant=<the surface you wish to use>

If you are using a codec where it is not possible to obtain the format
information, please type it in in the exact order shown below:

<dwDCICaps>, <dwCompression>, <mask[0]>, <mask[1]>, <mask[2]>, 
<dwBitCount>

If dwBitCount is 8, use the format below:

<dwDCICaps>, <dwCompression>, <dwBitCount>

The values must be in DWORDs and they must be identical to the values 
in one of the DCISURFACEINFOs obtained during the DCIEnum call.  
These values are subsequently used to make a 
DCICreateOffscreenSurface() call in order to create the 
offscreen surface desired.
 
IX.  How to report problems.
To report anomalies, drop off feedback, please send e-mail to

DCI-IHV@microsoft.com   and   DCI-IHV@ibeam.intel.com