-------------------------------------
JagPeg Conversion Tools version 1.5
PC Version Release 1.2
Release Date: 9/24/94

CONFIDENTIAL INFORMATION
-------------------------------------

Copyright 1993 Atari Corp. All Rights Reserved.
Author: Mike Pooler, Atari Corp.
Update: Mike Fulton, Atari Corp.

Introduction
------------

This describes how to use TGAJAG, a group of utility programs that convert a
Targa file (.TGA) to a JagPeg file (.JAG).

Background: JagPeg is Atari's version of JPEG.  A JagPeg file has a .JAG
extension, and it contains one compressed 24-bit true color bitmap.  It is
uncompressed by a program called DEJAG, which runs in the Jaguar's GPU.
DEJAG is described seperatly (see DEJAG.DOC).

The main utility for performing the conversion process is named TGAJAG.  On
MS-DOS, TGAJAG is an executable program named TGAJAG.EXE.


Input Files
-----------

TGAJAG takes the filename of a Targa file as its first argument.  The Targa
file must be:

- Uncompressed (Image type 2)

- 24-bits per pixel

- A multiple of 8 pixels in width
  (If HALF or QUAD subsampling, a multiple of 16 pixels in width)
  (Subsampling is explained below)

- A multiple of 8 pixels in height
  (If QUAD subsampling, a multiple of 16 pixels in height)

Some Targa files which meet the above requirements are stored from bottom-up,
(with the first screen-line at the end of the file), others from top-down.
Both types are supported by TGAJAG.



Output Files
------------

TGAJAG writes two files as output.  The first is a JagPeg file (.JAG), which
has this format:

[Word 0]  JagPeg version number (currently 1)

[Word 1]  Picture format code

	    1: YCrCb with no subsampling
            2: YCrCb with HALF subsampling
            3: YCrCb with QUAD subsampling

[Word 2]  Width in 8-pixel blocks (e.g. 40 == 320 pixels)

[Word 3]  Height in 8-pixel blocks

[Data...]

The second output file from TGAJAG is a file containing a dequantization table
for the requested compression quality, which is required by the JPEG decoding
routines.  This file will named 'DQ??.DAT' (where the ?? is the quality
percentage).



Using TGAJAG
------------

TGAJAG for MSDOS takes a command line of the form:

   TGAJAG [-quality n] [-quiet] [-o outputfile] [-quad | -half] inputfile

The command line options may be used in any order, but only one input file
may be specified, or else an error is generated.

-quality n      Sets the JPEG compression quality/compression ratio percentage.
                The value 'n' must be between 1-100.  The higher the value,
                the higher the image quality and the less the image is
		compressed.

-quiet          Supresses status messages from being shown on screen during
                the conversion process.

-o outputfile   Allows you to specify the desired filename of the converted
                picture file that will be output.

-quad or -half  Specify either QUAD or HALF subsampling.  The default is to
                use neither QUAD or HALF subsampling.  See below for more
		information.

inputfile       This parameter is the filename of the .TGA Targa picture file
		to be converted.  You may leave off the ".TGA" extension if
		you want.  The resulting .JAG file will be placed into the
		same directory as the inputfile, but the DQ??.DAT file will
		be placed into the current directory.

Examples:

   tgajag -quality 60 cat

will convert CAT.TGA to CAT.JAG with quality setting of 60.


   tgajag -half -quality 75 ship

will convert SHIP.TGA to SHIP.JAG, using HALF subsampling, and a quality
setting of 75.




Image Quality
-------------

For most purposes, an image quality setting between 60 and 80 will provide
the best balance between compression ratio and quality.  High quality
settings give less lossy compression, thus larger .JAG file sizes.  Lower
numbers get you better compression and smaller files, but if the number is
too low you will get a visable degradation in visual quality (this will
appear as fuzzyness and/or blockiness).

The goal is to find a quality setting that gives you acceptable compression
and a picture that is is nearly indistinguishable from the original .TGA,
visually.  This "ideal" setting is different for different pictures, so it's
a matter of trial and error.

The default quality setting is 75, which is usually a good starting point.
If you go much above 75 you lose more and more compression without a
significant gain in image quality.

TGAJAG produces a unique "dequantize" table for each quality setting, which
is used during the decompression process (see DEJAG.DOC).



SUBSAMPLING
-----------

You also have the option of using HALF subsampling or QUAD subsampling.

HALF subsampling means that the picture's color components are cut to half
their horizontal size before processing by CJPEG.  (The luminance component
is left as is).  While this is quite lossy, it often produces little visable
change in the final output, while getting a good reduction in size.  We
recommend that you use HALF subsampling as your default starting point.

QUAD subsampling means that the picture's color components are cut to one
quarter the original size (half vertical, half horizontal) before processing.
Size reductions over HALF are less dramatic, visual differences are more
dramatic.  It may be worth a try, but we recommend HALF as your best option.

Remember if you use HALF or QUAD, picture width must be a multiple of 16
pixels (instead of 8).  If you use QUAD, picture height must be a mulitple of
16 pixels.

Decompression speed is DIRECTLY related to .JAG size.  A .JAG file that is
30% smaller than another will usually decompress in about 30% less time.




Notes
-----

Free disk space requirements for TGAJAG are such that you should have at
least double the size of your TGA file, to be safe, before running TGAJAG
(e.g.  for a 200K TGA file, have 400K free).

Note that the utilities do not all detect disk-full conditions, and they will
probably do a whole lot of nothing once disk space runs out (even if they
look like they're working).

If the final JAG file is larger than you expect, try using HALF subsampling
and/or a lower quality setting.

There is little error checking - if you feed it an illegal Targa picture (see
above), or a bad filename, it may do ungraceful things.


v1.2 Release Notes:
-------------------

The MSDOS version formerly used the batch files TGAJAG.BAT, TGAJAGH.BAT, and
TGAJAGQ.BAT to run the various steps of the conversion process.  They have
been replaced by TGAJAG.EXE, which performs the same operation, but with
better control over the various options and with better error checking.

Note also that the archive setup has been changed so that the tools install
into the JAGUAR\BIN directory instead of JAGUAR\BIN\TGAJAG.  This was done so
that you can call the conversion utilities directly from your project's
directory, rather than changing to the utilities directory.  Please note that
the JAGUAR\BIN\TGAJAG directory is no longer used by the archives at all.

To avoid filename conflicts with other utilities, the filenames of the JAGPEG
compression utilities have been changed.  Basically, a "j" was added to the
beginning of the filename.  The old names and new names are shown below.

Old Name  New Name
--------  --------
STRIP     JSTRIP
QUAD      JQUAD
MERGE     JMERGE
MERGEH    JMERGEH
MERGEQ    JMERGEQ
SPLIT     JSPLIT
SPLITH    JSPLITH
SPLITQ    JSPLITQ
MAKEQ     JMAKEQ
CJPEG     JCJPEG

Normally you don't call these programs yourself directly; they are called by
the TGAJAG program.  If you have old versions of these files, please delete
them.


v1.1 Release Notes:
-------------------
Earlier versions of the PC version of the MAKEQ tool (one of the utilities
called by TGAJAG) did not work correctly, but this has now been fixed.

Earlier versions of the TGAJAG tools used an .ABS extension for the DQ??.ABS
files they created.  This has been changed to create a DQ??.DAT file instead,
to avoid confusion with the .ABS files created by the ALN linker.

