------------------------------------------------------------------------------
                  IMPORTANT!!! PLEASE READ CAREFULLY!!!
                CONFIDENTIAL ATARI DEVELOPER INFORMATION
------------------------------------------------------------------------------

Atari Developer Support is in the process of improving the quality and
quantity of example programs and support software available for developers.
This archive represents the first phase in this process.

The revised examples in this archive are designed to be more consistent with
one another and to document the right way to initialize the system, video, and
object lists. In addition, some older Jaguar sample programs used methods
which have since been found to be unreliable under all circumstances.

We are taking several steps, to make the sample programs more reliable and to
improve them to the point that they are useful as models for developer code
as follows:

1. Improve the quality and consistency of JAGUAR.INC/JAGUAR.H and the rest of
   the include file library.
2. Ensure that all sample programs follow the same, reliable methods for
   initializing the Jaguar console, initializing video, and creating and
   maintaining an object list.
3. Recode the existing samples to be more robust and document them in print
   form as well as in source code comments.

This archive addresses items one and most of item two (explained later in
this document). Item three will be phased in over the next few months as new
examples become available and the old ones are reworked. You should check
Compuserve or the Atari Jaguar BBS for the latest availability information.

----------------------------------
- Include File Structure Changes -
----------------------------------
Several improvements have been made to JAGUAR.INC and JAGUAR.H (hereinafter
referred to as simply JAGUAR.INC) and the rest of the include file structure.
Please read this document carefully to find out how this affects your current
projects.

JAGUAR.INC is now the only system include file. All other system include files
(not including those used for tool interaction) have been either rolled into
JAGUAR.INC or removed from the distribution.

The following files are now a part of JAGUAR.INC (some changes may have been
made - see below):

		BLIT.INC
		DSP.INC
		GPU.INC
		JOYPAD.INC

The following files have been removed from the distribution entirely:

		DEFS.INC
		OBJLIST.INC
		VIDEO.INC

In addition, several new equates have been added to compensate for the loss
of the three files removed and to create standard names which correspond to
the Jaguar Software Reference Manual v2.3 (which will be available soon from
Atari).

Please note that the files listed above still exist in the current
distribution, however, they are included to prevent compiler errors only and
should not be included in any new code. Some old equates are also contained in
them surrounded by an IF/ENDIF that will only include the code if COMPAT is
defined as 1 (which it is in JAGUAR.INC). If you are writing any new code from
scratch or want to ensure your code is 'makeable' with all current
distributions of JAGUAR.INC you should change the line in JAGUAR.INC to 
'COMPAT   EQU  0'.

The file MACROS.INC remains as part of the distibution as a separate file and
the following tool files will still be included separately:

		DEJAG.INC
		FULSYN.INC		

--------------------------------------
- Detailed Changes and Justification -
--------------------------------------
JAGUAR.INC
Any equates for hardware locations that were marked DO NOT MODIFY - FOR
INFORMATION ONLY have been removed. For now there are no valid reasons to use
these registers.

BLIT.INC
This file was rolled into JAGUAR.INC verbatim with one exception. The equate
NOGO was removed. This equate was for Blitter diagnostic purposes only and
should be of no interest to developers.

GPU.INC/DSP.INC
Most of the functionality of these files now exist in JAGUAR.INC, however,
some equate names have changed. Many of these changes were due to the
similarities between Tom and Jerry. For instance GPUM3x1 is now MATRIX3. Even
though there was no corresponding DSP equate, both the GPU and DSP use the
same format MATRIX registers so the names were made common. Other equates
removed were those with non-descriptive names such as in the series as
follows:

G_INTEN0
.
.
G_INTCLR0
.
.

These were changed to more descriptive equates such as:

G_CPUENA
.
.
G_CPUCLR
.
.

JOYPAD.INC
This file was completely rolled into JAGUAR.INC

DEFS.INC
The only equate from this file to survive the new revision is LEVEL0
(68k Autovector). LEVEL0 is now present in JAGUAR.INC

OBJLIST.INC
This file was completely removed from the distribution because it was
designed for a rather weird and time-wasteful method of constructing/
maintaining an object list. A few equates which represented useful bits 
in objects were moved to JAGUAR.INC with new names such as O_TRANS.

Please note that some of our example code still uses the OBJLIST.INC
method. In these cases, a local copy of OBJLIST.INC has been moved to
the project's directory. All of these examples are being redesigned to
use a better object list constuction method.

VIDEO.INC
This file was completely removed because it was designed for a
frowned-upon method of setting up video. A new set of equates for video
initialization is now present in JAGUAR.INC and uses the VIDINIT.S model of
determining the video values by working off of the known center-point of the
screen. This method is useful on all screens and NTSC/PAL.

-------------------------
- Easing the Transition -
-------------------------
Changing to the new JAGUAR.INC file will be fairly simple for most cases.
Before overwriting your old include files we recommend making a backup. Next
you can attempt to make your project with the new include file structure to
see how much revision needs to be done. We have included files with the same
names as those deleted with nothing but blank comments. This saves you the
hassle of removing references like:

		.include		"blit.inc"

The next most likely culprit of problems will arise if your project uses the
not recommended method of initializing video and constructing object lists
(using equates from VIDEO.INC or OBJLIST.INC). You will need to assess what
additional work this might require.

Besides these transitions, only a handful of equates remain which need to be
changed. Depending on the size of your project you might redefine the old
equates in your local include file(s) as necessary.

--------------
- Worst Case -
--------------
If your current project(s) are dependent on the old includes and your project
is time-critical enough that this change might delay your project enough to
matter then we recommend placing these headers aside for compiling the sample
programs only (if needed) and then integrate them as soon as possible. This
should probably not be a problem in most cases.

Less than 15 minutes work should be required if your object list code isn't
affected by the missing OBJLIST.INC. If your object list code relies on this
and it would be too much work to change it you can stick the old OBJLIST.INC
in your include directory and ignore the warnings for the four or five
multiply defined symbols.

-------------
- Moving On -
-------------
You will also find a file called \DOCS\JAGTIPS.TXT in the current
distribution that lists the best methods for accomplishing some of the most
common Jaguar programming. In addition, they represent the root of many of
the technical support questions we receive.

---------------
- Reaching Us -
---------------
If you have specific questions regarding example code, the forthcoming Jaguar
Workshop Series, or the include file distribution please contact:

Scott Sanders
Jaguar Guru
(408) 745-2143
Compuserve: 70007,1135

Other members of our developer support group include:

Norman Kowalewski
Manager, Jaguar Developer Support
(408) 745-2127
Compuserve: 75300,3444

Mike Fulton
Manager, Jaguar Development Tools
(408) 745-8821
Compuserve: 75300,1141

Bill Rehbock
VP, Software Business Development
(408) 745-2082
Compuserve: 75300,1606

J. Patton
Director, Third-Party Licensing and Contracts
(408) 745-2135
Compuserve: 70007,1072
