============================================================================
Jaguar Developer Weekly          August 4, 1995                  Vol.1, No.7
============================================================================

New BBS Number
--------------
The new Atari Software Development BBS phone line is now active.  The new
number is (408) 541-9164, and the old phone number is longer be active.  The
new line does not go through the rest of Atari's phone system, so it should
be more reliable for those callers who have had noise-related connection
problems in the past.



Don't Use More Than 1 File Per Track With Jaguar CD Emulator
------------------------------------------------------------
It is highly recommended that you specify only one file per CD track when
using the Jaguar CD Emulator program on the Falcon030 computer.  This file
should be exactly the same as what would be used when you actually master a
CD, complete with track header and tailer, and 64-byte sync markers (a unique
4 byte pattern repeated 16 times) in front of each distinct piece of data.

The emulator allows multiple files per track, but this causes certain
differences in behaviour compared with an actual CD.  These differences are
unavoidable, and can cause major problems when you later try to master a real
CD.  Using just one file per track means that the behaviour of the emulator
will be as close as possible to a real CD.

The emulator reads data from the hard disk at the same time as it sends data
to the Jaguar.  It reads one cluster at a time (16384 bytes) and sends the
data to the Jaguar.  When it gets to the end of one file, it doesn't have
enough time to start reading from the next one.  It must send the data on
time or it will cause an error in the I2S connection to the Jaguar.  To avoid
this, it sends zeroes until it can start reading the next file.  The result
is that file sizes get rounded up to multiples of 16384 bytes.  This doesn't
happen when you combine files together into a raw track file to master a CD,
and this is where things go wrong.

Suppose you have a track with 10 files that are 2000 bytes each, including
the required 64-byte sync pattern.  Normally when you create a track file for
CD mastering, you'll end up with 20000 bytes of data, plus 192 bytes for the
track header and tailer, for a total of 20192 bytes for the entire track
file.  Your program can easily read this in one step and then locate each
chunk of data once everything is in memory, which is going to be much more
efficient than loading each piece of data individually.

With the emulator, because each file's length is going to be rounded up to
16384 bytes, it will be necessary to read 196608 bytes of information to get
all the data in one step (10 data files, plus the files for the track header
and tailer).  And only about 11% of the data is actually used for anything.

Obviously if your track lengths are so dramatically different, the position
of the data from each file is going to be quite different as well.  This will
almost certainly break something in your program.

In order to support multiple files in a track, the emulator essentially
forces you to read each file's data individually, using the file position
specified in the header file created by the emulator.  (The padding is taken
into account when the emulator creates the header.) This allows you to ignore
the extra padding, but it is quite inefficient when reading many small chunks
of data.  Also, when you later create a real CD, the time codes given in
header file will no longer be correct (unless you duplicate the emulator's
padding when you create your track file for the mastering process).  The end
result is, you'll end up with your data in dramatically diffferent places on
the CD, and your program won't work.

The solution to all of these problems is to use only one file per track in
the first place.  Then the emulator will not have to worry about padding the
end of each file.  It is perhaps unfortunate that the emulator supports
multiple files per track in the first place, and we may change this in the
future.

The one file used for each track should be ready for CD mastering.  This way,
the difference between reading the data from the emulator or from a real CD
will be negligable.  Furthermore, when you are ready to master a CD, you
won't have to do anything additional to prepare the files.

The only drawback is that you have to manually calculate the time code of
each piece of data in the final track file.  Fortunately, this is not
difficult, as you can get the block offset by:

Block = int(data offset in bytes / 2352)

Once you have the block offset, this can easily be converted into a time
code.



Multiple Sessions on Jaguar CD
------------------------------
The ideal Jaguar CD has a total of two sessions.  Session #0 contains only
standard Red Book audio tracks.  Session #1 contains your boot track as well
as all your other code and data files.

Using additional sessions may be useful at times during the development
process, but serves no real purpose on a production disc.  Using more
sessions also increases the time needed to master the disc, as well as the
time it takes to start up and go through the encryption verification process
on an end-user's system.



Minimum Jaguar CD Track Size
----------------------------
When creating a Jaguar CD master, be aware that there is a minimum track size
of one megabyte imposed by the final encryption and re-mastering process done
by Atari.  In most cases, this will not be a problem, but if you are very
close to filling the disc completely, this may have an impact.  Remember to
always use a minimum of one megabyte per track when calculating disc usage.
Also remember that Atari will need space for a track containing encryption
information and at least one short audio track.



CD BIOS Notes
-------------
The CD BIOS documentation says the CD_read function returns an error code in
the err_flag variable.  This is not correct.  You do not get an error code
until you've called the CD_ptr function.  Also, the register usage shown is
not correct.  The CD_read function uses registers A0, A2, and D1.

When an error value appears in register A1 after a CD_ptr call, you should
check that the address in A0 is equal to or greater than the buffer start
address given in the last CD_read.  If not, a CD_ack should be issued prior
to any other CD BIOS call.  Also note also that the CD_ptr function sets the
high bit of register A0 when a seek error occurs.  This is not mentioned in
the documentation.

The CD_mode function will return an error condition in err_flag.  CD BIOS
versions 4.04 and below, however, always mistakenly report an error
condition.  This has been corrected for future releases of the BIOS.



Undefined Symbols In Madmac Expressions
---------------------------------------
There are certain limitations on using undefined symbol names in expressions
that do not generate warnings or error messages at assembly time, and which
aren't clearly defined in older versions of the Madmac documentation.  The
following text is a recent addition to the Expressions section:

Externally defined symbol names cannot be used in mathematical expressions.
If you do this, you will get unpredictable results.  This is true even if the
symbol is declared as being external using the .GLOBL or .EXTERN directives.
For example, if external_symbol is not defined within the same file, then
example 1 below will work, but examples 2 and 3 will not:

1) move.l	#external_symbol,a0
2) move.l	#external_symbol-2000,a0
3) move.l	#external_symbol-local_symbol,a0

The reason this does not work is that these types of expressions would
require a variety of different operations to be performed at link time in
order for them to be properly resolved, and the relocation method used by
MADMAC and the ALN linker does not currently support this.



Christmas is coming...
----------------------
Developers and publishers should keep in mind that all cartridge-based
products must be fully-tested and released into production by October 5, and
CD-based products by October 31, in order to insure that your product is
shipping in time for the Thanksgiving sales weekend, the beginning of the
Christmas selling season.  Remember to allow at least 4 weeks for final
testing.



New JAZ Synthesizer Demo Now Available
--------------------------------------
Now available online is a demo of the upcoming JAZ Music system for the
Jaguar.  JAZ is a completely updated version of the Jaguar Synth & Music
Driver that features much higher quality and greater capabilities.  JAZ will
also feature a completely new set of tools as well.  This demo gives you a
chance to hear for yourself the kind of quality audio you'll be able to
attain using JAZ when it is released in the near future.  Download the file
JAZDEMO.ZIP and make sure you have good speakers connected to your Jaguar!



Jaguar Tool Updates
-------------------
The Jaguar Developers Kit tools and related files listed below have been
updated in the last month.  You can download the latest versions from the
Atari Software Development BBS or from the Jaguar Developer library in the
Atari Gaming forum on Compuserve.

Jaguar Artwork Viewer  August 4, 1995.  This new version adds the ability to
control your horizontal resolution, and has improved communications
reliability.  Download ARTWORK.ZIP

Flash ROM Utility  July 27, 1995.  You can now hit Control-C to abort a
download and return to the DOS prompt.  Download UTILPC.ZIP.

Jaguar Graphics Tool  July 24, 1995.  Several minor bugs reported by Jaguar
Developers have been fixed.  Download ARTWORK.ZIP.

Jaguar NVRAM Simulator  July 21, 1995.  The NVRAM simulator uses the Alpine
board to emulate the Jaguar Memory Track cartridge, an add-on for the Jaguar
CD that allows CD game titles to save their user options, high score lists,
saved-games, and other information.  The archive has been updated with
additional documentation.  Download JAGLIB.ZIP for the complete package.



Dev Kit Roadmap
---------------
The tools, sample source code, libraries, and other components of the Jaguar
Developers Kit are updated frequently.  To keep track of what's new, see the
file ROADMAP.TXT that is posted online on the Atari Software Development BBS
and in the Jaguar Developer library in the Atari Gaming forum on Compuserve.
This file is updated and reposted whenever any of the standard distribution
archives from the Jaguar Developer's kit is updated.



If you've missed previous issues...
-----------------------------------
Then it's possible that we may not have a current fax number for you.  Just
in case, please contact us with your current address, telephone and fax
numbers.  Also, consider that the better solution would be to subscribe to
the Jaguar Developer Weekly Via EMAIL.

The preferred method for Atari to send out the Jaguar Developer Weekly is via
EMAIL, but unfortunately, we don't have a database of everybody's EMAIL
addresses.  If you have a current Internet or Compuserve EMAIL address,
please send a message to mfulton@atari.com so that we can add you to the list
of developers that receive the Jaguar Developer Weekly via EMAIL instead of
fax.

What you get each week will be the ASCII text of the issue, plus an online
readable version.

