*****************************************************************************

                              JXP version 2.01
                    Copyright + 1997-2000, Saxon Druce

                               saxon@saxon.cx

*****************************************************************************

Contents:

1. Introduction
2. Demo programmes
3. How to use the library
4. License agreement
5. Anticipated frequently asked questions
6. Acknowledgements
7. The end

*****************************************************************************
  1. Introduction
*****************************************************************************

JXP was originally a shortened version of the word 'JinxPEG', which was
a 'cutesy' amalgamation of the words 'JiNX' and 'JPEG'. This is because it
was originally JiNX's JPEG decoding library, with JiNX being the demo group
of which I am a member.

These days though JXP does a lot more that just decode JPEGs. So, JXP is just
3 letters used to refer to this library, and which don't mean much at all.

JXP is then a graphics library, including functions to decode JPEG files,
perform colour reduction and dithering, manipulate 'mask' files, load TGA
files, and perform resampling. This is generally just a mish-mash of things
which seemed useful at some point.

This distribution should include the files in the following list. If it
doesn't, something is missing.

readme.txt
JXPdemo.exe
TGA2MSK.exe
happy.jpg
jinx.msk
Source\JXP.dsw
Source\JXP\JXP.dsp
Source\JXP\JXP.cpp
Source\JXP\JXP.h
Source\JXP\JXP_Dither.cpp
Source\JXP\JXP_Dither.h
Source\JXP\JXP_JPEG.cpp
Source\JXP\JXP_JPEG.h
Source\JXP\JXP_Mask.cpp
Source\JXP\JXP_Mask.h
Source\JXP\JXP_Resample.cpp
Source\JXP\JXP_Resample.h
Source\JXP\JXP_Targa.cpp
Source\JXP\JXP_Targa.h
Source\JXPdemo\JXPdemo.dsp
Source\JXPdemo\JXPdemo.cpp
Source\TGA2MSK\TGA2MSK.dsp
Source\TGA2MSK\TGA2MSK.cpp

- readme.txt is the file you are reading now.
- JXPdemo.exe is a demo programme of the JXP library's capabilities, and
  TGA2MSK.exe is a utility.
- happy.jpg and jinx.msk are example files to use with JXPdemo.exe.
- The .dsw and .dsp files are Visual C++ 6.0 project files.
- The .cpp and .h files in the Source\JXP directory are the library sources.
- JXPdemo.cpp is the source to JXPdemo.exe.
- TGA2MSK.cpp is the source to TGA2MSK.exe.

*****************************************************************************
  2. Demo programmes
*****************************************************************************

JXPdemo.exe is a demo programme which demonstrates most of the JXP library's
capabilities. It accepts a list of parameters on the command line.

The demo will go through the list of parameters. If a parameter begins with
a '/' character, the parameter is taken as an option which sets something.
Otherwise, it is taken as a filename. The filename may be a wildcard, which
is then expanded to the full list of files it matches. If it is not a
wildcard, then an extension of .jpg will be added if the filename is given
without an extension.

Once it has collected the list of filenames (which should be JPEGs), the demo
programme will decode all of them. It will then generate an 8bit palette, and
convert all of the images to 8bit images. The demo will then begin displaying
images.

When an image is displayed, the cursor keys can be used to change the image.
The left and right cursor keys will cycle through the list of images (if you
only specified one image on the command line left and right will therefore do
nothing). The up and down cursor keys will switch between viewing the
original 24bit image, and the reduced colour 8bit image. You can press escape
to quit, or click on the close box.

If JXPdemo.exe is run with no parameters, it will display a list of the
available parameters. Here is a more detailed description of what they do:

/no - no library output

Stops display of any output messages by the JXP library itself. The demo
programme itself will still print out some messages though.

/nd - no dithering

Turns off dithering when fitting the 24bit images to the palette. The default
is to use a Floyd-Steinberg error diffusion dither.

/c <num> - reduce to <num> colours

When generating the target palette, reduces it to <num> colours. The default
is 256. The number must be between 2 and 256.

/kw - keep white

When generating the target palette, ensures that pure white stays in the
palette.

/kb - keep black

Same as for /kw, but keeps pure black in the palette.

/fip - first image palette

By default, the demo programme will use all of the input images to generate
the optimum palette. Use of the /fip option instead causes the demo to
generate the palette based on the first image only. The remaining images are
then fit to this palette. This in general makes the other images look quite
bad, but this option is for the purpose of illustration :).

/m <filename[.msk]> - mask file

Uses the specifed mask file when displaying the images. White pixels in the
mask file will show through the actual image, and black pixels will not.

/sf <num> - scale images by <num> percent

After decoding all of the JPEGs, but before doing the colour reduction, this
parameter will cause the demo to scale all of the images by the supplied
percentage. Note that the library doesn't require that the image proportions
remain the same, just the demo programme does.

/nn - nearest neighbour resampling

When rescaling images (ie if /sf is used with a value other than 100), this
parameter will cause the demo to use nearest neighbour resampling instead of
the default bilinear filtering. Bilinear filtering generally looks a lot
better but is of course slower.

If all of that is too confusing, try this to display the example happy.jpg:

JXPdemo happy

And to display it with the example mask file, use:

JXPdemo happy /m jinx


TGA2MSK.exe is a simple utility which can be used to generate .MSK mask files
from .TGA Targa files. Since .MSK files are black and white, the input .TGA
has to be a black and white image. If you type TGA2MSK with no parameters,
the description of the syntax should be obvious enough.

*****************************************************************************
  3. How to use the library
*****************************************************************************

Using the JXP library in a programme of your own should be very simple.

Of course, you should first read and agree to the license agreement in the
next section before using the library.

Include in your project all of the JXP*.cpp files in the Source\JXP
directory. Make sure all of the header files in that directory can be found
by the compiler. Then, in any source file in which you want to use the JXP
functions, simply include JXP.h.

The entire interface to the JXP library is in JXP.h - so, you should only
need to call the functions in there. You shouldn't need to include any other
source files, or deal with any of the code in the other header files.

Hopefully you should be able to figure out how to use JXP by just reading
JXP.h, and using the code in JXPdemo.cpp as a reference.

*****************************************************************************
  4. License agreement
*****************************************************************************

To use the JXP library, you need to agree to this license agreement. If you
don't agree to it, then you should delete any JXP related files from your
system.

The JXP library is covered by an extremely liberal license. As the author of
this library, I give you the right to do anything you want with it, including
using it, modifying it and distributing it, for any purpose.

You don't even need to give me any credit. However, I believe that the 'nice'
thing to do is to give credit where it is due. So, if you do use JXP, I'd
appreciate it if you give me credit somewhere within your work... but you
don't have to.

At the very least, it would give me that warm fuzzy feeling if you sent me
an email if you found JXP useful :)

Naturally, to protect myself I also need to add the standard clause about
this distribution being completely void of any warranty, including those of
merchantability or fitness for a particular purpose. I am in no way
responsible for anything which JXP does or doesn't do, either from its use,
misuse or anything else. If JXP starts World War III it's not my fault.

*****************************************************************************
  5. Anticipated frequently asked questions
*****************************************************************************

I haven't released JXP yet, so I don't have any questions yet... However,
here are some 'anticipated' frequently asked questions.

1. What's a JPEG?
-----------------

Oh please, spare me....

2. Why have you released the entire source?
-------------------------------------------

Previous versions of JXP I wrote were 'released' (internally within JiNX) as
pre-compiled libraries, without the actual source.

However, I don't have all of the compilers in the world, and even if I did I
wouldn't feel like compiling a million libraries.

So, instead I'm releasing the full source to the library. It would be a shame
if somebody actually wanted to use JXP but couldn't just because they had the
wrong compiler or system. JXP may also be more useful to more people if they
can hack at it themselves.

3. Didn't the Independent JPEG Group (IJG) write a JPEG decoder? Why use JXP?
-----------------------------------------------------------------------------

I'm one of those crazy people who like the satisfaction of doing something
myself. Hence the reason why I wrote my own JPEG decoder instead of using
IJG's.

And their license agreement insists on giving them credit... sheesh ;)

4. Has anybody actually ever used JXP?
--------------------------------------

Yes, amazingly the JXP demo isn't the only programme to use JXP. Version 1.21
of JXP was used in JiNX's last demo release, 'Repertoire', which won
Coven 98. Visit the 'past releases' page at www.coven2000.org to download
Repertoire.

This new version (2.01) of JXP should also be used in JiNX's next demo
production, to be released at Coven 2000 (in February 2000).

In addition, JXP (v1.21) has also been used in the demo versions of the
'Powerslide' and 'Dirt Track Racing' games by Ratbag, to minimise their size
for download. Admittedly though I work there, which is the reason why JXP was
used :). Visit www.ratbaggames.com for info about Ratbag, and to download the
demo versions.

So, JXP has truly never been used by anyone outside of the people I know, but
then I've not released it to the public yet!

5. What is a mask file?
-----------------------

A mask (.MSK) file is a black and white run-length encoded image. This seemed
like something useful to create when I was originally writing JXP.

Surprisingly I have actually used mask files for something useful - to
compress the alpha component in 1bit alpha textures, as well as for the
colour key mask in chroma-keyed bitmaps.

6. How can I check if I have the latest version of JXP?
-------------------------------------------------------

I plan to upload JXP to ftp.scene.org, so you could check there.
Alternatively, send me an email (saxon@saxon.cx).

7. What platforms do JXP run on?
--------------------------------

JXP 1.x was developed on Watcom C version 11, for Protected Mode DOS, over 2
years ago.

The current version (2.x) of JXP has been significantly re-written, using
Visual C++ 6.0. I've not tested it under any other compilers or platforms,
however the library itself shouldn't include any platform-specific code
(except for perhaps the calling convention defines).

The demo programmes on the other hand will only work under win32, and
possibly only under Visual C.

8. Where is happy.jpg from?
---------------------------

happy.jpg is the end image from JiNX's second demo, 'Happiness', which won
Coven 97. Happiness can also be downloaded from www.coven2000.org.

Happiness was released before JXP was written. Hence, in Happiness the end
picture is a 900K raw image file!!

9. So what is JiNX?
-------------------

JiNX is the demo group which I have been a member of since it began in 
roughly mid 1996. My involvement in JiNX is generally in the area of coding,
although I haven't really done much since Coven 97. Visit the JiNX web site
at http://jinx.vg/ for more information on JiNX.

*****************************************************************************
  6. Acknowledgements
*****************************************************************************

JPG decoder: From the book 'JPEG: still image data compression standard', by
William B. Pennebaker and Joan L. Mitchell.

Colour reduction: Based on a description of an algorithm used by ImageMagick,
a graphics library for Unix.

Floyd-Steinberg dithering: Originally from a description of John DiCamillo's
Alpha engine. Bug-finding help from the Independent JPEG Group's quantisation
source (jquant2.c). Final implementation based on that used by the public
domain mpeg_play MPEG library's dithering source (fs2.c).

I'd also like to thank the other members of JiNX for their extensive testing
of the JXP library throughout its development. And especially Mark Hodson
(Hex/JiNX), for being the only person so far other than me to use JXP (in
Repertoire).

*****************************************************************************
  7. The end
*****************************************************************************

If you have any problems, comments or suggestions, email me at
saxon@saxon.cx.

Saxon Druce (aka Penfold/JiNX)
22nd Januray, 2000

*****************************************************************************
