Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/misc/volume34/jpeg/part09

Text File | 1992-12-16 | 58.9 KB | 1,210 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Independent JPEG Group)
Subject:  v34i063:  jpeg - JPEG image compression, Part09/18
Message-ID: <[e-mail]>
X-Md4-Signature: 31715189cae6a7e3a9a26e8d63e5ad16
Date: Thu, 17 Dec 1992 04:18:49 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Independent JPEG Group)
Posting-number: Volume 34, Issue 63
Archive-name: jpeg/part09
Environment: UNIX, VMS, MS-DOS, Mac, Amiga, Atari, Cray
Supersedes: jpeg: Volume 29, Issue 1-18

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then feed it
# into a shell via "sh file" or similar.  To overwrite existing files,
# type "sh file -c".
# Contents:  SETUP architecture.A jinclude.h
# Wrapped by kent@sparky on Wed Dec 16 20:52:28 1992
PATH=/bin:/usr/bin:/usr/ucb:/usr/local/bin:/usr/lbin ; export PATH
echo If this archive is complete, you will see the following message:
echo '          "shar: End of archive 9 (of 18)."'
if test -f 'SETUP' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'SETUP'\"
else
  echo shar: Extracting \"'SETUP'\" \(26242 characters\)
  sed "s/^X//" >'SETUP' <<'END_OF_FILE'
XSETUP instructions for the Independent JPEG Group's JPEG software
X=================================================================
X
XThis file explains how to configure and compile the JPEG software.  We have
Xtried to make this software extremely portable and flexible, so that it can be
Xadapted to almost any environment.  The downside of this decision is that the
Xinstallation process is not very automatic; you will need at least a little
Xfamiliarity with C programming and program build procedures for your system.
X
XThis file contains general instructions, then sections of specific hints for
Xcertain systems.  You may save yourself considerable time if you scan the
Xwhole file before starting to do anything.
X
XBefore installing the software you must unpack the distributed source code.
XSince you are reading this file, you have probably already succeeded in this
Xtask.  However, there is one potential trap if you are on a non-Unix system:
Xyou may need to convert these files to the local standard text file format
X(for example, if you are on MS-DOS you probably have to convert LF end-of-line
Xto CR/LF).  If so, apply the conversion to all the files EXCEPT those whose
Xnames begin with "test".  The test files contain binary data; if you change
Xthem in any way then the self-test will give bad results.
X
X
XSTEP 1: PREPARE A MAKEFILE
X==========================
X
XFirst, select a makefile and copy it to "Makefile" (or whatever your version
Xof make uses as the default makefile name; for example, "makefile.mak" for
Xold versions of Borland C).  We include several standard makefiles in the
Xdistribution:
X
X    makefile.ansi:    for Unix systems with ANSI-compatible C compilers.
X    makefile.unix:    for Unix systems with non-ANSI C compilers.
X    makefile.mc5:    for Microsoft C 5.x under MS-DOS.
X    makefile.mc6:    for Microsoft C 6.x and up under MS-DOS.
X    makefile.bcc:    for Borland C (Turbo C) under MS-DOS.
X    makefile.manx:    for Manx Aztec C on Amigas.
X    makefile.sas:    for SAS C on Amigas.
X    makcjpeg.st:    project file for Atari ST/STE/TT Pure C or Turbo C.
X    makdjpeg.st:    project file for Atari ST/STE/TT Pure C or Turbo C.
X    makljpeg.st:    project file for Atari ST/STE/TT Pure C or Turbo C.
X    makefile.mms:    for VAX/VMS systems with MMS.
X    makefile.vms:    for VAX/VMS systems without MMS.
X
XIf you don't see a makefile for your system, we recommend starting from either
Xmakefile.ansi or makefile.unix, depending on whether your compiler accepts
XANSI C or not.  Actually you should start with makefile.ansi whenever your
Xcompiler supports ANSI-style function definitions; you don't need full ANSI
Xcompatibility.  The difference between the two makefiles is that makefile.unix
Xpreprocesses the source code to convert function definitions to old-style C.
X(Our thanks to Peter Deutsch of Aladdin Enterprises for the ansi2knr program.)
X
XIf you don't know whether your compiler supports ANSI-style function
Xdefinitions, then take a look at ckconfig.c.  It is a test program that will
Xhelp you figure out this fact, as well as some other facts you'll need in
Xlater steps.  You must compile and execute ckconfig.c by hand; the makefiles
Xdon't provide any support for this.  ckconfig.c may not compile the first try
X(in fact, the whole idea is for it to fail if anything is going to).  If you
Xget compile errors, fix them by editing ckconfig.c according to the directions
Xgiven in ckconfig.c.  Once you get it to run, select a makefile according to
Xthe advice it prints out, and make any other changes it recommends.
X
XLook over the selected Makefile and adjust options as needed.  In particular
Xyou may want to change the CC and CFLAGS definitions.  For instance, if you
Xare using GCC, set CC=gcc.  If you had to use any compiler switches to get
Xckconfig.c to work, make sure the same switches are in CFLAGS.
X
XIf you are on a system that doesn't use makefiles, you'll need to set up
Xproject files (or whatever you do use) to compile all the source files and
Xlink them into executable files cjpeg and djpeg.  See the file lists in any of
Xthe makefiles to find out which files go into each program.  As a last resort,
Xyou can make a batch script that just compiles everything and links it all
Xtogether; makefile.vms is an example of this (it's for VMS systems that have
Xno make-like utility).
X
X
XSTEP 2: EDIT JCONFIG.H
X======================
X
XLook over jconfig.h and adjust #defines to reflect the properties of your
Xsystem and C compiler.  If you prefer, you can usually leave jconfig.h
Xunmodified and add -Dsymbol switches to the Makefile's CFLAGS definition.
X(This is already done if you used a compiler-specific makefile in step 1.)
XHowever, putting the switches in the Makefile is a bad idea if you are going
Xto incorporate the JPEG software into other programs --- you'd need to include
Xthe same -D switches in the other programs' Makefiles.  Better to change
Xjconfig.h.
X
XIf you have an ANSI-compliant C compiler, no changes should be necessary
Xexcept perhaps for RIGHT_SHIFT_IS_UNSIGNED and TWO_FILE_COMMANDLINE.  For
Xolder compilers other changes may be needed, depending on what ANSI features
Xare supported.
X
XIf you don't know enough about C programming to understand the questions in
Xjconfig.h, then use ckconfig.c to figure out what to change.  (See description
Xof ckconfig.c in step 1.)
X
XA note about TWO_FILE_COMMANDLINE: defining this selects the command line
Xsyntax in which the input and output files are both named on the command line.
XIf it's not defined, the output image goes to standard output, and the input
Xcan optionally come from standard input.  You MUST use two-file style on any
Xsystem that doesn't cope well with binary data fed through stdin/stdout; this
Xis true for most MS-DOS compilers, for example.  If you're not on a Unix
Xsystem, it's probably safest to assume you need two-file style.
X
X
XSTEP 3: SELECT SYSTEM-DEPENDENT FILES
X=====================================
X
XA few places in the JPEG software are so system-dependent that we have to
Xprovide several different implementations and let you select the one you need.
X
XThe only system-dependent file in the current version is jmemsys.c.  This file
Xcontrols use of temporary files for big images that won't fit in main memory.
XYou'll notice there is no file named jmemsys.c in the distribution; you must
Xselect one of the provided versions and copy, rename, or link it to jmemsys.c.
XHere are the provided versions:
X
X    jmemansi.c    This is a reasonably portable version that should
X            work on most ANSI and near-ANSI C compilers.  It uses
X            the ANSI-standard library routine tmpfile(), which not
X            all non-ANSI systems have.  On some systems tmpfile()
X            may put the temporary file in a non-optimal location;
X            if you don't like what it does, use jmemname.c.
X
X    jmemname.c    This version constructs the temp file name by itself.
X            For anything except a Unix machine, you'll need to
X            configure the select_file_name() routine appropriately;
X            see the comments near the head of jmemname.c.
X            If you use this version, define NEED_SIGNAL_CATCHER
X            in jconfig.h or in the Makefile to make sure the temp
X            files are removed if the program is aborted.
X
X    jmemnobs.c    (That stands for No Backing Store :-).  This will
X            compile on almost any system, but it assumes you
X            have enough main memory or virtual memory to hold
X            the biggest images you need to work with.
X
X    jmemdos.c    This should be used in most MS-DOS installations; see
X            the system-specific notes about MS-DOS for more info.
X            IMPORTANT: if you use this, also copy jmemdos.h to
X            jmemsys.h, replacing the standard version.  ALSO,
X            include the assembly file jmemdosa.asm in the programs.
X            (This last is already done if you used one of the
X            supplied MS-DOS-specific makefiles.)
X
XIf you have plenty of (real or virtual) main memory, just use jmemnobs.c.
X"Plenty" means at least ten bytes for every pixel in the largest images
Xyou plan to process, so a lot of systems don't meet this criterion.
XIf yours doesn't, try jmemansi.c first.  If that doesn't compile, you'll have
Xto use jmemname.c; be sure to adjust select_file_name() for local conditions.
XYou may also need to change unlink() to remove() in close_backing_store().
X
XExcept with jmemnobs.c, you need to adjust the #define DEFAULT_MAX_MEM to a
Xreasonable value for your system (either by editing jmemsys.c, or by adding
Xa -D switch to the Makefile).  This value limits the amount of data space the
Xprogram will attempt to allocate.  Code and static data space isn't counted,
Xso the actual memory needs for cjpeg or djpeg are typically 100 to 150Kb more
Xthan the max-memory setting.  Larger max-memory settings reduce the amount of
XI/O needed to process a large image, but too large a value can result in
X"insufficient memory" failures.  On most Unix machines (and other systems with
Xvirtual memory), just set DEFAULT_MAX_MEM to several million and forget it.
XAt the other end of the spectrum, for MS-DOS machines you probably can't go
Xmuch above 300K to 400K.  (On MS-DOS the value refers to conventional memory;
Xextended/expanded memory is handled separately by jmemdos.c.)
X
X
XSTEP 4: MAKE
X============
X
XNow you should be able to "make" the software.
X
XIf you have trouble with missing system include files or inclusion of the
Xwrong ones, look at jinclude.h (or use ckconfig.c, if you are not a C expert).
X
XIf your compiler complains about big_sarray_control and big_barray_control
Xbeing undefined structures, you should be able to shut it up by adding
X-DINCOMPLETE_TYPES_BROKEN to CFLAGS (or add #define INCOMPLETE_TYPES_BROKEN
Xto jconfig.h).  If you don't have a getenv() library routine, define NO_GETENV.
X
XThere are a fair number of routines that do not use all of their parameters;
Xsome compilers will issue warnings about this, which you can ignore.  Any
Xother warning deserves investigation.
X
X
XSTEP 5: TEST
X============
X
XAs a quick test of functionality we've included a small sample image in
Xseveral forms:
X    testorig.jpg    A reduced section of the well-known Lenna picture.
X    testimg.ppm    The output of djpeg testorig.jpg
X    testimg.gif    The output of djpeg -gif testorig.jpg
X    testimg.jpg    The output of cjpeg testimg.ppm
X(The two .jpg files aren't identical since JPEG is lossy.)  If you can
Xgenerate duplicates of the testimg.* files then you probably have working
Xprograms.
X
XWith most of the makefiles, "make test" will perform the necessary
Xcomparisons.  If you're using a makefile that doesn't provide this option, run
Xdjpeg and cjpeg to generate testout.ppm, testout.gif, and testout.jpg, then
Xcompare these to testimg.* with whatever binary file comparison tool you have.
XThe files should be bit-for-bit identical.
X
XIf the cjpeg test run fails with "Missing Huffman code table entry", it's a
Xgood bet that you needed to define RIGHT_SHIFT_IS_UNSIGNED.  Go back to step 2
Xand run ckconfig.c.  (This is a good plan for any other test failure, too.)
X
XIf your choice of jmemsys.c was anything other than jmemnobs.c, you should
Xtest that temporary-file usage works.  Try "djpeg -gif -max 0 testorig.jpg"
Xand make sure its output matches testimg.gif.  If you have any really large
Ximages handy, try compressing them with -optimize and/or decompressing with
X-gif to make sure your DEFAULT_MAX_MEM setting is not too large.
X
XNOTE: this is far from an exhaustive test of the JPEG software; some modules,
Xsuch as 1-pass color quantization, are not exercised at all.  It's just a quick
Xtest to give you some confidence that you haven't missed something major.
X
X
XSTEP 6: INSTALLATION
X====================
X
XOnce you're done with the above steps, you can install the software by copying
Xthe executable files (cjpeg and djpeg) to wherever you normally install
Xprograms.  On Unix systems, you'll also want to put cjpeg.1 and djpeg.1 in the
Xcorresponding manual directory.  (The makefiles don't support this step since
Xthere's such a wide variety of installation procedures on different systems.)
X
XTo learn to use the programs, read the file USAGE (or manual pages cjpeg(1)
Xand djpeg(1) on Unix).
X
X
XOPTIMIZATION
X============
X
XUnless you own a Cray, you'll probably be interested in making the JPEG
Xsoftware go as fast as possible.  This section covers some machine-dependent
Xoptimizations you may want to try.  We suggest that before trying any of this,
Xyou first get the basic installation to pass the self-test (step 5 above).
XRepeat the self-test after any optimization to make sure that you haven't
Xbroken anything.
X
XThe JPEG DCT routines perform a lot of multiplications.  These multiplications
Xmust yield 32-bit results, but none of their input values are more than 16
Xbits wide.  On many machines, notably the 680x0 and 80x86 CPUs, a 16x16=>32
Xbit multiply instruction is faster than a full 32x32=>32 bit multiply.
XUnfortunately there is no portable way to specify such a multiplication in C,
Xbut some compilers can generate one when you use the right combination of
Xcasts.  See the MULTIPLY macro definitions in jfwddct.c and jrevdct.c.
XIf your compiler makes "int" be 32 bits and "short" be 16 bits, defining
XSHORTxSHORT_32 is fairly likely to work.  When experimenting with alternate
Xdefinitions, be sure to test not only whether the code still works (use the
Xself-test step), but also whether it is actually faster --- on some compilers,
Xalternate definitions may compute the right answer, yet be slower than the
Xdefault.  Timing cjpeg on a large PPM input file is the best way to check
Xthis, as the DCT will be the largest fraction of the runtime in that mode.
X(Note: some of the distributed compiler-specific makefiles already contain
X-D switches to select an appropriate MULTIPLY definition.)
X
XIf access to "short" arrays is slow on your machine, it may be a win to define
Xtype DCTELEM as int rather than as JCOEF (which is normally defined as short).
XThis will cause the DCT routines to operate on int arrays instead of short
Xarrays.  If shorts are slow and you have lots of memory to burn, you might
Xeven make JCOEF itself be int.
X
XIf your compiler can compile function calls in-line, make sure the INLINE
Xmacro in jconfig.h is defined as the keyword that marks a function
Xinline-able.  Some compilers have a switch that tells the compiler to inline
Xany function it thinks is profitable (e.g., -finline-functions for gcc).
XEnabling such a switch is likely to make the compiled code bigger but faster.
X
XIn general, it's worth trying the maximum optimization level of your compiler,
Xand experimenting with any optional optimizations such as loop unrolling.
X(Unfortunately, far too many compilers have optimizer bugs ... be prepared to
Xback off if the code fails self-test.)  If you do any experimentation along
Xthese lines, please report the optimal settings to [e-mail] so
Xwe can mention them in future releases.  Be sure to specify your machine and
Xcompiler version.
X
X
XOPTIONAL STUFF
X==============
X
XProgress monitor:
X
XIf you like, you can #define PROGRESS_REPORT (in jconfig.h or in the Makefile)
Xto enable display of percent-done progress reports.  The routines provided in
Xjcmain.c/jdmain.c merely print percentages to stderr, but you can customize
Xthem to do something fancier.
X
XUtah RLE file format support:
X
XWe distribute the software with support for RLE image files (Utah Raster
XToolkit format) disabled, because the RLE support won't compile without the
XUtah library.  If you have URT version 3.0, you can enable RLE support as
Xfollows:
X    1.  #define RLE_SUPPORTED in jconfig.h or in the Makefile.
X    2.  Add a -I option to CFLAGS in the Makefile for the directory
X        containing the URT .h files (typically the "include"
X        subdirectory of the URT distribution).
X    3.  Add -L... -lrle to LDLIBS in the Makefile, where ... specifies
X        the directory containing the URT "librle.a" file (typically the
X        "lib" subdirectory of the URT distribution).
X
XJPEG library:
X
XIf you want to incorporate the JPEG code as subroutines in a larger program,
Xwe recommend that you make libjpeg.a, then link that into your surrounding
Xprogram.  See file README for more info.
X
XCAUTION: When you use the JPEG code as subroutines, we recommend that you make
Xany required configuration changes by modifying jconfig.h, not by adding -D
Xswitches to the Makefile.  Otherwise you must be sure to provide the same -D
Xswitches when compiling any program that includes the JPEG .h files, to ensure
Xthat the parameter structures are interpreted the same way.  (This is only
Xcritical for the first few symbols mentioned in jconfig.h, down through
XNEED_FAR_POINTERS.)
X
XRemoving code:
X
XIf you need to make a smaller version of the JPEG software, some optional
Xfunctions can be removed at compile time.  See the xxx_SUPPORTED #defines in
Xjconfig.h.  If at all possible, we recommend that you leave in decoder support
Xfor all valid JPEG files, to ensure that you can read anyone's output.
XRestricting your encoder, or removing optional functions like block smoothing,
Xwon't hurt compatibility.  Taking out support for image file formats that you
Xdon't use is the most painless way to make the programs smaller.
X
X
XNOTES FOR SPECIFIC SYSTEMS
X==========================
X
XWe welcome reports on changes needed for systems not mentioned here.
XSubmit 'em to [e-mail].  Also, if ckconfig.c is wrong about
Xhow to configure the JPEG software for your system, please let us know.
X
X
XAmiga:
X
XMakefiles are provided for Manx Aztec C and SAS C.  I have also heard from
Xpeople who have compiled with the free DICE compiler, using makefile.ansi as a
Xstarting point (set "CC= dcc" and "CFLAGS= -c -DAMIGA -DTWO_FILE_COMMANDLINE
X-DNEED_SIGNAL_CATCHER" in the makefile).  For all compilers, we recommend you
Xuse jmemname.c as the system-dependent memory manager.  Assuming you have
X-DAMIGA in the makefile, jmemname.c will put temporary files in JPEGTMP:.
XChange jmemname.c if you don't like this.
X
X
XAtari:
X
XThe project files provided should work as-is with Pure C.  For Turbo C, change
Xlibrary filenames "PC..." to "TC..." in the project files for cjpeg.ttp and
Xdjpeg.ttp.  Don't forget to select a jmemsys.c file, see Step 3 (we recommend
Xjmemansi.c).  Also adjust the DEFAULT_MAX_MEM setting --- you probably want it
Xto be a couple hundred K less than your normal free memory.  Note that you
Xmust make jpeg.lib before making cjpeg.ttp or cjpeg.ttp.  You'll have to
Xperform the self-test (Step 5) by hand.
X
XThere is a bug in some older versions of the Turbo C library which causes the
Xspace used by temporary files created with "tmpfile()" not to be freed after
Xan abnormal program exit.  If you check your disk afterwards, you will find
Xcluster chains that are allocated but not used by a file.  This should not
Xhappen in cjpeg or djpeg, since we enable a signal catcher to explicitly close
Xtemp files before exiting.  But if you use the JPEG library with your own
Xcode, be sure to supply a signal catcher, or else use a different
Xsystem-dependent memory manager.
X
X
XCray:
X
XShould you be so fortunate as to be running JPEG on a Cray YMP, there is a
Xcompiler bug in Cray's Standard C versions prior to 3.1.  You'll need to
Xinsert a line reading "#pragma novector" just before the loop
X    for (i = 1; i <= (int) htbl->bits[l]; i++)
X      huffsize[p++] = (char) l;
Xin fix_huff_tbl (in V3, line 42 of jchuff.c and line 38 of jdhuff.c).  The
Xusual symptom of not adding this line is a core-dump.  See Cray's SPR 48222.
X
X
XHP/Apollo DOMAIN:
X
XWith system release 10.4 or later, makefile.ansi should work OK.  If you have
Xversion 10.3.anything, you need to figure out whether you have the ANSI C
Xcompiler (version 6.7 or later) and whether you've installed the ANSI C
Xinclude files (if so, the first line of <stdio.h> will mention ANSI C).
XIf you have the ANSI C compiler but not the ANSI C include files, use
Xmakefile.ansi and add -DNONANSI_INCLUDES to CFLAGS.  If you have both,
Xthen makefile.ansi should work as is.  If neither, use makefile.unix.
X
X
XHP-UX:
X
XIf you have HP-UX 7.05 or later with the "software development" C compiler,
Xthen you can use makefile.ansi.  Add "-Aa" to the CFLAGS line in the makefile
Xto make the compiler work in ANSI mode.  If you have a pre-7.05 system, or if
Xyou are using the non-ANSI C compiler delivered with a minimum HP-UX 8.0
Xsystem, then you must use makefile.unix (and do NOT add -Aa).  Also, adding
X"-lmalloc" to LDLIBS is recommended if you have libmalloc.a (it seems not to
Xbe present in minimum 8.0).
X
XOn HP 9000 series 800 machines, the HP C compiler is buggy in revisions prior
Xto A.08.07.  If you get complaints about "not a typedef name", you'll have to
Xconvert the code to K&R style (i.e., use makefile.unix).
X
X
XMacintosh MPW:
X
XWe don't directly support MPW in the current release, but Larry Rosenstein
Xreports that the JPEG code can be ported without very much trouble.  There's
Xuseful notes and conversion scripts in his kit for porting PBMPLUS to MPW.
XYou can obtain the kit by FTP to ftp.apple.com, file /pub/lsr/pbmplus-port*.
X
X
XMacintosh Think C:
X
XYou'll have to prepare project files for cjpeg and djpeg; we don't include
Xthose in the distribution since they are not text files.  The COBJECTS and
XDOBJECTS lists in makefile.unix show which files should be included in each
Xproject.  Also add the ANSI and Unix C libraries in a separate segment.  You
Xmay need to divide the JPEG files into more than one segment; you can do this
Xpretty much as you please.
X
XIf you have Think C version 5.0 you need not modify jconfig.h; instead you
Xshould turn on both the ANSI Settings and Language Extensions option buttons
X(so that both __STDC__ and THINK_C are predefined).  With version 4.0 you must
Xedit jconfig.h.  (You can #define HAVE_STDC to do the right thing for all
Xoptions except const; you must also #define const.)
X
Xjcmain and jdmain are set up to provide the usual command-line interface
Xby means of Think's ccommand() library routine.  A more Mac-like interface
Xis in the works.
X
X
XMS-DOS, generic comments:
X
XThe JPEG code is designed to be compiled with 80x86 "small" or "medium" memory
Xmodels (i.e., data pointers are 16 bits unless explicitly declared "far"; code
Xpointers can be either size).  You should be able to use small model to
Xcompile cjpeg or djpeg by itself, but you will probably have to go to medium
Xmodel if you include the JPEG code in a larger application.  This shouldn't
Xhurt performance much.  You *will* take a noticeable performance hit if you
Xcompile in a large-data memory model, and you should avoid "huge" model if at
Xall possible.  Be sure that NEED_FAR_POINTERS is defined by jconfig.h or by
Xthe Makefile if you use a small-data model; be sure it is NOT defined if you
Xuse a large-data memory model.  (As distributed, jconfig.h defines
XNEED_FAR_POINTERS if MSDOS is defined.)
X
XThe DOS-specific memory manager, jmemdos.c, should be used if possible.
X(Be sure to install jmemdos.h and jmemdosa.asm along with it.)  If you
Xcan't use jmemdos.c for some reason --- for example, because you don't have
Xa Microsoft-compatible assembler to assemble jmemdosa.asm --- you'll have
Xto fall back to jmemansi.c or jmemname.c.  IMPORTANT: if you use either of
Xthe latter two files, you will have to compile in a large-data memory model
Xin order to get the right stdio library.  Too bad.
X
XNone of the above advice applies if you are using a 386 flat-memory-space
Xenvironment, such as DJGPP or Watcom C.  (And you should use one if you have
Xit, as performance will be much better than 8086-compatible code!)  For
Xflat-memory-space compilers, do NOT define NEED_FAR_POINTERS, and do NOT use
Xjmemdos.c.  Use jmemnobs.c if the environment supplies adequate virtual
Xmemory, otherwise use jmemansi.c or jmemname.c.
X
XMost MS-DOS compilers treat stdin/stdout as text files, so you must use
Xtwo-file command line style.  But if your compiler has the setmode() library
Xroutine, you can define USE_SETMODE to get one-file style.  (Don't forget to
Xchange the "make test" script in the Makefile if you do so.)
X
XIf you add more switches to CFLAGS in the DOS-specific makefiles, you are
Xlikely to run up against DOS' 128-byte command line length limit.  In that
Xcase, remove some "-Dsymbol" switches from CFLAGS and instead put
Xcorresponding "#define symbol" lines at the head of jinclude.h.
X
X
XMS-DOS, Borland C:
X
XBe sure to convert all the source files to DOS text format (CR/LF newlines).
XAlthough Borland C will often work OK with unmodified Unix (LF newlines)
Xsource files, sometimes it will give bogus compile errors.
X"Illegal character '#'" is the most common such error.
X
XSome versions of Borland's MAKE erroneously display the warning message about
Xcreating jmemsys.c, even after you have done so.  If this happens to you,
Xdelete the four lines beginning with "jmemsys.c:" from the Makefile.
X
X
XMS-DOS, DJGPP:
X
XUse makefile.ansi and jmemnobs.c, and put "-UMSDOS" in CFLAGS to undo the
Xcompiler's automatic definition of MSDOS.  Also put either "-DUSE_SETMODE" or
X"-DTWO_FILE_COMMANDLINE" in CFLAGS, depending on whether you prefer one-file
Xor two-file command line style.  (If you choose two-file style, change the
X"make test" section of the Makefile accordingly.)  You'll also need to put the
Xobject-file lists into response files in order to circumvent DOS's 128-byte
Xcommand line length limit at the final linking step.
X
X
XMS-DOS, Microsoft C:
X
XOld versions of MS C fail with an "out of macro expansion space" error
Xbecause they can't cope with the macro TRACEMS8 (defined in jpegdata.h).
XIf this happens to you, the easiest solution is to change TRACEMS8 to
Xexpand to nothing.  You'll lose the ability to dump out JPEG coefficient
Xtables with djpeg -debug -debug, but at least you can compile.
X
XOriginal MS C 6.0 is buggy; it compiles incorrect code unless you turn off
Xoptimization (remove -O from CFLAGS).  That problem seems to have been fixed
Xin 6.00A and later versions.  6.00A still generates a bogus "conditional
Xexpression is constant" warning in jrdppm.c, but the emitted code seems OK.
X
X
XSGI:
X
XUse makefile.ansi, but set "AR2= ar -ts" rather than "AR2= ranlib".  Also
Xmake any changes recommended by ckconfig.c.
X
X
XSun:
X
XDon't forget to add -DBSD to CFLAGS.  If you are using GCC on SunOS 4.0.1 or
Xearlier, you will need to add -DNONANSI_INCLUDES to CFLAGS (your compiler may
Xbe ANSI, but your system include files aren't).  I've gotten conflicting
Xreports on whether this is still necessary on SunOS 4.1 or later.
END_OF_FILE
  if test 26242 -ne `wc -c <'SETUP'`; then
    echo shar: \"'SETUP'\" unpacked with wrong size!
  fi
  # end of 'SETUP'
fi
if test -f 'architecture.A' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'architecture.A'\"
else
  echo shar: Extracting \"'architecture.A'\" \(26089 characters\)
  sed "s/^X//" >'architecture.A' <<'END_OF_FILE'
X
X    JPEG SYSTEM ARCHITECTURE        1-DEC-92
X
X
XThis file provides an overview of the "architecture" of the portable JPEG
Xsoftware; that is, the functions of the various modules in the system and the
Xinterfaces between modules.  For more precise details about any data structure
Xor calling convention, see the header files.
X
XImportant note: when I say "module" I don't mean "a C function", which is what
Xsome people seem to think the term means.  A separate C source file is closer
Xto the mark.  Also, it is frequently the case that several different modules
Xpresent a common interface to callers; the term "object" or "method" refers to
Xthis common interface (see "Poor man's object-oriented programming", below).
X
XJPEG-specific terminology follows the JPEG standard:
X  A "component" means a color channel, e.g., Red or Luminance.
X  A "sample" is a pixel component value (i.e., one number in the image data).
X  A "coefficient" is a frequency coefficient (a DCT transform output number).
X  The term "block" refers to an 8x8 group of samples or coefficients.
X  "MCU" (minimum coded unit) is the same as "MDU" of the R8 draft; i.e., an
X    interleaved set of blocks of size determined by the sampling factors,
X    or a single block in a noninterleaved scan.
X
X
X*** System requirements ***
X
XWe must support compression and decompression of both Huffman and
Xarithmetic-coded JPEG files.  Any set of compression parameters allowed by the
XJPEG spec should be readable for decompression.  (We can be more restrictive
Xabout what formats we can generate.)  (Note: for legal reasons no arithmetic
Xcoding implementation is currently included in the publicly available sources.
XHowever, the architecture still supports it.)
X
XWe need to be able to handle both raw JPEG files (more specifically, the JFIF
Xformat) and JPEG-in-TIFF (C-cubed's format, and perhaps Kodak's).  Even if we
Xdon't implement TIFF ourselves, other people will want to use our code for
Xthat.  This means that generation and scanning of the file header has to be
Xseparated out.
X
XPerhaps we should be prepared to support the JPEG lossless mode (also referred
Xto in the spec as spatial DPCM coding).  A lot of people seem to believe they
Xneed this... whether they really do is debatable, but the customer is always
Xright.  On the other hand, there will not be much sharable code between the
Xlossless and lossy modes!  At best, a lossless program could be derived from
Xparts of the lossy version.  For now we will only worry about the lossy mode.
X
XI see no real value in supporting the JPEG progressive modes (note that
Xspectral selection and successive approximation are two different progressive
Xmodes).  These are only of interest when painting the decompressed image in
Xreal-time, which nobody is going to do with a pure software implementation.
X
XThere is some value in supporting the hierarchical mode, which allows for
Xsuccessive frames of higher resolution.  This could be of use for including
X"thumbnail" representations.  However, this appears to add a lot more
Xcomplexity than it is worth.
X
XA variety of uncompressed image file formats and user interfaces must be
Xsupported.  These aspects therefore have to be kept separate from the rest of
Xthe system.  A particularly important issue is whether color quantization of
Xthe output is needed (i.e., whether a colormap is used).  We should be able to
Xsupport both adaptive quantization (which requires two or more passes over the
Ximage) and nonadaptive (quantization to a prespecified colormap, which can be
Xdone in one pass).
X
XMemory usage is an important concern, since we will port this code to 80x86
Xand other limited-memory machines.  For large intermediate structures, we
Xshould be able to use either virtual memory or temporary files.
X
XIt should be possible to build programs that handle compression only,
Xdecompression only, or both, without much duplicate or unused code in any
Xversion.  (In particular, a decompression-only version should have no extra
Xbaggage.)
X
X
X*** Compression overview ***
X
XThe *logical* steps needed in (non-lossless) JPEG compression are:
X
X1. Conversion from incoming image format to a standardized internal form
X   (either RGB or grayscale).
X
X2. Color space conversion (e.g., RGB to YCbCr).  This is a null step for
X   grayscale (unless we support mapping color inputs to grayscale, which
X   would most easily be done here).  Gamma adjustment may also be needed here.
X
X3. Downsampling (reduction of number of samples in some color components).
X   This step operates independently on each color component.
X
X4. MCU extraction (creation of a single sequence of 8x8 sample blocks).
X   This step and the following ones are performed once for each scan
X   in the output JPEG file, i.e., once if making an interleaved file and more
X   than once for a noninterleaved file.
X   Note: both this step and the previous one must deal with edge conditions
X   for pictures that aren't a multiple of the MCU dimensions.  Alternately,
X   we could expand the picture to a multiple of an MCU before doing these
X   two steps.  (The latter seems better and has been adopted below.)
X
X5. DCT transformation of each 8x8 block.
X
X6. Quantization scaling and zigzag reordering of the elements in each 8x8
X   block.
X
X7. Huffman or arithmetic encoding of the transformed block sequence.
X
X8. Output of the JPEG file with whatever headers/markers are wanted.
X
XOf course, the actual implementation will combine some of these logical steps
Xfor efficiency.  The trick is to keep these logical functions as separate as
Xpossible without losing too much performance.
X
XIn addition to these logical pipeline steps, we need various modules that
Xaren't part of the data pipeline.  These are:
X
XA. Overall control (sequencing of other steps & management of data passing).
X
XB. User interface; this will determine the input and output files, and supply
X   values for some compression parameters.  Note that this module is highly
X   platform-dependent.
X
XC. Compression parameter selection: some parameters should be chosen
X   automatically rather than requiring the user to find a good value.
X   The prototype only does this for the back-end (Huffman or arithmetic)
X   parameters, but further in the future, more might be done.  A
X   straightforward approach to selection is to try several values; this
X   requires being able to repeatedly apply some portion of the pipeline and
X   inspect the results (without actually outputting them).  Probably only
X   entropy encoding parameters can reasonably be done this way; optimizing
X   earlier steps would require too much data to be reprocessed (not to mention
X   the problem of interactions between parameters for different steps).
X   What other facilities do we need to support automatic parameter selection?
X
XD. A memory management module to deal with small-memory machines.  This must
X   create the illusion of virtual memory for certain large data structures
X   (e.g., the downsampled image or the transformed coefficients).
X   The interface to this must be defined to minimize the overhead incurred,
X   especially on virtual-memory machines where the module won't do much.
X
XIn many cases we can arrange things so that a data stream is produced in
Xsegments by one module and consumed by another without the need to hold it all
Xin (virtual) memory.  This is obviously not possible for any data that must be
Xscanned more than once, so it won't work everywhere.
X
XThe major variable at this level of detail is whether the JPEG file is to be
Xinterleaved or not; that affects the order of processing so fundamentally that
Xthe central control module must know about it.  Some of the other modules may
Xneed to know it too.  It would simplify life if we didn't need to support
Xnoninterleaved images, but that is not reasonable.
X
XMany of these steps operate independently on each color component; the
Xknowledge of how many components there are, and how they are interleaved,
Xought to be confined to the central control module.  (Color space conversion
Xand MCU extraction probably have to know it too.)
X
X
X*** Decompression overview ***
X
XDecompression is roughly the inverse process from compression, but there are
Xsome additional steps needed to produce a good output image.
X
XThe *logical* steps needed in (non-lossless) JPEG decompression are:
X
X1. Scanning of the JPEG file, decoding of headers/markers etc.
X
X2. Huffman or arithmetic decoding of the coefficient sequence.
X
X3. Quantization descaling and zigzag reordering of the elements in each 8x8
X   block.
X
X4. MCU disassembly (conversion of a possibly interleaved sequence of 8x8
X   blocks back to separate components in pixel map order).
X
X5. (Optional)  Cross-block smoothing per JPEG section K.8 or a similar
X   algorithm.  (Steps 5-8 operate independently on each component.)
X
X6. Inverse DCT transformation of each 8x8 block.
X
X7. Upsampling.  At this point a pixel image of the original dimensions
X   has been recreated.
X
X8. Post-upsampling smoothing.  This can be combined with upsampling,
X   by using a convolution-like calculation to generate each output pixel
X   directly from one or more input pixels.
X
X9. Cropping to the original pixel dimensions (throwing away duplicated
X   pixels at the edges).  It is most convenient to do this now, as the
X   preceding steps are simplified by not having to worry about odd picture
X   sizes.
X
X10. Color space reconversion (e.g., YCbCr to RGB).  This is a null step for
X    grayscale.  (Note that mapping a color JPEG to grayscale output is most
X    easily done in this step.)  Gamma adjustment may also be needed here.
X
X11. Color quantization (only if a colormapped output format is requested).
X    NOTE: it is probably preferable to perform quantization in the internal
X    (JPEG) colorspace rather than the output colorspace.  Doing it that way,
X    color conversion need only be applied to the colormap entries, not to
X    every pixel; and quantization gets to operate in a non-gamma-corrected
X    space.  But the internal space may not be suitable for some algorithms.
X    The system design is such that only the color quantizer module knows
X    whether color conversion happens before or after quantization.
X
X12. Writing of the desired image format.
X
XAs before, some of these will be combined into single steps.  When dealing
Xwith a noninterleaved JPEG file, steps 2-9 will be performed once for each
Xscan; the resulting data will need to be buffered up so that steps 10-12 can
Xprocess all the color components together.
X
XThe same auxiliary modules are needed as before, except for compression
Xparameter selection.  Note that rerunning a pipeline stage should never be
Xneeded during decompression.  This may allow a simpler control module.  The
Xuser interface might also be simpler since it need not supply any compression
Xparameters.
X
XAs before, not all of these steps require the whole image to be stored.
XActually, two-pass color quantization is the only step that logically requires
Xthis; everything else could be done a few raster lines at a time (at least for
Xinterleaved images).  We might want to make color quantization be a separate
Xprogram because of this fact.
X
XAgain, many of the steps should be able to work on one color component in
Xignorance of the other components.
X
X
X*** Implications of noninterleaved formats ***
X
XMuch of the work can be done in a single pass if an interleaved JPEG file
Xformat is used.  With a noninterleaved JPEG file, separating or recombining
Xthe components will force use of virtual memory (on a small-memory machine,
Xwe probably would want one temp file per color component).
X
XIf any of the image formats we read or write are noninterleaved, the opposite
Xcondition might apply: processing a noninterleaved JPEG file would be more
Xefficient.  Offhand, though, I can't think of any popular image formats that
Xwork that way; besides the win would only come if the same color space were
Xused in JPEG and non-JPEG files.  It's not worth the complexity to make the
Xsystem design accommodate that case efficiently.
X
XAn argument against interleaving is that it makes the decompressor need more
Xmemory for cross-block smoothing (since the minimum processable chunk of the
Ximage gets bigger).  With images more than 1000 pixels across, 80x86 machines
Xare likely to have difficulty in handling this feature.
X
XAnother argument against interleaving is that the noninterleaved format allows
Xa wider range of sampling factors, since the limit of ten blocks per MCU no
Xlonger applies.  We could get around this by blithely ignoring the spec's
Xlimit of ten blocks, but that seems like a bad idea (especially since it makes
Xthe above problem worse).
X
XThe upshot is that we need to support both interleaved and noninterleaved JPEG
Xformats, since for any given machine and picture size one may be much more
Xefficient than the other.  However, the non-JPEG format we convert to or from
Xwill be assumed to be an interleaved format (i.e., it produces or stores all
Xthe components of a pixel together).
X
XI do not think it is necessary for the compressor to be able to output
Xpartially-interleaved formats (multiple scans, some of which interleave a
Xsubset of the components).  However, the decompressor must be able to read
Xsuch files to conform to the spec.
X
X
X*** Data formats ***
X
XPipeline steps that work on pixel sample values will use the following data
Xstructure:
X
X    typedef something JSAMPLE;        a pixel component value, 0..MAXJSAMPLE
X    typedef JSAMPLE *JSAMPROW;        ptr to a row of samples
X    typedef JSAMPROW *JSAMPARRAY;    ptr to a list of rows
X    typedef JSAMPARRAY *JSAMPIMAGE;    ptr to a list of color-component arrays
X
XThe basic element type JSAMPLE will be one of unsigned char, (signed) char, or
Xunsigned short.  Unsigned short will be used if samples wider than 8 bits are
Xto be supported (this is a compile-time option).  Otherwise, unsigned char is
Xused if possible.  If the compiler only supports signed chars, then it is
Xnecessary to mask off the value when reading.  Thus, all reads of sample
Xvalues should be coded as "GETJSAMPLE(value)", where the macro will be defined
Xas "((value)&0xFF)" on signed-char machines and "(value)" elsewhere.
X
XWith these conventions, JSAMPLE values can be assumed to be >= 0.  This should
Xsimplify correct rounding during downsampling, etc.  The JPEG draft's
Xspecification that sample values run from -128..127 will be accommodated by
Xsubtracting 128 just as the sample value is copied into the source array for
Xthe DCT step (this will be an array of signed shorts or longs).  Similarly,
Xduring decompression the output of the IDCT step will be immediately shifted
Xback to 0..255.  (NB: different values are required when 12-bit samples are in
Xuse.  The code should be written in terms of MAXJSAMPLE and CENTERJSAMPLE,
Xwhich will be #defined as 255 and 128 respectively in an 8-bit implementation,
Xand as 4095 and 2048 in a 12-bit implementation.)
X
XOn compilers that don't support "unsigned short", signed short can be used for
Xa 12-bit implementation.  To support lossless coding (which allows up to
X16-bit data precision) masking with 0xFFFF in GETJSAMPLE might be necessary.
X(But if "int" is 16 bits then using "unsigned int" is the best solution.)
X
XNotice that we use a pointer per row, rather than a two-dimensional JSAMPLE
Xarray.  This choice costs only a small amount of memory and has several
Xbenefits:
X
X* Code using the data structure doesn't need to know the allocated width of
Xthe rows.  This will simplify edge expansion/compression, since we can work
Xin an array that's wider than the logical picture width.
X
X* The rows forming a component array may be allocated at different times
Xwithout extra copying.  This will simplify working a few scanlines at a time,
Xespecially in smoothing steps that need access to the previous and next rows.
X
X* Indexing doesn't require multiplication; this is a performance win on many
Xmachines.
X
XNote that each color component is stored in a separate array; we don't use the
Xtraditional structure in which the components of a pixel are stored together.
XThis simplifies coding of steps that work on each component independently,
Xbecause they don't need to know how many components there are.  Furthermore,
Xwe can read or write each component to a temp file independently, which is
Xhelpful when dealing with noninterleaved JPEG files.
X
XA specific sample value will be accessed by code such as
X    GETJSAMPLE(image[colorcomponent][row][col])
Xwhere col is measured from the image left edge, but row is measured from the
Xfirst sample row currently in memory.  Either of the first two indexings can
Xbe precomputed by copying the relevant pointer.
X
X
XPipeline steps that work on frequency-coefficient values will use the
Xfollowing data structure:
X
X    typedef short JCOEF;        a 16-bit signed integer
X    typedef JCOEF JBLOCK[64];        an 8x8 block of coefficients
X    typedef JBLOCK *JBLOCKROW;        ptr to one horizontal row of 8x8 blocks
X    typedef JBLOCKROW *JBLOCKARRAY;    ptr to a list of such rows
X    typedef JBLOCKARRAY *JBLOCKIMAGE;    ptr to a list of color component arrays
X
XThe underlying type is always a 16-bit signed integer (this is "short" on all
Xmachines of interest, but let's use the typedef name anyway).  These are
Xgrouped into 8x8 blocks (we should use #defines DCTSIZE and DCTSIZE2 rather
Xthan "8" and "64").  The contents of a block may be either in "natural" or
Xzigzagged order, and may be true values or divided by the quantization
Xcoefficients, depending on where the block is in the pipeline.
X
XNotice that the allocation unit is now a row of 8x8 blocks, corresponding to
Xeight rows of samples.  Otherwise the structure is much the same as for
Xsamples, and for the same reasons.
X
XOn machines where malloc() can't handle a request bigger than 64Kb, this data
Xstructure limits us to rows of less than 512 JBLOCKs, which would be a picture
Xwidth of 4000 pixels.  This seems an acceptable restriction.
X
X
XOn 80x86 machines, the bottom-level pointer types (JSAMPROW and JBLOCKROW)
Xmust be declared as "far" pointers, but the upper levels can be "near"
X(implying that the pointer lists are allocated in the DS segment).
XTo simplify sharing code, we'll have a #define symbol FAR, which expands to
Xthe "far" keyword when compiling on 80x86 machines and to nothing elsewhere.
X
X
XThe data arrays used as input and output of the DCT transform subroutine will
Xbe declared using a separate typedef; they could be arrays of "short", "int"
Xor "long" independently of the above choices.  This would depend on what is
Xneeded to make the compiler generate correct and efficient multiply/add code
Xin the DCT inner loops.  No significant speed or memory penalty will be paid
Xto have a different representation than is used in the main image storage
Xarrays, since some additional value-by-value processing is done at the time of
Xcreation or extraction of the DCT data anyway (e.g., add/subtract 128).
X
X
X*** Poor man's object-oriented programming ***
X
XIt should be pretty clear by now that we have a lot of quasi-independent
Xsteps, many of which have several possible behaviors.  To avoid cluttering the
Xcode with lots of switch statements, we'll use a simple form of object-style
Xprogramming to separate out the different possibilities.
X
XFor example, Huffman and arithmetic coding will be implemented as two separate
Xmodules that present the same external interface; at runtime, the calling code
Xwill access the proper module indirectly through an "object".
X
XWe can get the limited features we need while staying within portable C.  The
Xbasic tool is a function pointer.  An "object" is just a struct containing one
Xor more function pointer fields, each of which corresponds to a method name in
Xreal object-oriented languages.  During initialization we fill in the function
Xpointers with references to whichever module we have determined we need to use
Xin this run.  Then invocation of the module is done by indirecting through a
Xfunction pointer; on most architectures this is no more expensive (and
Xpossibly cheaper) than a switch, which would be the only other way of making
Xthe required run-time choice.  The really significant benefit, of course, is
Xkeeping the source code clean and well structured.
X
XFor example, the interface for entropy decoding (Huffman or arithmetic
Xdecoding) might look like this:
X
X    struct function_ptr_struct {
X        ...
X        /* Entropy decoding methods */
X        void (*prepare_for_scan) ();
X        void (*get_next_mcu) ();
X        ...
X        };
X
X    typedef struct function_ptr_struct * function_ptrs;
X
XThe struct pointer is what will actually be passed around.  A call site might
Xlook like this:
X
X    some_function (function_ptrs fptrs)
X        {
X        ...
X        (*fptrs->get_next_mcu) (...);
X        ...
X        }
X
X(It might be worth inventing some specialized macros to hide the rather ugly
Xsyntax for method definition and call.)  Note that the caller doesn't know how
Xmany different get_next_mcu procedures there are, what their real names are,
Xnor how to choose which one to call.
X
XAn important benefit of this scheme is that it is easy to provide multiple
Xversions of any method, each tuned to a particular case.  While a lot of
Xprecalculation might be done to select an optimal implementation of a method,
Xthe cost per invocation is constant.  For example, the MCU extraction step
Xmight have a "generic" method, plus one or more "hardwired" methods for the
Xmost popular sampling factors; the hardwired methods would be faster because
Xthey'd use straight-line code instead of for-loops.  The cost to determine
Xwhich method to use is paid only once, at startup, and the selection criteria
Xare hidden from the callers of the method.
X
XThis plan differs a little bit from usual object-oriented structures, in that
Xonly one instance of each object class will exist during execution.  The
Xreason for having the class structure is that on different runs we may create
Xdifferent instances (choose to execute different modules).
X
XTo minimize the number of object pointers that have to be passed around, it
Xwill be easiest to have just a few big structs containing all the method
Xpointers.  We'll actually use two such structs, one for "system-dependent"
Xmethods (memory allocation and error handling) and one for everything else.
X
XBecause of this choice, it's best not to think of an "object" as a specific
Xdata structure.  Rather, an "object" is just a group of related methods.
XThere would typically be one or more C modules (source files) providing
Xconcrete implementations of those methods.  You can think of the term
X"method" as denoting the common interface presented by some set of functions,
Xand "object" as denoting a group of common method interfaces, or the total
Xshared interface behavior of a group of modules.
X
X
X*** Data chunk sizes ***
X
XTo make the cost of this object-oriented style really minimal, we should make
Xsure that each method call does a fair amount of computation.  To do that we
Xshould pass large chunks of data around; for example, the colorspace
Xconversion method should process much more than one pixel per call.
X
XFor many steps, the most natural unit of data seems to be an "MCU row".
XThis consists of one complete horizontal strip of the image, as high as an
XMCU.  In a noninterleaved scan, an MCU row is always eight samples high (when
Xlooking at samples) or one 8x8 block high (when looking at coefficients).  In
Xan interleaved scan, an MCU row consists of all the data for one horizontal
Xrow of MCUs; this may be from one to four blocks high (eight to thirty-two
Xsamples) depending on the sampling factors.  The height and width of an MCU
Xrow may be different in each component.  (Note that the height and width of an
XMCU row changes at the downsampling and upsampling steps.  An unsubsampled
Ximage has the same size in each component.  The preceding statements apply to
Xthe downsampled dimensions.)
X
XFor example, consider a 1024-pixel-wide image using (2h:2v)(1h:1v)(1h:1v)
Xsubsampling.  In the noninterleaved case, an MCU row of Y would contain 8x1024
Xsamples or the same number of frequency coefficients, so it would occupy
X8K bytes (samples) or 16K bytes (coefficients).  An MCU row of Cb or Cr would
Xcontain 8x512 samples and occupy half as much space.  In the interleaved case,
Xan MCU row would contain 16x1024 Y samples, 8x512 Cb and 8x512 Cr samples, so
Xa total of 24K (samples) or 48K (coefficients) would be needed.  This is a
Xreasonable amount of data to expect to retain in memory at one time.  (Bear in
Xmind that we'll usually need to have several MCU rows resident in memory at
Xonce, at the inputs and outputs to various pipeline steps.)
X
XThe worst case is probably (2h:4v)(1h:1v)(1h:1v) interleaving (this uses 10
Xblocks per MCU, which is the maximum allowed by the spec).  An MCU will then
Xcontain 32 sample rows worth of Y, so it would occupy 40K or 80K bytes for a
X1024-pixel-wide image.  The most memory-intensive step is probably cross-block
Xsmoothing, for which we'd need 3 MCU rows of coefficients as input and another
Xone as output; that would be 320K of working storage.  Anything much larger
Xwould not fit in an 80x86 machine.  (To decompress wider pictures on an 80x86,
Xwe'll have to skip cross-block smoothing or else use temporary files.)
X
XThis unit is thus a reasonable-sized chunk for passing through the pipeline.
XOf course, its major advantage is that it is a natural chunk size for the MCU
Xassembly and disassembly steps to work with.
X
XFor the entropy (Huffman or arithmetic) encoding/decoding steps, the most
Xconvenient chunk is a single MCU: one 8x8 block if not interleaved, three to
Xten such blocks if interleaved.  The advantage of this is that when handling
Xinterleaved data, the blocks have the same sequence of component membership on
Xeach call.  (For example, Y,Y,Y,Y,Cb,Cr when using (2h:2v)(1h:1v)(1h:1v)
Xsubsampling.)  The code needs to know component membership so that it can
Xapply the right set of compression coefficients to each block.  A prebuilt
Xarray describing this membership can be used during each call.  This chunk
Xsize also makes it easy to handle restart intervals: just count off one MCU
Xper call and reinitialize when the count reaches zero (restart intervals are
Xspecified in numbers of MCU).
END_OF_FILE
  if test 26089 -ne `wc -c <'architecture.A'`; then
    echo shar: \"'architecture.A'\" unpacked with wrong size!
  elif test -f 'architecture.B'; then
    echo shar: Combining  \"'architecture'\" \(66550 characters\)
    cat 'architecture.A' 'architecture.B' > 'architecture'
    if test 66550 -ne `wc -c <'architecture'`; then
      echo shar: \"'architecture'\" combined with wrong size!
    else
      rm architecture.A architecture.B
    fi
  fi
  # end of 'architecture.A'
fi
if test -f 'jinclude.h' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'jinclude.h'\"
else
  echo shar: Extracting \"'jinclude.h'\" \(3902 characters\)
  sed "s/^X//" >'jinclude.h' <<'END_OF_FILE'
X/*
X * jinclude.h
X *
X * Copyright (C) 1991, 1992, Thomas G. Lane.
X * This file is part of the Independent JPEG Group's software.
X * For conditions of distribution and use, see the accompanying README file.
X *
X * This is the central file that's #include'd by all the JPEG .c files.
X * Its purpose is to provide a single place to fix any problems with
X * including the wrong system include files.
X * You can edit these declarations if you use a system with nonstandard
X * system include files.
X */
X
X
X/*
X * Normally the __STDC__ macro can be taken as indicating that the system
X * include files conform to the ANSI C standard.  However, if you are running
X * GCC on a machine with non-ANSI system include files, that is not the case.
X * In that case change the following, or add -DNONANSI_INCLUDES to your CFLAGS.
X */
X
X#ifdef __STDC__
X#ifndef NONANSI_INCLUDES
X#define INCLUDES_ARE_ANSI    /* this is what's tested before including */
X#endif
X#endif
X
X/*
X * <stdio.h> is included to get the FILE typedef and NULL macro.
X * Note that the core portable-JPEG files do not actually do any I/O
X * using the stdio library; only the user interface, error handler,
X * and file reading/writing modules invoke any stdio functions.
X * (Well, we did cheat a bit in jmemmgr.c, but only if MEM_STATS is defined.)
X */
X
X#include <stdio.h>
X
X/*
X * We need the size_t typedef, which defines the parameter type of malloc().
X * In an ANSI-conforming implementation this is provided by <stdio.h>,
X * but on non-ANSI systems it's more likely to be in <sys/types.h>.
X * On some not-quite-ANSI systems you may find it in <stddef.h>.
X */
X
X#ifndef INCLUDES_ARE_ANSI    /* shouldn't need this if ANSI C */
X#include <sys/types.h>
X#endif
X#ifdef __SASC            /* Amiga SAS C provides it in stddef.h. */
X#include <stddef.h>
X#endif
X
X/*
X * In ANSI C, and indeed any rational implementation, size_t is also the
X * type returned by sizeof().  However, it seems there are some irrational
X * implementations out there, in which sizeof() returns an int even though
X * size_t is defined as long or unsigned long.  To ensure consistent results
X * we always use this SIZEOF() macro in place of using sizeof() directly.
X */
X
X#undef SIZEOF            /* in case you included X11/xmd.h */
X#define SIZEOF(object)    ((size_t) sizeof(object))
X
X/*
X * fread() and fwrite() are always invoked through these macros.
X * On some systems you may need to twiddle the argument casts.
X * CAUTION: argument order is different from underlying functions!
X */
X
X#define JFREAD(file,buf,sizeofbuf)  \
X  ((size_t) fread((void *) (buf), (size_t) 1, (size_t) (sizeofbuf), (file)))
X#define JFWRITE(file,buf,sizeofbuf)  \
X  ((size_t) fwrite((const void *) (buf), (size_t) 1, (size_t) (sizeofbuf), (file)))
X
X/*
X * We need the memcpy() and strcmp() functions, plus memory zeroing.
X * ANSI and System V implementations declare these in <string.h>.
X * BSD doesn't have the mem() functions, but it does have bcopy()/bzero().
X * Some systems may declare memset and memcpy in <memory.h>.
X *
X * NOTE: we assume the size parameters to these functions are of type size_t.
X * Change the casts in these macros if not!
X */
X
X#ifdef INCLUDES_ARE_ANSI
X#include <string.h>
X#define MEMZERO(target,size)    memset((void *)(target), 0, (size_t)(size))
X#define MEMCOPY(dest,src,size)    memcpy((void *)(dest), (const void *)(src), (size_t)(size))
X#else /* not ANSI */
X#ifdef BSD
X#include <strings.h>
X#define MEMZERO(target,size)    bzero((void *)(target), (size_t)(size))
X#define MEMCOPY(dest,src,size)    bcopy((const void *)(src), (void *)(dest), (size_t)(size))
X#else /* not BSD, assume Sys V or compatible */
X#include <string.h>
X#define MEMZERO(target,size)    memset((void *)(target), 0, (size_t)(size))
X#define MEMCOPY(dest,src,size)    memcpy((void *)(dest), (const void *)(src), (size_t)(size))
X#endif /* BSD */
X#endif /* ANSI */
X
X
X/* Now include the portable JPEG definition files. */
X
X#include "jconfig.h"
X
X#include "jpegdata.h"
END_OF_FILE
  if test 3902 -ne `wc -c <'jinclude.h'`; then
    echo shar: \"'jinclude.h'\" unpacked with wrong size!
  fi
  # end of 'jinclude.h'
fi
echo shar: End of archive 9 \(of 18\).
cp /dev/null ark9isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 18 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still must unpack the following archives:
    echo "        " ${MISSING}
fi
exit 0
exit 0 # Just in case...