install.doc

Jpeg source code,jpeg编码解码示范

probably have working programs.

With most of the makefiles, "make test" will perform the necessary
comparisons.

If you're using a makefile that doesn't provide the test option, run djpeg
and cjpeg by hand and compare the output files to testimg* with whatever
binary file comparison tool you have.  The files should be bit-for-bit
identical.

If the programs complain "MAX_ALLOC_CHUNK is wrong, please fix", then you
need to reduce MAX_ALLOC_CHUNK to a value that fits in type size_t.
Try adding "#define MAX_ALLOC_CHUNK 65520L" to jconfig.h.  A less likely
configuration error is "ALIGN_TYPE is wrong, please fix": defining ALIGN_TYPE
as long should take care of that one.

If the cjpeg test run fails with "Missing Huffman code table entry", it's a
good bet that you needed to define RIGHT_SHIFT_IS_UNSIGNED.  Go back to the
configuration step and run ckconfig.c.  (This is a good plan for any other
test failure, too.)

If you are using Unix (one-file) command line style on a non-Unix system,
it's a good idea to check that binary I/O through stdin/stdout actually
works.  You should get the same results from "djpeg <testorig.jpg >out.ppm"
as from "djpeg -outfile out.ppm testorig.jpg".  Note that the makefiles all
use the latter style and therefore do not exercise stdin/stdout!  If this
check fails, try recompiling with USE_SETMODE or USE_FDOPEN defined.
If it still doesn't work, better use two-file style.

If you chose a memory manager other than jmemnobs.c, you should test that
temporary-file usage works.  Try "djpeg -gif -max 0 testorig.jpg" and make
sure its output matches testimg.gif.  If you have any really large images
handy, try compressing them with -optimize and/or decompressing with -gif to
make sure your DEFAULT_MAX_MEM setting is not too large.

NOTE: this is far from an exhaustive test of the JPEG software; some modules,
such as 1-pass color quantization, are not exercised at all.  It's just a
quick test to give you some confidence that you haven't missed something
major.


INSTALLING THE SOFTWARE
=======================

Once you're done with the above steps, you can install the software by
copying the executable files (cjpeg, djpeg, jpegtran, rdjpgcom, and wrjpgcom)
to wherever you normally install programs.  On Unix systems, you'll also want
to put the man pages (cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1)
in the man-page directory.  The canned makefiles don't support this step
since there's such a wide variety of installation procedures on different
systems.

If you generated a Makefile with the "configure" script, you can just say
	make install
to install the programs and their man pages into the standard places.
(You'll probably need to be root to do this.)  We recommend first saying
	make -n install
to see where configure thought the files should go.  You may need to edit
the Makefile, particularly if your system's conventions for man page
filenames don't match what configure expects.

If you want to install the library file libjpeg.a and the include files j*.h
(for use in compiling other programs besides the IJG ones), then say
	make install-lib


OPTIONAL STUFF
==============

Progress monitor:

If you like, you can #define PROGRESS_REPORT (in jconfig.h) to enable display
of percent-done progress reports.  The routine provided in cdjpeg.c merely
prints percentages to stderr, but you can customize it to do something
fancier.

Utah RLE file format support:

We distribute the software with support for RLE image files (Utah Raster
Toolkit format) disabled, because the RLE support won't compile without the
Utah library.  If you have URT version 3.1 or later, you can enable RLE
support as follows:
	1.  #define RLE_SUPPORTED in jconfig.h.
	2.  Add a -I option to CFLAGS in the Makefile for the directory
	    containing the URT .h files (typically the "include"
	    subdirectory of the URT distribution).
	3.  Add -L... -lrle to LDLIBS in the Makefile, where ... specifies
	    the directory containing the URT "librle.a" file (typically the
	    "lib" subdirectory of the URT distribution).

Support for 12-bit-deep pixel data:

The JPEG standard allows either 8-bit or 12-bit data precision.  (For color,
this means 8 or 12 bits per channel, of course.)  If you need to work with
deeper than 8-bit data, you can compile the IJG code for 12-bit operation.
To do so:
  1. In jmorecfg.h, define BITS_IN_JSAMPLE as 12 rather than 8.
  2. In jconfig.h, undefine BMP_SUPPORTED, RLE_SUPPORTED, and TARGA_SUPPORTED,
     because the code for those formats doesn't handle 12-bit data and won't
     even compile.  (The PPM code does work, as explained below.  The GIF
     code works too; it scales 8-bit GIF data to and from 12-bit depth
     automatically.)
  3. Compile.  Don't expect "make test" to pass, since the supplied test
     files are for 8-bit data.

Currently, 12-bit support does not work on 16-bit-int machines.

Note that a 12-bit version will not read 8-bit JPEG files, nor vice versa;
so you'll want to keep around a regular 8-bit compilation as well.
(Run-time selection of data depth, to allow a single copy that does both,
is possible but would probably slow things down considerably; it's very low
on our to-do list.)

The PPM reader (rdppm.c) can read 12-bit data from either text-format or
binary-format PPM and PGM files.  Binary-format PPM/PGM files which have a
maxval greater than 255 are assumed to use 2 bytes per sample, LSB first
(little-endian order).  As of early 1995, 2-byte binary format is not
officially supported by the PBMPLUS library, but it is expected that the
next release of PBMPLUS will support it.  Note that the PPM reader will
read files of any maxval regardless of the BITS_IN_JSAMPLE setting; incoming
data is automatically rescaled to either maxval=255 or maxval=4095 as
appropriate for the cjpeg bit depth.

The PPM writer (wrppm.c) will normally write 2-byte binary PPM or PGM
format, maxval 4095, when compiled with BITS_IN_JSAMPLE=12.  Since this
format is not yet widely supported, you can disable it by compiling wrppm.c
with PPM_NORAWWORD defined; then the data is scaled down to 8 bits to make a
standard 1-byte/sample PPM or PGM file.  (Yes, this means still another copy
of djpeg to keep around.  But hopefully you won't need it for very long.
Poskanzer's supposed to get that new PBMPLUS release out Real Soon Now.)

Of course, if you are working with 12-bit data, you probably have it stored
in some other, nonstandard format.  In that case you'll probably want to
write your own I/O modules to read and write your format.

Note that a 12-bit version of cjpeg always runs in "-optimize" mode, in
order to generate valid Huffman tables.  This is necessary because our
default Huffman tables only cover 8-bit data.

Removing code:

If you need to make a smaller version of the JPEG software, some optional
functions can be removed at compile time.  See the xxx_SUPPORTED #defines in
jconfig.h and jmorecfg.h.  If at all possible, we recommend that you leave in
decoder support for all valid JPEG files, to ensure that you can read anyone's
output.  Taking out support for image file formats that you don't use is the
most painless way to make the programs smaller.  Another possibility is to
remove some of the DCT methods: in particular, the "IFAST" method may not be
enough faster than the others to be worth keeping on your machine.  (If you
do remove ISLOW or IFAST, be sure to redefine JDCT_DEFAULT or JDCT_FASTEST
to a supported method, by adding a #define in jconfig.h.)


OPTIMIZATION
============

Unless you own a Cray, you'll probably be interested in making the JPEG
software go as fast as possible.  This section covers some machine-dependent
optimizations you may want to try.  We suggest that before trying any of
this, you first get the basic installation to pass the self-test step.
Repeat the self-test after any optimization to make sure that you haven't
broken anything.

The integer DCT routines perform a lot of multiplications.  These
multiplications must yield 32-bit results, but none of their input values
are more than 16 bits wide.  On many machines, notably the 680x0 and 80x86
CPUs, a 16x16=>32 bit multiply instruction is faster than a full 32x32=>32
bit multiply.  Unfortunately there is no portable way to specify such a
multiplication in C, but some compilers can generate one when you use the
right combination of casts.  See the MULTIPLYxxx macro definitions in
jdct.h.  If your compiler makes "int" be 32 bits and "short" be 16 bits,
defining SHORTxSHORT_32 is fairly likely to work.  When experimenting with
alternate definitions, be sure to test not only whether the code still works
(use the self-test), but also whether it is actually faster --- on some
compilers, alternate definitions may compute the right answer, yet be slower
than the default.  Timing cjpeg on a large PGM (grayscale) input file is the
best way to check this, as the DCT will be the largest fraction of the runtime
in that mode.  (Note: some of the distributed compiler-specific jconfig files
already contain #define switches to select appropriate MULTIPLYxxx
definitions.)

If your machine has sufficiently fast floating point hardware, you may find
that the float DCT method is faster than the integer DCT methods, even
after tweaking the integer multiply macros.  In that case you may want to
make the float DCT be the default method.  (The only objection to this is
that float DCT results may vary slightly across machines.)  To do that, add
"#define JDCT_DEFAULT JDCT_FLOAT" to jconfig.h.  Even if you don't change
the default, you should redefine JDCT_FASTEST, which is the method selected
by djpeg's -fast switch.  Don't forget to update the documentation files
(usage.doc and/or cjpeg.1, djpeg.1) to agree with what you've done.

If access to "short" arrays is slow on your machine, it may be a win to
define type JCOEF as int rather than short.  This will cost a good deal of
memory though, particularly in some multi-pass modes, so don't do it unless
you have memory to burn and short is REALLY slow.

If your compiler can compile function calls in-line, make sure the INLINE
macro in jmorecfg.h is defined as the keyword that marks a function
inline-able.  Some compilers have a switch that tells the compiler to inline
any function it thinks is profitable (e.g., -finline-functions for gcc).
Enabling such a switch is likely to make the compiled code bigger but faster.

In general, it's worth trying the maximum optimization level of your compiler,
and experimenting with any optional optimizations such as loop unrolling.
(Unfortunately, far too many compilers have optimizer bugs ... be prepared to
back off if the code fails self-test.)  If you do any experimentation along
these lines, please report the optimal settings to [e-mail] so
we can mention them in future releases.  Be sure to specify your machine and
compiler version.


HINTS FOR SPECIFIC SYSTEMS
==========================

We welcome reports on changes needed for systems not mentioned here.  Submit
'em to [e-mail].  Also, if configure or ckconfig.c is wrong
about how to configure the JPEG software for your system, please let us know.


Acorn RISC OS:

(Thanks to Simon Middleton for these hints on compiling with Desktop C.)
After renaming the files according to Acorn conventions, take a copy of
makefile.ansi, change all occurrences of 'libjpeg.a' to 'libjpeg.o' and
change these definitions as indicated:

CFLAGS= -throwback -IC: -Wn
LDLIBS=C:o.Stubs
SYSDEPMEM=jmemansi.o
LN=Link
AR=LibFile -c -o

Also add a new line '.c.o:; $(cc) $< $(cflags) -c -o $@'.  Remove the
lines '$(RM) libjpeg.o' and '$(AR2) libjpeg.o' and the 'jconfig.h'
dependency section.

Copy jconfig.doc to jconfig.h.  Edit jconfig.h to define TWO_FILE_COMMANDLINE
and CHAR_IS_UNSIGNED.

Run the makefile using !AMU not !Make.  If you want to use the 'clean' and
'test' makefile entries then you will have to fiddle with the syntax a bit
and rename the test files.


Amiga:

SAS C 6.50 reportedly is too buggy to compile the IJG code properly.
A patch to update to 6.51 is available from SAS or AmiNet FTP sites.

The supplied config files are set up to use jmemname.c as the memory
manager, with temporary files being created on the device named by
"JPEGTMP:".


Atari ST/STE/TT:
 
Copy the project files makcjpeg.st, makdjpeg.st, maktjpeg.st, and makljpeg.st
to cjpeg.prj, djpeg.prj, jpegtran.prj, and libjpeg.prj respectively.  The
project files should work as-is with Pure C.  For Turbo C, change library
filenames "PC..." to "TC..." in each project file.  Note that libjpeg.prj
selects jmemansi.c as the recommended memory manager.  You'll probably want to
adjust the DEFAULT_MAX_MEM setting --- you want it to be a couple hundred K
less than your normal free memory.  Put "#define DEFAULT_MAX_MEM nnnn" into
jconfig.h to do this.

To use the 68881/68882 coprocessor for the floating point DCT, add the
compiler option "-8" to the project files and replace PCFLTLIB.LIB with
PC881LIB.LIB in cjpeg.prj and djpeg.prj.  Or if you don't have a
coprocessor, you may prefer to remove the float DCT code by undefining
DCT_FLOAT_SUPPORTED in jmorecfg.h (since without a coprocessor, the float
code will be too slow to be useful).  In that case, you can delete
PCFLTLIB.LIB from the project files.

Note that you must make libjpeg.lib before making cjpeg.ttp, djpeg.ttp,
or jpegtran.ttp.  You'll have to perform the self-test by hand.

We haven't bothered to include project files for rdjpgcom and wrjpgcom.
Those source files should just be compiled by themselves; they don't
depend on the JPEG library.

There is a bug in some older versions of the Turbo C library which causes the
space used by temporary files created with "tmpfile()" not to be freed after
an abnormal program exit.  If you check your disk afterwards, you will find
cluster chains that are allocated but not used by a file.  This should not
happen in cjpeg/djpeg/jpegtran, since we enable a signal catcher to explicitly
close temp files before exiting.  But if you use the JPEG library with your
own code, be sure to supply a signal catcher, or else use a different
system-dependent memory manager.


Cray:

Should you be so fortunate as to be running JPEG on a Cray YMP, there is a
compiler bug in old versions of Cray's Standard C (prior to 3.1).  If you
still have an old compiler, you'll need to insert a line reading
"#pragma novector" just before the loop	
    for (i = 1; i <= (int) htbl->bits[l]; i++)
      huffsize[p++] = (char) l;
in fix_huff_tbl (in V5beta1, line 204 of jchuff.c and line 176 of jdhuff.c).
[This bug may or may not still occur with the current IJG code, but it's
probably a dead issue anyway...]


HP-UX:

If you have HP-UX 7.05 or later with the "software development" C compiler,
you should run the compiler in ANSI mode.  If using the configure script,
say
	./configure CC='cc -Aa'
(or -Ae if you prefer).  If configuring by hand, use makefile.ansi and add
"-Aa" to the CFLAGS line in the makefile.