***************************************************************************
           3D RAGE PRO Windows 95 4.1 Software Development Kit
      Copyright (c) 1997 ATI Technologies Inc.  All rights reserved.
***************************************************************************

ATI Technologies Inc.
33 Commerce Valley Drive East
Thornhill, Ontario
Canada L3T 7N6

Developer Relations .................... (905) 882-2600 ext. 6000
Engineering/Developer Relations FAX .... (905) 882-9339
Email: devrel@atitech.ca

Preliminary
-----------
This is the version 4.1 release of the ATI 3D RAGE PRO SDK. This is the first 
official release version of the 3D RAGE SDK that has support for the production
part of the 3D RAGE PRO graphics processor.  This SDK is specifically for the 
3D RAGE PRO, and the sample programs included will not operate correctly on 
previous 3D RAGE based graphics cards.

Here are the major changes for this revision of the SDK:

-addition of the Cut and Paste examples
-specular highlights example


1.0 Introduction
----------------
Welcome to the ATI 3D RAGE PRO Windows 95 Software Development Kit (RAGESDK). 
This SDK demonstrates how to use the ATI3DCIF (ATI 3D C InterFace) to 
accelerate 3D rendering operations using the ATI 3D RAGE PRO graphics 
processor. The RAGESDK provides a programmer's guide in Adobe Acrobat PDF 
format, sample source code in C/C++, ATI3DCIF header files and libraries, and 
on-line help documentation. 

ATI3DCIF is designed as a proprietary interface for using 3D RAGE acceleration.
ATI3DCIF is able to incrementally expose the evolving features of the 3D RAGE 
graphics processors, while remaining backwards compatible.  We also support
the same features under Direct3D, as they become available.  Some developers
prefer using chip specific APIs to be "closer" to the hardware, and also so they
do not rely on some of the operating systems dependencies of DirectX.

The example programs use DirectDraw. At the time of this release, the RAGESDK 
has been tested against the official release of the Microsoft DirectX 5 SDK 
(this will be referred to as DirectX SDK in the rest of this document). To 
rebuild the sample programs in the RAGESDK, the DirectX SDK must be installed 
on the target system. The runtime libraries for DirectX are included in the 
REDIST directory of the RAGESDK CD, and they can be installed by running 
DXSETUP.EXE from the REDIST\DIRECTX directory.  ATI enhanced drivers should 
be installed after the DirectX run-time binaries have been installed.

**************************************************************************
*                                                                        *
*  WARNING! - All sample programs in the RAGESDK\BIN directory REQUIRE   *
*             a 3D RAGE PRO based graphics adapter.  Running these       *
*             applications on other hardware will result in system       *
*             instability and possible lock ups.                         *
*                                                                        *
**************************************************************************


2.0 System Requirements
-----------------------
1. Pentium (or compatible) system
2. 32-bit PCI Local Bus 2.1
3. graphics board with ATI 3D RAGE PRO family graphics processor
4. Microsoft DirectX 5 SDK, beta 1 or newer.
5. Microsoft Visual C\C++ 4.2


3.0 3D RAGE SDK and Display Driver Installation
-----------------------------------------------
To install the 3D RAGE SDK, run INSTALL.EXE from the INSTALL directory on
the CD. INSTALL.EXE will guide you through the complete installation process.

By default, INSTALL.EXE will create the 3D RAGE SDK at C:\RAGESDK. The root 
drive and directory may be changed during installation. If the default is chosen, 
INSTALL.EXE will create the following directory tree on the target system:

C:\RAGESDK
 -BIN            - Contains sample executables, including ATIVQCON.EXE.
 -BMPETC         - Bitmaps and other files used in above examples
 -DOCS           - Contains RAGESDK.PDF programmer's guide document, and other
                   important reference documents.
 -HELP           - Contains 3D RAGE SDK help file
 -INC            - Contains ATI3DCIF.H
 -LIB            - Contains link library for ATI3DCIF.DLL
 -SAMPLES        - Sample program subdirectory
     -COMMON    - Utility source files for some examples
     -CUT_PAST  - 4 explosion examples in different 3D display modes
     -R3TEXCMP  - triangle renderstate program
     -RPROEX1   - Demonstrates texture compositing feature of the 3D RAGE PRO
     -RPROEX2   - example showing texture clamping
     -RPROEX3   - example demonstrating texture compositing with spinning cubes
     -RPROEX4   - another spinning cube, using a VQ texture
     -KNIGHT    - a version of the Knight demo which encompasses many features,
                  and two smaller demos showing compositing and VQ textures.
     -SPECULAR  - sample program demonstrating specular highlights on the RAGE PRO

**************************************************************************
*                                                                        *
*  WARNING! - All sample programs in the RAGESDK\BIN directory REQUIRE   *
*             a 3D RAGE PRO based graphics adapter.  Running these       *
*             applications on other hardware will result in system       *
*             instability and possible lock ups.                         *
*                                                                        *
**************************************************************************

To install DirectX 5 run-time binaries, run DXSETUP.EXE from the REDIST\DIRECTX 
directory of the CD. Follow the installation directions to completion.

To install the ATI enhanced drivers, right-click the mouse on the desktop
to bring up the pop-up menu. Select Properties. Click on the Settings tab.
Click the Change Display Type... button. Click on the Change.. button in the
Adapter Type box. When the Select Device dialog box appears, click on the 
Have Disk... button. When the Install From Disk dialog box appears, enter
the appropriate directory in the Copy manufacturer's files from: list box and
either press ENTER or click on the OK button. Select the appropriate driver 
from the Models: list box and click the OK button. The ATI enhanced display 
drivers will be loaded on your system. Reboot the system to activate the change 
in display drivers. The RAGESDK programs will not work untill the system has 
been rebooted and the ATI display drivers activated.


4.0 Building the sample applications
------------------------------------
To build the sample applications in Microsoft Visual C++ 4.2 Developer 
Studio, the DirectX SDK INC and LIB directories must be included in the
Visual C++ search path. To do this, look under Tools/Options... in the 
Developer Studio menu. Select the Directories tab and ensure that the DirectX 
INC directory is first in the Include files list and that the DirectX LIB 
directory is first in the Library files list.  MS Visual C++ 4.2 ships with 
older versions of the DirectX include and library files which may cause problems 
with applications designed for DirectX 5.

To open the makefile associated with each example, select 
File/Open Workspace... in the Developer Studio menu.  Select Files of type
"Makefiles (*.mak)" and open the appropriate make file.  Developer Studio
will reconstruct the necessary .MDP and .NCB workspace files as required.

The batch file MAKEALL.BAT is included in the SAMPLES directory.  This batch
file allows you to build all of the examples from the command prompt.  For
this batch file to work, the following is necessary:

- The search path must include the Visual C++ BIN directory
- The INCLUDE= environment variable must include both the Visual C++ include
  and the DirectX SDK include directories
- The LIB= environment variable must include both the Visual C++ library
  and the DirectX SDK library directory


5.0 3D RAGE PRO SDK Example Applications
----------------------------------------

**********************************************************************
**                                                                  **
** THE FOLLOWING EXAMPLES ARE FOR 3D RAGE PRO EQUIPPED SYSTEMS ONLY **
**                                                                  **
**********************************************************************
ATIVQCON:
---------
This sample application converts 24bpp .bmp files into VQ textures.  You can
then used the compressed textures (8 to 1 compression) in your app with the 
3D RAGE PRO, which decompresses the textures on the fly.

EXPLOSION 1555:
---------------
This example displays a sequence of seven 16-bit alpha blended texture
maps. It shows how to display a 2D texture map on a 3D primitive (this 
is important for converting legacy code which handles only 3D
acceleration).

EXPLOSION 1555 windowed:
------------------------
This example displays a sequence of seven 16-bit alpha blended texture
maps in a window. It shows how to display a 2D texture map on a 3D
primitive (this is important for converting legacy code which handles
only 3D acceleration).

EXPLOSION 8888 windowed:
------------------------
This example displays a sequence of seven 32-bit alpha blended texture
maps in a window. It shows how to display a 2D texture map on a 3D
primitive (this is important for converting legacy code which handles
only 3D acceleration).

EXPLOSION 4444 windowed:
------------------------
This example displays a sequence of seven 16-bit alpha blended texture
maps in a window. It shows how to display a 2D texture map on a 3D
primitive (this is important for converting legacy code which handles
only 3D acceleration).

KNIGHT DEMO:
------------
The ATI Knight demo used at trade shows.  Many of the cool effects available on 
the 3D RAGE PRO are demonstrated by this program.

KNIGHT MORPH:
-------------
The Knight from the previous demo is featured, showing texture compositing from 
stone to "living" textures.

KNIGHT VQ:
----------
The Dragon from the Knight demo is shown in a split screen, one side using 
RGB1555 textures, the other using VQ textures.  This is meant to show the 
difference between VQ (compressed) and RGB (uncompressed) textures.

R3TEXCMP:
---------
This example shows the effects of various renderstates on a simple triangle.  You 
can toggle various menu options to see the effects on the triangle, and you can 
double click on the triangle to change the triangle co-ordinates.

RPROEX1:
--------
This example demonstrates texture compositing, including the setting of the 
necessary renderstates and levels.

RPROEX2:
--------
This example demonstrates the texture clamping features of the 3D RAGE PRO.  The 
example shows texture clamping along the combination of the S and T axes.

RPROEX3:
--------
A spinning cube that demonstrates texture compositing.

RPROEX4:
--------
The same as RPROEX3, but the cube has a VQ texture applied.

SPECULAR:
---------
This example displays a red and blue textured triangle on a black
background. White specular color is set for the lower left vertex on the
triangle. Vertex descriptions use the newly implemented C3D_TLVERTEX
vertex type.


6.0 Bitmap and Data Files
-------------------------
The BMPETC subdirectory contains bitmap and other data files used by many of the 
examples. The example executables expect to find these files in this 
subdirectory. Therefore, ensure that the relative path between BIN and BMPETC
is maintained if the executables are moved to a different directory.


----------------------------------------------------------------------------
Windows is a registered trademark of Microsoft in the U.S. and other
countries.
