view release on metacpan or  search on metacpan

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

To use the two-file style, make jconfig.h say "#define TWO_FILE_COMMANDLINE".

Selecting a memory manager
--------------------------

The IJG code is capable of working on images that are too big to fit in main
memory; data is swapped out to temporary files as necessary.  However, the
code to do this is rather system-dependent.  We provide five different
memory managers:

* jmemansi.c	This version uses the ANSI-standard library routine tmpfile(),
		which not all non-ANSI systems have.  On some systems
		tmpfile() may put the temporary file in a non-optimal
		location; if you don't like what it does, use jmemname.c.

* jmemname.c	This version creates named temporary files.  For anything
		except a Unix machine, you'll need to configure the
		select_file_name() routine appropriately; see the comments
		near the head of jmemname.c.  If you use this version, define
		NEED_SIGNAL_CATCHER in jconfig.h to make sure the temp files
		are removed if the program is aborted.

* jmemnobs.c	(That stands for No Backing Store :-).)  This will compile on
		almost any system, but it assumes you have enough main memory
		or virtual memory to hold the biggest images you work with.

* jmemdos.c	This should be used with most 16-bit MS-DOS compilers.
		See the system-specific notes about MS-DOS for more info.
		IMPORTANT: if you use this, define USE_MSDOS_MEMMGR in
		jconfig.h, and include the assembly file jmemdosa.asm in the
		programs.  The supplied makefiles and jconfig files for
		16-bit MS-DOS compilers already do both.

* jmemmac.c	Custom version for Apple Macintosh; see the system-specific
		notes for Macintosh for more info.

To use a particular memory manager, change the SYSDEPMEM variable in your
makefile to equal the corresponding object file name (for example, jmemansi.o
or jmemansi.obj for jmemansi.c).

If you have plenty of (real or virtual) main memory, just use jmemnobs.c.
"Plenty" means about ten bytes for every pixel in the largest images
you plan to process, so a lot of systems don't meet this criterion.
If yours doesn't, try jmemansi.c first.  If that doesn't compile, you'll have
to use jmemname.c; be sure to adjust select_file_name() for local conditions.
You may also need to change unlink() to remove() in close_backing_store().

Except with jmemnobs.c or jmemmac.c, you need to adjust the DEFAULT_MAX_MEM
setting to a reasonable value for your system (either by adding a #define for
DEFAULT_MAX_MEM to jconfig.h, or by adding a -D switch to the Makefile).
This value limits the amount of data space the program will attempt to
allocate.  Code and static data space isn't counted, so the actual memory
needs for cjpeg or djpeg are typically 100 to 150Kb more than the max-memory
setting.  Larger max-memory settings reduce the amount of I/O needed to
process a large image, but too large a value can result in "insufficient
memory" failures.  On most Unix machines (and other systems with virtual
memory), just set DEFAULT_MAX_MEM to several million and forget it.  At the
other end of the spectrum, for MS-DOS machines you probably can't go much
above 300K to 400K.  (On MS-DOS the value refers to conventional memory only.
Extended/expanded memory is handled separately by jmemdos.c.)


BUILDING THE SOFTWARE
=====================

Now you should be able to compile the software.  Just say "make" (or
whatever's necessary to start the compilation).  Have a cup of coffee.

Here are some things that could go wrong:

If your compiler complains about undefined structures, you should be able to
shut it up by putting "#define INCOMPLETE_TYPES_BROKEN" in jconfig.h.

If you have trouble with missing system include files or inclusion of the
wrong ones, read jinclude.h.  This shouldn't happen if you used configure
or ckconfig.c to set up jconfig.h.

There are a fair number of routines that do not use all of their parameters;
some compilers will issue warnings about this, which you can ignore.  There
are also a few configuration checks that may give "unreachable code" warnings.
Any other warning deserves investigation.

If you don't have a getenv() library routine, define NO_GETENV.

Also see the system-specific hints, below.


TESTING THE SOFTWARE
====================

As a quick test of functionality we've included a small sample image in
several forms:
	testorig.jpg	Starting point for the djpeg tests.
	testimg.ppm	The output of djpeg testorig.jpg
	testimg.bmp	The output of djpeg -bmp -colors 256 testorig.jpg
	testimg.jpg	The output of cjpeg testimg.ppm
	testprog.jpg	Progressive-mode equivalent of testorig.jpg.
	testimgp.jpg	The output of cjpeg -progressive -optimize testimg.ppm
(The first- and second-generation .jpg files aren't identical since the
default compression parameters are lossy.)  If you can generate duplicates
of the testimg* files then you 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.)

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

wrjpgcom needs to be compiled in large model, because it malloc()s a 64KB
work area to hold the comment text.  If your C library's malloc can't
handle that, reduce MAX_COM_LENGTH as necessary in wrjpgcom.c.

Most MS-DOS compilers treat stdin/stdout as text files, so you must use
two-file command line style.  But if your compiler has either fdopen() or
setmode(), you can use one-file style if you like.  To do this, define
USE_SETMODE or USE_FDOPEN so that stdin/stdout will be set to binary mode.
(USE_SETMODE seems to work with more DOS compilers than USE_FDOPEN.)  You
should test that I/O through stdin/stdout produces the same results as I/O
to explicitly named files... the "make test" procedures in the supplied
makefiles do NOT use stdin/stdout.


MS-DOS, generic comments for 32-bit compilers:

None of the above comments about memory models apply if you are using a
32-bit flat-memory-space environment, such as DJGPP or Watcom C.  (And you
should use one if you have it, as performance will be much better than
8086-compatible code!)  For flat-memory-space compilers, do NOT define
NEED_FAR_POINTERS, and do NOT use jmemdos.c.  Use jmemnobs.c if the
environment supplies adequate virtual memory, otherwise use jmemansi.c or
jmemname.c.

You'll still need to be careful about binary I/O through stdin/stdout.
See the last paragraph of the previous section.


MS-DOS, Borland C:

Be sure to convert all the source files to DOS text format (CR/LF newlines).
Although Borland C will often work OK with unmodified Unix (LF newlines)
source files, sometimes it will give bogus compile errors.
"Illegal character '#'" is the most common such error.  (This is true with
Borland C 3.1, but perhaps is fixed in newer releases.)

If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE.
jconfig.bcc already includes #define USE_SETMODE to make this work.
(fdopen does not work correctly.)


MS-DOS, Microsoft C:

makefile.mc6 works with Microsoft C, DOS Visual C++, etc.  It should only
be used if you want to build a 16-bit (small or medium memory model) program.

If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE.
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