| 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). |
