[ViewVC] Annotation of: cvs/Video-Capture-V4l/RTjpeg/codec/README

[release 0.1.2]

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, 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 co-efficients 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:
=============
A number of modules are avaliable (in the modules directory).  Some work
better on different architectures.  Select the module of your choice by
editing compose.sh .

Please benchmark these routines on various machines and send me your
compression/decompression rate (and machine type).

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

test2 <filename> <Q>: compresses <filename> to stdout with Q factor Q.
        The input file is a PPM with 2h2v subsapled Cr and Cb attached to
        the end.

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

test3d: play "ostr" on X display.  Hard coded for 32bpp, change
         Rtjpeg_yuvrgb32 to the conversion of your choice.

TC(subdir): experimental constrained rate encoder.
VS(subdir): experimental compressed Vstream version.

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

To compress single images:
1) RTjpeg_init_compress
2) (it is a good idea to save the tables with the image)
3) RTjpeg_compress
4) save result.

To decompress a single image:
1) Read saved tables (or call RTjpeg_init_compress with the same Q factor as
was used to compress the data) 
2) RTjpeg_init_decompress
3) store the YUV420 image, or
3) RTjpeg_yuvrgbXX where XX is the desired RGB depth (8 (grey) 16 (565) 24
and 32)
4) (possible) RTjpeg_doubleXX to double the image size.

To compress an image stream (with interframe coding):
As for single image except:
1) RTjpeg_init_mcompress AFTER RTjpeg_init compress.
2) Use RTjpeg_mcompress instead of RTjpeg_compress

To decompress an image stream (with interframe coding):
As for single frame except:
1) Initialise output buffer to 0's
2) do not modify the output buffer except by RTjpeg_decompress.

RTjpeg Functions:
=================
(some functions may not yet be implemented for all module types)

extern void RTjpeg_init_Q(__u8 Q);
----------------------------------
Change the quality factor for future compressions/decompressions to Q.
Q=255 ==> IJG jpeg 75% (max)
Q=128 ==> IJG jpeg 50%
Q=32 (min usable)
Q=1 (abstract art)

extern void RTjpeg_init_compress(__u32 *buf, int width, int height, __u8 Q);
----------------------------------------------------------------------------
Initialise the compressor.
  *buf is a pointer to 128 ints.  The de-quantizer values are stored in this
array.  It is best to save these with the image for reliable decompression
between versions (although it is probably not necessary).
  width is the width of the Y component of the image.
  height is the height of the Y component of the image.
  Q is the quality factor (see above)

extern void RTjpeg_init_decompress(__u32 *buf, int width, int height);
----------------------------------------------------------------------
Initialise decompressor (and color convertor).
  *buf is a pointer to the 128 ints produced by init_compress.
  width and height, as before.

extern int RTjpeg_compress(__s8 *sp, unsigned char *bp);
--------------------------------------------------------
Compress the image.
  *sp is a pointer to the output data (for safety, this buffer should be as 
    large as the uncompressed data).
  *bp is a pointer to the input data (YUV420P format).
  RETURN: the number of bytes actually used for the output stream.

extern void RTjpeg_decompress(__s8 *sp, __u8 *bp);
--------------------------------------------------
Decompress the image.
  as before (no RETURN).

extern void RTjpeg_init_mcompress(void);
----------------------------------------
Initialise interframe compression.

extern int RTjpeg_mcompress(__s8 *sp, unsigned char *bp, __u16 lmask, __u16 cmask);
-----------------------------------------------------------------------------------
Perform interframe compression.
 *sp, *bp as for compress
 lmask, cmask threshold value for change in quantized luma and chroma
   components before transmitting the block. NB works on quantized values,
   so use lower thresholds for lower Q values.

extern void RTjpeg_set_test(int i);
-----------------------------------
Enable test-compressions.
  i=0: disable test mode
  i=1: enable test mode
(In test mode interframe compression is performed WITHOUT updating the local
copy of the reference image.  This is used for constrained rate encoding to
test multiple compression factors for compressed block size. Remember to
call mcompress with test mode = 0 BEFORE transmitting an encoded block.)

extern void RTjpeg_yuvrgb(__u8 *buf, __u8 *rgb);
------------------------------------------------
Convert decompressed YUV420P data to RGB data
  *buf pointer to YUV420P data
  *rgb pointer to RGB data

extern void RTjpeg_yuvrgb32(__u8 *buf, __u8 *rgb);
--------------------------------------------------
convert to RGB32 data (display order)

extern void RTjpeg_yuvrgb24(__u8 *buf, __u8 *rgb);
--------------------------------------------------
convert to RGB24 (display order)

extern void RTjpeg_yuvrgb16(__u8 *buf, __u8 *rgb);
--------------------------------------------------
convert to RGB 565

extern void RTjpeg_yuvrgb8(__u8 *buf, __u8 *rgb);
-------------------------------------------------
convert to grey-scale (grin)

extern void RTjpeg_double32(__u32 *buf);
extern void RTjpeg_double24(__u8 *buf);
extern void RTjpeg_double16(__u16 *buf);
extern void RTjpeg_double8(__u8 *buf);
--------------------------------------
convert the image pointed to by *buf to double size (size is determined by
with and height from init_decompress).
Revision:	1.1
Committed:	Fri May 5 20:21:52 2000 UTC (26 years, 5 months ago) by pcg
Branch:	MAIN
CVS Tags:	rel-0_9, rel-0_902, HEAD
Log Message:	Initial check-in
#	User	Rev	Content
1	pcg	1.1	[release 0.1.2]
2
3			RTjpeg
4			(C) 1998 Justin Schoeman (justin@suntiger.ee.up.ac.za)
5
6			License+Disclaimer
7			==================
8			This code is distributed under GPLv2 (in other words, do what you like with
9			it, but don't sell it, and give credit if you use it).
10			THIS SOFTWARE IS IN NO WAY GUARANTEED TO WORK. IF YOU USE IT AND IT DOESN'T
11			WORK, OR MESSES UP YOUR COMPUTER, IT'S YOUR OWN PROBLEM.
12
13			General:
14			========
15			This is still a rather developmental real time compressor. It is based on
16			the jpeg compressor by the IJG (see LICENSE.jpeg for license details). The
17			only real difference is the encoder. This compressor uses a home brew
18			redundant data coder (makes use of the fact that some co-efficients have a
19			limited range) to very quickly (but not that efficiently) encode the data.
20
21			Basic interframe coding (only coefficients that have varied significantly
22			are transmitted) is included.
23
24			This codec is currently real time at CIF resolutions on anything faster than
25			a pentium 200 (on most P133s too now).
26
27			Installation:
28			=============
29			A number of modules are avaliable (in the modules directory). Some work
30			better on different architectures. Select the module of your choice by
31			editing compose.sh .
32
33			Please benchmark these routines on various machines and send me your
34			compression/decompression rate (and machine type).
35
36			Applications:
37			=============
38			test: out of date captures from bttv0 and compresses to out.pgm (1
39			image).
40
41			test2 <filename> <Q>: compresses <filename> to stdout with Q factor Q.
42			The input file is a PPM with 2h2v subsapled Cr and Cb attached to
43			the end.
44
45			test3 <Q> <M>: capture compressed stream to "ostr" with Q factor Q and
46			motion threshold "M".
47
48			test3d: play "ostr" on X display. Hard coded for 32bpp, change
49			Rtjpeg_yuvrgb32 to the conversion of your choice.
50
51			TC(subdir): experimental constrained rate encoder.
52			VS(subdir): experimental compressed Vstream version.
53
54			Using the library:
55			==================
56			(see below for function descriptions)
57
58			To compress single images:
59			1) RTjpeg_init_compress
60			2) (it is a good idea to save the tables with the image)
61			3) RTjpeg_compress
62			4) save result.
63
64			To decompress a single image:
65			1) Read saved tables (or call RTjpeg_init_compress with the same Q factor as
66			was used to compress the data)
67			2) RTjpeg_init_decompress
68			3) store the YUV420 image, or
69			3) RTjpeg_yuvrgbXX where XX is the desired RGB depth (8 (grey) 16 (565) 24
70			and 32)
71			4) (possible) RTjpeg_doubleXX to double the image size.
72
73			To compress an image stream (with interframe coding):
74			As for single image except:
75			1) RTjpeg_init_mcompress AFTER RTjpeg_init compress.
76			2) Use RTjpeg_mcompress instead of RTjpeg_compress
77
78			To decompress an image stream (with interframe coding):
79			As for single frame except:
80			1) Initialise output buffer to 0's
81			2) do not modify the output buffer except by RTjpeg_decompress.
82
83			RTjpeg Functions:
84			=================
85			(some functions may not yet be implemented for all module types)
86
87			extern void RTjpeg_init_Q(__u8 Q);
88			----------------------------------
89			Change the quality factor for future compressions/decompressions to Q.
90			Q=255 ==> IJG jpeg 75% (max)
91			Q=128 ==> IJG jpeg 50%
92			Q=32 (min usable)
93			Q=1 (abstract art)
94
95			extern void RTjpeg_init_compress(__u32 *buf, int width, int height, __u8 Q);
96			----------------------------------------------------------------------------
97			Initialise the compressor.
98			*buf is a pointer to 128 ints. The de-quantizer values are stored in this
99			array. It is best to save these with the image for reliable decompression
100			between versions (although it is probably not necessary).
101			width is the width of the Y component of the image.
102			height is the height of the Y component of the image.
103			Q is the quality factor (see above)
104
105			extern void RTjpeg_init_decompress(__u32 *buf, int width, int height);
106			----------------------------------------------------------------------
107			Initialise decompressor (and color convertor).
108			*buf is a pointer to the 128 ints produced by init_compress.
109			width and height, as before.
110
111			extern int RTjpeg_compress(__s8 sp, unsigned char bp);
112			--------------------------------------------------------
113			Compress the image.
114			*sp is a pointer to the output data (for safety, this buffer should be as
115			large as the uncompressed data).
116			*bp is a pointer to the input data (YUV420P format).
117			RETURN: the number of bytes actually used for the output stream.
118
119			extern void RTjpeg_decompress(__s8 sp, __u8 bp);
120			--------------------------------------------------
121			Decompress the image.
122			as before (no RETURN).
123
124			extern void RTjpeg_init_mcompress(void);
125			----------------------------------------
126			Initialise interframe compression.
127
128			extern int RTjpeg_mcompress(__s8 sp, unsigned char bp, __u16 lmask, __u16 cmask);
129			-----------------------------------------------------------------------------------
130			Perform interframe compression.
131			sp, bp as for compress
132			lmask, cmask threshold value for change in quantized luma and chroma
133			components before transmitting the block. NB works on quantized values,
134			so use lower thresholds for lower Q values.
135
136			extern void RTjpeg_set_test(int i);
137			-----------------------------------
138			Enable test-compressions.
139			i=0: disable test mode
140			i=1: enable test mode
141			(In test mode interframe compression is performed WITHOUT updating the local
142			copy of the reference image. This is used for constrained rate encoding to
143			test multiple compression factors for compressed block size. Remember to
144			call mcompress with test mode = 0 BEFORE transmitting an encoded block.)
145
146			extern void RTjpeg_yuvrgb(__u8 buf, __u8 rgb);
147			------------------------------------------------
148			Convert decompressed YUV420P data to RGB data
149			*buf pointer to YUV420P data
150			*rgb pointer to RGB data
151
152			extern void RTjpeg_yuvrgb32(__u8 buf, __u8 rgb);
153			--------------------------------------------------
154			convert to RGB32 data (display order)
155
156			extern void RTjpeg_yuvrgb24(__u8 buf, __u8 rgb);
157			--------------------------------------------------
158			convert to RGB24 (display order)
159
160			extern void RTjpeg_yuvrgb16(__u8 buf, __u8 rgb);
161			--------------------------------------------------
162			convert to RGB 565
163
164			extern void RTjpeg_yuvrgb8(__u8 buf, __u8 rgb);
165			-------------------------------------------------
166			convert to grey-scale (grin)
167
168			extern void RTjpeg_double32(__u32 *buf);
169			extern void RTjpeg_double24(__u8 *buf);
170			extern void RTjpeg_double16(__u16 *buf);
171			extern void RTjpeg_double8(__u8 *buf);
172			--------------------------------------
173			convert the image pointed to by *buf to double size (size is determined by
174			with and height from init_decompress).