|
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. |