view release on metacpan or  search on metacpan

src/Source/LibJPEG/install.txt  view on Meta::CPAN

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 -bmp -colors 256 -max 0 testorig.jpg"
and make sure its output matches testimg.bmp.  If you have any really large
images handy, try compressing them with -optimize and/or decompressing with
-colors 256 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 pre-fab 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 IJG library itself, for use in compiling other
programs besides ours, then you need to put the four include files
	jpeglib.h jerror.h jconfig.h jmorecfg.h
into your include-file directory, and put the library file libjpeg.a
(extension may vary depending on system) wherever library files go.
If you generated a Makefile with "configure", it will do what it thinks
is the right thing if you 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 9-bit to 12-bit deep pixel data:

The IJG code currently allows 8, 9, 10, 11, or 12 bits sample data precision.
(For color, this means 8 to 12 bits per channel, of course.)  If you need to
work with deeper than 8-bit data, you can compile the IJG code for 9-bit to
12-bit operation.
To do so:
  1. In jmorecfg.h, define BITS_IN_JSAMPLE as 9, 10, 11, or 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 deeper than 8-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, 9-bit to 12-bit support does not work on 16-bit-int machines.

Run-time selection and conversion of data precision are currently not
supported and may be added later.
Exception:  The transcoding part (jpegtran) supports all settings in a
single instance, since it operates on the level of DCT coefficients and
not sample values.

The PPM reader (rdppm.c) can read deeper than 8-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,
MSB first (big-endian order).  As of early 1995, 2-byte binary format is not
officially supported by the PBMPLUS library, but it is expected that a
future 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 maxval=MAXJSAMPLE as appropriate for the
cjpeg bit depth.

The PPM writer (wrppm.c) will normally write 2-byte binary PPM or PGM
format, maxval=MAXJSAMPLE, when compiled with BITS_IN_JSAMPLE>8.  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 9-bit to 12-bit data, you probably have
it stored in some other, nonstandard format.  In that case you'll probably

src/Source/LibJPEG/install.txt  view on Meta::CPAN

jconfig.mc6 already includes #define USE_SETMODE to make this work.
(fdopen does not work correctly.)

Note that this makefile assumes that the working copy of itself is called
"makefile".  If you want to call it something else, say "makefile.mak",
be sure to adjust the dependency line that reads "$(RFILE) : makefile".
Otherwise the make will fail because it doesn't know how to create "makefile".
Worse, some releases of Microsoft's make utilities give an incorrect error
message in this situation.

Old versions of MS C fail with an "out of macro expansion space" error
because they can't cope with the macro TRACEMS8 (defined in jerror.h).
If this happens to you, the easiest solution is to change TRACEMS8 to
expand to nothing.  You'll lose the ability to dump out JPEG coefficient
tables with djpeg -debug -debug, but at least you can compile.

Original MS C 6.0 is very buggy; it compiles incorrect code unless you turn
off optimization entirely (remove -O from CFLAGS).  6.00A is better, but it
still generates bad code if you enable loop optimizations (-Ol or -Ox).

MS C 8.0 crashes when compiling jquant1.c with optimization switch /Oo ...
which is on by default.  To work around this bug, compile that one file
with /Oo-.


Microsoft Windows (all versions), generic comments:

Some Windows system include files define typedef boolean as "unsigned char".
The IJG code also defines typedef boolean, but we make it an "enum" by default.
This doesn't affect the IJG programs because we don't import those Windows
include files.  But if you use the JPEG library in your own program, and some
of your program's files import one definition of boolean while some import the
other, you can get all sorts of mysterious problems.  A good preventive step
is to make the IJG library use "unsigned char" for boolean.  To do that,
add something like this to your jconfig.h file:
	/* Define "boolean" as unsigned char, not enum, per Windows custom */
	#ifndef __RPCNDR_H__	/* don't conflict if rpcndr.h already read */
	typedef unsigned char boolean;
	#endif
	#ifndef FALSE		/* in case these macros already exist */
	#define FALSE	0	/* values of boolean */
	#endif
	#ifndef TRUE
	#define TRUE	1
	#endif
	#define HAVE_BOOLEAN	/* prevent jmorecfg.h from redefining it */
(This is already in jconfig.vc, by the way.)

windef.h contains the declarations
	#define far
	#define FAR far
Since jmorecfg.h tries to define FAR as empty, you may get a compiler
warning if you include both jpeglib.h and windef.h (which windows.h
includes).  To suppress the warning, you can put "#ifndef FAR"/"#endif"
around the line "#define FAR" in jmorecfg.h.
(Something like this is already in jmorecfg.h, by the way.)

When using the library in a Windows application, you will almost certainly
want to modify or replace the error handler module jerror.c, since our
default error handler does a couple of inappropriate things:
  1. it tries to write error and warning messages on stderr;
  2. in event of a fatal error, it exits by calling exit().

A simple stopgap solution for problem 1 is to replace the line
	fprintf(stderr, "%s\n", buffer);
(in output_message in jerror.c) with
	MessageBox(GetActiveWindow(),buffer,"JPEG Error",MB_OK|MB_ICONERROR);
It's highly recommended that you at least do that much, since otherwise
error messages will disappear into nowhere.  (Beginning with IJG v6b, this
code is already present in jerror.c; just define USE_WINDOWS_MESSAGEBOX in
jconfig.h to enable it.)

The proper solution for problem 2 is to return control to your calling
application after a library error.  This can be done with the setjmp/longjmp
technique discussed in libjpeg.txt and illustrated in example.c.  (NOTE:
some older Windows C compilers provide versions of setjmp/longjmp that
don't actually work under Windows.  You may need to use the Windows system
functions Catch and Throw instead.)

The recommended memory manager under Windows is jmemnobs.c; in other words,
let Windows do any virtual memory management needed.  You should NOT use
jmemdos.c nor jmemdosa.asm under Windows.

For Windows 3.1, we recommend compiling in medium or large memory model;
for newer Windows versions, use a 32-bit flat memory model.  (See the MS-DOS
sections above for more info about memory models.)  In the 16-bit memory
models only, you'll need to put
	#define MAX_ALLOC_CHUNK 65520L	/* Maximum request to malloc() */
into jconfig.h to limit allocation chunks to 64Kb.  (Without that, you'd
have to use huge memory model, which slows things down unnecessarily.)
jmemnobs.c works without modification in large or flat memory models, but to
use medium model, you need to modify its jpeg_get_large and jpeg_free_large
routines to allocate far memory.  In any case, you might like to replace
its calls to malloc and free with direct calls on Windows memory allocation
functions.

You may also want to modify jdatasrc.c and jdatadst.c to use Windows file
operations rather than fread/fwrite.  This is only necessary if your C
compiler doesn't provide a competent implementation of C stdio functions.

You might want to tweak the RGB_xxx macros in jmorecfg.h so that the library
will accept or deliver color pixels in BGR sample order, not RGB; BGR order
is usually more convenient under Windows.  Note that this change will break
the sample applications cjpeg/djpeg, but the library itself works fine.


Many people want to convert the IJG library into a DLL.  This is reasonably
straightforward, but watch out for the following:

  1. Don't try to compile as a DLL in small or medium memory model; use
large model, or even better, 32-bit flat model.  Many places in the IJG code
assume the address of a local variable is an ordinary (not FAR) pointer;
that isn't true in a medium-model DLL.

  2. Microsoft C cannot pass file pointers between applications and DLLs.
(See Microsoft Knowledge Base, PSS ID Number Q50336.)  So jdatasrc.c and
jdatadst.c don't work if you open a file in your application and then pass
the pointer to the DLL.  One workaround is to make jdatasrc.c/jdatadst.c
part of your main application rather than part of the DLL.

  3. You'll probably need to modify the macros GLOBAL() and EXTERN() to
attach suitable linkage keywords to the exported routine names.  Similarly,
you'll want to modify METHODDEF() and JMETHOD() to ensure function pointers
are declared in a way that lets application routines be called back through
the function pointers.  These macros are in jmorecfg.h.  Typical definitions