*************************
*** DirectDraw Notes ***
*************************

Last updated  July 23, 1995

Topics
======
- Multiple Applications
- Drivers 
- Low Res Modes
- Exclusive Mode Changes
- Changes to All Create Functions
- CreateSurface Changes
- Known bugs/gotchas

=====================
Multiple Applications
=====================
DirectDraw will now support multiple applications.  You can switch away from
you DirectDraw application using the standard keys (alt-tab, ctrl-esc, 
alt-esc).   When you do this, your application will minimize itself on the
tray.   You can then select the game from the tray and it will restart.

Please pay careful attention to the DDERR_SURFACELOST message.   You can
receive this error whenever you flip, blt or lock a surface.   What this is
telling you is that a mode change has happened since the last time you
accessed the surface.   If a mode change happens, the video memory storage
is "lost".   You should call the Restore method on the surface to recover its
video memory, and you can reload the surface with its original data.

Also remember to pay attention to the WM_ACTIVATEAPP message.  This message
tells you if your application is being activated or deactivated.  When
your application is deactivated, you should not process your game loop.  Here
is a code snipit from the Fox & Bear sample:

from message loop:

    case WM_ACTIVATEAPP:
    	bIsActive = (BOOL) wParam;
    	break;
	
from main game loop:

    while( 1 )
    {
	if( !bIsActive || PeekMessage( &msg, NULL, 0, 0, PM_NOREMOVE ) )
	{
	    if( !GetMessage( &msg, NULL, 0, 0 ) )
	    {
		return msg.wParam;
	    }
	    TranslateMessage(&msg); 
	    DispatchMessage(&msg);
	}
	else
	{
	    ProcessFox(lastInput);
	}
    }
    
Note that the game blocks on a GetMessageCall whenever the game has been
deactivated.


=======
Drivers 
=======
We have included the Win95 drivers for:

ATIM32.DRV: 			ATI
ATIM64.DRV: 			ATI
CHIPS.DRV 			Chips & Technologies 
CIRRUS.DRV/CIRRUSMM.DRV:	Cirrus Logic 
S3.DRV: 			S3
TSENG.DRV: 			Tseng

We are just finishing up the FrameBuf, Matrox, Compaq QVision, and the 
Western Digital drivers.   They should be done in the next couple of weeks 
and will be available before the final release of the Game SDK.

=============
Low Res Modes
=============
We are introducing low res modes in this beta of the Game SDK.

640x400
320x200
320x240

We currently have 640x400 in all the drivers except the Mach32 driver.
320x200 and 320x240 is in the framebuf and Cirrus driver, and will be available 
in the other drivers in the next few weeks.   We will put updated drivers
on CIS as they are available.

======================
Exclusive Mode Changes
======================
SetExclusiveModeOwner has been changed to SetCooperativeLevel.

change from:

lpdd->lpVtbl->SetExclusiveModeOwner( lpdd, DDSEMO_FULLSCREEN, TRUE );

to:

lpdd->lpVtbl->SetCooperativeLevel( lpdd, hWnd, DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN );

SetCooperativeLevel is required to run a DirectDraw application.
Just follow your DirectDrawCreate call with a SetCooperativeLevel call.

SetCooperativeLevel mode requires a valid HWND.  DirectDraw uses this HWND to
handle various messages to control changing the mode when the user switches
to and from your application.   

DirectDraw reserves the GWL_USERDATA field in the HWND for its use; if you 
need per window data, you should add data to the class. 

If you do a SetCoopertativeLevel with DDSCL_EXCLUSIVE, then your HWND must
be a topmost window, created with CreateWindowEx:

    hwnd = CreateWindowEx( WS_EX_TOPMOST, ... )

In this release, you must declare that you are DDSCL_FULLSCREEN when 
you use DDSCL_EXCLUSIVE.

===============================
Changes to All Create Functions
===============================
DirectDrawCreate
CreateSurface
CreatePalette

These have xHave been modified to take a pointer to a controlling IUnknown 
as the last parameter.   This allows our objects to be aggregatable by other 
COM objects; you will normally set it to NULL.    Unless you are a real 
OLE 2/COM-head, this will not impact your life one iota.

=====================
CreateSurface Changes
=====================
CreateSurface has also been modified to be consistent with the rest of the
create functions.   Instead of the surface object being passed in the
DDSURFACEDESC structure, it is now a parameter... so code (using C++ notation)
goes from:

    ddrval = lpDD->CreateSurface( &ddsd );
    if( ddrval != DD_OK )
    {
	return initFail(hwnd);
    }

    lpDDSPrimary = ddsd.lpDDSurface;
    
To:
    ddrval = lpDD->CreateSurface( &ddsd, &lpDDSPrimary, NULL );
    if( ddrval != DD_OK )
    {
	return initFail(hwnd);
    }
    
In C Notation:

From:
    ddrval = lpDD->lpVtbl->CreateSurface( lpDD, &ddsd );
    if( ddrval != DD_OK )
    {
	return initFail(hwnd);
    }

    lpDDSPrimary = ddsd.lpDDSurface;
    
To:
    ddrval = lpDD->lpVtbl->CreateSurface( lpDD, &ddsd, &lpDDSPrimary, NULL );
    if( ddrval != DD_OK )
    {
	return initFail(hwnd);
    }
    
==================
Known Bugs/Gotchas
==================
1) BltBatch is not supported

2) Possible hang when starting a ddraw app from a full screen DOS box.

3) Emulation-only (non-DirectDraw drivers) isn't supported in < 8 or > 16bpp.

4) Changing bit depth can sometimes result in your display being washed out
   with an invalid color when you come back to Windows.
