install.doc

game engine, which is useful for everyone who is interested in it. I hope you can enjoy it.

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 "int" 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 int, per Windows custom */
	#ifndef __RPCNDR_H__	/* don't conflict if rpcndr.h already read */
	typedef unsigned char boolean;
	#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.

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.doc 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
for a 16-bit DLL are:
	#define GLOBAL(type)		type _far _pascal _loadds _export
	#define EXTERN(type)		extern type _far _pascal _loadds
	#define METHODDEF(type)		static type _far _pascal
	#define JMETHOD(type,methodname,arglist)  \
		type (_far _pascal *methodname) arglist
For a 32-bit DLL you may want something like
	#define GLOBAL(type)		__declspec(dllexport) type
	#define EXTERN(type)		extern __declspec(dllexport) type
Although not all the GLOBAL routines are actually intended to be called by
the application, the performance cost of making them all DLL entry points is
negligible.

The unmodified IJG library presents a very C-specific application interface,
so the resulting DLL is only usable from C or C++ applications.  There has
been some talk of writing wrapper code that would present a simpler interface
usable from other languages, such as Visual Basic.  This is on our to-do list
but hasn't been very high priority --- any volunteers out there?


Microsoft Windows, Borland C:

The provided jconfig.bcc should work OK in a 32-bit Windows environment,
but you'll need to tweak it in a 16-bit environment (you'd need to define
NEED_FAR_POINTERS and MAX_ALLOC_CHUNK).  Beware that makefile.bcc will need
alteration if you want to use it for Windows --- in particular, you should
use jmemnobs.c not jmemdos.c under Windows.

Borland C++ 4.5 fails with an internal compiler error when trying to compile
jdmerge.c in 32-bit mode.  If enough people complain, perhaps Borland will fix
it.  In the meantime, the simplest known workaround is to add a redundant
definition of the variable range_limit in h2v1_merged_upsample(), at the head
of the block that handles odd image width (about line 268 in v6 jdmerge.c):
  /* If image width is odd, do the last output column separately */
  if (cinfo->output_width & 1) {
    register JSAMPLE * range_limit = cinfo->sample_range_limit; /* ADD THIS */
    cb = GETJSAMPLE(*inptr1);
Pretty bizarre, especially since the very similar routine h2v2_merged_upsample
doesn't trigger the bug.
Recent reports suggest that this bug does not occur with "bcc32a" (the
Pentium-optimized version of the compiler).

Another report from a user of Borland C 4.5 was that incorrect code (leading
to a color shift in processed images) was produced if any of the following
optimization switch combinations were used: 
	-Ot -Og
	-Ot -Op
	-Ot -Om
So try backing off on optimization if you see such a problem.  (Are there
several different releases all numbered "4.5"??)


Microsoft Windows, Microsoft Visual C++:

jconfig.vc should work OK with any Microsoft compiler for a 32-bit memory
model.  makefile.vc is intended for command-line use.  (If you are using
the Developer Studio environment, you may prefer the DevStudio project
files; see below.)

Some users feel that it's easier to call the library from C++ code if you
force VC++ to treat the library as C++ code, which you can do by renaming
all the *.c files to *.cpp (and adjusting the makefile to match).  This
avoids the need to put extern "C" { ... } around #include "jpeglib.h" in
your C++ application.


Microsoft Windows, Microsoft Developer Studio:

We include makefiles that should work as project files in DevStudio 4.2 or
later.  There is a library makefile that builds the IJG library as a static
Win32 library, and an application makefile that builds the sample applications
as Win32 console applications.  (Even if you only want the library, we
recommend building the applications so that you can run the self-test.)

To use:
1. Copy jconfig.vc to jconfig.h, makelib.ds to jpeg.mak, and
   makeapps.ds to apps.mak.  (Note that the renaming is critical!)
2. Click on the .mak files to construct project workspaces.
   (If you are using DevStudio more recent than 4.2, you'll probably
   get a message saying that the makefiles are being updated.)
3. Build the library project, then the applications project.
4. Move the application .exe files from `app`\Release to an
   appropriate location on your path.
5. To perform the self-test, execute the command line
	NMAKE /f makefile.vc  test


OS/2, Borland C++:

Watch out for optimization bugs in older Borland compilers; you may need
to back off the optimization switch settings.  See the comments in
makefile.bcc.


SGI:

On some SGI systems, you may need to set "AR2= ar -ts" in the Makefile.
If you are using configure, you can do this by saying
	./configure RANLIB='ar -ts'
This change is not needed on all SGIs.  Use it only if the make fails at the
stage of linking the completed programs.

On the MIPS R4000 architecture (Indy, etc.), the compiler option "-mips2"
reportedly speeds up the float DCT method substantially, enough to make it
faster than the default int method (but still slower than the fast int
method).  If you use -mips2, you may want to alter the default DCT method to
be float.  To do this, put "#define JDCT_DEFAULT JDCT_FLOAT" in jconfig.h.


VMS:

On an Alpha/VMS system with MMS, be sure to use the "/Marco=Alpha=1"
qualifier with MMS when building the JPEG package.

VAX/VMS v5.5-1 may have problems with the test step of the build procedure
reporting differences when it compares the original and test images.  If the
error points to the last block of the files, it is most likely bogus and may
be safely ignored.  It seems to be because the files are Stream_LF and
Backup/Compare has difficulty with the (presumably) null padded files.
This problem was not observed on VAX/VMS v6.1 or AXP/VMS v6.1.