/******************************************************************************
 * ATI 3D RAGE SDK sample code README file                                    *
 *                                                                            *
 * Copyright (c) 1997 ATI Technologies Inc. All rights reserved.              *
 *  																		  *
 * This is a work-in-progress. Currently only the following directories are	  *
 * available: EXPLOSN and UNCOMMEN. Check our website at www.atitech.ca	for	  *
 * updates.																	  *
 *																			  *
 ******************************************************************************/


This file applies to all sample code in this directory and subdirectories.



Purpose:
========
Purpose of the samples in this directory:
  
  (a) Provide tutorial material for developers who want a quick look at the  
	  general procedure to be followed to get an application up and running 
	  using the ATI3DCIF driver interface.

  (b) Provide tutorial material for developers who have never ported to a 
	  3D accelerator and who have never used a proprietary interface (such as 
	  ATI3DCIF), or a standard API (such as DirectX or OpenGL).
  
  (c) Provide easy to use, easy to understand and easy to combine cut and paste 
	  code snippets that can be used experimentally to determine:

		(1) appropriateness of a given feature 

		(2) difficulty of implementing a given feature

All the examples in a given directory will explore one or two features (e.g. 
alpha blending) in a variety of application formats. For example, the EXPLOSN 
directory contains sample applications that show the same explosion sequence 
but address the following issues:

	- windowed vs. full-screen
	- 2D vs. 3D
	- different pixel / texture formats

Developers can thus get a feel for which features interest them and how
to implement a specific feature in different ways.



Requirements:
=============
Except where noted, all applications require a 2MB RAGE PRO accelerator 
and DirectX 3.0 or later. Note, however, that the ATI3DCIF driver interface
does not require DirectDraw as it's surface manager. Any valid pointer to a
surface will be accepted. This allows use of other surface management layers.
All samples were created with Microsoft Visual C/C++ 4.2. This code has not
been tested with other compilers.



Sample Documentation:
=====================
Each sample's header comment includes:
  (a) General requirements
  (b) Requirements specific to that sample	(such as video mode dependencies)
  (c) Description of what the sample does
  (d) Specific features and functionality covered by the sample
  (e) General ATI3DCIF application overview

Each sample is heavily commented, but uncommented versions exist in the 
UNCOMMEN directory to facilitate cut-and-paste operations.
 


ANSI compatibility:
===================
In the interests of ANSI compatibility the traditional C file and memory 
manipulation functions were used. These include malloc, free, fopen, fread, 
fseek, fclose, memset, and memcpy. Feel free to Win95-ize them.



Coding style:
=============
The current code style was chosen for the following reasons:

Readability - the style is quite structured and therefore easy to understand;
it is also easy to use. In addition, error messages appear in the function 
in which the error can occur, so it is very easy to follow what the function 
should be doing.

Robustness - all deallocations and releases are executed explicitly, either
as soon as a failure occurs, or when no longer required by the application.
This eliminates the use of a single "on error, clean up and quit" function 
in which all possible deallocations/releases that can occur during the life
of the application are handled. Such deallocations are usually of the form
"if p is non-NULL then free p", and it is impossible to know whether p was 
freed 'accidently' or not, without stepping through the code with a debugger.
In other words, if allocations are handled explicitly instead of in one 
global function, use of the following becomes possible:

		if (p == NULL)						//strong error check
			ErrorMessage ("Bad Pointer");		
		else
			//release p
			
This is a much stronger validation check than:

		if (p) //release p 					//no error check

Size and maintainability - the samples are approximately 1/3 the size of 
the more traditional left justified format. Each failure is only handled 
once per function. This massively decreases both the code size and the 
likelihood of cut-and-paste errors.

Error messages - more error information is available to the developer
because errors propagate up the active call stack, generating messages 
as the functions they are called from fail.	This provides a chain of 
useful error messages showing the execution path from the point where 
the failure occurred.

In some functions, you will note a commented out deallocation or release
function with the comment "reminder for future expansion". This will appear
right after a 'return TRUE' statement. This is a reminder that the last 
function called performed an allocation of some kind, and that, if any code 
is added in the future, the commented out function call should be added back
in as the deallocator.

If you find that your functions are running off the right side of the page, 
yank the middle out and make a new function, the thing's probably too long 
anyway. (This doesn't apply to speed critical code, but speed critical code 
isn't likely to have a lot of if tests in it in any case).

The only exceptions to this style are WinMain and WndProc. The 
format promoted by Petzold and Microsoft for these standard Windows95 
functions was maintained.

Although RELEASE builds were tested for all samples, this code is for 
teaching purposes and, as such, it is recommended that it be built and 
executed in a DEBUG environment. 

Commentary and feedback on the style is strongly encouraged and may be
directed to devrel@atitech.ca.



Other notes:
============
Locking/unlocking surfaces:
The samples all unlock surfaces immediately after locking them (the lock is 
required to obtain a pointer (.lpSurface) with which to access the surface). 
This makes debugging surface writes possible. Although not currently 
implemented, it may one day be possible for DirectDraw to move your surfaces 
around in memory, so for production code that's going to be around for awhile 
it is suggested that you use the lock/write/unlock sequence formally endorsed 
by MicroSoft.

Blit/Flip/Surface Lost failures: 
For brevity, no error handling is provided in the samples for blit or flip 
failures or if a surface is lost. For most tutorial/example/cut-and-paste 
situations this should be acceptable. Production code, however, should 
handle all return codes from these functions appropriately.

Targa file loading:
The Targa file loader is not robust. It expects an uncompressed 32 bit (8888) 
Targa file; if you give it a bad file, most likely you'll get garbage or hang 
the system. (Incidentally, PhotoShop (or any similar paint program) does a 
nice job of creating alpha channels for 24-bit images from a variety of file 
formats and then saving them as 32 bit uncompressed Targa images.)
