home *** CD-ROM | disk | FTP | other *** search
/ Geek 6 / Geek-006.iso / linux / video / xmovie-1.5.3.tar.gz / xmovie-1.5.3.tar / xmovie-1.5.3 / quicktime / jpeg / install.doc < prev    next >
Text File  |  2000-11-29  |  52KB  |  1,064 lines
  1. INSTALLATION INSTRUCTIONS for the Independent JPEG Group's JPEG software
  2.  
  3. Copyright (C) 1991-1998, Thomas G. Lane.
  4. This file is part of the Independent JPEG Group's software.
  5. For conditions of distribution and use, see the accompanying README file.
  6.  
  7.  
  8. This file explains how to configure and install the IJG software.  We have
  9. tried to make this software extremely portable and flexible, so that it can be
  10. adapted to almost any environment.  The downside of this decision is that the
  11. installation process is complicated.  We have provided shortcuts to simplify
  12. the task on common systems.  But in any case, you will need at least a little
  13. familiarity with C programming and program build procedures for your system.
  14.  
  15. If you are only using this software as part of a larger program, the larger
  16. program's installation procedure may take care of configuring the IJG code.
  17. For example, Ghostscript's installation script will configure the IJG code.
  18. You don't need to read this file if you just want to compile Ghostscript.
  19.  
  20. If you are on a Unix machine, you may not need to read this file at all.
  21. Try doing
  22.     ./configure
  23.     make
  24.     make test
  25. If that doesn't complain, do
  26.     make install
  27. (better do "make -n install" first to see if the makefile will put the files
  28. where you want them).  Read further if you run into snags or want to customize
  29. the code for your system.
  30.  
  31.  
  32. TABLE OF CONTENTS
  33. -----------------
  34.  
  35. Before you start
  36. Configuring the software:
  37.     using the automatic "configure" script
  38.     using one of the supplied jconfig and makefile files
  39.     by hand
  40. Building the software
  41. Testing the software
  42. Installing the software
  43. Optional stuff
  44. Optimization
  45. Hints for specific systems
  46.  
  47.  
  48. BEFORE YOU START
  49. ================
  50.  
  51. Before installing the software you must unpack the distributed source code.
  52. Since you are reading this file, you have probably already succeeded in this
  53. task.  However, there is a potential for error if you needed to convert the
  54. files to the local standard text file format (for example, if you are on
  55. MS-DOS you may have converted LF end-of-line to CR/LF).  You must apply
  56. such conversion to all the files EXCEPT those whose names begin with "test".
  57. The test files contain binary data; if you change them in any way then the
  58. self-test will give bad results.
  59.  
  60. Please check the last section of this file to see if there are hints for the
  61. specific machine or compiler you are using.
  62.  
  63.  
  64. CONFIGURING THE SOFTWARE
  65. ========================
  66.  
  67. To configure the IJG code for your system, you need to create two files:
  68.   * jconfig.h: contains values for system-dependent #define symbols.
  69.   * Makefile: controls the compilation process.
  70. (On a non-Unix machine, you may create "project files" or some other
  71. substitute for a Makefile.  jconfig.h is needed in any environment.)
  72.  
  73. We provide three different ways to generate these files:
  74.   * On a Unix system, you can just run the "configure" script.
  75.   * We provide sample jconfig files and makefiles for popular machines;
  76.     if your machine matches one of the samples, just copy the right sample
  77.     files to jconfig.h and Makefile.
  78.   * If all else fails, read the instructions below and make your own files.
  79.  
  80.  
  81. Configuring the software using the automatic "configure" script
  82. ---------------------------------------------------------------
  83.  
  84. If you are on a Unix machine, you can just type
  85.     ./configure
  86. and let the configure script construct appropriate configuration files.
  87. If you're using "csh" on an old version of System V, you might need to type
  88.     sh configure
  89. instead to prevent csh from trying to execute configure itself.
  90. Expect configure to run for a few minutes, particularly on slower machines;
  91. it works by compiling a series of test programs.
  92.  
  93. Configure was created with GNU Autoconf and it follows the usual conventions
  94. for GNU configure scripts.  It makes a few assumptions that you may want to
  95. override.  You can do this by providing optional switches to configure:
  96.  
  97. * If you want to build libjpeg as a shared library, say
  98.     ./configure --enable-shared
  99. To get both shared and static libraries, say
  100.     ./configure --enable-shared --enable-static
  101. Note that these switches invoke GNU libtool to take care of system-dependent
  102. shared library building methods.  If things don't work this way, please try
  103. running configure without either switch; that should build a static library
  104. without using libtool.  If that works, your problem is probably with libtool
  105. not with the IJG code.  libtool is fairly new and doesn't support all flavors
  106. of Unix yet.  (You might be able to find a newer version of libtool than the
  107. one included with libjpeg; see ftp.gnu.org.  Report libtool problems to
  108. bug-libtool@gnu.org.)
  109.  
  110. * Configure will use gcc (GNU C compiler) if it's available, otherwise cc.
  111. To force a particular compiler to be selected, use the CC option, for example
  112.     ./configure CC='cc'
  113. The same method can be used to include any unusual compiler switches.
  114. For example, on HP-UX you probably want to say
  115.     ./configure CC='cc -Aa'
  116. to get HP's compiler to run in ANSI mode.
  117.  
  118. * The default CFLAGS setting is "-O" for non-gcc compilers, "-O2" for gcc.
  119. You can override this by saying, for example,
  120.     ./configure CFLAGS='-g'
  121. if you want to compile with debugging support.
  122.  
  123. * Configure will set up the makefile so that "make install" will install files
  124. into /usr/local/bin, /usr/local/man, etc.  You can specify an installation
  125. prefix other than "/usr/local" by giving configure the option "--prefix=PATH".
  126.  
  127. * If you don't have a lot of swap space, you may need to enable the IJG
  128. software's internal virtual memory mechanism.  To do this, give the option
  129. "--enable-maxmem=N" where N is the default maxmemory limit in megabytes.
  130. This is discussed in more detail under "Selecting a memory manager", below.
  131. You probably don't need to worry about this on reasonably-sized Unix machines,
  132. unless you plan to process very large images.
  133.  
  134. Configure has some other features that are useful if you are cross-compiling
  135. or working in a network of multiple machine types; but if you need those
  136. features, you probably already know how to use them.
  137.  
  138.  
  139. Configuring the software using one of the supplied jconfig and makefile files
  140. -----------------------------------------------------------------------------
  141.  
  142. If you have one of these systems, you can just use the provided configuration
  143. files:
  144.  
  145. Makefile    jconfig file    System and/or compiler
  146.  
  147. makefile.manx    jconfig.manx    Amiga, Manx Aztec C
  148. makefile.sas    jconfig.sas    Amiga, SAS C
  149. makeproj.mac    jconfig.mac    Apple Macintosh, Metrowerks CodeWarrior
  150. mak*jpeg.st    jconfig.st    Atari ST/STE/TT, Pure C or Turbo C
  151. makefile.bcc    jconfig.bcc    MS-DOS or OS/2, Borland C
  152. makefile.dj    jconfig.dj    MS-DOS, DJGPP (Delorie's port of GNU C)
  153. makefile.mc6    jconfig.mc6    MS-DOS, Microsoft C (16-bit only)
  154. makefile.wat    jconfig.wat    MS-DOS, OS/2, or Windows NT, Watcom C
  155. makefile.vc    jconfig.vc    Windows NT/95, MS Visual C++
  156. make*.ds    jconfig.vc    Windows NT/95, MS Developer Studio
  157. makefile.mms    jconfig.vms    Digital VMS, with MMS software
  158. makefile.vms    jconfig.vms    Digital VMS, without MMS software
  159.  
  160. Copy the proper jconfig file to jconfig.h and the makefile to Makefile (or
  161. whatever your system uses as the standard makefile name).  For more info see
  162. the appropriate system-specific hints section near the end of this file.
  163.  
  164.  
  165. Configuring the software by hand
  166. --------------------------------
  167.  
  168. First, generate a jconfig.h file.  If you are moderately familiar with C,
  169. the comments in jconfig.doc should be enough information to do this; just
  170. copy jconfig.doc to jconfig.h and edit it appropriately.  Otherwise, you may
  171. prefer to use the ckconfig.c program.  You will need to compile and execute
  172. ckconfig.c by hand --- we hope you know at least enough to do that.
  173. ckconfig.c may not compile the first try (in fact, the whole idea is for it
  174. to fail if anything is going to).  If you get compile errors, fix them by
  175. editing ckconfig.c according to the directions given in ckconfig.c.  Once
  176. you get it to run, it will write a suitable jconfig.h file, and will also
  177. print out some advice about which makefile to use.
  178.  
  179. You may also want to look at the canned jconfig files, if there is one for a
  180. system similar to yours.
  181.  
  182. Second, select a makefile and copy it to Makefile (or whatever your system
  183. uses as the standard makefile name).  The most generic makefiles we provide
  184. are
  185.     makefile.ansi:    if your C compiler supports function prototypes
  186.     makefile.unix:    if not.
  187. (You have function prototypes if ckconfig.c put "#define HAVE_PROTOTYPES"
  188. in jconfig.h.)  You may want to start from one of the other makefiles if
  189. there is one for a system similar to yours.
  190.  
  191. Look over the selected Makefile and adjust options as needed.  In particular
  192. you may want to change the CC and CFLAGS definitions.  For instance, if you
  193. are using GCC, set CC=gcc.  If you had to use any compiler switches to get
  194. ckconfig.c to work, make sure the same switches are in CFLAGS.
  195.  
  196. If you are on a system that doesn't use makefiles, you'll need to set up
  197. project files (or whatever you do use) to compile all the source files and
  198. link them into executable files cjpeg, djpeg, jpegtran, rdjpgcom, and wrjpgcom.
  199. See the file lists in any of the makefiles to find out which files go into
  200. each program.  Note that the provided makefiles all make a "library" file
  201. libjpeg first, but you don't have to do that if you don't want to; the file
  202. lists identify which source files are actually needed for compression,
  203. decompression, or both.  As a last resort, you can make a batch script that
  204. just compiles everything and links it all together; makefile.vms is an example
  205. of this (it's for VMS systems that have no make-like utility).
  206.  
  207. Here are comments about some specific configuration decisions you'll
  208. need to make:
  209.  
  210. Command line style
  211. ------------------
  212.  
  213. These programs can use a Unix-like command line style which supports
  214. redirection and piping, like this:
  215.     cjpeg inputfile >outputfile
  216.     cjpeg <inputfile >outputfile
  217.     source program | cjpeg >outputfile
  218. The simpler "two file" command line style is just
  219.     cjpeg inputfile outputfile
  220. You may prefer the two-file style, particularly if you don't have pipes.
  221.  
  222. You MUST use two-file style on any system that doesn't cope well with binary
  223. data fed through stdin/stdout; this is true for some MS-DOS compilers, for
  224. example.  If you're not on a Unix system, it's safest to assume you need
  225. two-file style.  (But if your compiler provides either the Posix-standard
  226. fdopen() library routine or a Microsoft-compatible setmode() routine, you
  227. can safely use the Unix command line style, by defining USE_FDOPEN or
  228. USE_SETMODE respectively.)
  229.  
  230. To use the two-file style, make jconfig.h say "#define TWO_FILE_COMMANDLINE".
  231.  
  232. Selecting a memory manager
  233. --------------------------
  234.  
  235. The IJG code is capable of working on images that are too big to fit in main
  236. memory; data is swapped out to temporary files as necessary.  However, the
  237. code to do this is rather system-dependent.  We provide five different
  238. memory managers:
  239.  
  240. * jmemansi.c    This version uses the ANSI-standard library routine tmpfile(),
  241.         which not all non-ANSI systems have.  On some systems
  242.         tmpfile() may put the temporary file in a non-optimal
  243.         location; if you don't like what it does, use jmemname.c.
  244.  
  245. * jmemname.c    This version creates named temporary files.  For anything
  246.         except a Unix machine, you'll need to configure the
  247.         select_file_name() routine appropriately; see the comments
  248.         near the head of jmemname.c.  If you use this version, define
  249.         NEED_SIGNAL_CATCHER in jconfig.h to make sure the temp files
  250.         are removed if the program is aborted.
  251.  
  252. * jmemnobs.c    (That stands for No Backing Store :-).)  This will compile on
  253.         almost any system, but it assumes you have enough main memory
  254.         or virtual memory to hold the biggest images you work with.
  255.  
  256. * jmemdos.c    This should be used with most 16-bit MS-DOS compilers.
  257.         See the system-specific notes about MS-DOS for more info.
  258.         IMPORTANT: if you use this, define USE_MSDOS_MEMMGR in
  259.         jconfig.h, and include the assembly file jmemdosa.asm in the
  260.         programs.  The supplied makefiles and jconfig files for
  261.         16-bit MS-DOS compilers already do both.
  262.  
  263. * jmemmac.c    Custom version for Apple Macintosh; see the system-specific
  264.         notes for Macintosh for more info.
  265.  
  266. To use a particular memory manager, change the SYSDEPMEM variable in your
  267. makefile to equal the corresponding object file name (for example, jmemansi.o
  268. or jmemansi.obj for jmemansi.c).
  269.  
  270. If you have plenty of (real or virtual) main memory, just use jmemnobs.c.
  271. "Plenty" means about ten bytes for every pixel in the largest images
  272. you plan to process, so a lot of systems don't meet this criterion.
  273. If yours doesn't, try jmemansi.c first.  If that doesn't compile, you'll have
  274. to use jmemname.c; be sure to adjust select_file_name() for local conditions.
  275. You may also need to change unlink() to remove() in close_backing_store().
  276.  
  277. Except with jmemnobs.c or jmemmac.c, you need to adjust the DEFAULT_MAX_MEM
  278. setting to a reasonable value for your system (either by adding a #define for
  279. DEFAULT_MAX_MEM to jconfig.h, or by adding a -D switch to the Makefile).
  280. This value limits the amount of data space the program will attempt to
  281. allocate.  Code and static data space isn't counted, so the actual memory
  282. needs for cjpeg or djpeg are typically 100 to 150Kb more than the max-memory
  283. setting.  Larger max-memory settings reduce the amount of I/O needed to
  284. process a large image, but too large a value can result in "insufficient
  285. memory" failures.  On most Unix machines (and other systems with virtual
  286. memory), just set DEFAULT_MAX_MEM to several million and forget it.  At the
  287. other end of the spectrum, for MS-DOS machines you probably can't go much
  288. above 300K to 400K.  (On MS-DOS the value refers to conventional memory only.
  289. Extended/expanded memory is handled separately by jmemdos.c.)
  290.  
  291.  
  292. BUILDING THE SOFTWARE
  293. =====================
  294.  
  295. Now you should be able to compile the software.  Just say "make" (or
  296. whatever's necessary to start the compilation).  Have a cup of coffee.
  297.  
  298. Here are some things that could go wrong:
  299.  
  300. If your compiler complains about undefined structures, you should be able to
  301. shut it up by putting "#define INCOMPLETE_TYPES_BROKEN" in jconfig.h.
  302.  
  303. If you have trouble with missing system include files or inclusion of the
  304. wrong ones, read jinclude.h.  This shouldn't happen if you used configure
  305. or ckconfig.c to set up jconfig.h.
  306.  
  307. There are a fair number of routines that do not use all of their parameters;
  308. some compilers will issue warnings about this, which you can ignore.  There
  309. are also a few configuration checks that may give "unreachable code" warnings.
  310. Any other warning deserves investigation.
  311.  
  312. If you don't have a getenv() library routine, define NO_GETENV.
  313.  
  314. Also see the system-specific hints, below.
  315.  
  316.  
  317. TESTING THE SOFTWARE
  318. ====================
  319.  
  320. As a quick test of functionality we've included a small sample image in
  321. several forms:
  322.     testorig.jpg    Starting point for the djpeg tests.
  323.     testimg.ppm    The output of djpeg testorig.jpg
  324.     testimg.bmp    The output of djpeg -bmp -colors 256 testorig.jpg
  325.     testimg.jpg    The output of cjpeg testimg.ppm
  326.     testprog.jpg    Progressive-mode equivalent of testorig.jpg.
  327.     testimgp.jpg    The output of cjpeg -progressive -optimize testimg.ppm
  328. (The first- and second-generation .jpg files aren't identical since JPEG is
  329. lossy.)  If you can generate duplicates of the testimg* files then you
  330. probably have working programs.
  331.  
  332. With most of the makefiles, "make test" will perform the necessary
  333. comparisons.
  334.  
  335. If you're using a makefile that doesn't provide the test option, run djpeg
  336. and cjpeg by hand and compare the output files to testimg* with whatever
  337. binary file comparison tool you have.  The files should be bit-for-bit
  338. identical.
  339.  
  340. If the programs complain "MAX_ALLOC_CHUNK is wrong, please fix", then you
  341. need to reduce MAX_ALLOC_CHUNK to a value that fits in type size_t.
  342. Try adding "#define MAX_ALLOC_CHUNK 65520L" to jconfig.h.  A less likely
  343. configuration error is "ALIGN_TYPE is wrong, please fix": defining ALIGN_TYPE
  344. as long should take care of that one.
  345.  
  346. If the cjpeg test run fails with "Missing Huffman code table entry", it's a
  347. good bet that you needed to define RIGHT_SHIFT_IS_UNSIGNED.  Go back to the
  348. configuration step and run ckconfig.c.  (This is a good plan for any other
  349. test failure, too.)
  350.  
  351. If you are using Unix (one-file) command line style on a non-Unix system,
  352. it's a good idea to check that binary I/O through stdin/stdout actually
  353. works.  You should get the same results from "djpeg <testorig.jpg >out.ppm"
  354. as from "djpeg -outfile out.ppm testorig.jpg".  Note that the makefiles all
  355. use the latter style and therefore do not exercise stdin/stdout!  If this
  356. check fails, try recompiling with USE_SETMODE or USE_FDOPEN defined.
  357. If it still doesn't work, better use two-file style.
  358.  
  359. If you chose a memory manager other than jmemnobs.c, you should test that
  360. temporary-file usage works.  Try "djpeg -bmp -colors 256 -max 0 testorig.jpg"
  361. and make sure its output matches testimg.bmp.  If you have any really large
  362. images handy, try compressing them with -optimize and/or decompressing with
  363. -colors 256 to make sure your DEFAULT_MAX_MEM setting is not too large.
  364.  
  365. NOTE: this is far from an exhaustive test of the JPEG software; some modules,
  366. such as 1-pass color quantization, are not exercised at all.  It's just a
  367. quick test to give you some confidence that you haven't missed something
  368. major.
  369.  
  370.  
  371. INSTALLING THE SOFTWARE
  372. =======================
  373.  
  374. Once you're done with the above steps, you can install the software by
  375. copying the executable files (cjpeg, djpeg, jpegtran, rdjpgcom, and wrjpgcom)
  376. to wherever you normally install programs.  On Unix systems, you'll also want
  377. to put the man pages (cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1)
  378. in the man-page directory.  The pre-fab makefiles don't support this step
  379. since there's such a wide variety of installation procedures on different
  380. systems.
  381.  
  382. If you generated a Makefile with the "configure" script, you can just say
  383.     make install
  384. to install the programs and their man pages into the standard places.
  385. (You'll probably need to be root to do this.)  We recommend first saying
  386.     make -n install
  387. to see where configure thought the files should go.  You may need to edit
  388. the Makefile, particularly if your system's conventions for man page
  389. filenames don't match what configure expects.
  390.  
  391. If you want to install the IJG library itself, for use in compiling other
  392. programs besides ours, then you need to put the four include files
  393.     jpeglib.h jerror.h jconfig.h jmorecfg.h
  394. into your include-file directory, and put the library file libjpeg.a
  395. (extension may vary depending on system) wherever library files go.
  396. If you generated a Makefile with "configure", it will do what it thinks
  397. is the right thing if you say
  398.     make install-lib
  399.  
  400.  
  401. OPTIONAL STUFF
  402. ==============
  403.  
  404. Progress monitor:
  405.  
  406. If you like, you can #define PROGRESS_REPORT (in jconfig.h) to enable display
  407. of percent-done progress reports.  The routine provided in cdjpeg.c merely
  408. prints percentages to stderr, but you can customize it to do something
  409. fancier.
  410.  
  411. Utah RLE file format support:
  412.  
  413. We distribute the software with support for RLE image files (Utah Raster
  414. Toolkit format) disabled, because the RLE support won't compile without the
  415. Utah library.  If you have URT version 3.1 or later, you can enable RLE
  416. support as follows:
  417.     1.  #define RLE_SUPPORTED in jconfig.h.
  418.     2.  Add a -I option to CFLAGS in the Makefile for the directory
  419.         containing the URT .h files (typically the "include"
  420.         subdirectory of the URT distribution).
  421.     3.  Add -L... -lrle to LDLIBS in the Makefile, where ... specifies
  422.         the directory containing the URT "librle.a" file (typically the
  423.         "lib" subdirectory of the URT distribution).
  424.  
  425. Support for 12-bit-deep pixel data:
  426.  
  427. The JPEG standard allows either 8-bit or 12-bit data precision.  (For color,
  428. this means 8 or 12 bits per channel, of course.)  If you need to work with
  429. deeper than 8-bit data, you can compile the IJG code for 12-bit operation.
  430. To do so:
  431.   1. In jmorecfg.h, define BITS_IN_JSAMPLE as 12 rather than 8.
  432.   2. In jconfig.h, undefine BMP_SUPPORTED, RLE_SUPPORTED, and TARGA_SUPPORTED,
  433.      because the code for those formats doesn't handle 12-bit data and won't
  434.      even compile.  (The PPM code does work, as explained below.  The GIF
  435.      code works too; it scales 8-bit GIF data to and from 12-bit depth
  436.      automatically.)
  437.   3. Compile.  Don't expect "make test" to pass, since the supplied test
  438.      files are for 8-bit data.
  439.  
  440. Currently, 12-bit support does not work on 16-bit-int machines.
  441.  
  442. Note that a 12-bit version will not read 8-bit JPEG files, nor vice versa;
  443. so you'll want to keep around a regular 8-bit compilation as well.
  444. (Run-time selection of data depth, to allow a single copy that does both,
  445. is possible but would probably slow things down considerably; it's very low
  446. on our to-do list.)
  447.  
  448. The PPM reader (rdppm.c) can read 12-bit data from either text-format or
  449. binary-format PPM and PGM files.  Binary-format PPM/PGM files which have a
  450. maxval greater than 255 are assumed to use 2 bytes per sample, LSB first
  451. (little-endian order).  As of early 1995, 2-byte binary format is not
  452. officially supported by the PBMPLUS library, but it is expected that a
  453. future release of PBMPLUS will support it.  Note that the PPM reader will
  454. read files of any maxval regardless of the BITS_IN_JSAMPLE setting; incoming
  455. data is automatically rescaled to either maxval=255 or maxval=4095 as
  456. appropriate for the cjpeg bit depth.
  457.  
  458. The PPM writer (wrppm.c) will normally write 2-byte binary PPM or PGM
  459. format, maxval 4095, when compiled with BITS_IN_JSAMPLE=12.  Since this
  460. format is not yet widely supported, you can disable it by compiling wrppm.c
  461. with PPM_NORAWWORD defined; then the data is scaled down to 8 bits to make a
  462. standard 1-byte/sample PPM or PGM file.  (Yes, this means still another copy
  463. of djpeg to keep around.  But hopefully you won't need it for very long.
  464. Poskanzer's supposed to get that new PBMPLUS release out Real Soon Now.)
  465.  
  466. Of course, if you are working with 12-bit data, you probably have it stored
  467. in some other, nonstandard format.  In that case you'll probably want to
  468. write your own I/O modules to read and write your format.
  469.  
  470. Note that a 12-bit version of cjpeg always runs in "-optimize" mode, in
  471. order to generate valid Huffman tables.  This is necessary because our
  472. default Huffman tables only cover 8-bit data.
  473.  
  474. Removing code:
  475.  
  476. If you need to make a smaller version of the JPEG software, some optional
  477. functions can be removed at compile time.  See the xxx_SUPPORTED #defines in
  478. jconfig.h and jmorecfg.h.  If at all possible, we recommend that you leave in
  479. decoder support for all valid JPEG files, to ensure that you can read anyone's
  480. output.  Taking out support for image file formats that you don't use is the
  481. most painless way to make the programs smaller.  Another possibility is to
  482. remove some of the DCT methods: in particular, the "IFAST" method may not be
  483. enough faster than the others to be worth keeping on your machine.  (If you
  484. do remove ISLOW or IFAST, be sure to redefine JDCT_DEFAULT or JDCT_FASTEST
  485. to a supported method, by adding a #define in jconfig.h.)
  486.  
  487.  
  488. OPTIMIZATION
  489. ============
  490.  
  491. Unless you own a Cray, you'll probably be interested in making the JPEG
  492. software go as fast as possible.  This section covers some machine-dependent
  493. optimizations you may want to try.  We suggest that before trying any of
  494. this, you first get the basic installation to pass the self-test step.
  495. Repeat the self-test after any optimization to make sure that you haven't
  496. broken anything.
  497.  
  498. The integer DCT routines perform a lot of multiplications.  These
  499. multiplications must yield 32-bit results, but none of their input values
  500. are more than 16 bits wide.  On many machines, notably the 680x0 and 80x86
  501. CPUs, a 16x16=>32 bit multiply instruction is faster than a full 32x32=>32
  502. bit multiply.  Unfortunately there is no portable way to specify such a
  503. multiplication in C, but some compilers can generate one when you use the
  504. right combination of casts.  See the MULTIPLYxxx macro definitions in
  505. jdct.h.  If your compiler makes "int" be 32 bits and "short" be 16 bits,
  506. defining SHORTxSHORT_32 is fairly likely to work.  When experimenting with
  507. alternate definitions, be sure to test not only whether the code still works
  508. (use the self-test), but also whether it is actually faster --- on some
  509. compilers, alternate definitions may compute the right answer, yet be slower
  510. than the default.  Timing cjpeg on a large PGM (grayscale) input file is the
  511. best way to check this, as the DCT will be the largest fraction of the runtime
  512. in that mode.  (Note: some of the distributed compiler-specific jconfig files
  513. already contain #define switches to select appropriate MULTIPLYxxx
  514. definitions.)
  515.  
  516. If your machine has sufficiently fast floating point hardware, you may find
  517. that the float DCT method is faster than the integer DCT methods, even
  518. after tweaking the integer multiply macros.  In that case you may want to
  519. make the float DCT be the default method.  (The only objection to this is
  520. that float DCT results may vary slightly across machines.)  To do that, add
  521. "#define JDCT_DEFAULT JDCT_FLOAT" to jconfig.h.  Even if you don't change
  522. the default, you should redefine JDCT_FASTEST, which is the method selected
  523. by djpeg's -fast switch.  Don't forget to update the documentation files
  524. (usage.doc and/or cjpeg.1, djpeg.1) to agree with what you've done.
  525.  
  526. If access to "short" arrays is slow on your machine, it may be a win to
  527. define type JCOEF as int rather than short.  This will cost a good deal of
  528. memory though, particularly in some multi-pass modes, so don't do it unless
  529. you have memory to burn and short is REALLY slow.
  530.  
  531. If your compiler can compile function calls in-line, make sure the INLINE
  532. macro in jmorecfg.h is defined as the keyword that marks a function
  533. inline-able.  Some compilers have a switch that tells the compiler to inline
  534. any function it thinks is profitable (e.g., -finline-functions for gcc).
  535. Enabling such a switch is likely to make the compiled code bigger but faster.
  536.  
  537. In general, it's worth trying the maximum optimization level of your compiler,
  538. and experimenting with any optional optimizations such as loop unrolling.
  539. (Unfortunately, far too many compilers have optimizer bugs ... be prepared to
  540. back off if the code fails self-test.)  If you do any experimentation along
  541. these lines, please report the optimal settings to jpeg-info@uunet.uu.net so
  542. we can mention them in future releases.  Be sure to specify your machine and
  543. compiler version.
  544.  
  545.  
  546. HINTS FOR SPECIFIC SYSTEMS
  547. ==========================
  548.  
  549. We welcome reports on changes needed for systems not mentioned here.  Submit
  550. 'em to jpeg-info@uunet.uu.net.  Also, if configure or ckconfig.c is wrong
  551. about how to configure the JPEG software for your system, please let us know.
  552.  
  553.  
  554. Acorn RISC OS:
  555.  
  556. (Thanks to Simon Middleton for these hints on compiling with Desktop C.)
  557. After renaming the files according to Acorn conventions, take a copy of
  558. makefile.ansi, change all occurrences of 'libjpeg.a' to 'libjpeg.o' and
  559. change these definitions as indicated:
  560.  
  561. CFLAGS= -throwback -IC: -Wn
  562. LDLIBS=C:o.Stubs
  563. SYSDEPMEM=jmemansi.o
  564. LN=Link
  565. AR=LibFile -c -o
  566.  
  567. Also add a new line '.c.o:; $(cc) $< $(cflags) -c -o $@'.  Remove the
  568. lines '$(RM) libjpeg.o' and '$(AR2) libjpeg.o' and the 'jconfig.h'
  569. dependency section.
  570.  
  571. Copy jconfig.doc to jconfig.h.  Edit jconfig.h to define TWO_FILE_COMMANDLINE
  572. and CHAR_IS_UNSIGNED.
  573.  
  574. Run the makefile using !AMU not !Make.  If you want to use the 'clean' and
  575. 'test' makefile entries then you will have to fiddle with the syntax a bit
  576. and rename the test files.
  577.  
  578.  
  579. Amiga:
  580.  
  581. SAS C 6.50 reportedly is too buggy to compile the IJG code properly.
  582. A patch to update to 6.51 is available from SAS or AmiNet FTP sites.
  583.  
  584. The supplied config files are set up to use jmemname.c as the memory
  585. manager, with temporary files being created on the device named by
  586. "JPEGTMP:".
  587.  
  588.  
  589. Atari ST/STE/TT:
  590.  
  591. Copy the project files makcjpeg.st, makdjpeg.st, maktjpeg.st, and makljpeg.st
  592. to cjpeg.prj, djpeg.prj, jpegtran.prj, and libjpeg.prj respectively.  The
  593. project files should work as-is with Pure C.  For Turbo C, change library
  594. filenames "pc..." to "tc..." in each project file.  Note that libjpeg.prj
  595. selects jmemansi.c as the recommended memory manager.  You'll probably want to
  596. adjust the DEFAULT_MAX_MEM setting --- you want it to be a couple hundred K
  597. less than your normal free memory.  Put "#define DEFAULT_MAX_MEM nnnn" into
  598. jconfig.h to do this.
  599.  
  600. To use the 68881/68882 coprocessor for the floating point DCT, add the
  601. compiler option "-8" to the project files and replace pcfltlib.lib with
  602. pc881lib.lib in cjpeg.prj and djpeg.prj.  Or if you don't have a
  603. coprocessor, you may prefer to remove the float DCT code by undefining
  604. DCT_FLOAT_SUPPORTED in jmorecfg.h (since without a coprocessor, the float
  605. code will be too slow to be useful).  In that case, you can delete
  606. pcfltlib.lib from the project files.
  607.  
  608. Note that you must make libjpeg.lib before making cjpeg.ttp, djpeg.ttp,
  609. or jpegtran.ttp.  You'll have to perform the self-test by hand.
  610.  
  611. We haven't bothered to include project files for rdjpgcom and wrjpgcom.
  612. Those source files should just be compiled by themselves; they don't
  613. depend on the JPEG library.
  614.  
  615. There is a bug in some older versions of the Turbo C library which causes the
  616. space used by temporary files created with "tmpfile()" not to be freed after
  617. an abnormal program exit.  If you check your disk afterwards, you will find
  618. cluster chains that are allocated but not used by a file.  This should not
  619. happen in cjpeg/djpeg/jpegtran, since we enable a signal catcher to explicitly
  620. close temp files before exiting.  But if you use the JPEG library with your
  621. own code, be sure to supply a signal catcher, or else use a different
  622. system-dependent memory manager.
  623.  
  624.  
  625. Cray:
  626.  
  627. Should you be so fortunate as to be running JPEG on a Cray YMP, there is a
  628. compiler bug in old versions of Cray's Standard C (prior to 3.1).  If you
  629. still have an old compiler, you'll need to insert a line reading
  630. "#pragma novector" just before the loop    
  631.     for (i = 1; i <= (int) htbl->bits[l]; i++)
  632.       huffsize[p++] = (char) l;
  633. in fix_huff_tbl (in V5beta1, line 204 of jchuff.c and line 176 of jdhuff.c).
  634. [This bug may or may not still occur with the current IJG code, but it's
  635. probably a dead issue anyway...]
  636.  
  637.  
  638. HP-UX:
  639.  
  640. If you have HP-UX 7.05 or later with the "software development" C compiler,
  641. you should run the compiler in ANSI mode.  If using the configure script,
  642. say
  643.     ./configure CC='cc -Aa'
  644. (or -Ae if you prefer).  If configuring by hand, use makefile.ansi and add
  645. "-Aa" to the CFLAGS line in the makefile.
  646.  
  647. If you have a pre-7.05 system, or if you are using the non-ANSI C compiler
  648. delivered with a minimum HP-UX system, then you must use makefile.unix
  649. (and do NOT add -Aa); or just run configure without the CC option.
  650.  
  651. On HP 9000 series 800 machines, the HP C compiler is buggy in revisions prior
  652. to A.08.07.  If you get complaints about "not a typedef name", you'll have to
  653. use makefile.unix, or run configure without the CC option.
  654.  
  655.  
  656. Macintosh, generic comments:
  657.  
  658. The supplied user-interface files (cjpeg.c, djpeg.c, etc) are set up to
  659. provide a Unix-style command line interface.  You can use this interface on
  660. the Mac by means of the ccommand() library routine provided by Metrowerks
  661. CodeWarrior or Think C.  This is only appropriate for testing the library,
  662. however; to make a user-friendly equivalent of cjpeg/djpeg you'd really want
  663. to develop a Mac-style user interface.  There isn't a complete example
  664. available at the moment, but there are some helpful starting points:
  665. 1. Sam Bushell's free "To JPEG" applet provides drag-and-drop conversion to
  666. JPEG under System 7 and later.  This only illustrates how to use the
  667. compression half of the library, but it does a very nice job of that part.
  668. The CodeWarrior source code is available from http://www.pobox.com/~jsam.
  669. 2. Jim Brunner prepared a Mac-style user interface for both compression and
  670. decompression.  Unfortunately, it hasn't been updated since IJG v4, and
  671. the library's API has changed considerably since then.  Still it may be of
  672. some help, particularly as a guide to compiling the IJG code under Think C.
  673. Jim's code is available from the Info-Mac archives, at sumex-aim.stanford.edu
  674. or mirrors thereof; see file /info-mac/dev/src/jpeg-convert-c.hqx.
  675.  
  676. jmemmac.c is the recommended memory manager back end for Macintosh.  It uses
  677. NewPtr/DisposePtr instead of malloc/free, and has a Mac-specific
  678. implementation of jpeg_mem_available().  It also creates temporary files that
  679. follow Mac conventions.  (That part of the code relies on System-7-or-later OS
  680. functions.  See the comments in jmemmac.c if you need to run it on System 6.)
  681. NOTE that USE_MAC_MEMMGR must be defined in jconfig.h to use jmemmac.c.
  682.  
  683. You can also use jmemnobs.c, if you don't care about handling images larger
  684. than available memory.  If you use any memory manager back end other than
  685. jmemmac.c, we recommend replacing "malloc" and "free" by "NewPtr" and
  686. "DisposePtr", because Mac C libraries often have peculiar implementations of
  687. malloc/free.  (For instance, free() may not return the freed space to the
  688. Mac Memory Manager.  This is undesirable for the IJG code because jmemmgr.c
  689. already clumps space requests.)
  690.  
  691.  
  692. Macintosh, Metrowerks CodeWarrior:
  693.  
  694. The Unix-command-line-style interface can be used by defining USE_CCOMMAND.
  695. You'll also need to define TWO_FILE_COMMANDLINE to avoid stdin/stdout.
  696. This means that when using the cjpeg/djpeg programs, you'll have to type the
  697. input and output file names in the "Arguments" text-edit box, rather than
  698. using the file radio buttons.  (Perhaps USE_FDOPEN or USE_SETMODE would
  699. eliminate the problem, but I haven't heard from anyone who's tried it.)
  700.  
  701. On 680x0 Macs, Metrowerks defines type "double" as a 10-byte IEEE extended
  702. float.  jmemmgr.c won't like this: it wants sizeof(ALIGN_TYPE) to be a power
  703. of 2.  Add "#define ALIGN_TYPE long" to jconfig.h to eliminate the complaint.
  704.  
  705. The supplied configuration file jconfig.mac can be used for your jconfig.h;
  706. it includes all the recommended symbol definitions.  If you have AppleScript
  707. installed, you can run the supplied script makeproj.mac to create CodeWarrior
  708. project files for the library and the testbed applications, then build the
  709. library and applications.  (Thanks to Dan Sears and Don Agro for this nifty
  710. hack, which saves us from trying to maintain CodeWarrior project files as part
  711. of the IJG distribution...)
  712.  
  713.  
  714. Macintosh, Think C:
  715.  
  716. The documentation in Jim Brunner's "JPEG Convert" source code (see above)
  717. includes detailed build instructions for Think C; it's probably somewhat
  718. out of date for the current release, but may be helpful.
  719.  
  720. If you want to build the minimal command line version, proceed as follows.
  721. You'll have to prepare project files for the programs; we don't include any
  722. in the distribution since they are not text files.  Use the file lists in
  723. any of the supplied makefiles as a guide.  Also add the ANSI and Unix C
  724. libraries in a separate segment.  You may need to divide the JPEG files into
  725. more than one segment; we recommend dividing compression and decompression
  726. modules.  Define USE_CCOMMAND in jconfig.h so that the ccommand() routine is
  727. called.  You must also define TWO_FILE_COMMANDLINE because stdin/stdout
  728. don't handle binary data correctly.
  729.  
  730. On 680x0 Macs, Think C defines type "double" as a 12-byte IEEE extended float.
  731. jmemmgr.c won't like this: it wants sizeof(ALIGN_TYPE) to be a power of 2.
  732. Add "#define ALIGN_TYPE long" to jconfig.h to eliminate the complaint.
  733.  
  734. jconfig.mac should work as a jconfig.h configuration file for Think C,
  735. but the makeproj.mac AppleScript script is specific to CodeWarrior.  Sorry.
  736.  
  737.  
  738. MIPS R3000:
  739.  
  740. MIPS's cc version 1.31 has a rather nasty optimization bug.  Don't use -O
  741. if you have that compiler version.  (Use "cc -V" to check the version.)
  742. Note that the R3000 chip is found in workstations from DEC and others.
  743.  
  744.  
  745. MS-DOS, generic comments for 16-bit compilers:
  746.  
  747. The IJG code is designed to work well in 80x86 "small" or "medium" memory
  748. models (i.e., data pointers are 16 bits unless explicitly declared "far";
  749. code pointers can be either size).  You may be able to use small model to
  750. compile cjpeg or djpeg by itself, but you will probably have to use medium
  751. model for any larger application.  This won't make much difference in
  752. performance.  You *will* take a noticeable performance hit if you use a
  753. large-data memory model, and you should avoid "huge" model if at all
  754. possible.  Be sure that NEED_FAR_POINTERS is defined in jconfig.h if you use
  755. a small-data memory model; be sure it is NOT defined if you use a large-data
  756. model.  (The supplied makefiles and jconfig files for Borland and Microsoft C
  757. compile in medium model and define NEED_FAR_POINTERS.)
  758.  
  759. The DOS-specific memory manager, jmemdos.c, should be used if possible.
  760. It needs some assembly-code routines which are in jmemdosa.asm; make sure
  761. your makefile assembles that file and includes it in the library.  If you
  762. don't have a suitable assembler, you can get pre-assembled object files for
  763. jmemdosa by FTP from ftp.uu.net:/graphics/jpeg/jdosaobj.zip.  (DOS-oriented
  764. distributions of the IJG source code often include these object files.)
  765.  
  766. When using jmemdos.c, jconfig.h must define USE_MSDOS_MEMMGR and must set
  767. MAX_ALLOC_CHUNK to less than 64K (65520L is a typical value).  If your
  768. C library's far-heap malloc() can't allocate blocks that large, reduce
  769. MAX_ALLOC_CHUNK to whatever it can handle.
  770.  
  771. If you can't use jmemdos.c for some reason --- for example, because you
  772. don't have an assembler to assemble jmemdosa.asm --- you'll have to fall
  773. back to jmemansi.c or jmemname.c.  You'll probably still need to set
  774. MAX_ALLOC_CHUNK in jconfig.h, because most DOS C libraries won't malloc()
  775. more than 64K at a time.  IMPORTANT: if you use jmemansi.c or jmemname.c,
  776. you will have to compile in a large-data memory model in order to get the
  777. right stdio library.  Too bad.
  778.  
  779. wrjpgcom needs to be compiled in large model, because it malloc()s a 64KB
  780. work area to hold the comment text.  If your C library's malloc can't
  781. handle that, reduce MAX_COM_LENGTH as necessary in wrjpgcom.c.
  782.  
  783. Most MS-DOS compilers treat stdin/stdout as text files, so you must use
  784. two-file command line style.  But if your compiler has either fdopen() or
  785. setmode(), you can use one-file style if you like.  To do this, define
  786. USE_SETMODE or USE_FDOPEN so that stdin/stdout will be set to binary mode.
  787. (USE_SETMODE seems to work with more DOS compilers than USE_FDOPEN.)  You
  788. should test that I/O through stdin/stdout produces the same results as I/O
  789. to explicitly named files... the "make test" procedures in the supplied
  790. makefiles do NOT use stdin/stdout.
  791.  
  792.  
  793. MS-DOS, generic comments for 32-bit compilers:
  794.  
  795. None of the above comments about memory models apply if you are using a
  796. 32-bit flat-memory-space environment, such as DJGPP or Watcom C.  (And you
  797. should use one if you have it, as performance will be much better than
  798. 8086-compatible code!)  For flat-memory-space compilers, do NOT define
  799. NEED_FAR_POINTERS, and do NOT use jmemdos.c.  Use jmemnobs.c if the
  800. environment supplies adequate virtual memory, otherwise use jmemansi.c or
  801. jmemname.c.
  802.  
  803. You'll still need to be careful about binary I/O through stdin/stdout.
  804. See the last paragraph of the previous section.
  805.  
  806.  
  807. MS-DOS, Borland C:
  808.  
  809. Be sure to convert all the source files to DOS text format (CR/LF newlines).
  810. Although Borland C will often work OK with unmodified Unix (LF newlines)
  811. source files, sometimes it will give bogus compile errors.
  812. "Illegal character '#'" is the most common such error.  (This is true with
  813. Borland C 3.1, but perhaps is fixed in newer releases.)
  814.  
  815. If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE.
  816. jconfig.bcc already includes #define USE_SETMODE to make this work.
  817. (fdopen does not work correctly.)
  818.  
  819.  
  820. MS-DOS, Microsoft C:
  821.  
  822. makefile.mc6 works with Microsoft C, DOS Visual C++, etc.  It should only
  823. be used if you want to build a 16-bit (small or medium memory model) program.
  824.  
  825. If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE.
  826. jconfig.mc6 already includes #define USE_SETMODE to make this work.
  827. (fdopen does not work correctly.)
  828.  
  829. Note that this makefile assumes that the working copy of itself is called
  830. "makefile".  If you want to call it something else, say "makefile.mak",
  831. be sure to adjust the dependency line that reads "$(RFILE) : makefile".
  832. Otherwise the make will fail because it doesn't know how to create "makefile".
  833. Worse, some releases of Microsoft's make utilities give an incorrect error
  834. message in this situation.
  835.  
  836. Old versions of MS C fail with an "out of macro expansion space" error
  837. because they can't cope with the macro TRACEMS8 (defined in jerror.h).
  838. If this happens to you, the easiest solution is to change TRACEMS8 to
  839. expand to nothing.  You'll lose the ability to dump out JPEG coefficient
  840. tables with djpeg -debug -debug, but at least you can compile.
  841.  
  842. Original MS C 6.0 is very buggy; it compiles incorrect code unless you turn
  843. off optimization entirely (remove -O from CFLAGS).  6.00A is better, but it
  844. still generates bad code if you enable loop optimizations (-Ol or -Ox).
  845.  
  846. MS C 8.0 crashes when compiling jquant1.c with optimization switch /Oo ...
  847. which is on by default.  To work around this bug, compile that one file
  848. with /Oo-.
  849.  
  850.  
  851. Microsoft Windows (all versions), generic comments:
  852.  
  853. Some Windows system include files define typedef boolean as "unsigned char".
  854. The IJG code also defines typedef boolean, but we make it "int" by default.
  855. This doesn't affect the IJG programs because we don't import those Windows
  856. include files.  But if you use the JPEG library in your own program, and some
  857. of your program's files import one definition of boolean while some import the
  858. other, you can get all sorts of mysterious problems.  A good preventive step
  859. is to make the IJG library use "unsigned char" for boolean.  To do that,
  860. add something like this to your jconfig.h file:
  861.     /* Define "boolean" as unsigned char, not int, per Windows custom */
  862.     #ifndef __RPCNDR_H__    /* don't conflict if rpcndr.h already read */
  863.     typedef unsigned char boolean;
  864.     #endif
  865.     #define HAVE_BOOLEAN    /* prevent jmorecfg.h from redefining it */
  866. (This is already in jconfig.vc, by the way.)
  867.  
  868. windef.h contains the declarations
  869.     #define far
  870.     #define FAR far
  871. Since jmorecfg.h tries to define FAR as empty, you may get a compiler
  872. warning if you include both jpeglib.h and windef.h (which windows.h
  873. includes).  To suppress the warning, you can put "#ifndef FAR"/"#endif"
  874. around the line "#define FAR" in jmorecfg.h.
  875.  
  876. When using the library in a Windows application, you will almost certainly
  877. want to modify or replace the error handler module jerror.c, since our
  878. default error handler does a couple of inappropriate things:
  879.   1. it tries to write error and warning messages on stderr;
  880.   2. in event of a fatal error, it exits by calling exit().
  881.  
  882. A simple stopgap solution for problem 1 is to replace the line
  883.     fprintf(stderr, "%s\n", buffer);
  884. (in output_message in jerror.c) with
  885.     MessageBox(GetActiveWindow(),buffer,"JPEG Error",MB_OK|MB_ICONERROR);
  886. It's highly recommended that you at least do that much, since otherwise
  887. error messages will disappear into nowhere.  (Beginning with IJG v6b, this
  888. code is already present in jerror.c; just define USE_WINDOWS_MESSAGEBOX in
  889. jconfig.h to enable it.)
  890.  
  891. The proper solution for problem 2 is to return control to your calling
  892. application after a library error.  This can be done with the setjmp/longjmp
  893. technique discussed in libjpeg.doc and illustrated in example.c.  (NOTE:
  894. some older Windows C compilers provide versions of setjmp/longjmp that
  895. don't actually work under Windows.  You may need to use the Windows system
  896. functions Catch and Throw instead.)
  897.  
  898. The recommended memory manager under Windows is jmemnobs.c; in other words,
  899. let Windows do any virtual memory management needed.  You should NOT use
  900. jmemdos.c nor jmemdosa.asm under Windows.
  901.  
  902. For Windows 3.1, we recommend compiling in medium or large memory model;
  903. for newer Windows versions, use a 32-bit flat memory model.  (See the MS-DOS
  904. sections above for more info about memory models.)  In the 16-bit memory
  905. models only, you'll need to put
  906.     #define MAX_ALLOC_CHUNK 65520L    /* Maximum request to malloc() */
  907. into jconfig.h to limit allocation chunks to 64Kb.  (Without that, you'd
  908. have to use huge memory model, which slows things down unnecessarily.)
  909. jmemnobs.c works without modification in large or flat memory models, but to
  910. use medium model, you need to modify its jpeg_get_large and jpeg_free_large
  911. routines to allocate far memory.  In any case, you might like to replace
  912. its calls to malloc and free with direct calls on Windows memory allocation
  913. functions.
  914.  
  915. You may also want to modify jdatasrc.c and jdatadst.c to use Windows file
  916. operations rather than fread/fwrite.  This is only necessary if your C
  917. compiler doesn't provide a competent implementation of C stdio functions.
  918.  
  919. You might want to tweak the RGB_xxx macros in jmorecfg.h so that the library
  920. will accept or deliver color pixels in BGR sample order, not RGB; BGR order
  921. is usually more convenient under Windows.  Note that this change will break
  922. the sample applications cjpeg/djpeg, but the library itself works fine.
  923.  
  924.  
  925. Many people want to convert the IJG library into a DLL.  This is reasonably
  926. straightforward, but watch out for the following:
  927.  
  928.   1. Don't try to compile as a DLL in small or medium memory model; use
  929. large model, or even better, 32-bit flat model.  Many places in the IJG code
  930. assume the address of a local variable is an ordinary (not FAR) pointer;
  931. that isn't true in a medium-model DLL.
  932.  
  933.   2. Microsoft C cannot pass file pointers between applications and DLLs.
  934. (See Microsoft Knowledge Base, PSS ID Number Q50336.)  So jdatasrc.c and
  935. jdatadst.c don't work if you open a file in your application and then pass
  936. the pointer to the DLL.  One workaround is to make jdatasrc.c/jdatadst.c
  937. part of your main application rather than part of the DLL.
  938.  
  939.   3. You'll probably need to modify the macros GLOBAL() and EXTERN() to
  940. attach suitable linkage keywords to the exported routine names.  Similarly,
  941. you'll want to modify METHODDEF() and JMETHOD() to ensure function pointers
  942. are declared in a way that lets application routines be called back through
  943. the function pointers.  These macros are in jmorecfg.h.  Typical definitions
  944. for a 16-bit DLL are:
  945.     #define GLOBAL(type)        type _far _pascal _loadds _export
  946.     #define EXTERN(type)        extern type _far _pascal _loadds
  947.     #define METHODDEF(type)        static type _far _pascal
  948.     #define JMETHOD(type,methodname,arglist)  \
  949.         type (_far _pascal *methodname) arglist
  950. For a 32-bit DLL you may want something like
  951.     #define GLOBAL(type)        __declspec(dllexport) type
  952.     #define EXTERN(type)        extern __declspec(dllexport) type
  953. Although not all the GLOBAL routines are actually intended to be called by
  954. the application, the performance cost of making them all DLL entry points is
  955. negligible.
  956.  
  957. The unmodified IJG library presents a very C-specific application interface,
  958. so the resulting DLL is only usable from C or C++ applications.  There has
  959. been some talk of writing wrapper code that would present a simpler interface
  960. usable from other languages, such as Visual Basic.  This is on our to-do list
  961. but hasn't been very high priority --- any volunteers out there?
  962.  
  963.  
  964. Microsoft Windows, Borland C:
  965.  
  966. The provided jconfig.bcc should work OK in a 32-bit Windows environment,
  967. but you'll need to tweak it in a 16-bit environment (you'd need to define
  968. NEED_FAR_POINTERS and MAX_ALLOC_CHUNK).  Beware that makefile.bcc will need
  969. alteration if you want to use it for Windows --- in particular, you should
  970. use jmemnobs.c not jmemdos.c under Windows.
  971.  
  972. Borland C++ 4.5 fails with an internal compiler error when trying to compile
  973. jdmerge.c in 32-bit mode.  If enough people complain, perhaps Borland will fix
  974. it.  In the meantime, the simplest known workaround is to add a redundant
  975. definition of the variable range_limit in h2v1_merged_upsample(), at the head
  976. of the block that handles odd image width (about line 268 in v6 jdmerge.c):
  977.   /* If image width is odd, do the last output column separately */
  978.   if (cinfo->output_width & 1) {
  979.     register JSAMPLE * range_limit = cinfo->sample_range_limit; /* ADD THIS */
  980.     cb = GETJSAMPLE(*inptr1);
  981. Pretty bizarre, especially since the very similar routine h2v2_merged_upsample
  982. doesn't trigger the bug.
  983. Recent reports suggest that this bug does not occur with "bcc32a" (the
  984. Pentium-optimized version of the compiler).
  985.  
  986. Another report from a user of Borland C 4.5 was that incorrect code (leading
  987. to a color shift in processed images) was produced if any of the following
  988. optimization switch combinations were used: 
  989.     -Ot -Og
  990.     -Ot -Op
  991.     -Ot -Om
  992. So try backing off on optimization if you see such a problem.  (Are there
  993. several different releases all numbered "4.5"??)
  994.  
  995.  
  996. Microsoft Windows, Microsoft Visual C++:
  997.  
  998. jconfig.vc should work OK with any Microsoft compiler for a 32-bit memory
  999. model.  makefile.vc is intended for command-line use.  (If you are using
  1000. the Developer Studio environment, you may prefer the DevStudio project
  1001. files; see below.)
  1002.  
  1003. Some users feel that it's easier to call the library from C++ code if you
  1004. force VC++ to treat the library as C++ code, which you can do by renaming
  1005. all the *.c files to *.cpp (and adjusting the makefile to match).  This
  1006. avoids the need to put extern "C" { ... } around #include "jpeglib.h" in
  1007. your C++ application.
  1008.  
  1009.  
  1010. Microsoft Windows, Microsoft Developer Studio:
  1011.  
  1012. We include makefiles that should work as project files in DevStudio 4.2 or
  1013. later.  There is a library makefile that builds the IJG library as a static
  1014. Win32 library, and an application makefile that builds the sample applications
  1015. as Win32 console applications.  (Even if you only want the library, we
  1016. recommend building the applications so that you can run the self-test.)
  1017.  
  1018. To use:
  1019. 1. Copy jconfig.vc to jconfig.h, makelib.ds to jpeg.mak, and
  1020.    makeapps.ds to apps.mak.  (Note that the renaming is critical!)
  1021. 2. Click on the .mak files to construct project workspaces.
  1022.    (If you are using DevStudio more recent than 4.2, you'll probably
  1023.    get a message saying that the makefiles are being updated.)
  1024. 3. Build the library project, then the applications project.
  1025. 4. Move the application .exe files from `app`\Release to an
  1026.    appropriate location on your path.
  1027. 5. To perform the self-test, execute the command line
  1028.     NMAKE /f makefile.vc  test
  1029.  
  1030.  
  1031. OS/2, Borland C++:
  1032.  
  1033. Watch out for optimization bugs in older Borland compilers; you may need
  1034. to back off the optimization switch settings.  See the comments in
  1035. makefile.bcc.
  1036.  
  1037.  
  1038. SGI:
  1039.  
  1040. On some SGI systems, you may need to set "AR2= ar -ts" in the Makefile.
  1041. If you are using configure, you can do this by saying
  1042.     ./configure RANLIB='ar -ts'
  1043. This change is not needed on all SGIs.  Use it only if the make fails at the
  1044. stage of linking the completed programs.
  1045.  
  1046. On the MIPS R4000 architecture (Indy, etc.), the compiler option "-mips2"
  1047. reportedly speeds up the float DCT method substantially, enough to make it
  1048. faster than the default int method (but still slower than the fast int
  1049. method).  If you use -mips2, you may want to alter the default DCT method to
  1050. be float.  To do this, put "#define JDCT_DEFAULT JDCT_FLOAT" in jconfig.h.
  1051.  
  1052.  
  1053. VMS:
  1054.  
  1055. On an Alpha/VMS system with MMS, be sure to use the "/Marco=Alpha=1"
  1056. qualifier with MMS when building the JPEG package.
  1057.  
  1058. VAX/VMS v5.5-1 may have problems with the test step of the build procedure
  1059. reporting differences when it compares the original and test images.  If the
  1060. error points to the last block of the files, it is most likely bogus and may
  1061. be safely ignored.  It seems to be because the files are Stream_LF and
  1062. Backup/Compare has difficulty with the (presumably) null padded files.
  1063. This problem was not observed on VAX/VMS v6.1 or AXP/VMS v6.1.
  1064.