RTjpeg
(C) 1998 Justin Schoeman (justin@suntiger.ee.up.ac.za)

License+Disclaimer
==================
This code is distributed under GPLv2 (in other words, do what you like with
it, but don't sell it, make all your changes available to others, and give 
credit if you use it).
THIS SOFTWARE IS IN NO WAY GUARANTEED TO WORK. IF YOU USE IT AND IT DOESN'T
WORK, OR MESSES UP YOUR COMPUTER, IT'S YOUR OWN PROBLEM.

General:
========
This is still a rather developmental real-time compressor.  It is based on
the jpeg compressor by the IJG (see LICENSE.jpeg for license details).  The
only real difference is the encoder.  This compressor uses a home brew
redundant data coder (makes use of the fact that some coefficients have a
limited range) to very quickly (but not that efficiently) encode the data.

Basic interframe coding (only coefficients that have varied significantly
are transmitted) is included.

This codec is currently real time at CIF resolutions on anything faster than
a pentium 200 (on most P133s too now).

Installation:
=============
Edit the top level Makefile.  Set the CFLAGS to the optimal options for your
system.  Type "make" and hope...

Applications:
=============
test: *out of date* captures from bttv0 and compresses to out.pgm (1
	image).

test2 <filename> <Q>: compresses <filename> to stdout with quality  factor Q.
	The input file must be PPM.

(The following are only available on Linux platforms)

test3 <Q> <M>: capture compressed stream to "ostr" with Q factor Q and
		motion threshold "M".

test3d: play "ostr" on X display.  Does not autodetyect 24/32bpp correctly -
	  you will have to do some editting to get these to work...

Using the library:
==================
(see below for function descriptions)

To compress images:
1) RTjpeg_init
2) RTjpeg_set_size
3) RTjpeg_set_quality
4) RTjpeg_set_format
(The following step is only if you want interframe coding)
 5) RTjpeg_set_intra
6) RTjpeg_compress  }(Repeat as often as required)
7) Store data       }
7) RTjpeg_close

To decompress images:
1) RTjpeg_init
2) RTjpeg_set_format
3) Read data        }
4) RTjpeg_decompress  }(Repeat as often as required)
5) RTjpeg_close

RTjpeg Functions:
=================

extern RTjpeg_t *RTjpeg_init();
-------------------------------
Initialise and return a new codec handle "rtj".  CALL THIS FIRST!

extern void RTjpeg_close(RTjpeg_t *rtj);
---------------------------------------
Close codec handle "rtj".  CALL THIS LAST!

extern void RTjpeg_set_quality(RTjpeg_t *rtj, int *quality);
------------------------------------------------------------
Change the quality factor for future compressions to *quality.
quality=255 ==> IJG jpeg 75% (max)
quality=128 ==> IJG jpeg 50%
quality=32 (min usable)
quality=1 (abstract art)

extern void RTjpeg_set_format(RTjpeg_t *rtj, int *format);
----------------------------------------------------------
Change the format of the input/output data to *format.  Only RTJ_YUV420 is
tested.
Possible formats:
 RTJ_YUV420 ==> YUV420 (planar)
 RTJ_YUV422 ==> YUV422 (planar)
 RTJ_RGB8 ==> greyscale

extern void RTjpeg_set_size(RTjpeg_t *rtj, int *width, int *height);
--------------------------------------------------------------------
Set the size of the image to be compressed to *width x *height.
Width and height must be multiples of 16.

extern void RTjpeg_set_intra(RTjpeg_t *rtj, int *key, int *lm, int *cm);
------------------------------------------------------------------------
Set the interframe coding parameters:
 *key ==> Send a key frame every "*key" frames.
 *lm  ==> Change threshold for luma values.
 *cm  ==> Chaneg threshold for chroma values (typically lm/2)

extern int RTjpeg_compress(RTjpeg_t *rtj, int8_t *sp, uint8_t **planes);
------------------------------------------------------------------------
Compress the image.
  *sp is a pointer to the output data (for safety, this buffer should be as
    large as the uncompressed data).
  **planes is a list of the input planes - typically an array of three
    values - pointers to the Y, U and V planes, in that order.
RETURN: the number of bytes actually used for the output stream.

extern void RTjpeg_decompress(RTjpeg_t *rtj, int8_t *sp, uint8_t **planes);
--------------------------------------------------------------------------
Decompress the image.
  *sp is a pointer to the compressed data.
  **planes is a list of the output planes - typically an array of three
    values - pointers to the Y, U and V planes, in that order.

uint32_t RTjpeg_frame_framesize(int8_t *sp);
---------------------------------------
Macro for extracting size of the frame from the header of a compressed
frame.
  *sp is a pointer to the compressed data.

uint8_t RTjpeg_frame_headersize(int8_t *sp);
---------------------------------------
Macro for extracting size of the frame header from the header of a compressed
frame.
  *sp is a pointer to the compressed data.

uint8_t RTjpeg_frame_version(int8_t *sp);
---------------------------------------
Macro for extracting size of the file version from the header of a compressed
frame.
  *sp is a pointer to the compressed data.

uint16_t RTjpeg_frame_width(int8_t *sp);
----------------------------------------
Macro for extracting width of compressed image from the header of a
compressed frame.
  *sp is a pointer to the compressed data.

uint16_t RTjpeg_frame_height(int8_t *sp);
-----------------------------------------
Macro for extracting height of compressed image from the header of a
compressed frame.
  *sp is a pointer to the compressed data.

uint8_t RTjpeg_frame_quality(int8_t *sp);
------------------------------------------
Macro for extracting quality factor of compressed image from the header of a 
compressed frame.
  *sp is a pointer to the compressed data.

uint8_t RTjpeg_frame_key(int8_t *sp);
--------------------------------------
Macro for extracting key frame distance from the header of a compressed frame.
This is the distance to the last encoded keyframe (i.e. 0 means this is a
keyframe).
  *sp is a pointer to the compressed data.

void RTjpeg_yuv420rgb32(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows);
void RTjpeg_yuv420bgr32(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows);
void RTjpeg_yuv420rgb24(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows);
void RTjpeg_yuv420bgr24(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows);
void RTjpeg_yuv420rgb16(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows);
void RTjpeg_yuv420rgb8(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows); 
void RTjpeg_yuv422rgb24(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows);
void RTjpeg_yuv422rgb8(RTjpeg_t *rtj, uint8_t **planes, uint8_t **rows);
------------------------------------------------------------------------
Convert planar to rgb formats (according to the name of the function).
  **planes is a list of the input planes - typically an array of three
    values - pointers to the Y, U and V planes, in that order.
  **rows is a list of rows to write the rgb data to.  It has "height" items,
    each a pointer to where to store the data for that row.

uint8_t *RTJPEG_COMPAT_STREAM(int8_t *sp);
------------------------------------------

The adress of the stream data you would have seen in earlier RTjpeg.
releases.

uint32_t RTJPEG_COMPAT_LENGTH(int8_t *sp);
------------------------------------------

The length of the frame data, as seen in earlier versions of RTjpeg.

USAGE:
======

See the test*.c programs for examples.
